チュートリアル: iText.NET

目次

• 文書を作る五つの手順
• step 1: Document オブジェクト
• step 2: Writer オブジェクト
• step 3: 文書を開く
• step 4: コンテンツを追加する
• step 5: 文書を閉じる

次の節では、それぞれの段階についてより詳しく説明します。

com.lowagie.text.Document クラスには 三つのコンストラクタがあります。

public Document();
public Document(Rectangle pageSize);
public Document(Rectangle pageSize,
   int marginLeft,
   int marginRight,
   int marginTop,
   int marginBottom);

最初のコンストラクタは、パラメータ PageSize.A4 をとって二番目のコンストラクタを呼び出します。二番目のコンストラクタは、三番目のコンストラクタをそれぞれのマージンを 36 として呼び出します。

既定のページサイズは DIN A4 (iText は、ヨーロッパで作られたライブラリです。A4　版は、ヨーロッパではもっとも一般的な紙の大きさです。)ですが、 A0-A10, LEGAL, LETTER, HALFLETTER, _11x17, LEDGER, NOTE, B0-B5, ARCH_A-ARCH_E, FLSA, FLSE といった、ほとんどすべての標準的なページサイズを提供する com.lowagie.text.PageSize クラスがあります。 ここに挙げた標準的なページサイズは縦長です。横長の文書を作成したければ、ただ単に高さを幅より短くするだけです。PageSize クラスを使いたいならば、rotate() をつけて Rectangle を得ます。 もちろん、ここに挙げた以外にも任意のサイズのページを作ることはできますが、最大 200 × 200 インチ （Acrobat 3.0 と互換性をとるならば 45 × 45 インチ） という制限があります。また、PageSize インスタンスにより背景色を指定することもできます。次の例では、長細い黄色の背景の文書を作成します。 測量単位について知りたいという場合には、FAQを参照してください。

step 4 では、document にコンテンツを追加します。高機能オブジェクトを使うときには、マージンやページレイアウトのことは気にする必要はありません。高機能オブジェクトについては、ちょっと覚えておいてください。もちろん、標準のマージンである 36 pt（1/2 インチ）以外のマージン幅にするときには、マージンは最初に指定する必要があります。
コンテンツを追加している間にマージンを変更することはできますが、そのマージンが有効になるのは、『次』のページからです。（偶数ページ、奇数ページで）非対称のマージンを設定したいときには、setMarginMirroring(true) というメソッドを使うことができます。 測量単位について知りたいという場合には、FAQを参照してください。

Document クラスはコンテンツレベルのクラスであり、プレゼンテーションレベルのクラスではありません。同じ Document インスタンス に対して複数の Writer インスタンスが 監視していることもあるので、Document オブジェクトに対して、ページ番号を問い合わせることは本質的に無意味です。Document は どんな数字を返せばいいのでしょうか？ PDF ? HTML ? (この場合は、より意味がない) 要するに、ページ番号は、Document ではなく、Writer に問い合わせなければなりません。

Document が作成された時点で、document を監視するひとつ以上の Writer インスタンスを作成することができます。あらゆる Writer クラスは、com.lowagie.text.DocWriter 抽象クラスから派生しなければなりません。今のところ、三種類の Writer がサポートされています。

PdfWriter

Portable Document Format 文書を生成する。

RtfWriter

RTF 文書を生成する。これについては、'RTF' の章をご覧ください。

HtmlWriter

HTML 文書を生成する。これは、もともとデバッグのために作成されました(iText による HTML の生成)。

これらの Writer クラスは DocWriter 抽象クラスから派生しており、そのコンストラクタは protected です。インスタンスを作成するときには、スタティックメソッドの PdfWriter.getInstance、RtfWriter2.getInstance あるいは HtmlWriter.getInstance を使います。 (xxx は Pdf, Rtf あるいは Html です). たとえば、次のように作成します。 これは、一見すると何のオブジェクトも得ていないように見えます。きっと、次のような構文を思い浮かべたでしょう。 実際には、Writer オブジェクトはどちらの場合でも存続しますが、単純なアプリケーションでは Writer オブジェクトを使うことはありません。

getInstance メソッドの最初のパラメータは、step 1 で作成した com.lowagie.text.Document オブジェクトです。二番目のパラメータは、任意の java.io.OutputStream オブジェクトです。このチュートリアルでは、java.io.FileOutputStream を使いますが、java.io.ByteArrayOutputStream によりメモリ上に PDF を作ることや、javax.servlet.ServletOutputStream (Web アプリケーションにおける iText 参照) も使うことができます。お望みならば、標準出力にも書き込むことができます。（しかし次のような結果になるので、良い考えとは思いません。）

ここで強調したいことは、ひとつの document に対して、異なる Writer を同時に割り当てることができるということです。たとえば、サーブレットから PDF をブラウザへ直接表示し、それと同時にその PDF のコピーをサーバに保存したいようなときには、ひとつの Document オブジェクトに対して、OutputStream の異なる getInstance を二度呼び出すことができます。
Ghent 大学では、開講情報について書かれた二種類のカタログ（ひとつは Web サイト用の HTML、もうひとつは印刷用の PDF）があります。これらを、同じソースコードで同時に作成することができます。たった一つの異なる点は、HTML のページに PDF ファイルへのリンクを追加するために、PDFWriter を一時停止するだけです。これは、次の例でお示しします。

Document.open() を呼び出すことは重要です。iText は、document が open される前にコンテンツを追加すると例外をスローします。これは、デザイン上の問題です。Document オブジェクトを open する前に必要な初期化はいくつかあります。そのほとんどは、このチュートリアルで説明します。ここでは、それらのうち二つを見てみましょう。 暗号化された文書を生成するときには、Document オブジェクトを開く前に、setEncryption を呼び出す必要があります。暗号化オプションを Document.open() を呼び出し後に設定すると、DocumentException 例外が、”Encryption can only be added before opening the document” というメッセージとともに投げられます。 Acrobat で文書のプロパティ（ファイルメニューの中にあります）を見ると、既定では、いくつかの項目が空白であることが解ります。


既定では、PDF 変換を設定する addProducer() と 作成日時を設定する addCreationDate() が呼び出されます。これらを変更することはできますが、すべきではありません。
そこで、概要エリアにあるメタデータを変更するためのメソッドのみをここに記載します。

タイトル	addTitle(String)
作成者	addAuthor(String)
サブタイトル	addSubject(String)
キーワード	addKeywords(String)
アプリケーション	addCreator(String)

次の簡単な例で説明します。

document.addTitle("Hello World example");
document.addAuthor("Bruno Lowagie");
document.addSubject("This example explains how to add metadata.");
document.addKeywords("iText, Hello World, step 3, metadata");
document.addCreator("My program using iText");

次に結果を示しますが、上記の結果と比べてみてください。

API を良く調べると、addHeader(java.lang.String, java.lang.String) というメソッドが見つかります。このメソッドは、PdfWriter に対しては無意味ですが、HtmlWriter に対しては意味があります。

PDF にコンテンツを追加する方法はいくつかあります。最も簡単な方法は、Chunk、Phrase、Paragraph といった 高機能オブジェクト を利用することです。重要なことは、これらのオブジェクトは、すべての Wrtier がその機能を実現しているというわけではないということです。たとえば、PdfPTable オブジェクトは PDF でのみサポートされており、RTF や HTML ではサポートされません。PdfPTable を RtfWriter や HtmlWriter が監視する Document オブジェクトに加えても、それは無視されます。
RTF やHTML が必要ないならば、コンテンツを絶対位置へ追加することもできます。かなり多くの標準 PDF シンタックスが iText でサポートされているので、このライブラリで相当強力なことをすることができます。
(java.awt.Graphics2D から派生している) PdfGraphics2D オブジェクトも使うことができます。このオブジェクトの使い方はこのチュートリアルの他の場所で説明します。

Document オブジェクトを閉じることは非常に重要です。これによって、ストリームへの書き込みを実際に行っている OutputStream オブジェクトを フラッシュし、閉じるからです。close メソッドは finalize メソッドでも呼ばれていますが、明示的に呼び出すべきです。

Copyright © 1999-2005 Bruno Lowagie
iText is a Free Java-Pdf library by Bruno Lowagie and Paulo Soares.