hexapdf 0.13.0 → 0.14.0

data/lib/hexapdf/type/acro_form/button_field.rb

@@ -228,10 +228,12 @@ module HexaPDF
         #
         # The created appearance streams depend on the actual type of the button field. See
         # AppearanceGenerator for the details.
-        def create_appearances
+        #
+        # By setting +force+ to +true+ the creation of the appearances can be forced.
+        def create_appearances(force: false)
           appearance_generator_class = document.config.constantize('acro_form.appearance_generator')
           each_widget do |widget|
-            next if widget.appearance?
+            next if !force && widget.appearance?
             if check_box?
               appearance_generator_class.new(widget).create_check_box_appearances
             elsif radio_button?
@@ -245,6 +247,7 @@ module HexaPDF
         # Updates the widgets so that they reflect the current field value.
         def update_widgets
           return if push_button?
+          create_appearances
           value = self[:V]
           each_widget do |widget|
             widget[:AS] = (widget.appearance&.normal_appearance&.value&.key?(value) ? value : :Off)

data/lib/hexapdf/type/acro_form/choice_field.rb

@@ -122,17 +122,24 @@ module HexaPDF
         end
 
         # Sets the field value to the given string or array of strings.
+        #
+        # The dictionary field /I is also modified to correctly represent the selected item(s).
         def field_value=(value)
           items = option_items
-          all_included = [value].flatten.all? {|v| items.include?(v) }
+          array_value = [value].flatten
+          all_included = array_value.all? {|v| items.include?(v) }
           self[:V] = if (combo_box? && value.kind_of?(String) &&
-                          (flagged?(:edit) || all_included)) ||
-                         (list_box? && all_included &&
-                          (value.kind_of?(String) || flagged?(:multi_select)))
+                         (flagged?(:edit) || all_included))
+                       delete(:I)
                        value
+                     elsif list_box? && all_included &&
+                         (value.kind_of?(String) || flagged?(:multi_select))
+                       self[:I] = array_value.map {|val| items.index(val) }.sort!
+                       array_value.length == 1 ? value : array_value
                      else
                        @document.config['acro_form.on_invalid_value'].call(self, value)
                      end
+          update_widgets
         end
 
         # Returns the default field value.
@@ -155,13 +162,47 @@ module HexaPDF
         end
 
         # Returns the array with the available option items.
+        #
+        # Note that this *only* returns the option items themselves! For getting the export values,
+        # the #export_values method has to be used.
         def option_items
-          key?(:Opt) ? process_value(self[:Opt]) : self[:Opt] ||= []
+          key?(:Opt) ? process_value(self[:Opt].map {|i| i.kind_of?(Array) ? i[1] : i }) : []
+        end
+
+        # Returns the export values of the option items.
+        #
+        # If you need the display strings (as in most cases), use the #option_items method.
+        def export_values
+          key?(:Opt) ? process_value(self[:Opt].map {|i| i.kind_of?(Array) ? i[0] : i }) : []
         end
 
         # Sets the array with the available option items to the given value.
+        #
+        # Each entry in the array may either be a string representing the text to be displayed. Or
+        # an array of two strings where the first describes the export value (to be used when
+        # exporting form field data from the document) and the second is the display value.
+        #
+        # See: #option_items, #export_values
         def option_items=(value)
-          self[:Opt] = value
+          self[:Opt] = if flagged?(:sort)
+                         value.sort_by {|i| process_value(i.kind_of?(Array) ? i[1] : i) }
+                       else
+                         value
+                       end
+        end
+
+        # Returns the index of the first visible option item of a list box.
+        def list_box_top_index
+          self[:TI]
+        end
+
+        # Makes the option item referred to via the given +index+ the first visible option item of a
+        # list box.
+        def list_box_top_index=(index)
+          if index < 0 || !key?(:Opt) || index >= self[:Opt].length
+            raise ArgumentError, "Index out of range for the set option items"
+          end
+          self[:TI] = index
         end
 
         # Returns the concrete choice field type, either :list_box, :combo_box or
@@ -178,19 +219,32 @@ module HexaPDF
         #
         # For information on how this is done see AppearanceGenerator.
         #
-        # Note that an appearance for a choice field widget is *always* created even if there is an
-        # existing one to make sure the current field value is properly represented.
-        def create_appearances
+        # Note that no new appearances are created if the dictionary fields involved in the creation
+        # of the appearance stream have not been changed between invocations.
+        #
+        # By setting +force+ to +true+ the creation of the appearances can be forced.
+        def create_appearances(force: false)
+          current_appearance_state = [self[:V], self[:I], self[:Opt], self[:TI]]
+
           appearance_generator_class = document.config.constantize('acro_form.appearance_generator')
           each_widget do |widget|
+            next if !force && widget.cached?(:appearance_state) &&
+              widget.cache(:appearance_state) == current_appearance_state
+
+            widget.cache(:appearance_state, current_appearance_state, update: true)
             if combo_box?
               appearance_generator_class.new(widget).create_combo_box_appearances
             else
-              raise HexaPDF::Error, "List boxes not yet supported"
+              appearance_generator_class.new(widget).create_list_box_appearances
             end
           end
         end
 
+        # Updates the widgets so that they reflect the current field value.
+        def update_widgets
+          create_appearances
+        end
+
         private
 
         # Uses the HexaPDF::DictionaryFields::StringConverter to process the value (a string or an

data/lib/hexapdf/type/acro_form/form.rb

@@ -153,8 +153,83 @@ module HexaPDF
         #
         # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
         # fields must already exist. If it doesn't contain dots, a top-level field is created.
-        def create_text_field(name)
-          create_field(name, :Tx)
+        #
+        # The optional keyword arguments allow setting often used properties of the field:
+        #
+        # +font+::
+        #     The font that should be used for the text of the field. If +font_size+ is specified
+        #     but +font+ isn't, the font Helvetica is used.
+        #
+        # +font_size+::
+        #     The font size that should be used. If +font+ is specified but +font_size+ isn't, font
+        #     size defaults to 0 (= auto-sizing).
+        #
+        # +align+::
+        #     The alignment of the text, either :left, :center or :right.
+        def create_text_field(name, font: nil, font_size: nil, align: nil)
+          create_field(name, :Tx) do |field|
+            apply_variable_text_properties(field, font: font, font_size: font_size, align: align)
+          end
+        end
+
+        # Creates a new multiline text field with the given name and adds it to the form.
+        #
+        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
+        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        #
+        # The optional keyword arguments allow setting often used properties of the field, see
+        # #create_text_field for details.
+        def create_multiline_text_field(name, font: nil, font_size: nil, align: nil)
+          create_field(name, :Tx) do |field|
+            field.initialize_as_multiline_text_field
+            apply_variable_text_properties(field, font: font, font_size: font_size, align: align)
+          end
+        end
+
+        # Creates a new comb text field with the given name and adds it to the form.
+        #
+        # The +max_chars+ argument defines the maximum number of characters the comb text field can
+        # accommodate.
+        #
+        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
+        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        #
+        # The optional keyword arguments allow setting often used properties of the field, see
+        # #create_text_field for details.
+        def create_comb_text_field(name, max_chars:, font: nil, font_size: nil, align: nil)
+          create_field(name, :Tx) do |field|
+            field.initialize_as_comb_text_field
+            apply_variable_text_properties(field, font: font, font_size: font_size, align: align)
+            field[:MaxLen] = max_chars
+          end
+        end
+
+        # Creates a new file select field with the given name and adds it to the form.
+        #
+        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
+        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        #
+        # The optional keyword arguments allow setting often used properties of the field, see
+        # #create_text_field for details.
+        def create_file_select_field(name, font: nil, font_size: nil, align: nil)
+          create_field(name, :Tx) do |field|
+            field.initialize_as_file_select_field
+            apply_variable_text_properties(field, font: font, font_size: font_size, align: align)
+          end
+        end
+
+        # Creates a new password field with the given name and adds it to the form.
+        #
+        # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
+        # fields must already exist. If it doesn't contain dots, a top-level field is created.
+        #
+        # The optional keyword arguments allow setting often used properties of the field, see
+        # #create_text_field for details.
+        def create_password_field(name, font: nil, font_size: nil, align: nil)
+          create_field(name, :Tx) do |field|
+            field.initialize_as_password_field
+            apply_variable_text_properties(field, font: font, font_size: font_size, align: align)
+          end
         end
 
         # Creates a new check box with the given name and adds it to the form.
@@ -162,7 +237,7 @@ module HexaPDF
         # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
         # fields must already exist. If it doesn't contain dots, a top-level field is created.
         def create_check_box(name)
-          create_field(name, :Btn).tap(&:initialize_as_check_box)
+          create_field(name, :Btn, &:initialize_as_check_box)
         end
 
         # Creates a radio button with the given name and adds it to the form.
@@ -170,23 +245,58 @@ module HexaPDF
         # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
         # fields must already exist. If it doesn't contain dots, a top-level field is created.
         def create_radio_button(name)
-          create_field(name, :Btn).tap(&:initialize_as_radio_button)
+          create_field(name, :Btn, &:initialize_as_radio_button)
         end
 
         # Creates a combo box with the given name and adds it to the form.
         #
         # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
         # fields must already exist. If it doesn't contain dots, a top-level field is created.
-        def create_combo_box(name)
-          create_field(name, :Ch).tap(&:initialize_as_combo_box)
+        #
+        # The optional keyword arguments allow setting often used properties of the field:
+        #
+        # +option_items+::
+        #     Specifies the values of the list box.
+        #
+        # +editable+::
+        #     If set to +true+, the combo box allows entering an arbitrary value in addition to
+        #     selecting one of the provided option items.
+        #
+        # +font+, +font_size+ and +align+::
+        #     See #create_text_field
+        def create_combo_box(name, option_items: nil, editable: nil, font: nil, font_size: nil,
+                             align: nil)
+          create_field(name, :Ch) do |field|
+            field.initialize_as_combo_box
+            field.option_items = option_items if option_items
+            field.flag(:edit) if editable
+            apply_variable_text_properties(field, font: font, font_size: font_size, align: align)
+          end
         end
 
         # Creates a list box with the given name and adds it to the form.
         #
         # The +name+ may contain dots to signify a field hierarchy. If so, the referenced parent
         # fields must already exist. If it doesn't contain dots, a top-level field is created.
-        def create_list_box(name)
-          create_field(name, :Ch).tap(&:initialize_as_list_box)
+        #
+        # The optional keyword arguments allow setting often used properties of the field:
+        #
+        # +option_items+::
+        #     Specifies the values of the list box.
+        #
+        # +multi_select+::
+        #     If set to +true+, the list box allows selecting multiple items instead of only one.
+        #
+        # +font+, +font_size+ and +align+::
+        #     See #create_text_field.
+        def create_list_box(name, option_items: nil, multi_select: nil, font: nil, font_size: nil,
+                            align: nil)
+          create_field(name, :Ch) do |field|
+            field.initialize_as_list_box
+            field.option_items = option_items if option_items
+            field.flag(:multi_select) if multi_select
+            apply_variable_text_properties(field, font: font, font_size: font_size, align: align)
+          end
         end
 
         # Returns the dictionary containing the default resources for form field appearance streams.
@@ -213,9 +323,11 @@ module HexaPDF
         end
 
         # Creates the appearances for all widgets of all terminal fields if they don't exist.
-        def create_appearances
+        #
+        # If +force+ is +true+, new appearances are created even if there are existing ones.
+        def create_appearances(force: false)
           each_field do |field|
-            field.create_appearances if field.respond_to?(:create_appearances)
+            field.create_appearances(force: force) if field.respond_to?(:create_appearances)
           end
         end
 
@@ -246,9 +358,20 @@ module HexaPDF
           else
             (self[:Fields] ||= []) << field
           end
+
+          yield(field)
+
           field
         end
 
+        # Applies the given variable field properties to the field.
+        def apply_variable_text_properties(field, font: nil, font_size: nil, align: nil)
+          if font || font_size
+            field.set_default_appearance_string(font: font || 'Helvetica', font_size: font_size || 0)
+          end
+          field.text_alignment(align) if align
+        end
+
         def perform_validation # :nodoc:
           super
 

data/lib/hexapdf/type/acro_form/text_field.rb

@@ -44,6 +44,9 @@ module HexaPDF
       # 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.
@@ -88,6 +91,63 @@ module HexaPDF
           }
         ).freeze
 
+        # 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.
+        def initialize_as_multiline_text_field
+          flag(:multiline)
+          unflag(:file_select, :comb, :password)
+        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.
+        def initialize_as_comb_text_field
+          flag(:comb)
+          unflag(:file_select, :multiline, :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.
+        def initialize_as_password_field
+          delete(:V)
+          flag(:password)
+          unflag(:comb, :multiline, :file_select)
+        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.
+        def initialize_as_file_select_field
+          flag(:file_select)
+          unflag(:comb, :multiline, :password)
+        end
+
+        # Returns +true+ if this field is a multiline text field.
+        def multiline_text_field?
+          flagged?(:multiline) && !(flagged?(:file_select) || flagged?(:comb) || flagged?(:password))
+        end
+
+        # Returns +true+ if this field is a comb text field.
+        def comb_text_field?
+          flagged?(:comb) && !(flagged?(:file_select) || flagged?(:multiline) || flagged?(:password))
+        end
+
+        # Returns +true+ if this field is a password field.
+        def password_field?
+          flagged?(:password) && !(flagged?(:file_select) || flagged?(:multiline) || flagged?(:comb))
+        end
+
+        # Returns +true+ if this field is a file select field.
+        def file_select_field?
+          flagged?(:file_select) && !(flagged?(:password) || flagged?(:multiline) || flagged?(:comb))
+        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
@@ -147,11 +207,16 @@ module HexaPDF
         #
         # For information on how this is done see AppearanceGenerator.
         #
-        # Note that an appearance for a text field widget is *always* created even if there is an
-        # existing one to make sure the current field value is properly represented.
-        def create_appearances
+        # 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.
+        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

data/lib/hexapdf/type/cid_font.rb

@@ -95,7 +95,7 @@ module HexaPDF
       #
       # See: PDF1.7 s9.7.4.3
       def widths
-        document.cache(@data, :widths) do
+        cache(:widths) do
           result = {}
           index = 0
           array = self[:W] || []

data/lib/hexapdf/type/font.rb

@@ -102,7 +102,7 @@ module HexaPDF
 
       # Parses and caches the ToUnicode CMap.
       def to_unicode_cmap
-        document.cache(@data, :to_unicode_cmap) do
+        cache(:to_unicode_cmap) do
           if key?(:ToUnicode)
             HexaPDF::Font::CMap.parse(self[:ToUnicode].stream)
           else

data/lib/hexapdf/type/font_simple.rb

@@ -57,7 +57,7 @@ module HexaPDF
       #
       # Note that the encoding is cached internally when accessed the first time.
       def encoding
-        document.cache(@data, :encoding) do
+        cache(:encoding) do
           case (val = self[:Encoding])
           when Symbol
             encoding = HexaPDF::Font::Encoding.for_name(val)