hexapdf 0.12.1 → 0.14.1

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.
@@ -148,20 +155,54 @@ module HexaPDF
         def default_field_value=(value)
           items = option_items
           self[:DV] = if [value].flatten.all? {|v| items.include?(v) }
-                       value
-                     else
-                       @document.config['acro_form.on_invalid_value'].call(self, value)
-                     end
+                        value
+                      else
+                        @document.config['acro_form.on_invalid_value'].call(self, value)
+                      end
         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/field.rb

@@ -236,6 +236,11 @@ module HexaPDF
           kids.nil? || kids.empty? || kids.none? {|kid| kid.key?(:T) }
         end
 
+        # Returns +true+ if the field contains an embedded widget.
+        def embedded_widget?
+          key?(:Subtype)
+        end
+
         # :call-seq:
         #   field.each_widget {|widget| block}    -> field
         #   field.each_widget                     -> Enumerator
@@ -245,7 +250,7 @@ module HexaPDF
         # See: HexaPDF::Type::Annotations::Widget
         def each_widget # :yields: widget
           return to_enum(__method__) unless block_given?
-          if self[:Subtype]
+          if embedded_widget?
             yield(document.wrap(self))
           elsif terminal_field?
             self[:Kids]&.each {|kid| yield(document.wrap(kid)) }
@@ -275,9 +280,9 @@ module HexaPDF
 
           widget_data = {Type: :Annot, Subtype: :Widget, Rect: [0, 0, 0, 0], **values}
 
-          if !allow_embedded || key?(:Subtype) || (key?(:Kids) && !self[:Kids].empty?)
+          if !allow_embedded || embedded_widget? || (key?(:Kids) && !self[:Kids].empty?)
             kids = self[:Kids] ||= []
-            kids << extract_widget if key?(:Subtype)
+            kids << extract_widget if embedded_widget?
             widget = document.add(widget_data)
             widget[:Parent] = self
             self[:Kids] << widget
@@ -291,6 +296,31 @@ module HexaPDF
           widget
         end
 
+        # Deletes the given widget annotation object from this field, the page it appears on and the
+        # document.
+        #
+        # If the given widget is not a widget of this field, nothing is done.
+        def delete_widget(widget)
+          widget = if embedded_widget? && self == widget
+                     widget
+                   elsif terminal_field?
+                     (widget_index = self[:Kids]&.index(widget)) && widget
+                   end
+
+          return unless widget
+
+          document.pages.each do |page|
+            break if page[:Annots]&.delete(widget) # See comment in #extract_widget
+          end
+
+          if embedded_widget?
+            WIDGET_FIELDS.each {|key| delete(key) }
+          else
+            self[:Kids].delete_at(widget_index)
+            document.delete(widget)
+          end
+        end
+
         private
 
         # An array of all widget annotation field names.
@@ -300,14 +330,14 @@ module HexaPDF
         # directly in the field and adjust the references accordingly. If the field doesn't have any
         # widget data, +nil+ is returned.
         def extract_widget
-          return unless key?(:Subtype)
+          return unless embedded_widget?
           data = WIDGET_FIELDS.each_with_object({}) do |key, hash|
             hash[key] = delete(key) if key?(key)
           end
           widget = document.add(data, type: :Annot)
           widget[:Parent] = self
           document.pages.each do |page|
-            if page.key?(:Annots) && (index = page[:Annots].index {|annot| annot.data == self.data })
+            if page.key?(:Annots) && (index = page[:Annots].index(self))
               page[:Annots][index] = widget
               break # Each annotation dictionary may only appear on one page, see PDF1.7 12.5.2
             end

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,28 +245,64 @@ 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.
         def default_resources
-          self[:DR] ||= document.wrap({}, type: :XXResources)
+          self[:DR] ||= document.wrap({ProcSet: [:PDF, :Text, :ImageB, :ImageC, :ImageI]},
+                                      type: :XXResources)
         end
 
         # Sets the global default appearance string using the provided values.
@@ -212,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
 
@@ -245,18 +358,30 @@ 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
+
           if (da = self[:DA])
             unless self[:DR]
               yield("When the field /DA is present, the field /DR must also be present")
+              return
             end
             font_name = nil
-            HexaPDF::Content::Parser.parse(da) do |obj, params|
-              font_name = params[0] if obj == :Tf
-            end
+            HexaPDF::Content::Parser.parse(da) {|obj, params| font_name = params[0] if obj == :Tf }
             if font_name && !(self[:DR][:Font] && self[:DR][:Font][font_name])
               yield("The font specified in /DA is not in the /DR resource dictionary")
             end

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
@@ -173,8 +238,9 @@ module HexaPDF
 
           if self[:V] && !(self[:V].kind_of?(String) || self[:V].kind_of?(HexaPDF::Stream))
             yield("Text field doesn't contain text but #{self[:V].class} object")
+            return
           end
-          if (max_len = self[:MaxLen]) && field_value.length > max_len
+          if (max_len = self[:MaxLen]) && field_value && field_value.length > max_len
             yield("Text contents of field '#{full_field_name}' is too long")
           end
         end