hexapdf 0.32.2 → 0.34.0

data/lib/hexapdf/font/encoding/mac_expert_encoding.rb

@@ -42,7 +42,7 @@ module HexaPDF
 
       # The MacExpertEncoding for Latin texts.
       #
-      # See: PDF1.7 sD.4
+      # See: PDF2.0 sD.4
       class MacExpertEncoding < Base
 
         def initialize #:nodoc:

data/lib/hexapdf/font/encoding/mac_roman_encoding.rb

@@ -42,7 +42,7 @@ module HexaPDF
 
       # The Mac Roman standard encoding for Latin texts.
       #
-      # See: PDF1.7 sD.1, sD.2
+      # See: PDF2.0 sD.1, sD.2
       class MacRomanEncoding < Base
 
         def initialize #:nodoc:
@@ -256,7 +256,7 @@ module HexaPDF
             0264 => :yen,
             0172 => :z,
             0060 => :zero,
-            # additions due to PDF1.7 sD.2 footnote 6
+            # additions due to PDF2.0 sD.2 footnote 6
             0312 => :space,
           }
         end

data/lib/hexapdf/font/encoding/standard_encoding.rb

@@ -42,7 +42,7 @@ module HexaPDF
 
       # The Adobe standard encoding for Latin texts.
       #
-      # See: PDF1.7 sD.1, sD.2
+      # See: PDF2.0 sD.1, sD.2
       class StandardEncoding < Base
 
         def initialize #:nodoc:

data/lib/hexapdf/font/encoding/symbol_encoding.rb

@@ -42,7 +42,7 @@ module HexaPDF
 
       # The built-in encoding of the Symbol font.
       #
-      # See: PDF1.7 sD.5
+      # See: PDF2.0 sD.5
       class SymbolEncoding < Base
 
         def initialize #:nodoc:

data/lib/hexapdf/font/encoding/win_ansi_encoding.rb

@@ -42,7 +42,7 @@ module HexaPDF
 
       # The Windows Code Page 1252, the standard Windows encoding for Latin texts.
       #
-      # See: PDF1.7 sD.1, sD.2
+      # See: PDF2.0 sD.1, sD.2
       class WinAnsiEncoding < Base
 
         def initialize #:nodoc:
@@ -265,11 +265,11 @@ module HexaPDF
             0172 => :z,
             0236 => :zcaron,
             0060 => :zero,
-            # additions due to PDF1.7 sD.2 footnote 5,6
+            # additions due to PDF2.0 sD.2 footnote 5,6
             0240 => :space,
             0255 => :hyphen,
           }
-          # additions due to PDF1.7 sD.2 footnote 3
+          # additions due to PDF2.0 sD.2 footnote 3
           041.upto(255) do |i|
             next if @code_to_name.key?(i)
             @code_to_name[i] = :bullet

data/lib/hexapdf/font/encoding/zapf_dingbats_encoding.rb

@@ -42,7 +42,7 @@ module HexaPDF
 
       # The built-in encoding of the ZapfDingbats font.
       #
-      # See: PDF1.7 sD.6
+      # See: PDF2.0 sD.6
       class ZapfDingbatsEncoding < Base
 
         def initialize #:nodoc:

data/lib/hexapdf/font/invalid_glyph.rb

@@ -41,6 +41,9 @@ module HexaPDF
     # font.
     class InvalidGlyph
 
+      # The associated font object.
+      attr_reader :font
+
       # The string that could not be represented as a glyph.
       attr_reader :str
 

data/lib/hexapdf/font/true_type_wrapper.rb

@@ -51,7 +51,7 @@ module HexaPDF
     #
     # * By using a composite font more than 256 characters can be encoded with one font object.
     # * Fonts for vertical writing can potentially be used.
-    # * The PDF specification recommends using a composite font (see PDF1.7 s9.9 at the end).
+    # * The PDF specification recommends using a composite font (see PDF2.0 s9.9.1 at the end).
     #
     # Additionally, TrueType fonts are *always* embedded.
     class TrueTypeWrapper
@@ -59,6 +59,9 @@ module HexaPDF
       # Represents a single glyph of the wrapped font.
       class Glyph
 
+        # The associated font object.
+        attr_reader :font
+
         # The glyph ID.
         attr_reader :id
 
@@ -171,6 +174,18 @@ module HexaPDF
           end
       end
 
+      # Returns a custom Glyph object which represents the given +string+ via the given glyph +id+.
+      #
+      # This functionality can be used to associate a single glyph id with multiple, different
+      # strings for replacement glyph purposes. When used in such a way, the used glyph id is often
+      # 0 which represents the missing glyph.
+      def custom_glyph(id, string)
+        if id < 0 || id >= @wrapped_font[:maxp].num_glyphs
+          raise HexaPDF::Error, "Glyph ID #{id} is invalid for font '#{@wrapped_font.full_name}'"
+        end
+        Glyph.new(@wrapped_font, id, string)
+      end
+
       # Returns an array of glyph objects representing the characters in the UTF-8 encoded string.
       def decode_utf8(str)
         str.codepoints.map! do |c|
@@ -187,9 +202,7 @@ module HexaPDF
       def encode(glyph)
         (@encoded_glyphs[glyph.id] ||=
           begin
-            if glyph.kind_of?(InvalidGlyph)
-              raise HexaPDF::Error, "Glyph for #{glyph.str.inspect} missing"
-            end
+            raise HexaPDF::MissingGlyphError.new(glyph) if glyph.kind_of?(InvalidGlyph)
             if @subsetter
               [[@subsetter.use_glyph(glyph.id)].pack('n'), glyph]
             else

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.
@@ -120,10 +127,24 @@ module HexaPDF
       #
       # This can be used to store arbitrary information on boxes for later use. For example, a
       # generic style layer could use one or more custom properties for its work.
+      #
+      # The Box class itself uses the following properties:
+      #
+      # optional_content::
+      #
+      #       If this property is set, it needs to be an optional content group dictionary, a String
+      #       defining an (optionally existing) optional content group dictionary, or an optional
+      #       content membership dictionary.
+      #
+      #       The whole content of the box, i.e. including padding, border, background..., is
+      #       wrapped with the appropriate commands so that the optional content group or membership
+      #       dictionary specifies whether the content is shown or not.
+      #
+      #       See: HexaPDF::Type::OptionalContentProperties
       attr_reader :properties
 
       # :call-seq:
-      #    Box.new(width: 0, height: 0, style: nil, properties: {}) {|canv, box| block} -> box
+      #    Box.new(width: 0, height: 0, style: nil, properties: nil) {|canv, box| block} -> box
       #
       # Creates a new Box object with the given width and height that uses the provided block when
       # it is asked to draw itself on a canvas (see #draw).
@@ -131,11 +152,11 @@ module HexaPDF
       # Since the final location of the box is not known beforehand, the drawing operations inside
       # the block should draw inside the rectangle (0, 0, content_width, content_height) - note that
       # the width and height of the box may not be known beforehand.
-      def initialize(width: 0, height: 0, style: nil, properties: {}, &block)
+      def initialize(width: 0, height: 0, style: nil, properties: nil, &block)
         @width = @initial_width = width
         @height = @initial_height = height
         @style = Style.create(style)
-        @properties = properties
+        @properties = properties || {}
         @draw_block = block
         @fit_successful = false
         @split_box = false
@@ -213,6 +234,10 @@ module HexaPDF
       # instance variable to +nil+ or a valid block. This is useful to avoid unnecessary set-up
       # operations when the block does nothing.
       def draw(canvas, x, y)
+        if (oc = properties['optional_content'])
+          canvas.optional_content(oc)
+        end
+
         if style.background_color? && style.background_color
           canvas.save_graphics_state do
             canvas.opacity(fill_alpha: style.background_alpha).
@@ -226,6 +251,8 @@ module HexaPDF
         draw_content(canvas, x + reserved_width_left, y + reserved_height_bottom)
 
         style.overlays.draw(canvas, x, y, self) if style.overlays?
+
+        canvas.end_optional_content if oc
       end
 
       # Returns +true+ if no drawing operations are performed.

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
@@ -171,7 +177,8 @@ module HexaPDF
                                      [column_left, column_bottom + height])
               shape = Geom2D::Algorithms::PolygonOperation.run(frame.shape, rect, :intersection)
             end
-            column_frame = Frame.new(column_left, column_bottom, column_width, height, shape: shape)
+            column_frame = Frame.new(column_left, column_bottom, column_width, height,
+                                     shape: shape, context: frame.context)
             @box_fitter << column_frame
           end
 
@@ -199,6 +206,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 +246,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