hexapdf 0.23.0 → 0.24.0

data/lib/hexapdf/composer.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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
@@ -58,24 +58,6 @@ module HexaPDF
   # page. Behind the scenes HexaPDF::Layout::Box (and subclass) objects are created and drawn on the
   # page via the frame.
   #
-  # All drawing methods accept HexaPDF::Layout::Style objects or names for style objects (defined
-  # via #style). The HexaPDF::Layout::Style#font is handled specially:
-  #
-  # * If no font is set on a style, the font "Times" is automatically set because otherwise there
-  #   would be problems with text drawing operations (font is the only style property that has no
-  #   valid default value).
-  #
-  # * Standard style objects only allow font wrapper objects to be set via the
-  #   HexaPDF::Layout::Style#font method. Composer makes usage easier by allowing strings or an
-  #   array [name, options_hash] to be used, like with e.g Content::Canvas. So using Helvetica as
-  #   font, one could just do this by saying
-  #
-  #     style.font = 'Helvetica'
-  #
-  #   And if Helvetica bold should be used it would be
-  #
-  #     style.font = ['Helvetica', variant: :bold]
-  #
   # If the frame of a page is full and a box doesn't fit anymore, a new page is automatically
   # created. The box is either split into two boxes where one fits on the first page and the other
   # on the new page, or it is drawn completely on the new page. A new page can also be created by
@@ -146,7 +128,6 @@ module HexaPDF
       @page_size = page_size
       @page_orientation = page_orientation
       @margin = Layout::Style::Quad.new(margin)
-      @styles = {base: Layout::Style.new}
 
       new_page
       yield(self) if block_given?
@@ -189,24 +170,14 @@ module HexaPDF
     end
 
     # :call-seq:
-    #    composer.style(:header)                              -> style
-    #    composer.style(:header, base: :base, **properties)   -> style
+    #    composer.style(name)                              -> style
+    #    composer.style(name, base: :base, **properties)   -> style
     #
     # Creates or updates the HexaPDF::Layout::Style object called +name+ with the given property
-    # values and returns it. Such a style can then be used by name in the various box drawing
-    # methods, e.g. #text or #image.
-    #
-    # If neither +base+ nor any style properties are specified, the style +name+ is just returned.
-    #
-    # If the style +name+ does not exist yet and the argument +base+ specifies the name of another
-    # style, that style is duplicated and used as basis for the style.
+    # values and returns it.
     #
-    # The special name :base should be used for setting the base style which is used when no
-    # specific style is set. It is best to fully initialize the base style before creating any
-    # other styles.
-    #
-    # Note that the style property 'font' is handled specially by Composer, see the class
-    # documentation for details.
+    # See HexaPDF::Document::Layout#style for details; this method is just a thin wrapper around
+    # that method.
     #
     # Example:
     #
@@ -216,35 +187,20 @@ module HexaPDF
     #
     # See: HexaPDF::Layout::Style
     def style(name, base: :base, **properties)
-      style = @styles[name] ||= (@styles.key?(base) ? @styles[base].dup : Layout::Style.new)
-      style.update(**properties) unless properties.empty?
-      style
+      @document.layout.style(name, base: base, **properties)
     end
 
     # Draws the given text at the current position into the current frame.
     #
-    # This method is the main method for displaying text on a PDF page. It uses a
-    # HexaPDF::Layout::TextBox behind the scenes to do the actual work.
-    #
     # The text will be positioned at the current position if possible. Otherwise the next best
     # position is used. If the text doesn't fit onto the current page or only partially, new pages
     # are created automatically.
     #
-    # +width+, +height+::
-    #     The arguments +width+ and +height+ are used as constraints and are respected when fitting
-    #     the box. The default value of 0 means that no constraints are set.
+    # This method is of the two main methods for creating text boxes, the other being
+    # #formatted_text. It uses HexaPDF::Document::Layout#text_box behind the scenes to create the
+    # HexaPDF::Layout::TextBox that does the actual work.
     #
-    # +style+, +style_properties+::
-    #     The box and the text are styled using the given +style+. This can either be a style name
-    #     set via #style or anything HexaPDF::Layout::Style::create accepts. If any additional
-    #     +style_properties+ are specified, the style is duplicated and the additional styles are
-    #     applied.
-    #
-    # +box_style+::
-    #     Sometimes it is necessary for the box to have a different style than the text, e.g. when
-    #     using overlays. In such a case use +box_style+ for specifiying the style of the box (a
-    #     style name set via #style or anything HexaPDF::Layout::Style::create accepts). The +style+
-    #     together with the +style_properties+ will be used for the text style.
+    # See HexaPDF::Document::Layout#text_box for details on the arguments.
     #
     # Examples:
     #
@@ -255,35 +211,16 @@ module HexaPDF
     #   composer.text("Different box style", fill_color: 'white', box_style: {
     #     underlays: [->(c, b) { c.rectangle(0, 0, b.content_width, b.content_height).fill }]
     #   })
-    #
-    # See HexaPDF::HexaPDF::Layout::TextBox for details.
     def text(str, width: 0, height: 0, style: nil, box_style: nil, **style_properties)
-      style = retrieve_style(style, style_properties)
-      box_style = (box_style ? retrieve_style(box_style) : style)
-      draw_box(Layout::TextBox.new([Layout::TextFragment.create(str, style)],
-                                   width: width, height: height, style: box_style))
+      draw_box(@document.layout.text_box(str, width: width, height: height, style: style,
+                                         box_style: box_style, **style_properties))
     end
 
     # Draws text like #text but allows parts of the text to be formatted differently.
     #
-    # The argument +data+ needs to be an array of String and/or Hash objects:
-    #
-    # * A String object is treated like {text: data}.
-    #
-    # * Hashes can contain any style properties and the following special keys:
-    #
-    #   text:: The text to be formatted.
-    #
-    #   link:: A URL that should be linked to. If no text is provided but a link, the link is used
-    #          as text.
-    #
-    #   style:: The style to be use as basis instead of the style created from the +style+ and
-    #           +style_properties+ arguments. See HexaPDF::Layout::Style::create for allowed values.
-    #
-    #   If any style properties are set, the used style is copied and the additional properties
-    #   applied.
-    #
-    # See #text for details on +width+, +height+, +style+, +style_properties+ and +box_style+.
+    # It uses HexaPDF::Document::Layout#formatted_text_box behind the scenes to create the
+    # HexaPDF::Layout::TextBox that does the actual work. See that method for details on the
+    # arguments.
     #
     # Examples:
     #
@@ -296,37 +233,41 @@ module HexaPDF
     #
     # See: #text, HexaPDF::Layout::TextBox, HexaPDF::Layout::TextFragment
     def formatted_text(data, width: 0, height: 0, style: nil, box_style: nil, **style_properties)
-      style = retrieve_style(style, style_properties)
-      box_style = (box_style ? retrieve_style(box_style) : style)
-      data.map! do |hash|
-        if hash.kind_of?(String)
-          Layout::TextFragment.create(hash, style)
-        else
-          link = hash.delete(:link)
-          (hash[:overlays] ||= []) << [:link, {uri: link}] if link
-          text = hash.delete(:text) || link || ""
-          Layout::TextFragment.create(text, retrieve_style(hash.delete(:style) || style, hash))
-        end
-      end
-      draw_box(Layout::TextBox.new(data, width: width, height: height, style: box_style))
+      draw_box(@document.layout.formatted_text_box(data, width: width, height: height, style: style,
+                                                   box_style: box_style, **style_properties))
     end
 
     # Draws the given image at the current position.
     #
-    # The +file+ argument can be anything that is accepted by HexaPDF::Document::Images#add or a
-    # HexaPDF::Type::Form object.
-    #
-    # See #text for details on +width+, +height+, +style+ and +style_properties+.
+    # It uses HexaPDF::Document::Layout#image_box behind the scenes to create the
+    # HexaPDF::Layout::ImageBox that does the actual work. See that method for details on the
+    # arguments.
     #
     # Examples:
     #
     #   #>pdf-composer
     #   composer.image(machu_picchu, border: {width: 3})
     #   composer.image(machu_picchu, height: 30)
+    #
+    # See: HexaPDF::Layout::ImageBox
     def image(file, width: 0, height: 0, style: nil, **style_properties)
-      style = retrieve_style(style, style_properties)
-      image = file.kind_of?(HexaPDF::Stream) ? file : document.images.add(file)
-      draw_box(Layout::ImageBox.new(image, width: width, height: height, style: style))
+      draw_box(@document.layout.image_box(file, width: width, height: height,
+                                          style: style, **style_properties))
+    end
+
+    # Draws the named box at the current position.
+    #
+    # It uses HexaPDF::Document::Layout#box behind the scenes to create the named box. See that
+    # method for details on the arguments.
+    #
+    # Examples:
+    #
+    #   #>pdf-composer
+    #   composer.box(:image, image: composer.document.images.add(machu_picchu))
+    #
+    # See: HexaPDF::Document::Layout#box
+    def box(name, width: 0, height: 0, style: nil, **box_options, &block)
+      draw_box(@document.layout.box(name, width: width, height: height, style: style, **box_options, &block))
     end
 
     # Draws the given HexaPDF::Layout::Box.
@@ -340,16 +281,17 @@ module HexaPDF
     def draw_box(box)
       drawn_on_page = true
       while true
-        if @frame.fit(box)
-          @frame.draw(@canvas, box)
+        result = @frame.fit(box)
+        if result.success?
+          @frame.draw(@canvas, result)
           break
         elsif @frame.full?
           new_page
           drawn_on_page = false
         else
-          draw_box, box = @frame.split(box)
+          draw_box, box = @frame.split(result)
           if draw_box
-            @frame.draw(@canvas, draw_box)
+            @frame.draw(@canvas, result)
             drawn_on_page = true
           elsif !@frame.find_next_region
             unless drawn_on_page
@@ -394,29 +336,6 @@ module HexaPDF
                                  media_box.height - @margin.bottom - @margin.top)
     end
 
-    # Retrieves the appropriate HexaPDF::Layout::Style object based on the +style+ and +properties+
-    # arguments.
-    #
-    # The +style+ argument specifies the style to retrieve. It can either be a registered style name
-    # (see #style), a hash with style properties or +nil+. In the latter case the registered style
-    # :base is used
-    #
-    # If the +properties+ hash is not empty, the retrieved style is duplicated and the properties
-    # hash is applied to it.
-    #
-    # Finally, a default font is set if necessary to ensure that the style object works in all
-    # cases.
-    def retrieve_style(style, properties = nil)
-      style = Layout::Style.create(@styles[style] || style || @styles[:base])
-      style = style.dup.update(**properties) unless properties.nil? || properties.empty?
-      style.font('Times') unless style.font?
-      unless style.font.respond_to?(:pdf_object)
-        name, options = *style.font
-        style.font(@document.fonts.add(name, **(options || {})))
-      end
-      style
-    end
-
   end
 
 end

data/lib/hexapdf/configuration.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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
@@ -193,6 +193,9 @@ module HexaPDF
   # acro_form.text_field.default_width::
   #    A number specifying the default width of AcroForm text fields which should be auto-sized.
   #
+  # debug::
+  #    If set to +true+, enables debug output.
+  #
   # document.auto_decrypt::
   #    A boolean determining whether the document should be decrypted automatically when parsed.
   #
@@ -337,6 +340,12 @@ module HexaPDF
   #    This can be used to limit the memory needed for reading or writing PDF files with huge
   #    stream objects.
   #
+  # layout.boxes.map::
+  #    A mapping from layout box names to box classes. If the value is a String, it should contain
+  #    the name of a constant to such a class.
+  #
+  #    See HexaPDF::Layout::Box for more information.
+  #
   # page.default_media_box::
   #    The media box that is used for new pages that don't define a media box. Default value is
   #    A4. See HexaPDF::Type::Page::PAPER_SIZE for a list of predefined paper sizes.
@@ -403,6 +412,7 @@ module HexaPDF
                           "#{field.concrete_field_type} field #{field.full_field_name}"
                       end,
                       'acro_form.text_field.default_width' => 100,
+                      'debug' => false,
                       'document.auto_decrypt' => true,
                       'document.on_invalid_string' => proc do |str|
                         str.encode(Encoding::UTF_8, invalid: :replace, replace: '')
@@ -461,6 +471,12 @@ module HexaPDF
                       ],
                       'image_loader.pdf.use_stringio' => true,
                       'io.chunk_size' => 2**16,
+                      'layout.boxes.map' => {
+                        text: 'HexaPDF::Layout::TextBox',
+                        image: 'HexaPDF::Layout::ImageBox',
+                        column: 'HexaPDF::Layout::ColumnBox',
+                        list: 'HexaPDF::Layout::ListBox',
+                      },
                       'page.default_media_box' => :A4,
                       'page.default_media_orientation' => :portrait,
                       'parser.on_correctable_error' => proc { false },

data/lib/hexapdf/content/canvas.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/content/color_space.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/content/graphic_object/arc.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/content/graphic_object/endpoint_arc.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/content/graphic_object/geom2d.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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
@@ -128,6 +128,7 @@ module HexaPDF
           return unless @object.nr_of_vertices > 1
           canvas.move_to(@object[0].x, @object[0].y)
           1.upto(@object.nr_of_vertices - 1) {|i| canvas.line_to(@object[i].x, @object[i].y) }
+          canvas.close_subpath
           canvas.stroke unless @path_only
         end
 

data/lib/hexapdf/content/graphic_object/solid_arc.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/content/graphic_object.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/content/graphics_state.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/content/operator.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/content/parser.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/content/processor.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/content/transformation_matrix.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/content.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/data_dir.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/dictionary.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/dictionary_fields.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/document/files.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/document/fonts.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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

data/lib/hexapdf/document/images.rb

@@ -4,7 +4,7 @@
 # This file is part of HexaPDF.
 #
 # HexaPDF - A Versatile PDF Creation and Manipulation Library For Ruby
-# Copyright (C) 2014-2021 Thomas Leitner
+# Copyright (C) 2014-2022 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