hexapdf 1.2.0 → 1.3.0

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

@@ -174,11 +174,59 @@ module HexaPDF
 
         alias create_radio_button_appearances create_check_box_appearances
 
-        # Creates the appropriate appearances for push buttons.
+        # Creates the appropriate appearances for push button fields
         #
-        # This is currently a dummy implementation raising an error.
+        # The following describes how the appearance is built:
+        #
+        # * The widget's rectangle /Rect must be defined.
+        #
+        # * If the font size (used for the caption) is zero, a font size of
+        #   +acro_form.default_font_size+ is used.
+        #
+        # * 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 background color is determined by the widget's background color. See
+        #   HexaPDF::Type::Annotations::Widget#background_color.
         def create_push_button_appearances
-          raise HexaPDF::Error, "Push button appearance generation not yet supported"
+          default_resources = @document.acro_form(create: true).default_resources
+          border_style = @widget.border_style
+          padding = border_style.width
+          marker_style = @widget.marker_style
+          font = retrieve_font_information(marker_style.font_name, default_resources)
+
+          @widget[:AS] = :N
+          @widget.flag(:print)
+          @widget.unflag(:hidden)
+          rect = @widget[:Rect]
+
+          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 or the type of the object is wrong; we can do this since we know this has to be a
+          # Form object
+          unless form.type == :XObject && form[:Subtype] == :Form
+            form = @document.wrap(form, type: :XObject, subtype: :Form)
+          end
+          form.value.replace({Type: :XObject, Subtype: :Form, BBox: [0, 0, width, height],
+                              Matrix: matrix, Resources: HexaPDF::Object.deep_copy(default_resources)})
+          form.contents = ''
+
+          canvas = form.canvas
+          apply_background_and_border(border_style, canvas)
+
+          style = HexaPDF::Layout::Style.new(font: font, font_size: marker_style.size,
+                                             fill_color: marker_style.color)
+          if (text = marker_style.style) && text.kind_of?(String)
+            items = @document.layout.text_fragments(marker_style.style, style: style)
+            layouter = Layout::TextLayouter.new(style)
+            layouter.style.text_align(:center).text_valign(:center).line_spacing(:proportional, 1.25)
+            result = layouter.fit(items, width - 2 * padding, height - 2 * padding)
+            unless result.lines.empty?
+              result.draw(canvas, padding, height - padding)
+            end
+          end
         end
 
         # Creates the appropriate appearances for text fields, combo box fields and list box fields.
@@ -207,7 +255,8 @@ module HexaPDF
         # Note: Rich text fields are currently not supported!
         def create_text_appearances
           default_resources = @document.acro_form.default_resources
-          font, font_size, font_color = retrieve_font_information(default_resources)
+          font_name, font_size, font_color = @field.parse_default_appearance_string(@widget)
+          font = retrieve_font_information(font_name, default_resources)
           style = HexaPDF::Layout::Style.new(font: font, font_size: font_size, fill_color: font_color)
           border_style = @widget.border_style
           padding = [1, border_style.width].max
@@ -475,9 +524,9 @@ module HexaPDF
           end
         end
 
-        # Returns the font wrapper and font size to be used for a variable text field.
-        def retrieve_font_information(resources)
-          font_name, font_size, font_color = @field.parse_default_appearance_string(@widget)
+        # Returns the font wrapper, font size and font color to be used for variable text fields and
+        # push button captions.
+        def retrieve_font_information(font_name, resources)
           font_object = resources.font(font_name) rescue nil
           font = font_object&.font_wrapper
           unless font
@@ -493,7 +542,7 @@ module HexaPDF
               raise(HexaPDF::Error, "Font #{font_name} of the AcroForm's default resources not usable")
             end
           end
-          [font, font_size, font_color]
+          font
         end
 
         # Calculates the font size for single line text fields using auto-sizing, based on the font

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

@@ -392,6 +392,7 @@ module HexaPDF
               break # Each annotation dictionary may only appear on one page, see PDF2.0 12.5.2
             end
           end
+          document.revisions.current.update(self)
           widget
         end
 

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

@@ -568,12 +568,12 @@ module HexaPDF
           seen = {} # used for combining field
 
           validate_array = lambda do |parent, container|
-            container.reject! do |field|
+            container.map! do |field|
               if !field.kind_of?(HexaPDF::Object) || !field.kind_of?(HexaPDF::Dictionary) || field.null?
                 yield("Invalid object in AcroForm field hierarchy", true)
-                next true
+                next nil
               end
-              next false unless field.key?(:T) # Skip widgets
+              next field unless field.key?(:T) # Skip widgets
 
               field = Field.wrap(document, field)
               reject = false
@@ -597,14 +597,15 @@ module HexaPDF
                   widget[:Parent] = other_field
                   kids << widget
                 end
+                document.delete(field)
                 reject = true
               elsif !reject
                 seen[name] = field
               end
 
-              validate_array.call(field, field[:Kids]) if field.key?(:Kids)
-              reject
-            end
+              validate_array.call(field, field[:Kids]) if !field.null? && field.key?(:Kids)
+              reject ? nil : field
+            end.compact!
           end
           validate_array.call(nil, root_fields)
 

data/lib/hexapdf/type/annotation.rb

@@ -113,6 +113,18 @@ module HexaPDF
 
       end
 
+      # Border effect dictionary used by square, circle and polygon annotation types.
+      #
+      # See: PDF2.0 s12.5.4
+      class BorderEffect < Dictionary
+
+        define_type :XXBorderEffect
+
+        define_field :S,    type: Symbol, default: :S, allowed_values: [:C, :S]
+        define_field :I,    type: Numeric, default: 0, allowed_values: [0, 1, 2]
+
+      end
+
       extend Utils::BitField
 
       define_type :Annot

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

@@ -73,6 +73,8 @@ module HexaPDF
         def create_appearance
           case @annot[:Subtype]
           when :Line then create_line_appearance
+          when :Square then create_square_circle_appearance(:square)
+          when :Circle then create_square_circle_appearance(:circle)
           else
             raise HexaPDF::Error, "Appearance regeneration for #{@annot[:Subtype]} not yet supported"
           end
@@ -224,6 +226,79 @@ module HexaPDF
           cap_result.draw(canvas, cap_x + 1, cap_y) if captioned
         end
 
+        # Creates the appropriate appearance for a square or circle annotation depending on the
+        # given +type+ (which can either be +:square+ or +:circle+).
+        #
+        # The cloudy border effect is not supported.
+        #
+        # See: HexaPDF::Type::Annotations::Square, HexaPDF::Type::Annotations::Circle
+        def create_square_circle_appearance(type)
+          # Prepare the annotation
+          form = (@annot[:AP] ||= {})[:N] ||=
+            @document.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, 0, 0]})
+          form.contents = ""
+          @annot.flag(:print)
+          @annot.unflag(:hidden)
+
+          rect = @annot[:Rect]
+          x, y, w, h = rect.left, rect.bottom, rect.width, rect.height
+          border_style = @annot.border_style
+          interior_color = @annot.interior_color
+          opacity = @annot.opacity
+
+          # Take the differences array into account. If it exists, the boundary of the actual
+          # rectangle is the one with the differences applied to /Rect.
+          #
+          # If the differences array doesn't exist, we assume that the /Rect is the rectangle we
+          # want to draw, with the line width split on both side (like with Canvas#rectangle). In
+          # this case we need to update /Rect accordingly so that the line width on the outside is
+          # correctly shown.
+          line_width_adjustment = border_style.width / 2.0
+          if (rd = @annot[:RD])
+            x += rd[0]
+            y += rd[3]
+            w -= rd[0] + rd[2]
+            h -= rd[1] + rd[3]
+          else
+            @annot[:RD] = [0, 0, 0, 0]
+            x = rect.left -= line_width_adjustment
+            y = rect.bottom -= line_width_adjustment
+            w = rect.width += line_width_adjustment
+            h = rect.height += line_width_adjustment
+          end
+          x += line_width_adjustment
+          y += line_width_adjustment
+          w -= 2 * line_width_adjustment
+          h -= 2 * line_width_adjustment
+
+          x -= rect.left
+          y -= rect.bottom
+          form[:BBox] = [0, 0, rect.width, rect.height]
+
+          if border_style.color || interior_color
+            canvas = form.canvas
+            canvas.opacity(**opacity.to_h)
+            canvas.stroke_color(border_style.color) if border_style.color
+            canvas.fill_color(interior_color) if interior_color
+            canvas.line_width(border_style.width)
+            canvas.line_dash_pattern(border_style.style) if border_style.style.kind_of?(Array)
+
+            if type == :square
+              canvas.rectangle(x, y, w, h)
+            else
+              canvas.ellipse(x + w / 2.0, y + h / 2.0, a: w / 2.0, b: h / 2.0)
+            end
+
+            if border_style.color && interior_color
+              canvas.fill_stroke
+            elsif border_style.color
+              canvas.stroke
+            else
+              canvas.fill
+            end
+          end
+        end
+
         # Draws the line ending style +type+ at the position (+x+, +y+) and returns +true+ if the
         # shape needs to be filled.
         #

data/lib/hexapdf/type/annotations/border_effect.rb

@@ -0,0 +1,99 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2025 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'hexapdf/type/annotations'
+
+module HexaPDF
+  module Type
+    module Annotations
+
+      # This module provides a convenience method for getting and setting the border effect for
+      # square, circle and polygon annotations.
+      #
+      # See: PDF2.0 s12.5.4
+      module BorderEffect
+
+        # :call-seq:
+        #   annot.border_effect         => border_effect
+        #   annot.border_effect(type)   => annot
+        #
+        # Returns the border effect of the annotation when no argument is given. Otherwise sets the
+        # border effect of the annotation and returns self.
+        #
+        # The argument type can have the following values:
+        #
+        # +:none+:: No border effect is used.
+        #
+        # +:cloudy+:: The border appears "cloudy" (as a series of convex curved line segments).
+        #
+        # +:cloudier+:: Like +:cloudy+ but more intense.
+        #
+        # +:cloudiest+:: Like +:cloudier+ but still more intense.
+        def border_effect(type = :UNSET)
+          if type == :UNSET
+            be = self[:BE]
+            if !be || be[:S] != :C
+              :none
+            else
+              case be[:I]
+              when 0 then :cloudy
+              when 1 then :cloudier
+              when 2 then :cloudiest
+              else :cloudy
+              end
+            end
+          else
+            case type
+            when nil, :none
+              delete(:BE)
+            when :cloudy
+              self[:BE] = {S: :C, I: 0}
+            when :cloudier
+              self[:BE] = {S: :C, I: 1}
+            when :cloudiest
+              self[:BE] = {S: :C, I: 2}
+            else
+              raise ArgumentError, "Unknown value #{type} for type argument"
+            end
+            self
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/hexapdf/type/annotations/circle.rb

@@ -0,0 +1,65 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2025 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'hexapdf/type/annotations'
+
+module HexaPDF
+  module Type
+    module Annotations
+
+      # A circle annotation displays an ellipse inside the annotation rectangle (the "circle" name
+      # defined by the PDF specification is a bit misleading).
+      #
+      # Also see SquareCircle for more information.
+      #
+      # Example:
+      #
+      #   #>pdf-small
+      #   doc.annotations.create_ellipse(doc.pages[0], 50, 50, a: 30, b: 20).
+      #     border_style(color: "hp-blue", width: 2, style: [3, 1]).
+      #     interior_color("hp-orange").
+      #     regenerate_appearance
+      #
+      # See: PDF2.0 s12.5.6.8, HexaPDF::Type::Annotations::SquareCircle,
+      class Circle < SquareCircle
+
+        define_field :Subtype, type: Symbol, required: true, default: :Circle
+
+      end
+
+    end
+  end
+end

data/lib/hexapdf/type/annotations/interior_color.rb

@@ -0,0 +1,84 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2025 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'hexapdf/type/annotations'
+
+module HexaPDF
+  module Type
+    module Annotations
+
+      # This module provides a convenience method for getting and setting the interior color for
+      # various annotations.
+      #
+      # See: PDF2.0 s12.5
+      module InteriorColor
+
+        # :call-seq:
+        #   line.interior_color           => color or nil
+        #   line.interior_color(*color)   => line
+        #
+        # Returns the interior color or +nil+ (in case the interior color should be transparent)
+        # when no argument is given. Otherwise sets the interior color and returns self.
+        #
+        # How the interior color is used depends on the concrete annotation type. For line
+        # annotations, for example, it is the color to fill the line endings
+        #
+        # +color+:: The interior color. See
+        #           HexaPDF::Content::ColorSpace.device_color_from_specification for information on
+        #           the allowed arguments.
+        #
+        #           If the special value +:transparent+ is used when setting the color, no color is
+        #           used for filling the line endings.
+        def interior_color(*color)
+          if color.empty?
+            color = self[:IC]
+            color && !color.empty? ?  Content::ColorSpace.prenormalized_device_color(color.value) : nil
+          else
+            color = if color.length == 1 && color.first == :transparent
+                      []
+                    else
+                      Content::ColorSpace.device_color_from_specification(color).components
+                    end
+            self[:IC] = color
+            self
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/hexapdf/type/annotations/line.rb

@@ -43,10 +43,10 @@ module HexaPDF
       # A line annotation is a markup annotation that displays a single straight line.
       #
       # The style of the line annotation, like adding leader lines, changing the colors and so on,
-      # can be customized using the provided convenience methods.
+      # can be customized using the provided convenience methods and those from the included
+      # modules.
       #
-      # Note that changing the line width and color is done using the included
-      # BorderStyling#border_style. While that method allows special styling of the line (like
+      # Note that while BorderStyling#border_style allows special styling of the line (like
       # :beveled), only a simple line dash pattern is supported by the line annotation.
       #
       # Example:
@@ -70,6 +70,7 @@ module HexaPDF
       class Line < MarkupAnnotation
 
         include BorderStyling
+        include InteriorColor
 
         define_field :Subtype, type: Symbol, required: true, default: :Line
         define_field :L,       type: PDFArray, required: true
@@ -272,38 +273,6 @@ module HexaPDF
           end
         end
 
-        # :call-seq:
-        #   line.interior_color          => color or nil
-        #   line.interior_color(*color)   => line
-        #
-        # Returns the interior color or +nil+ (in case the interior color should be transparent)
-        # when no argument is given. Otherwise sets the interior color and returns self.
-        #
-        # The interior color is used to fill the line endings depending on the line ending styles.
-        #
-        # +color+:: The interior color. See
-        #           HexaPDF::Content::ColorSpace.device_color_from_specification for information on
-        #           the allowed arguments.
-        #
-        #           If the special value +:transparent+ is used when setting the color, no color is
-        #           used for filling the line endings.
-        #
-        # Also see: #line_ending_style
-        def interior_color(*color)
-          if color.empty?
-            color = self[:IC]
-            color && !color.empty? ?  Content::ColorSpace.prenormalized_device_color(color.value) : nil
-          else
-            color = if color.length == 1 && color.first == :transparent
-                      []
-                    else
-                      Content::ColorSpace.device_color_from_specification(color).components
-                    end
-            self[:IC] = color
-            self
-          end
-        end
-
         # :call-seq:
         #   line.leader_line_length          => leader_line_length
         #   line.leader_line_length(length)  => line

data/lib/hexapdf/type/annotations/square.rb

@@ -0,0 +1,65 @@
+# -*- encoding: utf-8; frozen_string_literal: true -*-
+#
+#--
+# This file is part of HexaPDF.
+#
+# HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
+# Copyright (C) 2014-2025 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'hexapdf/type/annotations'
+
+module HexaPDF
+  module Type
+    module Annotations
+
+      # A square annotation displays a rectangle inside the annotation rectangle (the "square" name
+      # defined by the PDF specification is a bit misleading).
+      #
+      # Also see SquareCircle for more information.
+      #
+      # Example:
+      #
+      #   #>pdf-small
+      #   doc.annotations.create_rectangle(doc.pages[0], 20, 30, 60, 40).
+      #     border_style(color: "hp-blue", width: 2, style: [3, 1]).
+      #     interior_color("hp-orange").
+      #     regenerate_appearance
+      #
+      # See: PDF2.0 s12.5.6.8, HexaPDF::Type::Annotations::SquareCircle,
+      class Square < SquareCircle
+
+        define_field :Subtype, type: Symbol, required: true, default: :Square
+
+      end
+
+    end
+  end
+end