Widget (ウィジェット)¶

PDFのみ。

This class represents a PDF Form field "widget". Widgets technically are a special case of PDF annotations, which allow users with limited permissions to enter information in a PDF. This is primarily used for filling out forms.

アノテーションと同様に、ウィジェットも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.

クラス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¶

A mandatory string defining the field's name. If the name contains one or more colons "." the field is considered to be a child of a parent field. If the parent field does not exist, it will be created automatically. If the (full) name already exists anywhere in the PDF, the widget will become a new child of the existing field.

All widgets with the same name -- whether or not a colon is part of it and independent of their position in the document -- will share the same field value and field flags.

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 text (unicode) to be performed before the field is formatted to display its current value. This action can modify the field's value before formatting. None if not present.

script_change¶

バージョン1.16.12で新登場

JavaScript text (unicode) to be performed when the field's value is changed. This action can check the new value for validity. None if not present.

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 supports the creation and update of most widget types.

テキスト（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 now supports the creation and update of Radio Button Groups (RBGs). Adding a new radio button widget with the same (full) name as an existing one anywhere in the PDF will automatically create or extend an RBG.
signature (PDF_WIDGET_TYPE_SIGNATURE) read only -- no update or creation of signatures and no signing support.

The Relationship between Form Fields and Widgets¶

A form field is a logical object in the document's form field tree. It may have one or more widgets, which are the visual appearances of that field on one or more pages. A widget is therefore the page-bound representation of a form field.

The connection between a widget and its form field is established through the widget's /Parent entry, which references the form field. Conversely, the form field's /Kids array contains references to all widgets that visually represent that field.

Form fields themselves are not tied to any page; they exist solely in the document's AcroForm hierarchy. Widgets, however, are page annotations and are always associated with a specific page.

A single form field may be represented by multiple widgets. For example, a field may have one widget on page 1 and another on page 2 (or even multiple widgets on the same page). In this case, both widgets share the same form field as their parent. Changing the value of one widget automatically updates the value shown by all other widgets of that field.

Form Field Hierarchy¶

Form fields support hierarchical naming. A form field may have child fields, forming a logical structure. The hierarchy is defined by the /Parent entry of a child field, which references its parent field. The parent field's /Kids array contains references to all its child fields.

This hierarchy is reflected in the field's name. For example, a field named "Parent.Child" has a parent field "Parent" and a child field "Child". The parent may have additional children such as "Parent.Child2" or "Parent.Child3".

Automatic Hierarchy Creation via Dotted Names¶

Using dots (".") in a widget's field_name automatically creates or updates the corresponding form field hierarchy. For example:

Creating a widget named "Person.Name" creates or updates the form field "Person" and adds the widget as a child of "Person".
Creating a widget named "Person.Address" adds another child field under "Person".
Creating a widget named "Person.MaritalStatus" adds yet another child field.

In all cases, the widget becomes the visual representation of the terminal field in the hierarchy.

This mechanism allows complex information structures to be expressed naturally within a PDF form.

脚注

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.