class HexaPDF:: Type:: AcroForm:: ButtonField
Parent | Field |
---|
AcroForm
button fields represent interactive controls to be used with the mouse.
They are divided into push buttons (things to click on), check boxes and radio buttons. All of these are represented with this class.
To create a push button, check box or radio button field, use the appropriate convenience methods on the main Form
instance (HexaPDF::Document#acro_form
). By using those methods, everything needed is automatically set up.
Radio buttons are widgets of a single radio button field. This is also called a radio button group. Of the radio button group only one radio button (= widget of the radio button field) may be selected at all times. Each widget must have a different value to be distinguishable; otherwise the widgets with the same value represent the same thing. Although there is the no_toggle_to_off
field flag, no PDF viewer implements that; one needs to use check boxes for this feature.
Check boxes can be toggled on and off. One check box field may have multiple widgets. If those widgets have the same value, they will all be toggled on or off simultaneously. Otherwise only one of those widgets will be toggled on while the others are off. In such a case the check box fields acts like a radio button group, with the additional feature that no check box may be selected.
Type
Specific Field
Flags¶ ↑
See the class description for Field
for the general field flags.
- :no_toggle_to_off
-
Only used with radio buttons fields. If this flag is set, one button needs to be selected at all times. Otherwise, clicking on the selected button deselects it.
Note: This deselectiong is not implemented in any tested PDF viewer. A work-around is to use multiple check box widgets with different on names.
- :radio
-
If this flag is set, the field is a set of radio buttons. Otherwise it is a check box. Additionally, the :pushbutton flag needs to be clear.
- :push_button
-
The field represents a pushbutton without a permanent value.
- :radios_in_unison
-
A group of radio buttons with the same value for the on state will turn on or off in unison.
See: PDF2.0 s12.7.4.2
Constants
Public Instance Methods
Returns the array of Symbol values (minus the /Off value) that can be used for the field value for check boxes or radio buttons.
Note that this will only return useful values if there is at least one correctly set-up widget.
Returns true
if this button field represents a check box.
Returns the concrete button field type, either :push_button, :check_box or :radio_button.
Creates appropriate appearances for all widgets if they don’t already exist.
The created appearance streams depend on the actual type of the button field. See AppearanceGenerator
for the details.
By setting force
to true
the creation of the appearances can be forced.
Creates a widget for the button field.
If defaults
is true
, then default values will be set on the widget so that it uses a default appearance.
If the widget is created for a radio button field, the value
argument needs to set to the value (a Symbol or an object responding to #to_sym
) this widget represents. It can be used with field_value=
to set this specific widget of the radio button set to on.
The value
is optional for check box fields; if not specified, the default of :Yes will be used.
See: Field#create_widget
, AppearanceGenerator
button field methods
Returns the default field value.
See: field_value
Sets the default field value.
See: field_value=
Returns the field value which depends on the concrete type.
- Push buttons
-
They don’t have a value, so
nil
is always returned. - Check boxes
-
For check boxes that are checked the value of the specific check box that is checked is returned. Otherwise
nil
is returned. - Radio buttons
-
If no radio button is selected,
nil
is returned. Otherwise the value (a Symbol) of the specific radio button that is selected is returned.
Sets the field value which depends on the concrete type.
- Push buttons
-
Since push buttons don’t store any value, the given value is ignored and nothing is stored for them (e.g a no-op).
- Check boxes
-
Provide
nil
orfalse
as value to toggle all check box widgets off. Iftrue
is provided, all check box widgets with the same name as the first one are toggled on. Otherwise provide the value (a Symbol or an object responding to#to_sym
) of the check box widget that should be toggled on. - Radio buttons
-
To turn all radio buttons off, provide
nil
as value. Otherwise provide the value (a Symbol or an object responding to#to_sym
) of a radio button that should be turned on.
Note that in most cases the field needs to already have widgets because the value is checked against the possibly allowed values which depend on the existing widgets.
Initializes the button field to be a check box.
This method should only be called directly after creating a new button field because it doesn’t completely reset the object.
Updates the widgets so that they reflect the current field value.