入門 2 - プログラム全般に関すること -

ここでは個別の話に入る前にプログラムに共通する全般的な事項を説明します。

1. 言語バインディング

PDFlib は主要な言語のほとんどで利用することができます。PDFlib 自身はANSI Cで開発されていますが、各言語で利用できるようAPIやライブラリー、リソースが言語バインディングとして整備されています。これにより原則として PDFlib の全ての機能をどのサポート言語からも利用することが可能となります。

言語バインディングは、どの言語でも PDFlib の各関数をほとんど同じ使い勝手で利用できるように工夫されていますが、一部言語に依存する相違、たとえばCの文字列パラメータでは文字列の長さを指定する必要があるなどの違いが残るので注意が必要です。各言語バインディングの詳細は日本語チュートリアルの「2章 PDFlib の言語バインディング」に記述されています。

2. スコープ

PDFlib では、関数の呼出し手順の妥当性を確保するために関数のスコープ(有効範囲)を規定しています。スコープは下図のように生成するPDFオブジェクトの構造に従って定義されています。各関数毎に使用できるスコープが規定されており、スコープの範囲外で関数を使用すると PDFlib の例外(Exception)エラーが発生するようになっています。各関数のスコープは 日本語 API リファレンスマニュアルの、各関数の説明のスコープの項に、またスコープの定義は「1.2 関数のスコープ」に記載されています。

3. パラメータ

PDFlib のさまざまな動作を制御するためのグローバルパラメータが定義されており、set_option() または get_option() で設定及び問い合せすることができます。たとえば、

  $p->set_option("searchpath=" . $searchpath);

では、ファイルを検索するときのパスを追加します。パラメータの使用方法は 日本語 API リファレンスマニュアルの PDF_set_option および PDF_get_option の項目に関連して記載されています。

4. 例外処理

PDFlib は独自の例外処理機能を持っています。深刻でない例外処理についてはグローバルパラメータ returnpolicy により例外の発生の可否を設定することができます。エラーメッセージ、エラーコード、例外処理を起こした関数名を返す例外処理関数が用意されています。ハローワールドのサンプルでも次のようにbegin_document()が失敗したときにエラーメッセージを出力するために例外処理関数が使われています。

  if($p->begin_document("", "") == 0) {
    die("Error: " . $p->get_errmsg());
  }

例外処理については 日本語チュートリアルの「3.1.1 例外処理」及び各言語バインディングの説明に記述されています。

5. オプションリスト

関数のパラメータの数を抑えながらさまざまな処理の指定を可能とするために、パラメータのひとつとしてオプションリストを指定することができます。オプションリストは、文字列のパラメータで、単純にはname=valueなどの形でさまざまな値を指定できるほか、複数の値を持つリスト値などをひとつのパラメータに対し設定できます。

  $p->fit_image($image, 0, 0, "scale 0.1 orientate west");

上記は画像を配置する関数ですが、最後のパラメータはオプションリスト形式となっており、「(1)1/10に縮小し、(2)左を上として配置すること」を指定しています。オプションリストについては 日本語 API リファレンスマニュアルで各関数ごとに詳しく説明されています。

6. ページと座標系

PDFlib の座標系はPDFの既定の座標系に従っています。PDFの既定の座標系はページの左下隅が原点となり、最初の座標が右方向に、2番目の座標が上方向に増えていきます。座標の単位はポイントです。ポイントとmmの関係は以下のようになります。

座標単位をポイントからセンチメートルに変更したい時は、72/2.54 = 28.3456 から

  $p->scale(28.3456, 28.3456);

と座標系を拡大します。座標変換関数やユーザ座標により用途に合わせた座標系を設定することができます。ページと座標系については 日本語チュートリアルマニュアルの「3.2 ページ記述」で詳しく説明されています。