class HexaPDF::Type::AcroForm::TextField
AcroForm
text fields provide a box or space to fill-in data entered from keyboard. The text may be restricted to a single line or can span multiple lines.
A special type of single-line text field is the comb text field. This type of field divides the existing space into /MaxLen equally spaced positions.
Type
Specific Field
Flags¶ ↑
- :multiline
-
If set, the text field may contain multiple lines.
- :password
-
The field is a password field. This changes the behaviour of the PDF reader application to not echo the input text and to not store it in the PDF file.
- :file_select
-
The text field represents a file selection control where the input text is the path to a file.
- :do_not_spell_check
-
The text should not be spell-checked.
- :do_not_scroll
-
The text field should not scroll (horizontally for single-line fields and vertically for multiline fields) to accomodate more text than fits into the annotation rectangle. This means that no more text can be entered once the field is full.
- :comb
-
The field is divided into /MaxLen equally spaced positions (so /MaxLen needs to be set). This is useful, for example, when entering things like social security numbers which always have the same length.
- :rich_text
-
The field is a rich text field.
See: PDF1.7 s12.7.4.3
Constants
- FLAGS_BIT_MAPPING
Updated list of field flags.
- INHERITABLE_FIELDS
All inheritable dictionary fields for text fields.
Public Instance Methods
Returns true
if this field is a comb text field.
# File lib/hexapdf/type/acro_form/text_field.rb, line 136 def comb_text_field? flagged?(:comb) && !(flagged?(:file_select) || flagged?(:multiline) || flagged?(:password)) end
Returns the concrete text field type, either :single_line_text_field, :multiline_text_field, :password_field, :file_select_field, :comb_text_field or :rich_text_field.
# File lib/hexapdf/type/acro_form/text_field.rb, line 189 def concrete_field_type if flagged?(:multiline) :multiline_text_field elsif flagged?(:password) :password_field elsif flagged?(:file_select) :file_select_field elsif flagged?(:comb) :comb_text_field elsif flagged?(:rich_text) :rich_text_field else :single_line_text_field end end
Creates appropriate appearances for all widgets.
For information on how this is done see AppearanceGenerator
.
Note that no new appearances are created if the field value hasn't changed between invocations.
By setting force
to true
the creation of the appearances can be forced.
# File lib/hexapdf/type/acro_form/text_field.rb, line 213 def create_appearances(force: false) current_value = field_value appearance_generator_class = document.config.constantize('acro_form.appearance_generator') each_widget do |widget| next if !force && widget.cached?(:last_value) && widget.cache(:last_value) == current_value widget.cache(:last_value, current_value, update: true) appearance_generator_class.new(widget).create_text_appearances end end
Returns the default field value.
See: field_value
# File lib/hexapdf/type/acro_form/text_field.rb, line 175 def default_field_value self[:DV].kind_of?(String) ? self[:DV] : self[:DV].stream end
Sets the default field value.
See: field_value=
# File lib/hexapdf/type/acro_form/text_field.rb, line 182 def default_field_value=(str) self[:DV] = str end
Returns the field value, i.e. the text contents of the field, or nil
if no value is set.
Note that modifying the returned value *might not* modify the text contents in case it is stored as stream! So always use field_value=
to set the field value.
# File lib/hexapdf/type/acro_form/text_field.rb, line 154 def field_value return unless value[:V] self[:V].kind_of?(String) ? self[:V] : self[:V].stream end
Sets the field value, i.e. the text contents of the field, to the given string.
Note that for single line text fields, all whitespace characters are changed to simple spaces.
# File lib/hexapdf/type/acro_form/text_field.rb, line 163 def field_value=(str) if flagged?(:password) raise HexaPDF::Error, "Storing a field value for a password field is not allowed" end str = str.gsub(/[[:space:]]/, ' ') if concrete_field_type == :single_line_text_field self[:V] = str update_widgets end
Returns true
if this field is a file select field.
# File lib/hexapdf/type/acro_form/text_field.rb, line 146 def file_select_field? flagged?(:file_select) && !(flagged?(:password) || flagged?(:multiline) || flagged?(:comb)) end
Initializes the text field to be a comb text field.
This method should only be called directly after creating a new text field because it doesn't completely reset the object.
# File lib/hexapdf/type/acro_form/text_field.rb, line 106 def initialize_as_comb_text_field flag(:comb) unflag(:file_select, :multiline, :password) end
Initializes the text field to be a file select field.
This method should only be called directly after creating a new text field because it doesn't completely reset the object.
# File lib/hexapdf/type/acro_form/text_field.rb, line 125 def initialize_as_file_select_field flag(:file_select) unflag(:comb, :multiline, :password) end
Initializes the text field to be a multiline text field.
This method should only be called directly after creating a new text field because it doesn't completely reset the object.
# File lib/hexapdf/type/acro_form/text_field.rb, line 97 def initialize_as_multiline_text_field flag(:multiline) unflag(:file_select, :comb, :password) end
Initializes the text field to be a password field.
This method should only be called directly after creating a new text field because it doesn't completely reset the object.
# File lib/hexapdf/type/acro_form/text_field.rb, line 115 def initialize_as_password_field delete(:V) flag(:password) unflag(:comb, :multiline, :file_select) end
Returns true
if this field is a multiline text field.
# File lib/hexapdf/type/acro_form/text_field.rb, line 131 def multiline_text_field? flagged?(:multiline) && !(flagged?(:file_select) || flagged?(:comb) || flagged?(:password)) end
Returns true
if this field is a password field.
# File lib/hexapdf/type/acro_form/text_field.rb, line 141 def password_field? flagged?(:password) && !(flagged?(:file_select) || flagged?(:multiline) || flagged?(:comb)) end
Updates the widgets so that they reflect the current field value.
# File lib/hexapdf/type/acro_form/text_field.rb, line 224 def update_widgets create_appearances end