PDAnnotationAdditionalActions

PDAnnotationAdditionalActionsは、Apache PDFBoxライブラリのクラスで、PDFアノテーションに関連付けられた追加アクション辞書を表します。このクラスは、ユーザーがアノテーションと特定の方法で対話する際に実行されるトリガーベースのアクションへのプログラマティックなアクセスを提供します。例えば、カーソルがアノテーション領域に入る、または出る場合や、アノテーションが入力フォーカスを受け取る、または失う場合などです。これらのアクショントリガーは、単純なアクティベーションアクションを超えたもので、PDF仕様 ( Citation: N.A., 2020 (N.A.). (2020). Document management — Portable document format — Part 2: PDF 2.0 .  International Organization for Standardization Retrieved from https://www.iso.org/standard/75839.html ) で定義されています。

PDAnnotationAdditionalActionsは、Apache PDFBoxの高レベルPDModel APIクラスで、アノテーションオブジェクトの追加アクション（AA）辞書をカプセル化します。PDF構造において、アノテーションは異なるユーザーインタラクションによってトリガーされる複数の関連アクションを持つことができます。標準的なアノテーションアクションはアノテーションがアクティブ化（通常はクリック）されたときに発生しますが、追加アクション辞書は他のインタラクションイベントの動作を定義します。これには、カーソル進入（E）、カーソル退出（X）、マウスボタンダウン（D）、マウスボタンアップ（U）、フォーカス受信（Fo）、フォーカス喪失（Bl）、ページ開く（PO）、ページ閉じる（PC）、ページ表示（PV）、ページ非表示（PI）が含まれます。

このクラスは、基本的なアノテーションアクション処理とは異なり、これらの特定のトリガーイベントに対してアクションを取得および設定するメソッドを提供します。これは、基盤となるPDF辞書構造のラッパーとして機能し、直接的な辞書操作を必要とする代わりに、型安全なJavaメソッドを提供します。

インタラクティブなPDFアプリケーションを構築する開発者にとって、PDAnnotationAdditionalActionsはPDFドキュメント内で洗練されたユーザーインターフェース動作を可能にします。この機能は、PDF/UA ( Citation: N.A., 2014 (N.A.). (2014). Document management applications — Electronic document file format enhancement for accessibility — Part 1: Use of ISO 32000-1 (PDF/UA-1) .  International Organization for Standardization Retrieved from https://www.iso.org/standard/64599.html ) などの標準に準拠したアクセシブルなドキュメントを作成する際に特に重要です。適切なアクション処理は、キーボードナビゲーションやスクリーンリーダーとのインタラクションを強化できるためです。このクラスを理解することで、開発者は以下のことが可能になります：

• ホバーイベント、フォーカス変更、ページ可視性に応答するアノテーションを使用した豊かなインタラクティブ体験の作成
• ユーザーがフォームフィールドやその他のアノテーション領域と対話する際のカスタム検証や前処理ロジックの実装
• 支援技術に適切なフィードバックを提供するアクセシブルなPDFフォームの構築
• アノテーションインタラクション中に予期しない動作を示す既存のPDFドキュメントのトラブルシューティングと修正

PDAnnotationAdditionalActionsは、PDF仕様で定義されたアクショントリガータイプに対応するgetterメソッドとsetterメソッドを提供することで機能します。PDAnnotationオブジェクトからgetActions()メソッドを使用してこのクラスのインスタンスを取得すると、カーソルとマウスイベント用のgetE()、getX()、getD()、getU()、およびフォーカス関連イベント用のgetFo()とgetBl()などのメソッドにアクセスできます。

各getterメソッドはPDActionオブジェクト（そのトリガーに対してアクションが定義されていない場合はnull）を返し、対応するsetterメソッドは新しい動作を定義するためにPDActionオブジェクトを受け取ります。返されるPDActionは、JavaScriptアクション、GoToアクション、URIアクションなど、PDFでサポートされる任意のアクションタイプにすることができます。PDFビューアがドキュメントを処理する際、これらのインタラクションイベントを監視し、対応するトリガーが発生したときに関連するアクションを実行します。

このクラスは内部的に、実際のPDFデータを格納するCOS（Carousel Object Structure）辞書を管理します。setterメソッドを呼び出すと、PDAnnotationAdditionalActionsはこの基盤となる辞書を変更し、getterメソッドを呼び出すと、辞書エントリを取得して適切なPDActionサブクラスのインスタンスにラップします。この抽象化により、開発者は低レベルの辞書操作から保護されながら、 ( Citation: N.A., 2020 (N.A.). (2020). Document management — Portable document format — Part 2: PDF 2.0 .  International Organization for Standardization Retrieved from https://www.iso.org/standard/75839.html ) で定義されたPDFの機能への完全なアクセスを維持できます。

• PDAnnotation – PDFBoxにおけるすべてのアノテーションタイプの基底クラスで、追加アクションをアタッチできます
• PDAction – PDFドキュメント内でトリガーできる任意のアクションを表す抽象基底クラス
• PDActionJavaScript – JavaScriptコードを実行するために追加アクションでよく使用される特定のアクションタイプ
• PDFormField – 検証や計算のために追加アクションを頻繁に使用するフォームフィールドアノテーション
• COSDictionary – PDAnnotationAdditionalActionsがラップして操作する低レベルの辞書構造