class HexaPDF::Type::AcroForm::AppearanceGenerator


The AppearanceGenerator class provides methods for generating and updating the appearance streams of form fields.

The only method needed is create_appearances since this method determines to what field the widget belongs and therefore which appearance should be generated.

The visual appearance of a field is constructed using information from the field itself as well as information from the widget. See the documentation for the individual methods which information is used in which way.

By default, any existing appearances are overwritten and the :print flag is set on the widget so that the field appearance will appear on print-outs.

The visual appearances are chosen to be similar to those used by Adobe Acrobat and others. By subclassing and overriding the necessary methods it is possible to define custom appearances.

See: PDF2.0 s12.5.5, s12.7

Public Class Methods


Creates a new instance for the given widget.

Public Instance Methods


Creates the appropriate appearances for the widget.


Creates the appropriate appearances for check boxes and radio buttons.

The unchecked box or unselected radio button is always represented by the appearance with the key /Off. If there is more than one other key besides the /Off key, the first one is used for the appearance of the checked box or selected radio button.

For unchecked boxes an empty rectangle is drawn. Similarly, for unselected radio buttons an empty circle (if the marker is :circle) or rectangle is drawn. When checked or selected, a symbol from the ZapfDingbats font is placed inside. How this is exactly done depends on the following values:


# check box: default appearance
widget.border_style(color: 0)
widget.marker_style(style: :check, size: 0, color: 0)

# check box: no visible rectangle, gray background, cross mark when checked
widget.border_style(color: :transparent, width: 2)
widget.marker_style(style: :cross)

# radio button: default appearance
widget.border_style(color: 0)
widget.marker_style(style: :circle, size: 0, color: 0)
Also aliased as: create_radio_button_appearances

Creates the appropriate appearances for push buttons.

This is currently a dummy implementation raising an error.


Creates the appropriate appearances for text fields, combo box fields and list box fields.

The following describes how the appearance is built:

  • The font, font size and font color are taken from the associated field’s default appearance string. See VariableTextField.

    If the font is not usable by HexaPDF (which may be due to a variety of reasons, e.g. no associated information in the form’s default resources), the font specified by the configuration option acro_form.fallback_font will be used.

  • The widget’s rectangle /Rect must be defined. If the height is zero, it is auto-sized based on the font size. If additionally the font size is zero, a font size of acro_form.default_font_size is used. If the width is zero, the acro_form.text_field.default_width value is used. In such cases the rectangle is appropriately updated.

  • The line width, style and color of the rectangle are taken from the widget’s border style. See HexaPDF::Type::Annotations::Widget#border_style.

  • The background color is determined by the widget’s background color. See HexaPDF::Type::Annotations::Widget#background_color.

Note: Rich text fields are currently not supported!

Also aliased as: create_combo_box_appearances, create_list_box_appearances