C++ における PDF アノテーション - テキストノート、リンク、ハイライト、スタンプ

はじめに

PDF 注釈は、ページコンテンツの上に重ねられる幅広いインタラクティブかつ視覚的要素をカバーします：付箋テキストノート、ハイパーリンク、ハイライトまたは取り消し線付きテキスト、幾何学的形状、インクストローク、ファイル添付、承認スタンプ。Aspose.PDF FOSS for C++ は、これらすべてを Annotation の具体的なサブクラスとして表現します。そのため、ページの注釈を走査するコードはベースクラスに対して汎用的に動作しつつ、必要に応じてサブタイプ固有のメンバー—例えば TextAnnotation 上の Icon() や LinkAnnotation 上の Action()—にアクセスできます。

ライブラリの Annotations::AnnotationType 列挙型は、認識するサブタイプを列挙します：Text、Link、FreeText、Line、Square、Circle、Polygon、PolyLine、Highlight、Underline、Squiggly、StrikeOut、Stamp、Caret、Ink、Popup、FileAttachment、Sound、Movie、Widget、Screen、PrinterMark、Watermark、Redaction、RichMedia、およびその他多数。各値は具体的なクラスに対応します — CircleAnnotation、SquareAnnotation、PolygonAnnotation、PolylineAnnotation、LineAnnotation はシェイプマークアップ用；FreeTextAnnotation と InkAnnotation はフリーフォームテキストと描画ストローク用；FileAttachmentAnnotation、SoundAnnotation、MovieAnnotation、ScreenAnnotation、RichMediaAnnotation は埋め込みコンテンツ用；WidgetAnnotation は AcroForm フィールドの外観用です。

本稿では、Annotation と AnnotationCollection の基本 API を取り上げ、テキストノートとリンクの追加、既存ドキュメントを読み込む際の注釈タイプの検出、そしてマークアップメタデータやスタンプの読み取り・更新について解説します。Aspose.PDF FOSS for C++ は、標準ライブラリ以外にランタイム依存がない C++20 ライブラリです。ヘッダーは aspose/pdf/annotations/ ディレクトリから直接インクルードされ、ライブラリは CMake ターゲットとしてビルドされます。

同梱内容

注釈と AnnotationCollection

Annotation はすべての注釈サブタイプの基底クラスです。注釈のバウンディング矩形を示す Rect() / Rect(value)、関連テキストを示す Contents()、Name()、Color()、Flags()（AnnotationFlags ビットマスク — Print、Hidden、Invisible、NoZoom、ReadOnly など）、Border()、Width() / Height()、AnnotationType()、および PageIndex() といった共有プロパティを公開します。AnnotationCollection は単一ページ上の注釈を保持し、Page.Annotations() を通じてアクセスできます。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_collection.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("reviewed.pdf");
AnnotationCollection& annots = doc.Pages()[1].Annotations();

std::cout << "Annotation count: " << annots.Count() << "\n";
for (int i = 0; i < annots.Count(); ++i) {
    Annotation& a = annots[i];
    std::cout << "  " << a.Name() << ": " << a.Contents() << "\n";
}

AnnotationCollection は Add(annotation)、Add(annotation, considerRotation)、Delete(index)、Delete(annotation)、Clear()、Remove(annotation)、Contains(annotation)、および IsReadOnly() も提供します。

テキストノート（TextAnnotation）

TextAnnotation はおなじみの付箋コメントを表します。基本の Annotation メンバーに加えて、ノートが展開状態かどうかを制御する Open() / Open(value) と、アイコンの字形を選択するための Icon() / Icon(value)（TextIcon 値で、例えば Note、Comment、Key、Help、または Check）が追加されます。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("input.pdf");

TextAnnotation note{doc};
note.Rect(Rectangle{100.0, 700.0, 200.0, 720.0, false});
note.Contents("Reviewed by QA");
note.Icon(TextIcon::Comment);
note.Open(true);

doc.Pages()[1].Annotations().Add(note);
doc.Save("annotated.pdf");

リンクとアクション（LinkAnnotation）

LinkAnnotation はページにクリック可能な領域を付与します。所有する Page と Rectangle から構築され、その動作は Action(value) で設定されます — 任意の PdfAction サブクラスで、NamedAction（PredefinedAction::LastPage などの事前定義ナビゲーション）や GoToAction、GoToURIAction、JavascriptAction を含みます。Destination() はリンクの IAppointment ターゲットを読み取り、Highlighting() / Highlighting(value) はリンクが有効化されたときに適用される HighlightingMode（None、Invert、Outline、Push、Toggle）を設定します。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/link_annotation.hpp>
#include <aspose/pdf/annotations/named_action.hpp>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc;
Page page = doc.Pages().Add();

LinkAnnotation link{page, Rectangle{0.0, 0.0, 100.0, 20.0, false}};
link.Action(NamedAction{PredefinedAction::LastPage});
link.Highlighting(HighlightingMode::Push);

page.Annotations().Add(link);

ロード時のアノテーションタイプ検出

ドキュメントが開かれると、既存のアノテーションは各ページの AnnotationCollection にすでに配置されており、AnnotationType() は各エントリが表す具体的なサブタイプを識別します。これにより、呼び出し側コードは事前に PDF に含まれるアノテーションタイプを知らなくても、列挙値で分岐できるようになります。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/annotation_type.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

Document doc("mixed-annotations.pdf");
auto& annots = doc.Pages()[1].Annotations();

for (int i = 0; i < annots.Count(); ++i) {
    switch (annots[i].AnnotationType()) {
        case AnnotationType::Text:      std::cout << "Text note\n"; break;
        case AnnotationType::Link:      std::cout << "Link\n"; break;
        case AnnotationType::Circle:    std::cout << "Circle shape\n"; break;
        case AnnotationType::Square:    std::cout << "Square shape\n"; break;
        case AnnotationType::Highlight: std::cout << "Highlight\n"; break;
        case AnnotationType::Stamp:     std::cout << "Stamp\n"; break;
        default: break;
    }
}

マークアップアノテーションメタデータ

MarkupAnnotation は、レビュアーメタデータを保持するアノテーションの基盤です: Title()（作者）、Subject()、書式付きコメントテキスト用の RichText()、ページコンテンツにブレンドするための Opacity()。InReplyTo() と Popup() は、マークアップアノテーションを所属するコメントスレッドに接続し、ClearState() / SetReviewState(state, userName) はそのレビュー状態を管理します。HighlightAnnotation、UnderlineAnnotation、StrikeOutAnnotation、SquigglyAnnotation はテキスト上に配置されるマークアップサブタイプで、共通の TextMarkupAnnotation 基盤は、カバーされる四角形領域を定義する QuadPoints() と、下のテキストを読み取るための GetMarkedText() を追加します。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/markup_annotation.hpp>

using namespace Aspose::Pdf::Annotations;

for (int i = 0; i < annots.Count(); ++i) {
    if (auto* markup = dynamic_cast<MarkupAnnotation*>(&annots[i])) {
        markup->Title("QA Reviewer");
        markup->Subject("Layout issue");
        markup->Opacity(0.6);
    }
}

StampAnnotation を使用したスタンプアノテーション

StampAnnotation はページに定義済みまたはカスタムのスタンプを配置します。Icon() / Icon(value) は StampIcon 値を選択します — Approved、Draft、Confidential、Final、Expired、NotApproved、ForComment、TopSecret など — そして Image() / Image(value) は組み込みアイコンの代わりにカスタムスタンプ外観用の生画像バイトを提供します。

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/stamp_annotation.hpp>

using namespace Aspose::Pdf::Annotations;

for (int i = 0; i < annots.Count(); ++i) {
    if (auto* stamp = dynamic_cast<StampAnnotation*>(&annots[i])) {
        stamp->Icon(StampIcon::Approved);
    }
}

クイックスタート

ライブラリを CMake のサブディレクトリとして追加し、aspose_pdf_foss ターゲットにリンクします:

add_subdirectory(aspose.pdf-foss-for-cpp)
target_link_libraries(your_app PRIVATE aspose_pdf_foss)

ドキュメントを開き、テキストノートを追加し、アノテーション数を取得します:

#include <aspose/pdf/document.hpp>
#include <aspose/pdf/annotations/text_annotation.hpp>
#include <iostream>

using namespace Aspose::Pdf;
using namespace Aspose::Pdf::Annotations;

int main() {
    Document doc("input.pdf");

    TextAnnotation note{doc};
    note.Rect(Rectangle{100.0, 700.0, 200.0, 720.0, false});
    note.Contents("Reviewed by QA");
    note.Icon(TextIcon::Comment);

    doc.Pages()[1].Annotations().Add(note);
    doc.Save("annotated.pdf");

    std::cout << "Annotations on page 1: "
              << doc.Pages()[1].Annotations().Count() << "\n";
}

サポートされているフォーマット

フォーマットのサポートはページレンダリングおよびドキュメントレベルのロードオプションに適用されます。これらのエントリは、アノテーション固有のシリアライズではなく、確認済みのエクスポート (BmpDevice、JpegDevice、TiffDevice、TextDevice) およびインポート (SvgLoadOptions) パスを示しています。

オープンソース & ライセンス

Aspose.PDF FOSS for C++ は MIT ライセンスの下でリリースされています。ソースコードは https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-Cpp で入手可能で、ライセンス料なしで商用およびオープンソースプロジェクトで使用できます。

はじめに

• はじめに
• 開発者ガイド
• KB 記事
• API Reference

関連リソース

• Aspose.PDF — Enterprise Blog