hexapdf 0.12.0 → 0.14.0

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

@@ -134,8 +134,8 @@ module HexaPDF
         # Check boxes:: For check boxes that are in the on state the value +true+ is returned.
         #               Otherwise +false+ is returned.
         #
-        # Radio buttons:: If no radio button is selected, +nil+ is returned. Otherwise the name of
-        #                 the specific radio button that is selected 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.
         def field_value
           normalized_field_value(:V)
         end
@@ -149,7 +149,8 @@ module HexaPDF
         #               +false+ for unchecking it.
         #
         # Radio buttons:: To turn all radio buttons off, provide +nil+ as value. Otherwise provide
-        #                 the name of a radio button that should be turned on.
+        #                 the value (a Symbol or an object responding to +#to_sym+) of a radio
+        #                 button that should be turned on.
         def field_value=(value)
           normalized_field_value_set(:V, value)
         end
@@ -179,7 +180,7 @@ module HexaPDF
           end
         end
 
-        # Returns the name used for setting the check box to the on state.
+        # Returns the name (a Symbol) used for setting the check box to the on state.
         #
         # Defaults to :Yes if no other name could be determined.
         def check_box_on_name
@@ -187,7 +188,8 @@ module HexaPDF
             find {|key| key != :Off } || :Yes
         end
 
-        # Returns the array of values that can be used for the field value of the radio button.
+        # Returns the array of Symbol values that can be used for the field value of the radio
+        # button.
         def radio_button_values
           each_widget.map do |widget|
             widget.appearance&.normal_appearance&.value&.each_key&.find {|key| key != :Off }
@@ -200,8 +202,8 @@ module HexaPDF
         # default appearance.
         #
         # If the widget is created for a radio button field, the +value+ argument needs to set to
-        # the value (a symbol) this widget represents. It can be used with #field_value= to set this
-        # specific widget of the radio button set to on.
+        # 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.
         #
         # See: Field#create_widget, AppearanceGenerator button field methods
         def create_widget(page, defaults: true, value: nil, **values)
@@ -209,8 +211,11 @@ module HexaPDF
             if check_box?
               widget[:AP] = {N: {Yes: nil, Off: nil}}
             elsif radio_button?
-              raise ArgumentError, "Argument value has to be provided for radio buttons" unless value
-              widget[:AP] = {N: {value => nil, Off: nil}}
+              unless value.respond_to?(:to_sym)
+                raise ArgumentError, "Argument 'value' has to be provided for radio buttons " \
+                  "and needs to respond to #to_sym"
+              end
+              widget[:AP] = {N: {value.to_sym => nil, Off: nil}}
             end
             next unless defaults
             widget.border_style(color: 0, width: 1, style: (push_button? ? :beveled : :solid))
@@ -223,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?
@@ -240,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)
@@ -271,8 +279,8 @@ module HexaPDF
                         value == true ? check_box_on_name : :Off
                       elsif value.nil?
                         :Off
-                      elsif radio_button_values.include?(value)
-                        value
+                      elsif radio_button_values.include?(value.to_sym)
+                        value.to_sym
                       else
                         @document.config['acro_form.on_invalid_value'].call(self, value)
                       end

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