class HexaPDF::Type::AcroForm::AppearanceGenerator

Parent

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: PDF1.7 s12.5.5, s12.7

Public Class Methods

new(widget)

Creates a new instance for the given widget.

Public Instance Methods

create_appearances()

Creates the appropriate appearances for the widget.

create_check_box_appearances()

Creates the appropriate appearances for check boxes.

For unchecked boxes an empty rectangle is drawn. When checked, a symbol from the ZapfDingbats font is placed inside the rectangle. How this is exactly done depends on the following values:

Examples:

widget.border_style(color: 0)
widget.background_color(1)
widget.marker_style(style: :check, size: 0, color: 0)
# => default appearance

widget.border_style(color: :transparent, width: 2)
widget.background_color(0.7)
widget.marker_style(style: :cross)
# => no visible rectangle, gray background, cross mark when checked
create_combo_box_appearances()
create_radio_button_appearances()

Creates the appropriate appearances for radio buttons.

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

Examples:

widget.border_style(color: 0)
widget.background_color(1)
widget.marker_style(style: :circle, size: 0, color: 0)
# => default appearance
create_text_appearances()

Creates the appropriate appearances for text 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: Multiline, comb and rich text fields are currently not supported!

Also aliased as: create_combo_box_appearances