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" and border_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.

button_caption

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.