iTextが提供する高機能オブジェクトによって相当たくさんのことができますが、PDFの全機能を使いたいのならば、PDFシンタックスについて学ぶ必要があります。まず、PDF Reference Manual (version 1.6) の 4章 (Graphics) と 5章 (Text) を読むことが必要です。それにより、次の章で使うさまざまな演算子や命令がわかるようになります。このチュートリアル章では、最も重要な概念の要約を試みます。
まず、Reference Manual の163ページの引用からはじめます。

グラフック演算子は、六つのグループよりなります。

• グラフィックステート演算子は、グラフィックステートと呼ばれるデータ構造 (内部でその他のグラフィックス演算子が実行されるグローバルフレームワーク) を操作します。グラフィックステートは、PDF コンテンツストリーム内部で使われているユーザ空間座標系から外部出力デバイス座標系へ変換する、現在の変換行列 (CTM) を含みます。これには、現在の色、現在のクリッピングパス、および数多くのパラメータが含まれており、これらは描画演算子の暗黙の命令となります。
  
  iText がこれをどのように取り扱うかについての詳しい情報は次を参照ください。

  • PDF 座標系
  • グラフックステート
  • 色
• パスを特定するパス構築演算子は、形、線の軌跡、さまざまな種類の領域を定義します。これらには、新しいパスのための演算子、線の断片を加える、曲げ、閉じるものも含まれます。
  
  iText がこれをどのように取り扱うかについての詳しい情報は次を参照ください。

  • パスの構築と描画
• パス描画演算子はパスを、色で塗りつぶしたり、それにそって描いたり、クリップ境界として使ったりします。
  iText がこれをどのように取り扱うかについての詳しい情報は次を参照ください。
  iText がこれをどのように取り扱うかについての詳しい情報は次を参照ください。

  • パスの構築と描画
• ほかの描画演算子は、ある自己記述をしているグラフィックスオブジェクトを描画します。これらには、サンプルされたイメージ、幾何学的に定義されたを含み、全体のコンテンツストリームは、順序付きの一連のグラフックス演算子となります。
  iText がこれをどのように取り扱うかについての詳しい情報は次を参照ください。
  iText がこれをどのように取り扱うかについての詳しい情報は次を参照ください。

  • イメージ XObject
  • フォーム XObject
  • PostScript XObject
• テキスト演算子は、フォント (テキスト文字を表現するタイプフェースの記述) から文字のグリフを選択し、表示します。PDF は、グリフを一般的なグラフィックシェープとして扱うので、テキスト演算子の多くは、グラフィックステートや描画演算子などに分類可能です。
  
  iText がこれをどのように取り扱うかについての詳しい情報は次を参照ください。

  • テキスト
  • フォント
• マークドコンテンツ演算子は、高機能論理情報をコンテンツストリームの中のオブジェクトに関連付けます。この情報は、コンテンツの見た目には影響しません。
  
  iText がこれをどのように取り扱うかについての詳しい情報は次を参照ください。

  • オプショナルコンテンツ

iText で高機能オブジェクト使えば、レイアウトの問題に悩まされることなく、テキストやイメージ、章や節、段落や句などを加えることができます。iText は、テキストを分割し、それぞれの、単語、文、段落をページ上に配置します。しかし、いつでも自動フォーマットが望ましいわけではありません。いくつかのグラフィックスやテキストをページ上の厳密な位置に配置したいときもあります。これを行う鍵のクラスは、com.lowagie.text.pdf.PdfContentByte です。
iText PDF においては、各ページは四つのレイヤーを使って構築されています。そのうちの（真中の）二つは、PdfDocument クラスで使われます。これにアクセスすることはできず、高機能オブジェクトを通して使われます。'text'と呼ばれる上層のレイヤーはテキストのために使われ、'graphics'と呼ばれる下層のレイヤーはその他のオブジェクトのために使われます。例えば、Chunk の中身は通常'text'レイヤーに加えられますが、Chunk がイメージであるときには 'graphics'レイヤーに追加されます。これにより、イメージは、テキストの上にはこないことになります。
PdfWriterクラスには、ほかに二つのレイヤーがあります。これらは、getDirectContent()  メソッドや getDirectContentUnder() メソッドで取り出すことができます。'ダイレクトコンテンツ'を表現しているひとつの PdfContentByte オブジェクトと、'下層ダイレクトコンテンツ'を表現しているひとつの PdfContentByte オブジェクトがあるだけです。これらのメソッドを複数回呼び出しても、常に同じ PdfContentByte インスタンスが返されます。

 コンテンツを、PdfContentByte インスタンスである 'ダイレクトコンテンツ' に書き込むことによって、高機能オブジェクトを覆うコンテンツを追加できます。コンテンツを インスタンスである '下層ダイレクトコンテンツ' に書き込むことによって、高機能オブジェクトの背面にコンテンツを追加できます。これは、次の例で示します。 要約すると、ページが終わる時に、四つのレイヤーは次の順番で描かれる。

1. getDirectContentUnder()  メソッドで得られるPdfContentByte
2. 高機能オブジェクトのうちグラフィックスが含まれている PdfContentByte オブジェクト
3. 高機能オブジェクトのうちテキストが含まれている PdfContentByte オブジェクト
4. getDirectContent() メソッドで得られるPdfContentByte

このiText特有の機能であり、この節で説明していることと、オプショナルコンテンツレイヤーの節で説明していることと混同しないように注意してください。

iText の四つのレイヤー（ダイレクトコンテンツ、高機能テキストオブジェクト、高機能グラフィックオブジェクト、下層ダイレクトコンテンツ）は、ページのPDF ストリームに書き込まれます。レイヤー、キャンバス、PdfTemplate は、ページのPDFストリームに属さないようにもできます。
PDFには、三種類の外部オブジェクトがあります。

1. イメージ XObject
2. フォーム XObject
3. PostScript XObject

iTextにおいては、PdfTemplate を作成することによって XObject フォームを使うことができる。これは、PdfContentByte.createTemplate(float, float)（パラメータは、幅と高さを指定します）によって行います。テンプレートは、PdfContentByte.addTemplate メソッドのひとつを使って追加します。これらのメソッドで指定するパラメータについて知りたいのならば、まず変換行列についてもっと読んでおかなければなりません。
もしも、これらの変換パラメータが難し過ぎて理解できないなら、PdfTemplate を Image オブジェクトにラップすることもできます。(Image クラスのメソッドはより簡単に理解できます。) 

XObject フォームは、一連のグラフィックスオブジェクトの自己含有的記述である PDF コンテンツストリームであると要約できます。。XObject フォームは、いくつかのページとか、同じページのいくつかの場所に、複数回、描画されることがあり、それらは、呼び出された時点におけるグラフィックスステートのみに従い、いつでも同じものが得られます。
XObject フォームと AcroForm を混同しないでください。XObject フォームは、対話的フォームのコンテキストにおけるフォーム（フィールド）とは違うものです（フォーム参照）。これが、私たちがXObject フォームを参照するときに、PdfTemplate を使う理由です。
iText において PdfTemplates は主に次の用途で使われます。

1. ある一連の PDF シンタックスを繰り返し使いたいが、ディスクスペースを節約（ストリームの再利用）し、処理時間も短くしたい（つまり、ストリームを一度しか書き込まない）。
2. あるコンテンツを加えたいが、そのコンテンツがどのようになるのかが、事前にはわからないとき。例えば、'ここは、y ページ中の x ページ' というフッタを加えたいが、y の値がわからないとき。この場合には、y のためのテンプレートを追加し、文書の正確なページ数がわかってから、テンプレートにコンテンツを追加することができます。

たぶん、PdfTemplate を使うために知っておくべきことは、たぶん、あとひとつしかない: まず、ページイベントについて学べば、ページの終端になるごとに PdfTemplate を加え、Document が閉じられる直前に PdfTemplate にコンテンツを埋める方法がわかります。

PostScript XObject の基本的な機能のサポートもされています (iText では、PdfPSXObject は PdfTemplate より派生しています)。PS シンタックスを setLiteral によってオブジェクトに追加し、その PS XObject を PdfContentByte.addPSXObject() によって追加します。しかし、PDF では Postscript XObject を使うことは推奨されていません。これらの PS の断片は、PostScript 出力機器に印刷するときにだけ使われます。つまり、そのPDF ファイルは正確に印刷されないかもしれないので、これを使うときには非常に気をつけなければなりません (PDF Reference Manual 4.7.1節 より: この機能は、将来のバージョンでは、PDF から除かれるかもしれない)。

Page Updated: 2005/04/08 07:33:23 Copyright © 1999-2005 Bruno Lowagie
iText is a Free Java-Pdf library by Bruno Lowagie and Paulo Soares.