Widget¶
This class represents the properties of a PDF Form field, a “widget”. Fields are a special case of annotations, which allow users with limited permissions to enter information in a PDF. This is usually used for filling out forms.
Class API
-
class
Widget
¶ -
border_color
¶ A list of up to 4 floats defining the field’s border. Default value is
None
which causes border style and border width to be ignored.
-
border_style
¶ A string defining the line style of the field’s border. See
Annot.border
. Default is “s” (“Solid”) – a continuous line. Only the first character (upper or lower case) will be regarded when creating a widget.
-
border_width
¶ A float defining the width of the border line. Default is 1.
-
border_dashes
¶ A list of integers defining the dash properties of the border line. This is only meaningful if
border_style == "D"
andborder_color
is provided.
-
choice_values
¶ A mandatory Python sequence of strings defining the valid choices of listboxes and comboboxes. Ignored for other field types. Equals
Annot.widget_choices
. The sequence must contain at least two items. When updating the widget, always the complete new list of values must be specified.
-
field_name
¶ A mandatory string defining the field’s name. Equals
Annot.widget_name
. No checking for duplicates takes place.
-
field_value
¶ The value of the field. Equals
Annot.widget_value
.
-
field_flags
¶ An integer defining a large amount of proprties of a field. Handle this attribute with care
-
field_type
¶ A mandatory integer defining the field type. This is a value in the range of 0 to 6. It cannot be changed when updating the widget.
-
field_type_string
¶ A string describing (and derived from) the field type.
-
fill_color
¶ A list of up to 4 floats defining the field’s background color.
For future use: the caption string of a button-type field.
-
rect
¶ The rectangle containing the field.
-
text_color
¶ A list of 1, 3 or 4 floats defining the text color. Default value is black ([0, 0, 0]).
-
text_font
¶ A string defining the font to be used. Default and replacement for invalid values is
"Helv"
. For valid font reference names see the table below.
-
text_fontsize
¶ A float defining the text fontsize. Default value is zero, which causes PDF viewer software to dynamically choose a size suitable for the annotation’s rectangle and text amount.
-
text_maxlen
¶ An integer defining the maximum number of text characters. PDF viewers will (should) not accept larger text amounts.
-
text_type
¶ An integer defining acceptable text types (e.g. numeric, date, time, etc.). For reference only for the time being – will be ignored when creating or updating widgets.
-
Standard Fonts for Widgets¶
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.
To find out already existing field fonts, inspect the list Document.FormFonts
.
Reference |
Base14 Fontname |
---|---|
CoBI |
Courier-BoldOblique |
CoBo |
Courier-Bold |
CoIt |
Courier-Oblique |
Cour |
Courier |
HeBI |
Helvetica-BoldOblique |
HeBo |
Helvetica-Bold |
HeIt |
Helvetica-Oblique |
Helv |
Helvetica (default) |
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.