hexapdf 0.27.0 → 0.28.0

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

@@ -34,6 +34,7 @@
 # commercial licenses are available at <https://gettalong.at/hexapdf/>.
 #++
 
+require 'json'
 require 'hexapdf/error'
 require 'hexapdf/layout/style'
 require 'hexapdf/layout/text_fragment'
@@ -74,12 +75,10 @@ module HexaPDF
         def create_appearances
           case @field.field_type
           when :Btn
-            if @field.check_box?
-              create_check_box_appearances
-            elsif @field.radio_button?
-              create_radio_button_appearances
+            if @field.push_button?
+              create_push_button_appearances
             else
-              raise HexaPDF::Error, "Unsupported button field type"
+              create_check_box_appearances
             end
           when :Tx, :Ch
             create_text_appearances
@@ -88,23 +87,24 @@ module HexaPDF
           end
         end
 
-        # Creates the appropriate appearances for check boxes.
+        # Creates the appropriate appearances for check boxes and radio buttons.
         #
-        # The unchecked box is always represented by the appearance with the key /Off. If there is
-        # more than one other key besides the /Off key, the first one is used for the appearance of
-        # the checked box.
+        # The unchecked box or unselected radio button is always represented by the appearance with
+        # the key /Off. If there is more than one other key besides the /Off key, the first one is
+        # used for the appearance of the checked box or selected radio button.
         #
-        # For unchecked boxes an empty rectangle is drawn. When checked, a symbol from the
-        # ZapfDingbats font is placed inside the rectangle. How this is exactly done depends on the
-        # following values:
+        # For unchecked boxes an empty rectangle is drawn. Similarly, for unselected radio buttons
+        # an empty circle (if the marker is :circle) or rectangle is drawn. When checked or
+        # selected, a symbol from the ZapfDingbats font is placed inside. How this is exactly done
+        # depends on the following values:
         #
         # * The widget's rectangle /Rect must be defined. If the height and/or width of the
         #   rectangle are zero, they are based on the configuration option
         #   +acro_form.default_font_size+ and widget's border width. In such a case the rectangle is
         #   appropriately updated.
         #
-        # * The line width, style and color of the rectangle are taken from the widget's border
-        #   style. See HexaPDF::Type::Annotations::Widget#border_style.
+        # * The line width, style and color of the cirle/rectangle are taken from the widget's
+        #   border style. See HexaPDF::Type::Annotations::Widget#border_style.
         #
         # * The background color is determined by the widget's background color. See
         #   HexaPDF::Type::Annotations::Widget#background_color.
@@ -114,94 +114,66 @@ module HexaPDF
         #
         # Examples:
         #
+        #   # check box: default appearance
         #   widget.border_style(color: 0)
         #   widget.background_color(1)
         #   widget.marker_style(style: :check, size: 0, color: 0)
-        #   # => default appearance
         #
+        #   # check box: no visible rectangle, gray background, cross mark when checked
         #   widget.border_style(color: :transparent, width: 2)
         #   widget.background_color(0.7)
         #   widget.marker_style(style: :cross)
-        #   # => no visible rectangle, gray background, cross mark when checked
-        def create_check_box_appearances
-          appearance_keys = @widget.appearance_dict&.normal_appearance&.value&.keys || []
-          on_name = (appearance_keys - [:Off]).first
-          unless on_name
-            raise HexaPDF::Error, "Widget of check box doesn't define name for on state"
-          end
-          border_style = @widget.border_style
-          border_width = border_style.width
-
-          rect = update_widget(@field[:V], border_width)
-
-          off_form = @widget.appearance_dict.normal_appearance[:Off] =
-            @document.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, rect.width, rect.height]})
-          apply_background_and_border(border_style, off_form.canvas)
-
-          on_form = @widget.appearance_dict.normal_appearance[on_name] =
-            @document.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, rect.width, rect.height]})
-          canvas = on_form.canvas
-          apply_background_and_border(border_style, canvas)
-          canvas.save_graphics_state do
-            draw_marker(canvas, rect, border_width, @widget.marker_style)
-          end
-        end
-
-        # Creates the appropriate appearances for radio buttons.
-        #
-        # For unselected radio buttons an empty circle (if the marker is :circle) or rectangle is
-        # drawn inside the widget annotation's rectangle. When selected, a symbol from the
-        # ZapfDingbats font is placed inside. How this is exactly done depends on the following
-        # values:
-        #
-        # * The widget's rectangle /Rect must be defined. If the height and/or width of the
-        #   rectangle are zero, they are based on the configuration option
-        #   +acro_form.default_font_size+ and the widget's border width. In such a case the
-        #   rectangle is appropriately updated.
-        #
-        # * The line width, style and color of the circle/rectangle are taken from the widget's
-        #   border style. See HexaPDF::Type::Annotations::Widget#border_style.
-        #
-        # * The background color is determined by the widget's background color. See
-        #   HexaPDF::Type::Annotations::Widget#background_color.
-        #
-        # * The symbol (marker) as well as its size and color are determined by the marker style of
-        #   the widget. See HexaPDF::Type::Annotations::Widget#marker_style for details.
-        #
-        # Examples:
         #
+        #   # radio button: default appearance
         #   widget.border_style(color: 0)
         #   widget.background_color(1)
         #   widget.marker_style(style: :circle, size: 0, color: 0)
-        #   # => default appearance
-        def create_radio_button_appearances
+        def create_check_box_appearances
           appearance_keys = @widget.appearance_dict&.normal_appearance&.value&.keys || []
           on_name = (appearance_keys - [:Off]).first
           unless on_name
-            raise HexaPDF::Error, "Widget of radio button doesn't define name for on state"
+            raise HexaPDF::Error, "Widget of button field doesn't define name for on state"
           end
 
+          @widget[:AS] = (@field[:V] == on_name ? on_name : :Off)
+          @widget.flag(:print)
+
           border_style = @widget.border_style
           marker_style = @widget.marker_style
+          circular = (@field.radio_button? && marker_style.style == :circle)
+
+          default_font_size = @document.config['acro_form.default_font_size']
+          rect = @widget[:Rect]
+          rect.width = default_font_size + 2 * border_style.width if rect.width == 0
+          rect.height = default_font_size + 2 * border_style.width if rect.height == 0
 
-          rect = update_widget(@field[:V] == on_name ? on_name : :Off, border_style.width)
+          width, height, matrix = perform_rotation(rect.width, rect.height)
 
           off_form = @widget.appearance_dict.normal_appearance[:Off] =
-            @document.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, rect.width, rect.height]})
-          apply_background_and_border(border_style, off_form.canvas,
-                                      circular: marker_style.style == :circle)
+            @document.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, width, height],
+                           Matrix: matrix})
+          apply_background_and_border(border_style, off_form.canvas, circular: circular)
 
           on_form = @widget.appearance_dict.normal_appearance[on_name] =
-            @document.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, rect.width, rect.height]})
+            @document.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, width, height],
+                           Matrix: matrix})
           canvas = on_form.canvas
-          apply_background_and_border(border_style, canvas,
-                                      circular: marker_style.style == :circle)
+          apply_background_and_border(border_style, canvas, circular: circular)
           canvas.save_graphics_state do
-            draw_marker(canvas, rect, border_style.width, @widget.marker_style)
+            draw_marker(canvas, width, height, border_style.width, marker_style)
           end
         end
 
-        # Creates the appropriate appearances for text fields.
+        alias create_radio_button_appearances create_check_box_appearances
+
+        # Creates the appropriate appearances for push buttons.
+        #
+        # This is currently a dummy implementation raising an error.
+        def create_push_button_appearances
+          raise HexaPDF::Error, "Push button appearance generation not yet supported"
+        end
+
+        # Creates the appropriate appearances for text fields, combo box fields and list box fields.
         #
         # The following describes how the appearance is built:
         #
@@ -242,31 +214,33 @@ module HexaPDF
             rect.height = style.scaled_y_max - style.scaled_y_min + 2 * padding
           end
 
+          width, height, matrix = perform_rotation(rect.width, rect.height)
+
           form = (@widget[:AP] ||= {})[:N] ||= @document.add({Type: :XObject, Subtype: :Form})
           # Wrap existing object in Form class in case the PDF writer didn't include the /Subtype
           # key; we can do this since we know this has to be a Form object
           form = @document.wrap(form, type: :XObject, subtype: :Form) unless form[:Subtype] == :Form
-          form.value.replace({Type: :XObject, Subtype: :Form, BBox: [0, 0, rect.width, rect.height]})
+          form.value.replace({Type: :XObject, Subtype: :Form, BBox: [0, 0, width, height],
+                              Matrix: matrix, Resources: HexaPDF::Object.deep_copy(default_resources)})
           form.contents = ''
-          form[:Resources] = HexaPDF::Object.deep_copy(default_resources)
 
           canvas = form.canvas
           apply_background_and_border(border_style, canvas)
-          style.font_size = calculate_font_size(font, font_size, rect, border_style)
+          style.font_size = calculate_font_size(font, font_size, height, border_style)
           style.clear_cache
 
           canvas.marked_content_sequence(:Tx) do
             if @field.field_value || @field.concrete_field_type == :list_box
               canvas.save_graphics_state do
-                canvas.rectangle(padding, padding, rect.width - 2 * padding,
-                                 rect.height - 2 * padding).clip_path.end_path
+                canvas.rectangle(padding, padding, width - 2 * padding,
+                                 height - 2 * padding).clip_path.end_path
                 case @field.concrete_field_type
                 when :multiline_text_field
-                  draw_multiline_text(canvas, rect, style, padding)
+                  draw_multiline_text(canvas, width, height, style, padding)
                 when :list_box
-                  draw_list_box(canvas, rect, style, padding)
+                  draw_list_box(canvas, width, height, style, padding)
                 else
-                  draw_single_line_text(canvas, rect, style, padding)
+                  draw_single_line_text(canvas, width, height, style, padding)
                 end
               end
             end
@@ -278,23 +252,20 @@ module HexaPDF
 
         private
 
-        # Updates the widget and returns its (possibly modified) rectangle.
-        #
-        # The following changes are made:
-        #
-        # * Sets the appearance state to +appearance_state+.
-        # * Sets the :print flag.
-        # * Adjusts the rectangle based on the default font size and the given border width if its
-        #   width and/or height are zero.
-        def update_widget(appearance_state, border_width)
-          @widget[:AS] = appearance_state
-          @widget.flag(:print)
-
-          default_font_size = @document.config['acro_form.default_font_size']
-          rect = @widget[:Rect]
-          rect.width = default_font_size + 2 * border_width if rect.width == 0
-          rect.height = default_font_size + 2 * border_width if rect.height == 0
-          rect
+        # Performs the rotation specified in /R of the appearance characteristics dictionary and
+        # returns the correct width, height and Form XObject matrix.
+        def perform_rotation(width, height)
+          matrix = case (@widget[:MK]&.[](:R) || 0) % 360
+                   when 90
+                     width, height = height, width
+                     [0, 1, -1, 0, 0, 0]
+                   when 270
+                     width, height = height, width
+                     [0, -1, 1, 0, 0, 0]
+                   when 180
+                     [0, -1, -1, 0, 0, 0]
+                   end
+          [width, height, matrix]
         end
 
         # Applies the background and border style of the widget annotation to the appearances.
@@ -353,31 +324,32 @@ module HexaPDF
         # Draws the marker defined by the marker style inside the widget's rectangle.
         #
         # This method can only used for check boxes and radio buttons!
-        def draw_marker(canvas, rect, border_width, marker_style)
+        def draw_marker(canvas, width, height, border_width, marker_style)
           if @field.radio_button? && marker_style.style == :circle
             # Acrobat handles this specially
             canvas.
               fill_color(marker_style.color).
-              circle(rect.width / 2.0, rect.height / 2.0,
-                     ([rect.width / 2.0, rect.height / 2.0].min - border_width) / 2).
+              circle(width / 2.0, height / 2.0,
+                     ([width / 2.0, height / 2.0].min - border_width) / 2).
               fill
           elsif marker_style.style == :cross # Acrobat just places a cross inside
             canvas.
               stroke_color(marker_style.color).
-              line(border_width, border_width, rect.width - border_width,
-                   rect.height - border_width).
-              line(border_width, rect.height - border_width, rect.width - border_width,
+              line(border_width, border_width, width - border_width,
+                   height - border_width).
+              line(border_width, height - border_width, width - border_width,
                    border_width).
               stroke
           else
             font = @document.fonts.add('ZapfDingbats')
-            mark = font.decode_utf8(@widget[:MK]&.[](:CA) || '4').first
-            square_width = [rect.width, rect.height].min - 2 * border_width
+            marker_string = @widget[:MK]&.[](:CA).to_s
+            mark = font.decode_utf8(marker_string.empty? ? '4' : marker_string).first
+            square_width = [width, height].min - 2 * border_width
             font_size = (marker_style.size == 0 ? square_width : marker_style.size)
             mark_width = mark.width * font.scaling_factor * font_size / 1000.0
             mark_height = (mark.y_max - mark.y_min) * font.scaling_factor * font_size / 1000.0
-            x_offset = (rect.width - square_width) / 2.0 + (square_width - mark_width) / 2.0
-            y_offset = (rect.height - square_width) / 2.0 + (square_width - mark_height) / 2.0 -
+            x_offset = (width - square_width) / 2.0 + (square_width - mark_width) / 2.0
+            y_offset = (height - square_width) / 2.0 + (square_width - mark_height) / 2.0 -
               (mark.y_min * font.scaling_factor * font_size / 1000.0)
 
             canvas.font(font, size: font_size)
@@ -387,8 +359,9 @@ module HexaPDF
         end
 
         # Draws a single line of text inside the widget's rectangle.
-        def draw_single_line_text(canvas, rect, style, padding)
-          value = @field.field_value
+        def draw_single_line_text(canvas, width, height, style, padding)
+          value, text_color = apply_javascript_formatting(@field.field_value)
+          style.fill_color = text_color if text_color
           fragment = HexaPDF::Layout::TextFragment.create(value, style)
 
           if @field.concrete_field_type == :comb_text_field
@@ -396,7 +369,7 @@ module HexaPDF
               raise HexaPDF::Error, "Missing or invalid dictionary field /MaxLen for comb text field"
             end
             new_items = []
-            cell_width = rect.width.to_f / @field[:MaxLen]
+            cell_width = width.to_f / @field[:MaxLen]
             scaled_cell_width = cell_width / style.scaled_font_size.to_f
             fragment.items.each_cons(2) do |a, b|
               new_items << a << -(scaled_cell_width - a.width / 2.0 - b.width / 2.0)
@@ -415,8 +388,8 @@ module HexaPDF
             # Adobe seems to be left/right-aligning based on twice the border width
             x = case @field.text_alignment
                 when :left then 2 * padding
-                when :right then [rect.width - 2 * padding - fragment.width, 2 * padding].max
-                when :center then [(rect.width - fragment.width) / 2.0, 2 * padding].max
+                when :right then [width - 2 * padding - fragment.width, 2 * padding].max
+                when :center then [(width - fragment.width) / 2.0, 2 * padding].max
                 end
           end
 
@@ -424,13 +397,13 @@ module HexaPDF
           # available
           cap_height = style.font.wrapped_font.cap_height * style.font.scaling_factor / 1000.0 *
             style.font_size
-          y = padding + (rect.height - 2 * padding - cap_height) / 2.0
+          y = padding + (height - 2 * padding - cap_height) / 2.0
           y = padding - style.scaled_font_descender if y < 0
           fragment.draw(canvas, x, y)
         end
 
         # Draws multiple lines  of text inside the widget's rectangle.
-        def draw_multiline_text(canvas, rect, style, padding)
+        def draw_multiline_text(canvas, width, height, style, padding)
           items = [Layout::TextFragment.create(@field.field_value, style)]
           layouter = Layout::TextLayouter.new(style)
           layouter.style.align(@field.text_alignment).line_spacing(:proportional, 1.25)
@@ -440,22 +413,22 @@ module HexaPDF
             style.font_size = 12 # Adobe seems to use this as starting point
             style.clear_cache
             loop do
-              result = layouter.fit(items, rect.width - 4 * padding, rect.height - 4 * padding)
+              result = layouter.fit(items, width - 4 * padding, height - 4 * padding)
               break if result.status == :success || style.font_size <= 4 # don't make text too small
               style.font_size -= 1
               style.clear_cache
             end
           else
-            result = layouter.fit(items, rect.width - 4 * padding, 2**20)
+            result = layouter.fit(items, width - 4 * padding, 2**20)
           end
 
           unless result.lines.empty?
-            result.draw(canvas, 2 * padding, rect.height - 2 * padding - result.lines[0].height / 2.0)
+            result.draw(canvas, 2 * padding, height - 2 * padding - result.lines[0].height / 2.0)
           end
         end
 
         # Draws the visible option items of the list box in the widget's rectangle.
-        def draw_list_box(canvas, rect, style, padding)
+        def draw_list_box(canvas, width, height, style, padding)
           option_items = @field.option_items
           top_index = @field.list_box_top_index
           items = [Layout::TextFragment.create(option_items[top_index..-1].join("\n"), style)]
@@ -464,18 +437,18 @@ module HexaPDF
 
           layouter = Layout::TextLayouter.new(style)
           layouter.style.align(@field.text_alignment).line_spacing(:proportional, 1.25)
-          result = layouter.fit(items, rect.width - 4 * padding, rect.height)
+          result = layouter.fit(items, width - 4 * padding, height)
 
           unless result.lines.empty?
             top_gap = style.line_spacing.gap(result.lines[0], result.lines[0])
             line_height = style.line_spacing.baseline_distance(result.lines[0], result.lines[0])
             canvas.fill_color(153, 193, 218) # Adobe's color for selection highlighting
-            indices.map! {|i| rect.height - padding - (i - top_index + 1) * line_height }.each do |y|
-              next if y + line_height > rect.height || y + line_height < padding
-              canvas.rectangle(padding, y, rect.width - 2 * padding, line_height)
+            indices.map! {|i| height - padding - (i - top_index + 1) * line_height }.each do |y|
+              next if y + line_height > height || y + line_height < padding
+              canvas.rectangle(padding, y, width - 2 * padding, line_height)
             end
             canvas.fill if canvas.graphics_object == :path
-            result.draw(canvas, 2 * padding, rect.height - padding - top_gap)
+            result.draw(canvas, 2 * padding, height - padding - top_gap)
           end
         end
 
@@ -501,8 +474,8 @@ module HexaPDF
         end
 
         # Calculates the font size for text fields based on the font and font size of the default
-        # appearance string, the annotation rectangle and the border style.
-        def calculate_font_size(font, font_size, rect, border_style)
+        # appearance string, the annotation rectangle's height and the border style.
+        def calculate_font_size(font, font_size, height, border_style)
           if font_size == 0
             case @field.concrete_field_type
             when :multiline_text_field
@@ -513,13 +486,86 @@ module HexaPDF
               unit_font_size = (font.wrapped_font.bounding_box[3] - font.wrapped_font.bounding_box[1]) *
                 font.scaling_factor / 1000.0
               # The constant factor was found empirically by checking what Adobe Reader etc. do
-              (rect.height - 2 * border_style.width) / unit_font_size * 0.83
+              (height - 2 * border_style.width) / unit_font_size * 0.83
             end
           else
             font_size
           end
         end
 
+        # Handles Javascript formatting routines for single-line text fields.
+        #
+        # Returns [value, nil_or_text_color] where value is the new, potentially adjusted field
+        # value and the second argument is either +nil+ or the color that should be used for the
+        # text value.
+        def apply_javascript_formatting(value)
+          format_action = @widget[:AA]&.[](:F)
+          return [value, nil] unless format_action && format_action[:S] == :JavaScript
+          if (match = AF_NUMBER_FORMAT_RE.match(format_action[:JS]))
+            apply_af_number_format(value, match)
+          else
+            [value, nil]
+          end
+        end
+
+        # Regular expression for matching the AFNumber_Format Javascript method.
+        AF_NUMBER_FORMAT_RE = /
+          \AAFNumber_Format\(
+            \s*(?<ndec>\d+)\s*,
+            \s*(?<sep_style>[0-3])\s*,
+            \s*(?<neg_style>[0-3])\s*,
+            \s*0\s*,
+            \s*(?<currency_string>".*?")\s*,
+            \s*(?<prepend>false|true)\s*
+          \);\z
+        /x
+
+        # Implements the Javascript AFNumber_Format method.
+        #
+        # See:
+        # - https://experienceleague.adobe.com/docs/experience-manager-learn/assets/FormsAPIReference.pdf
+        # - https://opensource.adobe.com/dc-acrobat-sdk-docs/library/jsapiref/JS_API_AcroJS.html#printf
+        def apply_af_number_format(value, match)
+          value = value.to_f
+          format = "%.#{match[:ndec]}f"
+          text_color = 'black'
+
+          currency_string = JSON.parse(match[:currency_string])
+          format = (match[:prepend] == 'true' ? currency_string + format : format + currency_string)
+
+          if value < 0
+            value = value.abs
+            case match[:neg_style]
+            when '0' # MinusBlack
+              format = "-#{format}"
+            when '1' # Red
+              text_color = 'red'
+            when '2' # ParensBlack
+              format = "(#{format})"
+            when '3' # ParensRed
+              format = "(#{format})"
+              text_color = 'red'
+            end
+          end
+
+          result = sprintf(format, value)
+
+          # sep_style: 0=12,345.67, 1=12345.67, 2=12.345,67, 3=12345,67
+          before_decimal_point, after_decimal_point = result.split('.')
+          if match[:sep_style] == '0' || match[:sep_style] == '2'
+            separator = (match[:sep_style] == '0' ? ',' : '.')
+            before_decimal_point.gsub!(/\B(?=(\d\d\d)+(?:[^\d]|\z))/, separator)
+          end
+          result = if after_decimal_point
+                     decimal_point = (match[:sep_style] =~ /[01]/ ? '.' : ',')
+                     "#{before_decimal_point}#{decimal_point}#{after_decimal_point}"
+                   else
+                     before_decimal_point
+                   end
+
+          [result, text_color]
+        end
+
       end
 
     end

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

@@ -84,6 +84,8 @@ module HexaPDF
       # See: PDF1.7 s12.7.4.2
       class ButtonField < Field
 
+        define_type :XXAcroFormField
+
         define_field :Opt, type: PDFArray, version: '1.4'
 
         # All inheritable dictionary fields for button fields.
@@ -206,7 +208,7 @@ module HexaPDF
         # Note that this will only return useful values if there is at least one correctly set-up
         # widget.
         def allowed_values
-          (each_widget.each_with_object([]) do |widget, result|
+          (each_widget.with_object([]) do |widget, result|
              keys = widget.appearance_dict&.normal_appearance&.value&.keys
              result.concat(keys) if keys
            end - [:Off]).uniq
@@ -254,14 +256,14 @@ module HexaPDF
             normal_appearance = widget.appearance_dict&.normal_appearance
             next if !force && normal_appearance &&
               ((!push_button? && normal_appearance.value.length == 2 &&
-                normal_appearance.value.each_value.all?(HexaPDF::Stream)) ||
+                normal_appearance.each.all? {|_, v| v.kind_of?(HexaPDF::Stream) }) ||
                (push_button? && normal_appearance.kind_of?(HexaPDF::Stream)))
             if check_box?
               appearance_generator_class.new(widget).create_check_box_appearances
             elsif radio_button?
               appearance_generator_class.new(widget).create_radio_button_appearances
             else
-              raise HexaPDF::Error, "Push buttons not yet supported"
+              appearance_generator_class.new(widget).create_push_button_appearances
             end
           end
         end

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

@@ -69,6 +69,8 @@ module HexaPDF
       # See: PDF1.7 s12.7.4.4
       class ChoiceField < VariableTextField
 
+        define_type :XXAcroFormField
+
         define_field :Opt, type: PDFArray
         define_field :TI, type: Integer, default: 0
         define_field :I, type: PDFArray, version: '1.4'

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

@@ -242,8 +242,8 @@ module HexaPDF
         end
 
         # :call-seq:
-        #   field.each_widget {|widget| block}    -> field
-        #   field.each_widget                     -> Enumerator
+        #   field.each_widget(direct_only: true) {|widget| block}    -> field
+        #   field.each_widget(direct_only: true)                     -> Enumerator
         #
         # Yields each widget, i.e. visual representation, of this field.
         #
@@ -253,11 +253,17 @@ module HexaPDF
         # 2. One or more widgets are defined as children of this field.
         # 3. Widgets of *another field instance with the same full field name*.
         #
-        # Because of possibility 3 all fields of the form have to be searched to check whether there
-        # is another field with the same full field name.
+        # With the default of +direct_only+ being +true+, only the usual cases 1 and 2 are handled/
+        # If case 3 also needs to be handled, set +direct_only+ to +false+ or run the validation on
+        # the main AcroForm object (HexaPDF::Document#acro_form) before using this method (this will
+        # reduce case 3 to case 2).
+        #
+        # *Note*: Setting +direct_only+ to +false+ will have a severe performance impact since all
+        # fields of the form have to be searched to check whether there is another field with the
+        # same full field name.
         #
         # See: HexaPDF::Type::Annotations::Widget
-        def each_widget(direct_only: false, &block) # :yields: widget
+        def each_widget(direct_only: true, &block) # :yields: widget
           return to_enum(__method__, direct_only: direct_only) unless block_given?
 
           if embedded_widget?

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

@@ -125,14 +125,22 @@ module HexaPDF
         def each_field(terminal_only: true)
           return to_enum(__method__, terminal_only: terminal_only) unless block_given?
 
-          process_field = lambda do |field|
-            field = document.wrap(field, type: :XXAcroFormField,
-                                  subtype: Field.inherited_value(field, :FT))
-            yield(field) if field.terminal_field? || !terminal_only
-            field[:Kids].each(&process_field) unless field.terminal_field?
+          process_field_array = lambda do |array|
+            array.each_with_index do |field, index|
+              unless field.respond_to?(:type) && field.type == :XXAcroFormField
+                array[index] = field = document.wrap(field, type: :XXAcroFormField,
+                                                     subtype: Field.inherited_value(field, :FT))
+              end
+              if field.terminal_field?
+                yield(field)
+              else
+                yield(field) unless terminal_only
+                process_field_array.call(field[:Kids])
+              end
+            end
           end
 
-          root_fields.each(&process_field)
+          process_field_array.call(root_fields)
           self
         end
 
@@ -393,7 +401,7 @@ module HexaPDF
             fields.each {|field| field.create_appearances if field.respond_to?(:create_appearances) }
           end
 
-          not_flattened = fields.map {|field| field.each_widget.to_a }.flatten
+          not_flattened = fields.map {|field| field.each_widget(direct_only: true).to_a }.flatten
           document.pages.each {|page| not_flattened = page.flatten_annotations(not_flattened) }
           not_flattened.map!(&:form_field)
           fields -= not_flattened
@@ -449,6 +457,8 @@ module HexaPDF
         def perform_validation # :nodoc:
           super
 
+          seen = {} # used for combining field
+
           validate_array = lambda do |parent, container|
             container.reject! do |field|
               if !field.kind_of?(HexaPDF::Object) || !field.kind_of?(HexaPDF::Dictionary) || field.null?
@@ -469,6 +479,22 @@ module HexaPDF
                   field[:Parent] = parent
                 end
               end
+
+              # Combine fields with same name
+              name = field.full_field_name
+              if (other_field = seen[name])
+                kids = other_field[:Kids] ||= []
+                kids << other_field.send(:extract_widget) if other_field.embedded_widget?
+                widgets = field.embedded_widget? ? [field.send(:extract_widget)] : field.each_widget.to_a
+                widgets.each do |widget|
+                  widget[:Parent] = other_field
+                  kids << widget
+                end
+                reject = true
+              elsif !reject
+                seen[name] = field
+              end
+
               validate_array.call(field, field[:Kids]) if field.key?(:Kids)
               reject
             end

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

@@ -192,6 +192,8 @@ module HexaPDF
 
         end
 
+        define_type :XXAcroFormField
+
         define_field :Lock, type: :SigFieldLock, indirect: true, version: '1.5'
         define_field :SV, type: :SV, indirect: true, version: '1.5'