Widget (ウィジェット)#
PDFのみ。
このクラスは、PDFフォームフィールド、または「ウィジェット」とも呼ばれるものを表します。このドキュメンテーション全体で、これらの用語を同義語として使用しています。フィールドは技術的にはPDF注釈の特殊なケースであり、制限付きの権限を持つユーザーがPDFに情報を入力することを可能にします。これは主にフォームの記入に使用されます。
アノテーションと同様に、ウィジェットもPDFページ上に存在します。注釈と同様に、ページ上の最初のウィジェットは Page.first_widget 経由でアクセスでき、その後のウィジェットは Widget.next プロパティ経由でアクセスできます。
（バージョン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
- 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_maxlen#
テキストの最大文字数を定義する整数。PDFビューアは（するはずです）より長いテキストを受け入れません。
- text_type#
許容可能なテキストタイプを定義する整数（例：数値、日付、時刻など）。現時点では参考用のみで、ウィジェットを作成または更新する際には無視されます。
- 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");'
ウィジェット用の標準フォント#
ウィジェットは独自のリソースオブジェクト /DR を使用します。ウィジェットのリソースオブジェクトには、少なくとも /Font オブジェクトを含める必要があります。ウィジェットフォントはページフォントとは独立しています。現在、以下の固定参照名を使用して、14のPDFベースフォントをサポートしています。また、既存のフィールドフォントの名前でもかまいません。新しいウィジェットまたは変更されたウィジェットのテキストフォントを指定する際には、最初の表の列（大文字と小文字がサポートされています）から1つを選択するか、既存のフォームフォントの1つを選択してください。後者の場合、スペルは厳密に一致する必要があります。
既存のフィールドフォントを見つけるには、リスト 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 |
一般的に、すべてのウィジェットに任意のフォントを使用することができます。ただし、チェックボックスには ZaDb （「ZapfDingbats」）フォントと fontsize 0を使用することをお勧めします。典型的なビューアは、フィールドの四角形をクリックすると正しくサイズ調整されたチェックマークを配置します。
対応ウィジェットの種類#
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 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 assigningTrueorfield.on_state()to the field value. De-selecting the button should be done assigningFalse.署名（
PDF_WIDGET_TYPE_SIGNATURE）は 読み取り専用です 。
脚注
