外観ストリーム

注釈は、枠線、色、形状などの独自の外観プロパティのセットを持っています。しかし、すべてのPDF ビューワがまったく同じ注釈の外観を描画することはありません。そのため、外観ストリームが必要となります。外観ストリームは、一連の描画コマンドとして注釈を視覚的に表現するため、ビューワは注釈を正確に描画する方法を知ることができます。

注釈は、状態に応じて次のような外観を持つことができます。

通常の外観：ユーザーが注釈に対して何もしていないときの外観です。注釈を印刷する際にも使用されます。
ロールオーバー外観：ユーザーがマウスボタンを押さずにカーソルを注釈のアクティブ領域に移動させたときの外観です。
マウスダウン外観：ユーザーが注釈のアクティブ領域にてマウスボタンを押下したときの外観です。

注釈には、1つまたは複数の外観ストリームが関連付けられている場合があります。外観ストリームは、基本的にグラフィックを含む矩形領域の FormXObject であり、そのグラフィック上に描画されたものは、注釈が通常状態、ロールオーバー状態、マウスダウン状態のときに表示されます。

DioDocs for PDF では、AppearanceStreams クラスにて、各状態に対応する Normal、Rollover、Down プロパティを提供しています。これらのプロパティは Appearance 型であり、デフォルトの FormXObject と特定の状態に関連付けられた FormXObject のディクショナリにアクセスすることができます。

ただし、フリーテキスト注釈や線注釈のようなリッチテキストを生成する注釈を扱うには、GcPdfDocument クラスの BuildRichTextAppearanceStreams プロパティを使用します。このプロパティは、デフォルトは false です。リッチテキストを生成する注釈の場合、DioDocs for PDF はデフォルトで外観ストリームを生成しません。BuildRichTextAppearanceStreams プロパティが true に設定されている場合、DioDocs for PDF はそれらの注釈の外観ストリームを生成し、注釈のリッチテキストをプレーンテキストとして描画します。

また、注釈に関連付けられている外観ストリームをすべて削除するには、AnnotationBase クラスの RemoveAppearance() メソッドを使用します。このメソッドは、ドキュメントの保存時に外観ストリームの生成を無効にします。これは、エクスポートされた PDF ドキュメントのファイルサイズを小さくするのに役立ちます。

次のサンプルコードは、PDF ドキュメントのスタンプ注釈に外観ストリームを追加および削除する方法を示します。

var doc = new GcPdfDocument();
// スタンプ注釈を追加する既存の PDF を読み込みます
var jsFile = Path.Combine("Resources", "PDFs", "The-Rich-History-of-JavaScript.pdf");

using (var fs = new FileStream(jsFile, FileMode.Open, FileAccess.Read))
{
    doc.Load(fs);
    var rect = new RectangleF(PointF.Empty, doc.Pages[0].Size);
    // スタンプ注釈の外観として使用する FormXObject を作成します
    var fxo = new FormXObject(doc, rect);
    // リソースから画像を取得し、FormXObject のグラフィックに描画します
    using (var image = Image.FromFile(Path.Combine("Resources", "ImagesBis", "draft-copy-450x72.png")))
    {
        var center = new Vector2(fxo.Bounds.Width / 2, fxo.Bounds.Height / 2);
        fxo.Graphics.Transform =
            Matrix3x2.CreateRotation((float)(-55 * Math.PI) / 180f, center) *
            Matrix3x2.CreateScale(6, center);
        fxo.Graphics.DrawImage(image, fxo.Bounds, null, ImageAlign.CenterImage);
        // ループ処理にて、各ページにスタンプ注釈を追加します
        foreach (var page in doc.Pages)
        {
            // ページ全体に StampAnnotation を作成します
            var stamp = new StampAnnotation()
            {
                Icon = StampAnnotationIcon.Draft.ToString(),
                Name = "draft",
                Page = page,
                Rect = rect,
                UserName = "Jaime Smith"
            };
            // すべてのページで同じ FormXObject を使用して、独自の外観ストリームを追加します
            stamp.AppearanceStreams.Normal.Default = fxo;
        }

        // 最初のページの1番目の注釈の外観ストリームを削除します
        var p = doc.Pages[0];
        var an = p.Annotations[0];
        an.RemoveAppearance();
        doc.Save(stream);
    }
}

次のサンプルコードは、リッチテキストを生成するフリーテキスト注釈に対して BuildRichTextAppearanceStreams を true に設定する方法を示します。

GcPdfDocument.BuildRichTextAppearanceStreams = true;
var doc = new GcPdfDocument();
var page = doc.NewPage();

// 内部にリッチテキストを含むフリーテキスト注釈
var freeRichAnnot = new FreeTextAnnotation()

{
    Rect = new RectangleF(10, 50, 288, 72),
    LineWidth = 1,
    Color = Color.LightSalmon,
    RichText =
    "<body><p>This is another <i>free text annotation</i>, with <b><i>Rich Text</i></b> content.</p>" +
    "<p><br />Even though a <b>free text</b> annotation displays text directly on a page, " +
    "as other annotations it can be placed outside the page's bounds.</p></body>"
};
page.Annotations.Add(freeRichAnnot);
// 完了
doc.Save("Annotations.pdf");