チュートリアル: iText.NET

Chunk は、文書にテキストを追加するときの最小単位であり、高機能オブジェクトを構成する基本要素となります。Chunk 内は、同じ性質―フォント、サイズ、スタイル、色など―をしています。Chunk は、文書へテキストを加えるときの最小単位です。この節では、Chunk のすべての機能を記載します。

フォント の章にあるように、下線や取り消し線のための Font.UNDERLINE や Font.STRIKETHRU というスタイルが定義されている。これは、RTF や HTML では、動作しますが PDF では動作しません。しかし、Chunk.setUnderline メソッドを使えばより多くのことができます。このメソッドには、二つのバリエーションがあります。

• Chunk.setUnderline(float thickness, float yPosition) は、Chunk の長さと同じ長さの線を描きます。thickness は、ポイントで表した線の幅、yPosition は、Chunk のベースラインから上への距離です。

  Chunk underlined = new Chunk("underlined");
  underlined.setUnderline(0.2f, -2f);
  Chunk strikethru = new Chunk("strike through example");
  strikethru.setUnderline(0.5f, 3f);

• Chunk.setUnderline(Color color, float thickness, float thicknessMul, float yPosition, float yPositionMul, int cap) は、線の色を定義します。thickness と yPosition パラメータは線の幅とベースラインからの距離を絶対座標で指定しますが、thicknessMul と yPositionMul は、フォントサイズに依存します。例では、フォントサイズ以外同じサイズの Chunk に、同じ線の指定をしています。見れば解るように、いくつかの線はフォントサイズに連動していますが、そうでないものもあります。これらは、setUnderline メソッドで渡されたパラメータによります。最後に、cap パラメータは、ラインキャップのスタイルを表します。(PDF Reference Manual の Table 4.4 参照).
  

  Chunk c = new Chunk("Multiple lines");
  c.setUnderline(new Color(0xFF, 0x00, 0x00),
  	0.0f, 0.3f, 0.0f, 0.4f,
  	PdfContentByte.LINE_CAP_ROUND);
  c.setUnderline(new Color(0x00, 0xFF, 0x00),
  	5.0f, 0.0f, 0.0f, -0.5f,
  	PdfContentByte.LINE_CAP_PROJECTING_SQUARE);
  c.setUnderline(new Color(0x00, 0x00, 0xFF),
  	0.0f, 0.2f, 15.0f, 0.0f,
  	PdfContentByte.LINE_CAP_BUTT);

Chunk を現在の y 座標から上あるいは下に加えたいときには、setTextRise メソッドを使うことができます。例では、c.setUnderline(new Color(0xC0, 0xC0, 0xC0), 0.2f, 0.0f, 0.0f, 0.0f, PdfContentByte.LINE_CAP_BUTT); によってベースラインを引き、正の TextRise により上付きになること、負の TextRise により下付きになることを示します。
下線の定義は、TextRise には影響されないことには注意すべきです。下線は、通常のテキストと上付きのテキストが混在していても連続すべきですが、不連続になってしまいます。下付きでは、見た目は良くありません。

With the methods setBackground(Color color) と setBackground(Color color, float extraLeft, float extraBottom, float extraRight, float extraTop) メソッドにより、(たとえば、単語を強調するために) Chunk の背景色を変更することができます。最初のメソッドは、Chunk を囲むように塗りつぶされ、二番目のメソッドは、その四角形を大きくしたり、小さくしたりすることができます。

PDF 文法での文字（グリフ）は、塗りつぶした形とみなされています。文字の色を変えたいときには、フォントの色を変えることができますが、実際のところは '塗りつぶす' 色を変えているのです。これを、例で示します。

setTextRenderMode(int mode, float strokeWidth, Color strokeColor) メソッドによって、テキストの輪郭を変えることができます。ダイレクトコンテンツの章を読めば解りますが、線は '塗りつぶされる' のではなく、'筆書きされる'のです。strokeWidth と strokeColor パラメータにより、文字に描かれる線の太さと色が定義されます。
mode パラメータは、次のうちのひとつの値です。

1. PdfContentByte.TEXT_RENDER_MODE_FILL: グリフは、フォント色で塗りつぶされ、strokeWidth と strokeColor は無視される。
2. PdfContentByte.TEXT_RENDER_MODE_STROKE: strokeWidth と strokeColor で指定された輪郭で描かれる。
3. PdfContentByte.TEXT_RENDER_MODE_FILL_STROKE: strokeWidth と strokeColor で指定された輪郭で描かれ、フォント色で塗りつぶされる。
4. PdfContentByte.TEXT_RENDER_MODE_INVISIBLE: グリフは、不可視になる。

このメソッドは、（たとえば、Font.Bold をサポートしないフォントを使う場合に）太字をシミュレートするために使用できます。

setSkew(float alpha, float beta) メソッドは、（たとえば、Font.ITALIC をサポートしないフォントを使う場合に）斜字フォントをシミュレートするために使用できます。これは、単に alpha として 0f beta として 12f を指定するだけです。

Alfa は度で表したベースラインの角度です。例では、いくつかのテキストが 45f と -45f が指定されています。beta は、ベースラインにおける四辺形の角度です。

ここまでに挙げた機能で行いたいことがまだできないならば、PageEvent onGenericTag(PdfWriter writer, Document document, Rectangle rect, String text) によってあなた自身でそれを作成することができます。つまり、PdfPageEvent インターフェイスを実装したクラスを作成することができます。最も良い方法は、PdfPageEventHelper クラスから派生されたクラスでオーバーライドした onGenericTag メソッドでカスタム機能を定義することです。

public class Generic extends PdfPageEventHelper {
  public void onGenericTag(PdfWriter writer, Document document, Rectangle rect, String text) {
    // writer is the current writer to which the Chunk is written
    // document is the document to which the Chunk was added
    // rect is the area surrounding the Chunk
    // text is the text you passed with setGenericTag
  }
}

PageEvent を設定することを忘れないように。

writer.setPageEvent(new Generic());

最初の例では、genericTag (setGenericTag(String text)) を通過するテキストを監視しています。もしも、単語が、"ellipse" ならば、Chunk の上に楕円を描き、"box" ならば、Chunk の下に四角を描きます。

public void onGenericTag(PdfWriter writer, Document document, Rectangle rect, String text) {
  if ("ellipse".equals(text)) {
    PdfContentByte cb = writer.getDirectContent();
    cb.setRGBColorStroke(0xFF, 0x00, 0x00);
    cb.ellipse(rect.left(), rect.bottom() - 5f, rect.right(), rect.top());
    cb.stroke();
    cb.resetRGBColorStroke();
  }
  else if ("box".equals(text)) {
    PdfContentByte cb = writer.getDirectContentUnder();
    rect.setGrayFill(0.5f);
    cb.rectangle(rect);
  }
}

PDF 文法について学ぶためにも、ダイレクトコンテンツの章を呼んでください。これにより、無限の可能性が開けます。 次の例では、どの単語がどのページで使われたかの登録を保存する TreeMap を作るためにジェネリックタグを使用しています。 いったん文書が完結すると、ページを追加し索引を与えます。これは、単純な例ですが、少しの変更により、真に複雑なさまざまな用途にも使うことができます。

Chunk のページ上での幅を知りたいときには、 getWidthPoint() メソッドを使うことができます。これは、ポイント単位の幅を返します。インチやセンチメータ単位の幅を知りたいときには、計算が必要です。
setHorizontalScaling(float scale) メソッドによって、Chunk を、縮小 (scale < 1.0f) したり拡大 (scale > 1.0f) したりできます。例では、まず通常のサイズで Chunk を印字し、次に二分の一のサイズ (scale = 0.5f) で印字しています。

Chunk を文書に追加し続けていくと、あるときに行末に達します。もちろん何も定義していなくても、iText はそれなりの処理をします。既定では、iText は、復帰をします。それでは改行はどうなるのでしょう？ iText は、行間にどれぐらいの間を空けるべきなのでしょうか？ 二つの行（ベースライン）の間の幅は、改行幅と呼ばれ、Chunk クラスでは定義されません。このようなことを指定するときには、Paragraph のようなクラスを使う必要があります。

次の例では、あまり知られていない（不必要かもしれない）Phrase クラスを使っています。Phrase は、（異なるスタイルを持ちえる）Chunk の集まりであり、拡張パラメータとしてある改行幅を持っています。Paragraph と異なり、インデントに関する情報はありません。既定では、フォントサイズは 12であるので、改行幅として 16 が設定されています。例の最初のページを見てください。すべての Chunk は同じ行に、どんどん重ね書きされています。二ページ目では、同じ Chunk が 改行幅 16 の Phrase にグループ化され、行末に達すると、新しい行になります。

既定では iText は、できるだけ多くの '完全な単語' を一行に入れようとします。iText は、文中のスペースやハイフンがある位置で改行を入れます。それでは、Chunk がページの幅より長いときにはどうなるのでしょうか？ このような場合、iText は最初にページに収まらない文字の前で Chunk を分割します。この振る舞いは、ある場合には望ましい動作ではありません。これは、SplitCharacter インターフェースを実装したクラスを setSplitCharacter(SplitCharacter splitCharacter) を使って Chunk に登録することによって避けることができます。isSplitCharacter メソッドは、最初に思うほどは単純ではないように見えると思います。次に、既定の実装を示します。 （訳注：アジア言語の初歩的な禁則処理にも対応しています。）

public boolean isSplitCharacter(int start, int current, int end, char[] cc, PdfChunk[] ck) {
   char c;
   if (ck == null)
       c = cc[current];
   else
       c = ck[Math.min(current, ck.length - 1)].getUnicodeEquivalent(cc[current]);
   if (c <= ' ' || c == '-') {
       return true;
   }
   if (c < 0x2e80)
       return false;
   return ((c >= 0x2e80 && c < 0xd7a0)
   || (c >= 0xf900 && c < 0xfb00)
   || (c >= 0xfe30 && c < 0xfe50)
   || (c >= 0xff61 && c < 0xffa0));
}

カスタム SplitCharacter の実装はこのコードをコピーして作成することができます。次のように変更すると、iText は、ピリオドとスラッシュでも単語を分割するようになります。

if (c <= ' ' || c == '-' || c == '.' || c == '/') {
    return true;
}

この節を終わる前に、iTextは、自動的にハイフネーションをすることができるということを説明する。このためには、HyphenationAuto クラスのインスタンスを作成しなければならない。

// Hyphenating a British text
Chunk ckEN = new Chunk(textEN);
HyphenationAuto autoEN = new HyphenationAuto("en", "GB", 2, 2);
ckEN.setHyphenation(autoEN);
// Hyphenating a Dutch text
Chunk ckNL = new Chunk(textNL);
HyphenationAuto autoNL = new HyphenationAuto("nl", null, 2, 2);
ckNL.setHyphenation(autoNL);

例では、同じテキスト (初期のCharles Dickens の叙述詩 Tale of Two Cities) を最初はUKのハイフネーション規則、次に、US のハイフネーション規則にのっとって、ハイフネーションをしています。見て解るように、得られた文書には若干の違いがあります。

注意: この機能を使うときには、itext-hyph-xml.jar を CLASSPATH に加えなければなりません。この JAR には、次のようなファイルが含まれています。

• en_GB.xml
• en_US.xml
• fr.xml
• nl.xml

これらのファイルはその言語(GB 英語、US 英語、フランス語、オランダ語など) のハイフネーション規則が記述されています。見て解るように、HyphenationAuto constructor の最初の二つのパラメータは、ファイル名を表し、三つ目と四つ目は、それぞれ語頭あるいは語尾の何文字が取り残されるかを表します。

XMLファイルは、iText の開発者により作成されたものではなく、Apache FOP のために作成されたものです。iText では利便性のために、Apache FOP からダウンロードし、分離した JAR として配付していますが、そのうちのいくつかは、GPL であったり商業用には利用できないものであったりします。これらのライセンスを守るためにもそれぞれのファイルのライセンスを読んでください。もしも、お探しのハイフネーションパターンがなければ、FOP サイト記載の方法にしたがって、これをつくることもできます。XML ファイルは、com.lowagie.text.pdf.hyphenation.hyph パッケージにリソースとして配置するか、あるディレクトリに配置し、Hyphenator.setHyphenDir() を呼び出してください。

Chunkについての話題はまだまだたくさんあります。Anchors と Actions を見てください。

Page Updated: 2005/05/10 15:05:55 Copyright © 1999-2005 Bruno Lowagie
iText is a Free Java-Pdf library by Bruno Lowagie and Paulo Soares.