hexapdf 0.35.1 → 0.37.0

data/lib/hexapdf/layout/box.rb

@@ -60,28 +60,59 @@ module HexaPDF
     # instantiated from the common convenience method HexaPDF::Document::Layout#box. To use this
     # facility subclasses need to be registered with the configuration option 'layout.boxes.map'.
     #
-    # The methods #fit, #supports_position_flow?, #split or #split_content, #empty?, and #draw or
-    # #draw_content need to be customized according to the subclass's use case.
-    #
-    # #fit:: This method should return +true+ if fitting was successful. Additionally, the
-    #        @fit_successful instance variable needs to be set to the fit result as it is used in
-    #        #split.
+    # The methods #supports_position_flow?, #empty?, #fit or #fit_content, #split or #split_content,
+    # and #draw or #draw_content need to be customized according to the subclass's use case (also
+    # see the documentation of the methods besides the informatione below):
     #
     # #supports_position_flow?::
-    #        If the subclass supports the value :flow of the 'position' style property, this method
-    #        needs to be overridden to return +true+.
+    #     If the subclass supports the value :flow of the 'position' style property, this method
+    #     needs to be overridden to return +true+.
+    #
+    # #empty?::
+    #     This method should return +true+ if the subclass won't draw anything when #draw is called.
+    #
+    # #fit::
+    #     This method should return +true+ if fitting was successful. Additionally, the
+    #     @fit_successful instance variable needs to be set to the fit result as it is used in
+    #     #split.
+    #
+    #     The default implementation provides code common to most use-cases and delegates the
+    #     specifics to the #fit_content method which needs to return +true+ if fitting was
+    #     successful.
+    #
+    # #split::
+    #     This method splits the content so that the current region is used as good as possible. The
+    #     default implementation should be fine for most use-cases, so only #split_content needs to
+    #     be implemented. The method #create_split_box should be used for getting a basic cloned
+    #     box.
+    #
+    # #draw::
+    #     This method draws the content and the default implementation already handles things like
+    #     drawing the border and background. So it should not be overridden. The box specific
+    #     drawing commands should be implemented in the #draw_content method.
+    #
+    # This base class provides various private helper methods for use in the above methods:
+    #
+    # +reserved_width+, +reserved_height+::
+    #     Returns the width respectively the height of the reserved space inside the box that is
+    #     used for the border and padding.
+    #
+    # +reserved_width_left+, +reserved_width_right+, +reserved_height_top+,
+    # +reserved_height_bottom+::
+    #     Returns the reserved space inside the box at the specified edge (left, right, top,
+    #     bottom).
     #
-    # #split:: This method splits the content so that the current region is used as good as
-    #          possible. The default implementation should be fine for most use-cases, so only
-    #          #split_content needs to be implemented. The method #create_split_box should be used
-    #          for getting a basic cloned box.
+    # +update_content_width+, +update_content_height+::
+    #     Takes a block that should return the content width respectively height and sets the box's
+    #     width respectively height accordingly.
     #
-    # #empty?:: This method should return +true+ if the subclass won't draw anything when #draw is
-    #           called.
+    # +create_split_box+::
+    #     Creates a new box based on this one and resets the internal data back to their original
+    #     values.
     #
-    # #draw:: This method draws the content and the default implementation already handles things
-    #         like drawing the border and background. Therefore it's best to implement #draw_content
-    #         which should just draw the content.
+    #     The keyword argument +split_box_value+ (defaults to +true+) is used to set the
+    #     +@split_box+ variable to make the new box aware that it is a split box. This can be set to
+    #     any other truthy value to convey more meaning.
     class Box
 
       include HexaPDF::Utils
@@ -162,7 +193,8 @@ module HexaPDF
         @split_box = false
       end
 
-      # Returns +true+ if this is a split box, i.e. the rest of another box after it was split.
+      # Returns the set truthy value if this is a split box, i.e. the rest of another box after it
+      # was split.
       def split_box?
         @split_box
       end
@@ -184,18 +216,34 @@ module HexaPDF
         height < 0 ? 0 : height
       end
 
-      # Fits the box into the Frame and returns +true+ if fitting was successful.
+      # Fits the box into the *frame* and returns +true+ if fitting was successful.
       #
       # The arguments +available_width+ and +available_height+ are the width and height of the
-      # current region of the frame. The frame itself is provided as third argument.
+      # current region of the frame, adjusted for this box. The frame itself is provided as third
+      # argument.
       #
-      # The default implementation uses the available width and height for the box width and height
-      # if they were initially set to 0. Otherwise the specified dimensions are used.
-      def fit(available_width, available_height, _frame)
+      # The default implementation uses the given available width and height for the box width and
+      # height if they were initially set to 0. Otherwise the intially specified dimensions are
+      # used. Then the #fit_content method is called which allows sub-classes to fit their content.
+      #
+      # The following variables are set that may later be used during splitting or drawing:
+      #
+      # * (@fit_x, @fit_y): The lower-left corner of the content box where fitting was done. Can be
+      #   used to adjust the drawing position in #draw/#draw_content if necessary.
+      # * @fit_successful: +true+ if fitting was successful.
+      def fit(available_width, available_height, frame)
         @width = (@initial_width > 0 ? @initial_width : available_width)
         @height = (@initial_height > 0 ? @initial_height : available_height)
         @fit_successful = (float_compare(@width, available_width) <= 0 &&
                            float_compare(@height, available_height) <= 0)
+        return unless @fit_successful
+
+        @fit_successful = fit_content(available_width, available_height, frame)
+
+        @fit_x = frame.x + reserved_width_left
+        @fit_y = frame.y - @height + reserved_height_bottom
+
+        @fit_successful
       end
 
       # Tries to split the box into two, the first of which needs to fit into the current region of
@@ -237,6 +285,8 @@ module HexaPDF
       # arguments. Subclasses can specify an on-demand drawing method by setting the +@draw_block+
       # instance variable to +nil+ or a valid block. This is useful to avoid unnecessary set-up
       # operations when the block does nothing.
+      #
+      # Alternatively, if a #draw_content method is defined, this method is called.
       def draw(canvas, x, y)
         if (oc = properties['optional_content'])
           canvas.optional_content(oc)
@@ -316,12 +366,26 @@ module HexaPDF
         result
       end
 
-      # Draws the content of the box at position [x, y] which is the bottom-left corner of the
-      # content box.
-      def draw_content(canvas, x, y)
-        if @draw_block
-          canvas.translate(x, y) { @draw_block.call(canvas, self) }
-        end
+      # Updates the width of the box using the content width returned by the block.
+      def update_content_width
+        return if @initial_width > 0
+        @width = yield + reserved_width
+      end
+
+      # Updates the height of the box using the content height returned by the block.
+      def update_content_height
+        return if @initial_height > 0
+        @height = yield + reserved_height
+      end
+
+      # Fits the content of the box and returns whether fitting was successful.
+      #
+      # This is just a stub implementation that returns +true+. Subclasses should override it to
+      # provide the box specific behaviour.
+      #
+      # See #fit for details.
+      def fit_content(available_width, available_height, frame)
+        true
       end
 
       # Splits the content of the box.
@@ -335,6 +399,17 @@ module HexaPDF
         [nil, self]
       end
 
+      # Draws the content of the box at position [x, y] which is the bottom-left corner of the
+      # content box.
+      #
+      # This implementation uses the drawing block provided on initialization, if set, to draw the
+      # contents. Subclasses should override it to provide box specific behaviour.
+      def draw_content(canvas, x, y)
+        if @draw_block
+          canvas.translate(x, y) { @draw_block.call(canvas, self) }
+        end
+      end
+
       # Creates a new box based on this one and resets the data back to their original values.
       #
       # The variable +@split_box+ is set to +split_box_value+ (defaults to +true+) to make the new

data/lib/hexapdf/layout/container_box.rb

@@ -0,0 +1,159 @@
+# -*- 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-2023 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/layout/box'
+require 'hexapdf/layout/box_fitter'
+require 'hexapdf/layout/frame'
+
+module HexaPDF
+  module Layout
+
+    # This is a simple container box for laying out a number of boxes together. It is registered
+    # under the :container name.
+    #
+    # The box does not support the value :flow for the style property position, so the child boxes
+    # are laid out in the current region only. Since the boxes should be laid out together, if any
+    # box doesn't fit, the whole container doesn't fit. Splitting the container is also not possible
+    # for the same reason.
+    #
+    # By default the child boxes are laid out from top to bottom by default. By appropriately
+    # setting the style properties 'mask_mode', 'align' and 'valign', it is possible to lay out the
+    # children bottom to top, left to right, or right to left:
+    #
+    # * The standard top to bottom layout:
+    #
+    #     #>pdf-composer100
+    #     composer.container do |container|
+    #       container.box(:base, height: 20, style: {background_color: "hp-blue-dark"})
+    #       container.box(:base, height: 20, style: {background_color: "hp-blue"})
+    #       container.box(:base, height: 20, style: {background_color: "hp-blue-light"})
+    #     end
+    #
+    # * The bottom to top layout (using valign = :bottom to fill up from the bottom and mask_mode =
+    #   :fill_horizontal to only remove the area to the left and right of the box):
+    #
+    #     #>pdf-composer100
+    #     composer.container do |container|
+    #       container.box(:base, height: 20, style: {background_color: "hp-blue-dark",
+    #                                                mask_mode: :fill_horizontal, valign: :bottom})
+    #       container.box(:base, height: 20, style: {background_color: "hp-blue",
+    #                                                mask_mode: :fill_horizontal, valign: :bottom})
+    #       container.box(:base, height: 20, style: {background_color: "hp-blue-light",
+    #                                                mask_mode: :fill_horizontal, valign: :bottom})
+    #     end
+    #
+    # * The left to right layout (using mask_mode = :fill_vertical to fill the area to the top and
+    #   bottom of the box):
+    #
+    #     #>pdf-composer100
+    #     composer.container do |container|
+    #       container.box(:base, width: 20, style: {background_color: "hp-blue-dark",
+    #                                               mask_mode: :fill_vertical})
+    #       container.box(:base, width: 20, style: {background_color: "hp-blue",
+    #                                               mask_mode: :fill_vertical})
+    #       container.box(:base, width: 20, style: {background_color: "hp-blue-light",
+    #                                               mask_mode: :fill_vertical})
+    #     end
+    #
+    # * The right to left layout (using align = :right to fill up from the right and mask_mode =
+    #   :fill_vertical to fill the area to the top and bottom of the box):
+    #
+    #     #>pdf-composer100
+    #     composer.container do |container|
+    #       container.box(:base, width: 20, style: {background_color: "hp-blue-dark",
+    #                                               mask_mode: :fill_vertical, align: :right})
+    #       container.box(:base, width: 20, style: {background_color: "hp-blue",
+    #                                               mask_mode: :fill_vertical, align: :right})
+    #       container.box(:base, width: 20, style: {background_color: "hp-blue-light",
+    #                                               mask_mode: :fill_vertical, align: :right})
+    #     end
+    class ContainerBox < Box
+
+      # The child boxes of this ContainerBox. They need to be finalized before #fit is called.
+      attr_reader :children
+
+      # Creates a new container box, optionally accepting an array of child boxes.
+      #
+      # Example:
+      #
+      #   #>pdf-composer100
+      #   composer.text("A paragraph here")
+      #   composer.container(height: 40, style: {border: {width: 1}, padding: 5,
+      #                                          align: :center}) do |container|
+      #     container.text("Some", mask_mode: :fill_vertical)
+      #     container.text("text", mask_mode: :fill_vertical, valign: :center)
+      #     container.text("here", mask_mode: :fill_vertical, valign: :bottom)
+      #   end
+      #   composer.text("Another paragraph")
+      def initialize(children: [], **kwargs)
+        super(**kwargs)
+        @children = children
+      end
+
+      # Returns +true+ if no box was fitted into the container.
+      def empty?
+        super && (!@box_fitter || @box_fitter.fit_results.empty?)
+      end
+
+      private
+
+      # Fits the children into the container.
+      def fit_content(available_width, available_height, frame)
+        my_frame = Frame.new(frame.x + reserved_width_left, frame.y - @height + reserved_height_bottom,
+                             content_width, content_height, context: frame.context)
+        @box_fitter = BoxFitter.new([my_frame])
+        children.each {|box| @box_fitter.fit(box) }
+
+        if @box_fitter.fit_successful?
+          update_content_width do
+            result = @box_fitter.fit_results.max_by {|result| result.mask.x + result.mask.width }
+            children.size > 0 ? result.mask.x + result.mask.width - my_frame.left : 0
+          end
+          update_content_height { @box_fitter.content_heights.max }
+          true
+        end
+      end
+
+      # Draws the image onto the canvas at position [x, y].
+      def draw_content(canvas, x, y)
+        dx = x - @fit_x
+        dy = y - @fit_y
+        @box_fitter.fit_results.each {|result| result.draw(canvas, dx: dx, dy: dy) }
+      end
+
+    end
+
+  end
+end

data/lib/hexapdf/layout/frame.rb

@@ -128,17 +128,20 @@ module HexaPDF
           @success
         end
 
-        # Draws the #box onto the canvas at (#x, #y).
+        # Draws the #box onto the canvas at (#x + *dx*, #y + *dy*).
+        #
+        # The relative offset (dx, dy) is useful when rendering results that were accumulated and
+        # then need to be moved because the container holding them changes its position.
         #
         # The configuration option "debug" can be used to add visual debug output with respect to
         # box placement.
-        def draw(canvas)
+        def draw(canvas, dx: 0, dy: 0)
           doc = canvas.context.document
           if doc.config['debug']
             name = "#{box.class} (#{x.to_i},#{y.to_i}-#{box.width.to_i}x#{box.height.to_i})"
             ocg = doc.optional_content.ocg(name)
             canvas.optional_content(ocg) do
-              canvas.save_graphics_state do
+              canvas.translate(dx, dy) do
                 canvas.fill_color("green").stroke_color("darkgreen").
                   opacity(fill_alpha: 0.1, stroke_alpha: 0.2).
                   draw(:geom2d, object: mask, path_only: true).fill_stroke
@@ -146,7 +149,7 @@ module HexaPDF
             end
             doc.optional_content.default_configuration.add_ocg_to_ui(ocg, path: 'Debug')
           end
-          box.draw(canvas, x, y)
+          box.draw(canvas, x + dx, y + dy)
         end
 
       end

data/lib/hexapdf/layout/list_box.rb

@@ -232,7 +232,8 @@ module HexaPDF
 
           if index != 0 || !split_box? || @split_box == :show_first_marker
             box = item_marker_box(frame.document, index)
-            break unless box.fit(content_indentation, height, nil)
+            marker_frame = Frame.new(0, 0, content_indentation, height, context: frame.context)
+            break unless box.fit(content_indentation, height, marker_frame)
             item_result.marker = box
             item_result.marker_pos_x = item_frame.x - content_indentation
             item_result.height = box.height

data/lib/hexapdf/layout.rb

@@ -58,6 +58,7 @@ module HexaPDF
     autoload(:ListBox, 'hexapdf/layout/list_box')
     autoload(:PageStyle, 'hexapdf/layout/page_style')
     autoload(:TableBox, 'hexapdf/layout/table_box')
+    autoload(:ContainerBox, 'hexapdf/layout/container_box')
 
   end
 

data/lib/hexapdf/type/annotation.rb

@@ -132,6 +132,77 @@ module HexaPDF
       define_field :StructParent, type: Integer, version: '1.3'
       define_field :OC,           type: Dictionary, version: '1.5'
 
+      ##
+      # :method: flags
+      #
+      # Returns an array of flag names representing the set bit flags for /F.
+      #
+      # The available flags are:
+      #
+      # :invisible or 0::
+      #     Applies only to non-standard annotations. If set, do not render or print the annotation.
+      #
+      # :hidden or 1::
+      #     If set, do not render the annotation or allow interactions.
+      #
+      # :print or 2::
+      #     If set, print the annotation unless the hidden flag is also set. Otherwise never print
+      #     the annotation.
+      #
+      # :no_zoom or 3::
+      #     If set, do not scale the annotation's appearance to match the magnification of the page.
+      #
+      # :no_rotate or 4::
+      #     If set, do not rotate the annotation's appearance to match the rotation of the page.
+      #
+      # :no_view or 5::
+      #     If set, do not render the annotation on the screen or allow interactions.
+      #
+      # :read_only or 6::
+      #     If set, do not allow user interactions.
+      #
+      # :locked or 7::
+      #     If set, do not allow the annotation to be deleted or its properties be modified.
+      #
+      # :toggle_no_view or 8::
+      #     If set, invert the interpretation of the :no_view flag for annotation selection and
+      #     mouse hovering.
+      #
+      # :locked_contents or 9::
+      #     If set, do not allow the contents of the annotation to be modified.
+      #
+
+      ##
+      # :method: flagged?
+      # :call-seq:
+      #   flagged?(flag)
+      #
+      # Returns +true+ if the given flag is set on /F. The argument can either be the flag name or
+      # the bit index.
+      #
+      # See #flags for the list of available flags.
+      #
+
+      ##
+      # :method: flag
+      # :call-seq:
+      #   flag(*flags, clear_existing: false)
+      #
+      # Sets the given flags on /F, given as flag names or bit indices. If +clear_existing+ is
+      # +true+, all prior flags will be cleared.
+      #
+      # See #flags for the list of available flags.
+      #
+
+      ##
+      # :method: unflag
+      # :call-seq:
+      #   flag(*flags)
+      #
+      # Clears the given flags from /F, given as flag names or bit indices.
+      #
+      # See #flags for the list of available flags.
+      #
       bit_field(:flags, {invisible: 0, hidden: 1, print: 2, no_zoom: 3, no_rotate: 4,
                          no_view: 5, read_only: 6, locked: 7, toggle_no_view: 8,
                          locked_contents: 9},

data/lib/hexapdf/type/catalog.rb

@@ -71,7 +71,7 @@ module HexaPDF
       define_field :AA,                type: Dictionary, version: '1.4'
       define_field :URI,               type: Dictionary, version: '1.1'
       define_field :AcroForm,          type: :XXAcroForm, version: '1.2'
-      define_field :Metadata,          type: Stream,     indirect: true, version: '1.4'
+      define_field :Metadata,          type: :Metadata,  indirect: true, version: '1.4'
       define_field :StructTreeRoot,    type: Dictionary, version: '1.3'
       define_field :MarkInfo,          type: :XXMarkInformation, version: '1.4'
       define_field :Lang,              type: String,     version: '1.4'

data/lib/hexapdf/type/font_simple.rb

@@ -95,7 +95,8 @@ module HexaPDF
       # Returns the UTF-8 string for the given character code, or calls the configuration option
       # 'font.on_missing_unicode_mapping' if no mapping was found.
       def to_utf8(code)
-        to_unicode_cmap&.to_unicode(code) || encoding.unicode(code) || missing_unicode_mapping(code)
+        to_unicode_cmap&.to_unicode(code) || (encoding.unicode(code) rescue nil) ||
+          missing_unicode_mapping(code)
       end
 
       # Returns the unscaled width of the given code point in glyph units, or 0 if the width for

data/lib/hexapdf/type/metadata.rb

@@ -0,0 +1,63 @@
+# -*- 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-2023 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/stream'
+
+module HexaPDF
+  module Type
+
+    # Represents an XMP metadata stream.
+    #
+    # XMP metadata streams may be attached to most PDF objects, though it only makes sense for some
+    # of them.
+    #
+    # There is also a main XMP metadata stream for the whole document that is accessible via the
+    # /Metadata key of the document catalog. That metadata stream should contain the same values as
+    # the PDF's info dictionary and may contain additional entries. This can be accomplished via
+    # HexaPDF::Document#metadata.
+    #
+    # See: PDF2.0 s14.3.2
+    class Metadata < Stream
+
+      define_type :Metadata
+
+      define_field :Type, type: Symbol, default: type, required: true
+      define_field :Subtype, type: Symbol, default: :XML, required: true
+
+    end
+
+  end
+end

data/lib/hexapdf/type.rb

@@ -80,6 +80,7 @@ module HexaPDF
     autoload(:OptionalContentMembership, 'hexapdf/type/optional_content_membership')
     autoload(:OptionalContentProperties, 'hexapdf/type/optional_content_properties')
     autoload(:OptionalContentConfiguration, 'hexapdf/type/optional_content_configuration')
+    autoload(:Metadata, 'hexapdf/type/metadata')
 
   end
 

data/lib/hexapdf/version.rb

@@ -37,6 +37,6 @@
 module HexaPDF
 
   # The version of HexaPDF.
-  VERSION = '0.35.1'
+  VERSION = '0.37.0'
 
 end

data/test/hexapdf/document/test_layout.rb

@@ -175,6 +175,12 @@ describe HexaPDF::Document::Layout do
       assert_equal(2, box.children.size)
     end
 
+    it "uses the provided block as drawing block for the base box class if name=:base" do
+      block = proc {}
+      box = @layout.box(width: 100, &block)
+      assert_equal(block, box.instance_variable_get(:@draw_block))
+    end
+
     it "fails if the name is not registered" do
       assert_raises(HexaPDF::Error) { @layout.box(:unknown) }
     end