hexapdf 0.32.2 → 0.33.0

data/lib/hexapdf/font/type1_wrapper.rb

@@ -48,6 +48,9 @@ module HexaPDF
       # Represents a single glyph of the wrapped font.
       class Glyph
 
+        # The associated font object.
+        attr_reader :font
+
         # The name of the glyph.
         attr_reader :name
         alias id name
@@ -164,6 +167,20 @@ module HexaPDF
           end
       end
 
+      # Returns a custom Glyph object which represents the given +string+ via the given glyph
+      # +name+.
+      #
+      # This functionality can be used to associate a single glyph name with multiple, different
+      # strings for replacement glyph purposes. When used in such a way, the used glyph name is
+      # often :question.
+      def custom_glyph(name, string)
+        unless @wrapped_font.metrics.character_metrics.key?(name)
+          raise HexaPDF::Error, "Glyph named #{name.inspect} not found in " \
+            "font '#{@wrapped_font.full_name}'"
+        end
+        Glyph.new(@wrapped_font, name, string)
+      end
+
       # Returns an array of glyph objects representing the characters in the UTF-8 encoded string.
       #
       # If a Unicode codepoint is not available as glyph object, it is tried to map the codepoint
@@ -188,9 +205,7 @@ module HexaPDF
       def encode(glyph)
         @encoded_glyphs[glyph.name] ||=
           begin
-            if glyph.name == @wrapped_font.missing_glyph_id
-              raise HexaPDF::Error, "Glyph for #{glyph.str.inspect} missing"
-            end
+            raise HexaPDF::MissingGlyphError.new(glyph) if glyph.kind_of?(InvalidGlyph)
             code = @encoding.code(glyph.name)
             if code
               code.chr.freeze
@@ -199,7 +214,7 @@ module HexaPDF
               @encoding.code_to_name[@max_code] = glyph.name
               @max_code.chr.freeze
             else
-              raise HexaPDF::Error, "Type1 encoding has no codepoint for #{glyph.name}"
+              raise HexaPDF::Error, "Used Type1 encoding has no codepoint for #{glyph.name.inspect}"
             end
           end
       end

data/lib/hexapdf/font_loader/from_configuration.rb

@@ -43,13 +43,14 @@ module HexaPDF
     # This module uses the configuration option 'font.map' for loading a font.
     module FromConfiguration
 
-      # Loads the given font by looking up the needed file in the 'font.map' configuration option.
+      # Returns a TrueType font wrapper for the given font by looking up the needed file in the
+      # 'font.map' configuration option.
       #
       # The file object representing the font file is *not* closed and if needed must be closed by
       # the caller once the font is not needed anymore.
       #
       # +document+::
-      #     The PDF document to associate the font object with.
+      #     The PDF document to associate the font wrapper with.
       #
       # +name+::
       #     The name of the font.
@@ -59,6 +60,8 @@ module HexaPDF
       #
       # +subset+::
       #     Specifies whether the font should be subset if possible.
+      #
+      # This method uses the FromFile font loader behind the scenes.
       def self.call(document, name, variant: :none, subset: true)
         file = document.config['font.map'].dig(name, variant)
         return nil if file.nil?

data/lib/hexapdf/font_loader/from_file.rb

@@ -39,15 +39,15 @@ require 'hexapdf/font/true_type_wrapper'
 module HexaPDF
   module FontLoader
 
-    # This module interprets the font name either as file name and tries to load it, or as font
-    # object to be wrapped directly.
+    # This module interprets the font name either as file name and tries to load it, or as TrueType
+    # font object to be wrapped directly.
     module FromFile
 
       # :call-seq:
       #   FromFile.call(document, file_name, subset: true, **)           -> wrapped_font
       #   FromFile.call(document, font_object, subset: true, **)    -> wrapped_font
       #
-      # Returns an appropriate font wrapper for the given file name or font object.
+      # Returns an appropriate font wrapper for the given file name or TrueType font object.
       #
       # If a file name is given, the file object representing the font file is *not* closed and if
       # needed must be closed by the caller once the font is not needed anymore.
@@ -57,10 +57,10 @@ module HexaPDF
       # font file.
       #
       # +document+::
-      #     The PDF document to associate the font object with.
+      #     The PDF document to associate the font wrapper with.
       #
       # +file_name+/+font_object+::
-      #     The file name or TrueType font object.
+      #     The file name or a HexaPDF::Font::TrueType::Font object.
       #
       # +subset+::
       #     Specifies whether the font should be subset if possible.

data/lib/hexapdf/font_loader/standard14.rb

@@ -71,10 +71,10 @@ module HexaPDF
         },
       }.freeze
 
-      # Creates a new font object backed by the AFM font metrics read from the file or IO stream.
+      # Returns a font wrapper for the named Standard PDF font.
       #
       # +document+::
-      #     The PDF document to associate the font object with.
+      #     The PDF document to associate the font wrapper with.
       #
       # +name+::
       #     The name of the built-in font. One of Times, Helvetica, Courier, Symbol or ZapfDingbats.
@@ -85,7 +85,7 @@ module HexaPDF
       #
       # +custom_encoding+::
       #     For Times, Helvetica and Courier the standard encoding WinAnsiEncoding is used. If this
-      #     option is not wanted because access to other glyphs is needed, set this to +true+
+      #     is not wanted because access to other glyphs is needed, set this to +true+
       def self.call(document, name, variant: :none, custom_encoding: false, **)
         name = MAPPING[name] && MAPPING[name][variant]
         return nil if name.nil?

data/lib/hexapdf/font_loader.rb

@@ -63,6 +63,7 @@ module HexaPDF
   # Optionally, a font loader can provide a method +available_fonts(document)+ that returns a hash
   # where the keys are the font names and the values are the variants of all the provided fonts.
   #
+  #
   # == Font Wrappers
   #
   # A font wrapper needs to provide the following generic interface so that it can be used correctly
@@ -80,6 +81,8 @@ module HexaPDF
   #     and returns an encoded string that can be decoded with the font dictionary returned by
   #     \#dict.
   #
+  # HexaPDF contains a font wrapper implementation for the Standard 14 PDF fonts (see
+  # HexaPDF::Font::Type1Wrapper) and one for TrueType fonts (see HexaPDF::Font::TrueTypeWrapper).
   module FontLoader
 
     autoload(:Standard14, 'hexapdf/font_loader/standard14')

data/lib/hexapdf/image_loader/jpeg.rb

@@ -41,7 +41,7 @@ module HexaPDF
 
     # This module is used for loading images in the JPEG format from files or IO streams.
     #
-    # See: PDF1.7 s7.4.8, ITU T.81 Annex B, ITU T.872
+    # See: PDF2.0 s7.4.8, ITU T.81 Annex B, ITU T.872
     module JPEG
 
       # The magic marker that tells us if the file/IO contains an image in JPEG format.
@@ -139,7 +139,7 @@ module HexaPDF
           break if components != 4 || invert_colors
         end
 
-        # PDF1.7 s8.9.5.1
+        # PDF2.0 s8.9.5.1
         if bits != 8
           raise HexaPDF::Error, "Unsupported number of bits per component: #{bits}"
         end

data/lib/hexapdf/image_loader/pdf.rb

@@ -46,7 +46,7 @@ module HexaPDF
     # image/xobject drawing methods of HexaPDF::Content::Canvas know how to handle them correctly so
     # that this doesn't matter from a user's point of view.
     #
-    # See: PDF1.7 s8.10
+    # See: PDF2.0 s8.10
     module PDF
 
       # The magic marker that tells us if the file/IO contains an PDF file.

data/lib/hexapdf/image_loader/png.rb

@@ -52,7 +52,7 @@ module HexaPDF
     #
     # All PNG specification section references are in reference to http://www.w3.org/TR/PNG/.
     #
-    # See: PDF1.7 s7.4.4., s8.9
+    # See: PDF2.0 s7.4.4., s8.9
     class PNG
 
       # The magic marker that tells us if the file/IO contains an image in PNG format.
@@ -261,7 +261,7 @@ module HexaPDF
       # Returns a hash for a CalRGB color space definition using the x,y chromaticity coordinates
       # of the white point and the red, green and blue primaries.
       #
-      # See: PDF1.7 s8.6.5.3
+      # See: PDF2.0 s8.6.5.3
       def calrgb_definition_from_chrm(xw, yw, xr, yr, xg, yg, xb, yb)
         z = yw * ((xg - xb) * yr - (xr - xb) * yg + (xr - xg) * yb)
 

data/lib/hexapdf/image_loader.rb

@@ -59,7 +59,7 @@ module HexaPDF
   # The image XObject may use any implemented filter. For example, an image loader for JPEG files
   # would typically use the DCTDecode filter instead of decoding the image itself.
   #
-  # See: PDF1.7 s8.9
+  # See: PDF2.0 s8.9
   module ImageLoader
 
     autoload(:JPEG, 'hexapdf/image_loader/jpeg')

data/lib/hexapdf/importer.rb

@@ -68,6 +68,19 @@ module HexaPDF
       @map[destination.hash] ||= new(destination)
     end
 
+    # Imports the given +object+ (belonging to the +source+ document) by completely copying it and
+    # all referenced objects into the +destination+ object.
+    #
+    # Specifying +source+ is optionial if it can be determined through +object+.
+    #
+    # After the operation is finished, all state is discarded. This means that another call to this
+    # method for the same object will yield a new - and different - object. This is in contrast to
+    # using ::for together with #import which remembers and returns already imported objects (which
+    # is generally what one wants).
+    def self.copy(destination, object, source: nil)
+      new(NullableWeakRef.new(destination)).import(object, source: source)
+    end
+
     private_class_method :new
 
     attr_reader :destination #:nodoc:

data/lib/hexapdf/layout/box.rb

@@ -60,18 +60,25 @@ 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, #split or #split_content, and #draw or #draw_content need to be customized
-    # according to the subclass's use case.
+    # 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.
     #
+    # #supports_position_flow?::
+    #        If the subclass supports the value :flow of the 'position' style property, this method
+    #        needs to be overridden to return +true+.
+    #
     # #split:: This method splits the content so that the available space 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.
     #
+    # #empty?:: This method should return +true+ if the subclass won't draw anything when #draw is
+    #           called.
+    #
     # #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.

data/lib/hexapdf/layout/box_fitter.rb

@@ -98,7 +98,7 @@ module HexaPDF
           if result.success?
             current_frame.remove_area(result.mask)
             @content_heights[@frame_index] = [@content_heights[@frame_index],
-                                              @initial_frame_y[@frame_index] - result.mask[0].y].max
+                                              @initial_frame_y[@frame_index] - result.mask.y].max
             @fit_results << result
             box = nil
             break
@@ -109,7 +109,7 @@ module HexaPDF
             if draw_box
               current_frame.remove_area(result.mask)
               @content_heights[@frame_index] = [@content_heights[@frame_index],
-                                                @initial_frame_y[@frame_index] - result.mask[0].y].max
+                                                @initial_frame_y[@frame_index] - result.mask.y].max
               @fit_results << result
             elsif !current_frame.find_next_region
               @frame_index += 1

data/lib/hexapdf/layout/column_box.rb

@@ -62,8 +62,9 @@ module HexaPDF
 
       # The columns definition.
       #
-      # This is an array containing the widths of the columns. The size of the array is the number
-      # of columns.
+      # If the value is an array, it needs to contain the widths of the columns. The size of the
+      # array determines the number of columns. Otherwise, if the value is an integer, the value
+      # defines the number of equally sized columns, i.e. a value of +N+ is equal to [-1]*N.
       #
       # If a negative integer is used for the width, the column is auto-sized. Such columns split
       # the remaining width (after substracting the widths of the fixed columns) proportionally
@@ -132,6 +133,11 @@ module HexaPDF
         true
       end
 
+      # Returns +true+ if no box was fitted into the columns.
+      def empty?
+        super && (!@box_fitter || @box_fitter.fit_results.empty?)
+      end
+
       # Fits the column box into the available space.
       #
       # If the style property 'position' is set to :flow, the columns might not be rectangles but
@@ -199,6 +205,8 @@ module HexaPDF
 
         @width = columns[-1].sum + reserved_width
         @height = @box_fitter.content_heights.max + reserved_height
+        @draw_pos_x = frame.x + reserved_width_left
+        @draw_pos_y = frame.y - @height + reserved_height_bottom
 
         @box_fitter.fit_successful?
       end
@@ -237,8 +245,14 @@ module HexaPDF
       end
 
       # Draws the child boxes onto the canvas at position [x, y].
-      def draw_content(canvas, _x, _y)
-        @box_fitter.fit_results.each {|result| result.draw(canvas) }
+      def draw_content(canvas, x, y)
+        if style.position != :flow && (x != @draw_pos_x || y != @draw_pos_y)
+          canvas.translate(x - @draw_pos_x, y - @draw_pos_y) do
+            @box_fitter.fit_results.each {|result| result.draw(canvas) }
+          end
+        else
+          @box_fitter.fit_results.each {|result| result.draw(canvas) }
+        end
       end
 
     end

data/lib/hexapdf/layout/frame.rb

@@ -106,8 +106,8 @@ module HexaPDF
         # The available height in the frame for this particular box.
         attr_accessor :available_height
 
-        # The rectangle (a Geom2D::Polygon object) that will be removed from the frame when drawing
-        # the box.
+        # The rectangle (a Geom2D::Rectangle object) that will be removed from the frame when
+        # drawing the box.
         attr_accessor :mask
 
         # Initialize the result object for the given box.
@@ -157,7 +157,8 @@ module HexaPDF
       # The height of the frame.
       attr_reader :height
 
-      # The shape of the frame, a Geom2D::PolygonSet consisting of rectilinear polygons.
+      # The shape of the frame, either a Geom2D::Rectangle in the simple case or a
+      # Geom2D::PolygonSet consisting of rectilinear polygons in the more complex case.
       attr_reader :shape
 
       # The x-coordinate where the next box will be placed.
@@ -187,9 +188,8 @@ module HexaPDF
         @bottom = bottom
         @width = width
         @height = height
-        @shape = shape || Geom2D::PolygonSet.new(
-          [create_rectangle(left, bottom, left + width, bottom + height)]
-        )
+        @shape = shape || create_rectangle(left, bottom, left + width, bottom + height)
+
         @x = left
         @y = bottom + height
         @available_width = width
@@ -319,8 +319,16 @@ module HexaPDF
       def find_next_region
         case @region_selection
         when :max_width
-          find_max_width_region
-          @region_selection = :max_height
+          if @shape.kind_of?(Geom2D::Rectangle)
+            @x = @shape.x
+            @y = @shape.y + @shape.height
+            @available_width = @shape.width
+            @available_height = @shape.height
+            @region_selection = :trim_shape
+          else
+            find_max_width_region
+            @region_selection = :max_height
+          end
         when :max_height
           x, y, aw, ah = @x, @y, @available_width, @available_height
           find_max_height_region
@@ -338,7 +346,17 @@ module HexaPDF
 
       # Removes the given *rectilinear* polygon from the frame's shape.
       def remove_area(polygon)
-        @shape = Geom2D::Algorithms::PolygonOperation.run(@shape, polygon, :difference)
+        @shape = if @shape.kind_of?(Geom2D::Rectangle) && polygon.kind_of?(Geom2D::Rectangle) &&
+                     float_equal(@shape.x, polygon.x) && float_equal(@shape.width, polygon.width) &&
+                     float_equal(@shape.y + @shape.height, polygon.y + polygon.height)
+                   if float_equal(@shape.height, polygon.height)
+                     Geom2D::PolygonSet()
+                   else
+                     Geom2D::Rectangle(@shape.x, @shape.y, @shape.width, @shape.height - polygon.height)
+                   end
+                 else
+                   Geom2D::Algorithms::PolygonOperation.run(@shape, polygon, :difference)
+                 end
         @region_selection = :max_width
         find_next_region
       end
@@ -369,8 +387,7 @@ module HexaPDF
       # Creates a Geom2D::Polygon object representing the rectangle with the bottom left corner
       # (blx, bly) and the top right corner (trx, try).
       def create_rectangle(blx, bly, trx, try)
-        Geom2D::Polygon(Geom2D::Point(blx, bly), Geom2D::Point(trx, bly),
-                        Geom2D::Point(trx, try), Geom2D::Point(blx, try))
+        Geom2D::Rectangle(blx, bly, trx - blx, try - bly)
       end
 
       # Finds the region with the maximum width.
@@ -404,7 +421,8 @@ module HexaPDF
 
       # Trims the frame's shape so that the next starting point is different.
       def trim_shape
-        return unless (segments = find_starting_point)
+        @x = @y = @available_width = @available_height = 0
+        return if @shape.kind_of?(Geom2D::Rectangle) || !(segments = find_starting_point)
 
         # Just use the second top-most segment
         # TODO: not the optimal solution!

data/lib/hexapdf/layout/image_box.rb

@@ -74,6 +74,11 @@ module HexaPDF
         @image = image
       end
 
+      # Returns +false+ since the image is always drawn if it fits.
+      def empty?
+        false
+      end
+
       # Fits the image into the available space, taking the initially set width and height into
       # account (see the class description for details).
       def fit(available_width, available_height, _frame)

data/lib/hexapdf/layout/inline_box.rb

@@ -73,6 +73,7 @@ module HexaPDF
       # The +valign+ argument can be used to specify the vertical alignment of the box relative to
       # other items in the Line.
       def initialize(box, valign: :baseline)
+        raise HexaPDF::Error, "Width of box not set" if box.width == 0
         @box = box
         @valign = valign
         @fit_result = Frame.new(0, 0, box.width, box.height == 0 ? 100_000 : box.height).fit(box)

data/lib/hexapdf/layout/list_box.rb

@@ -177,6 +177,11 @@ module HexaPDF
         true
       end
 
+      # Returns +true+ if no box was fitted into the list box.
+      def empty?
+        super && (!@results || @results.all? {|box_fitter| box_fitter.fit_results.empty? })
+      end
+
       # Fits the list box into the available space.
       def fit(available_width, available_height, frame)
         @width = if @initial_width > 0
@@ -234,6 +239,8 @@ module HexaPDF
           (@results.count - 1) * item_spacing +
           reserved_height
 
+        @draw_pos_x = frame.x + reserved_width_left
+        @draw_pos_y = frame.y - @height + reserved_height_bottom
         @fit_successful = @results.all?(&:fit_successful?) && @results.size == @children.size
       end
 
@@ -333,7 +340,14 @@ module HexaPDF
       end
 
       # Draws the list items onto the canvas at position [x, y].
-      def draw_content(canvas, _x, _y)
+      def draw_content(canvas, x, y)
+        translate = (style.position != :flow && (x != @draw_pos_x || y != @draw_pos_y))
+
+        if translate
+          canvas.save_graphics_state
+          canvas.translate(x - @draw_pos_x, y - @draw_pos_y)
+        end
+
         @results.each_with_index do |box_fitter, index|
           if index != 0 || !split_box? || @split_box == :show_first_marker
             box = item_marker_box(canvas.context.document, index)
@@ -343,6 +357,8 @@ module HexaPDF
           end
           box_fitter.fit_results.each {|result| result.draw(canvas) }
         end
+
+        canvas.restore_graphics_state if translate
       end
 
     end

data/lib/hexapdf/layout/page_style.rb

@@ -95,8 +95,8 @@ module HexaPDF
       # If this attribute is +nil+ (the default), it means that this style should be used again.
       attr_accessor :next_style
 
-      # Creates a new page style instance for the given page size and orientation. If a block is
-      # given, it is used as template for defining the initial content.
+      # Creates a new page style instance for the given page size, orientation and next style
+      # values. If a block is given, it is used as template for defining the initial content.
       #
       # Example:
       #
@@ -105,12 +105,12 @@ module HexaPDF
       #     style.next_style = :other
       #     canvas.fill_color("fd0") { canvas.circle(100, 100, 50).fill }
       #   end
-      def initialize(page_size: :A4, orientation: :portrait, &block)
+      def initialize(page_size: :A4, orientation: :portrait, next_style: nil, &block)
         @page_size = page_size
         @orientation = orientation
         @template = block
         @frame = nil
-        @next_style = nil
+        @next_style = next_style
       end
 
       # Creates a new page in the given document with this page style and returns it.

data/lib/hexapdf/layout/style.rb

@@ -206,11 +206,16 @@ module HexaPDF
         # The styles of each edge. See Quad.
         attr_reader :style
 
+        # Specifies whether the border should be drawn inside the provided rectangle (+false+,
+        # default) or on it (+true+).
+        attr_accessor :draw_on_bounds
+
         # Creates a new border style. All arguments can be set to any value that a Quad can process.
-        def initialize(width: 0, color: 0, style: :solid)
+        def initialize(width: 0, color: 0, style: :solid, draw_on_bounds: false)
           @width = Quad.new(width)
           @color = Quad.new(color)
           @style = Quad.new(style)
+          @draw_on_bounds = draw_on_bounds
         end
 
         # Duplicates a Border object's properties.
@@ -226,10 +231,20 @@ module HexaPDF
           width.simple? && width.top == 0
         end
 
-        # Draws the border onto the canvas, inside the rectangle (x, y, w, h).
+        # Draws the border onto the canvas.
+        #
+        # Depending on #draw_on_bounds the border is drawn inside the rectangle (x, y, w, h) or on
+        # it.
         def draw(canvas, x, y, w, h)
           return if none?
 
+          if draw_on_bounds
+            x -= width.left / 2.0
+            y -= width.bottom / 2.0
+            w += (width.left + width.right) / 2.0
+            h += (width.top + width.bottom) / 2.0
+          end
+
           canvas.save_graphics_state do
             if width.simple? && color.simple? && style.simple?
               draw_simple_border(canvas, x, y, w, h)
@@ -444,7 +459,7 @@ module HexaPDF
       # Style objects using link annotations. Typical use cases would be linking to a (named)
       # destination on a different page or executing a URI action.
       #
-      # See: PDF1.7 s12.5.6.6, Layers, HexaPDF::Type::Annotations::Link
+      # See: PDF2.0 s12.5.6.5, Layers, HexaPDF::Type::Annotations::Link
       class LinkLayer
 
         # Creates a new LinkLayer object.