Widget (ウィジェット)#

PDFのみ。

このクラスは、PDFフォームフィールド、または「ウィジェット」とも呼ばれるものを表します。このドキュメンテーション全体で、これらの用語を同義語として使用しています。フィールドは技術的にはPDF注釈の特殊なケースであり、制限付きの権限を持つユーザーがPDFに情報を入力することを可能にします。これは主にフォームの記入に使用されます。

アノテーションと同様に、ウィジェットもPDFページ上に存在します。注釈と同様に、ページ上の最初のウィジェットは Page.first_widget 経由でアクセスでき、その後のウィジェットは Widget.next プロパティ経由でアクセスできます。

Like annotations, widgets also lose connection to their page when the page becomes unavailable, please see here for details. This is relevant especially when updating the widget: this will fail if the original page object is no longer available.

（バージョン1.16.0で変更） MuPDFはウィジェットを一般的な注釈のサブセットとして扱わなくなりました。したがって、Page.first_annot および Annot.next() は非ウィジェット注釈のみを返し、ページにフォームフィールドのみが存在する場合はNoneを返します。逆に、Page.first_widget および Widget.next() はウィジェットのみを表示します。この設計の決定はMuPDF内部におけるものであり、技術的にはリンク、注釈、およびフィールドは多くの共通点を持ち、また（Py-）MuPDF内でコードの大部分を共有し続けています。

クラスAPI

class Widget#

button_states()#

バージョン1.18.15で新しく追加

ボタンフィールドが持つOn / Off（選択/クリックしたかどうか）状態の名前を返します。通常、 'Off'状態も同様に名前が付けられていますが、 'On'状態は機能的なコンテキストに関連する名前がよく付けられます。たとえば、「Yes」、「Female」などです。

このメソッドは、これらのケースで field_value の可能な値を調べるのに役立ちます。
戻り値：:
normal の状態と pressed-down 状態のボタンウィジェットの 'On'と 'Off'の名前を持つ辞書。次の例では、「選択された」値は「Male」であることが示されています：
>>> print(field.field_name, field.button_states())
Gender Second person {'down': ['Male', 'Off'], 'normal': ['Male', 'Off']}

on_state()#

新機能（バージョン1.22.2で追加）

チェックボックスとラジオボタンの「ON」状態の値を返します。チェックボックスの場合、これは常に「Yes」という値です。ラジオボタンの場合、これはボタンを選択/アクティブ化する値です。
戻り値：:
ボタンを「選択」に設定する値が返されます。非チェックボックス、非ラジオボタンフィールドの場合、常に None が返されます。チェックボックスの場合、戻り値は True です。ラジオボタンの場合、次の例では値が「Male」です。
>>> print(field.field_name, field.button_states())
Gender Second person {'down': ['Male', 'Off'], 'normal': ['Male', 'Off']}
>>> print(field.on_state())
Male
したがって、チェックボックスとラジオボタンの場合、それらを「選択」または状態を確認するための推奨される方法は次のとおりです。
>>> field.field_value = field.on_state()
>>> field.field_value == field.on_state()
True

update(sync_flags=False)#

After any changes to a widget, this method must be used to reflect changes in the PDF [1].

パラメータ:: sync_flags (bool) -- if True, the widget's Widget.field_flags are copied to the Parent object (if present) and all widgets named in its Kids array. This provides a convenient way to -- for example -- set all instances of the widget to read-only, no matter on which page they may occur [2].

reset()#: フィールドの値をデフォルト値にリセットします。デフォルトが定義されている場合、それを削除します。その後、update() を実行するのを忘れないでください。

next#: ページ上の次のフォームフィールドを指します。最後のウィジェットは None を返します。

border_color#: フィールドの境界線の色を定義する最大4つの浮動小数点数のリストです。デフォルト値は None で、これにより境界線スタイルと境界線の幅が無視されます。

border_style#: フィールドの境界線の線スタイルを定義する文字列です。Annot.border を参照してください。デフォルトは "s" ("Solid") で、連続線です。ウィジェットを作成する際、最初の文字（大文字または小文字）のみが考慮されます。

border_width#: 境界線の幅を定義する浮動小数点数です。デフォルトは1です。

border_dashes#: border_style == "D" であり、border_color が指定されている場合にのみ意味があります。これは、境界線のダッシュプロパティを定義する整数のリスト/タプルです。

choice_values#: リストボックスとコンボボックスの有効な選択肢を定義するPythonシーケンスの文字列です。これらのウィジェットタイプでは、このプロパティが必須で、少なくとも2つのアイテムを含める必要があります。他のタイプでは無視されます。

field_name#: フィールドの名前を定義する必須の文字列です。重複をチェックしません。

field_label#: 「代替」フィールド名を含むオプションの文字列です。通常、フィールドの使用方法に関するメモ、ヘルプなどに使用されます。デフォルトはフィールド名です。

field_value#: フィールドの値です。

field_flags#: フィールドの多くのプロパティを定義する整数です。この属性を変更する際は注意してください。これはフィールドのタイプを変更する可能性があります。

field_type#: フィールドタイプを定義する必須の整数です。これは0から6の範囲の値です。ウィジェットを更新する際に変更できません。

field_type_string#: フィールドタイプを説明する文字列（フィールドタイプから派生）。

fill_color#: フィールドの背景色を定義する、最大4つの浮動小数点数のリスト。

button_caption#: ボタンタイプのフィールドのキャプション文字列。

is_signed#: 署名フィールドの署名ステータスを示すブール値。それ以外の場合は None。

rect#: フィールドを含む矩形。

text_color#: テキストの色を定義する、1、3、または4つの浮動小数点数 のリスト。デフォルト値は黒 ([0, 0, 0])です。

text_font#: 使用するフォントを定義する文字列。デフォルトおよび無効な値の置換は 「Helv」 です。有効なフォント参照名については以下の表を参照してください。

text_fontsize#: テキストの fontsize を定義する浮動小数点数。デフォルト値はゼロで、PDFビューアソフトウェアが注釈の矩形とテキストの量に適したサイズを動的に選択します。

text_maxlen#: テキストの最大文字数を定義する整数。PDFビューアは（するはずです）より長いテキストを受け入れません。

text_type#: 許容可能なテキストタイプを定義する整数（例：数値、日付、時刻など）。現時点では参考用のみで、ウィジェットを作成または更新する際には無視されます。

xref#: ウィジェットのPDF xref。

script#

バージョン1.16.12で新登場

ウィジェットに関連付けられたアクション用のJavaScriptテキスト（Unicode）、または None。これは ボタンタイプ のウィジェットに対してサポートされる唯一のスクリプトアクションです。

script_stroke#

バージョン1.16.12で新登場

JavaScriptテキスト（Unicode）は、ユーザーがテキストフィールドまたはコンボボックスにキーストロークを入力するか、スクロール可能なリストボックスの選択を変更するときに実行されるアクションです。このアクションはキーストロークの妥当性をチェックし、拒否または変更することができます。存在しない場合は None です。

script_format#

バージョン1.16.12で新登場

このアクションは、フィールドが現在の値を表示するためにフォーマットされる前に、フィールドの値を変更するために実行されるJavaScriptテキスト（Unicode）です。存在しない場合は None です。

script_change#

バージョン1.16.12で新登場

このアクションは、フィールドの値が変更されたときに実行されるJavaScriptテキスト（Unicode）です。このアクションは新しい値の妥当性をチェックすることができます。存在しない場合は None です。

script_calc#

バージョン1.16.12で新登場

バージョン1.16.12で新規追

script_blur#

バージョン1.22.6で新規追加

このフィールドからフォーカスを失ったときに実行されるJavaScriptテキスト（Unicode）です。存在しない場合は None です。

script_focus#

バージョン1.22.6で新規追加

このフィールドにフォーカスが当たったときに実行されるJavaScriptテキスト（Unicode）です。存在しない場合は None です。

注釈

上記のいずれかのスクリプトを追加または変更するには、

適切なJavaScriptソースコードをウィジェット属性に配置するだけです。スクリプトを 削除する には、該当する属性を None に設定します。

ボタンフィールドは script をサポートしています

他のスクリプトエントリは自動的に None に設定されます。

Adobeの標準スクリプトに関する多くの情報が含まれているこのマニュアルを確認する価値があります。たとえば、日付を表すテキストフィールドを追加する場合、次のスクリプトを保存することができます。これにより、パターン互換の日付形式が確保され、サポートされているビューアで日付ピッカーが表示されます。
```
widget.script_format = 'AFDate_FormatEx("mm/dd/yyyy");'
widget.script_stroke = 'AFDate_KeystrokeEx("mm/dd/yyyy");'
```

ウィジェット用の標準フォント#

Widgets use their own resources object /DR. A widget resources object must at least contain a /Font object. Widget fonts are independent from page fonts. We currently support the 14 PDF base fonts using the following fixed reference names, or any name of an already existing field font. When specifying a text font for new or changed widgets, either choose one in the first table column (upper and lower case supported), or one of the already existing form fonts. In the latter case, spelling must exactly match.

既存のフィールドフォントを見つけるには、リスト Document.FormFonts を調べてください。

参照	Base14フォント名
CoBI	Courier-BoldOblique
CoBo	Courier-Bold
CoIt	Courier-Oblique
Cour	Courier
HeBI	Helvetica-BoldOblique
HeBo	Helvetica-Bold
HeIt	Helvetica-Oblique
Helv	Helvetica (デフォルト)
Symb	Symbol
TiBI	Times-BoldItalic
TiBo	Times-Bold
TiIt	Times-Italic
TiRo	Times-Roman
ZaDb	ZapfDingbats

You are generally free to use any font for every widget. However, we recommend using ZaDb ("ZapfDingbats") and fontsize 0 for check boxes: typical viewers will put a correctly sized tickmark in the field's rectangle, when it is clicked.

対応ウィジェットの種類#

PyMuPDFは、多くのウィジェットタイプの作成および更新をサポートしていますが、すべてのウィジェットタイプには対応していません。

テキスト（PDF_WIDGET_TYPE_TEXT）
プッシュボタン（PDF_WIDGET_TYPE_BUTTON）
チェックボックス（PDF_WIDGET_TYPE_CHECKBOX）
コンボボックス（PDF_WIDGET_TYPE_COMBOBOX）
リストボックス（PDF_WIDGET_TYPE_LISTBOX）
radio button (PDF_WIDGET_TYPE_RADIOBUTTON): PyMuPDF does not currently support the creation of groups of (interconnected) radio buttons, where setting one button automatically unsets the other buttons in the group. The widget object also does not reflect the presence of a button group. However: consistently selecting (or unselecting) a radio button is supported. This includes correctly setting the value maintained in the owning button group. Selecting a radio button may be done by either assigning True or field.on_state() to the field value. De-selecting the button should be done assigning False.
signature (PDF_WIDGET_TYPE_SIGNATURE) read only -- no update or creation of signatures.

脚注

This software is provided AS-IS with no warranty, either express or implied. This software is distributed under license and may not be copied, modified or distributed except as expressly authorized under the terms of that license. Refer to licensing information at artifex.com or contact Artifex Software Inc., 39 Mesa Street, Suite 108A, San Francisco CA 94129, United States for further information.