hexapdf 1.8.0 → 1.9.0

data/lib/hexapdf/layout/table_box.rb

@@ -108,6 +108,17 @@ module HexaPDF
     #           [layout.text('E'), layout.text('F')]]
     #  composer.column(height: 50) {|col| col.table(cells) }
     #
+    # If a cell doesn't completely fit, it is split. Non-split cells in the same continuation row
+    # retain their style but are empty:
+    #
+    #  #>pdf-composer
+    #  cells = [[layout.text('A'), layout.text('B')],
+    #           [layout.text('C'), layout.text("D1\nD2")],
+    #           [layout.text('E'), layout.text('F')]]
+    #  composer.column(height: 50) {|col| col.table(cells) }
+    #
+    # Note that the above is only true for cells in rows that are not part of a row-span.
+    #
     # It is also possible to use row and column spans:
     #
     #  #>pdf-composer
@@ -237,6 +248,7 @@ module HexaPDF
 
         # Fits the children of the table cell into the given rectangular area.
         def fit_content(available_width, available_height, frame)
+          @remaining_boxes = nil
           width = available_width - reserved_width
           height = @used_height = available_height - reserved_height
           return if width <= 0 || height <= 0
@@ -245,21 +257,27 @@ module HexaPDF
           case children
           when Box
             child_result = frame.fit(children)
-            if child_result.success?
+            box, @remaining_boxes = children.split if child_result.overflow?
+            if child_result.success? || box
               @preferred_width = child_result.x + child_result.box.width + reserved_width
               @height = @preferred_height = child_result.box.height + reserved_height
               @fit_results = [child_result]
-              fit_result.success!
+              box ? fit_result.overflow! : fit_result.success!
             end
           when Array
             box_fitter = BoxFitter.new([frame])
             children.each {|box| box_fitter.fit(box) }
-            if box_fitter.success?
+            if box_fitter.success? || !box_fitter.fit_results.empty?
               max_x_result = box_fitter.fit_results.max_by {|result| result.x + result.box.width }
               @preferred_width = max_x_result.x + max_x_result.box.width + reserved_width
               @height = @preferred_height = box_fitter.content_heights[0] + reserved_height
               @fit_results = box_fitter.fit_results
-              fit_result.success!
+              if box_fitter.success?
+                fit_result.success!
+              else
+                @remaining_boxes = box_fitter.remaining_boxes
+                fit_result.overflow!
+              end
             end
           else
             @preferred_width = reserved_width
@@ -274,6 +292,14 @@ module HexaPDF
           end
         end
 
+        # Splits the content of the cell.
+        def split_content
+          box = create_split_box
+          box.instance_variable_set(:@children, @remaining_boxes)
+          box.instance_variable_set(:@remaining_boxes, nil)
+          [self, box]
+        end
+
         # Draws the content of the cell.
         def draw_content(canvas, x, y)
           return if @fit_results.empty?
@@ -363,7 +389,7 @@ module HexaPDF
         # Note that the same cell instance may be returned for different (row, column) arguments if
         # the cell spans more than one row and/or column.
         def [](row, column)
-          @cells[row]&.[](column)
+          row == @overridden_row_index ? @overridden_row_cells[column] : @cells[row]&.[](column)
         end
 
         # Returns the number of rows.
@@ -378,7 +404,15 @@ module HexaPDF
 
         # Iterates over each row.
         def each_row(&block)
-          @cells.each(&block)
+          return to_enum(__method__) unless block_given?
+
+          if @overridden_row_index
+            @cells[0...@overridden_row_index].each(&block)
+            block&.call(@overridden_row_cells)
+            @cells[(@overridden_row_index + 1)..-1].each(&block)
+          else
+            @cells.each(&block)
+          end
         end
 
         # Applies the given style properties to all cells and optionally yields all cells for more
@@ -409,12 +443,19 @@ module HexaPDF
           row_heights = {}
           zero_height_rows = {}
           row_spans = []
+          split_row_cells = nil
 
           @cells[start_row..-1].each.with_index(start_row) do |columns, row_index|
+            columns = @overridden_row_cells if row_index == @overridden_row_index
+
+            # Rows containing row-spanning cells aren't supported for cell-splitting
+            row_has_row_spans = columns.any? {|cell| cell.row != row_index || cell.row_span > 1 }
+
             # 1. Fit all columns of the row and record the max height of all non-row-span cells. If
             #    a row has zero height (usually because it only has row-span cells), record that
             #    information. Additionally store all cells with row-spans.
             row_fit = true
+            row_has_split_cells = false
             row_height = 0
             columns.each_with_index do |cell, col_index|
               next if cell.row != row_index || cell.column != col_index
@@ -423,9 +464,14 @@ module HexaPDF
                                      else
                                        column_info[cell.column].last
                                      end
-              unless cell.fit(available_cell_width, available_height, frame).success?
-                row_fit = false
-                break
+              cell_fit_result = cell.fit(available_cell_width, available_height, frame)
+              unless cell_fit_result.success?
+                if !row_has_row_spans && cell_fit_result.overflow?
+                  row_has_split_cells = true
+                else
+                  row_fit = false
+                  break
+                end
               end
               if row_height < cell.preferred_height && cell.row_span == 1
                 row_height = cell.preferred_height
@@ -462,6 +508,11 @@ module HexaPDF
                   available_height -= cell.preferred_height - row_span_height
                 end
               end
+
+              if row_has_split_cells
+                split_row_cells = create_split_row_cells(columns)
+                break
+              end
             else
               last_fitted_row_index = columns.min_by(&:row).row - 1 if height != available_height
               break
@@ -473,6 +524,7 @@ module HexaPDF
             #    final height and top-left corner of each cell needs to be set.
             running_height = 0
             @cells[start_row..last_fitted_row_index].each.with_index(start_row) do |columns, row_index|
+              columns = @overridden_row_cells if row_index == @overridden_row_index
               columns.each_with_index do |cell, col_index|
                 next if cell.row != row_index || cell.column != col_index
                 cell.left = column_info[cell.column].first
@@ -488,13 +540,15 @@ module HexaPDF
             end
           end
 
-          [height - available_height, last_fitted_row_index < start_row ? -1 : last_fitted_row_index]
+          [height - available_height, last_fitted_row_index < start_row ? -1 : last_fitted_row_index,
+           split_row_cells]
         end
 
         # Draws the rows from +start_row+ to +end_row+ on the given +canvas+, with the top-left
         # corner of the resulting table being at (+x+, +y+).
         def draw_rows(start_row, end_row, canvas, x, y)
           @cells[start_row..end_row].each.with_index(start_row) do |columns, row_index|
+            columns = @overridden_row_cells if row_index == @overridden_row_index
             columns.each_with_index do |cell, col_index|
               next if cell.row != row_index || cell.column != col_index
               cell.draw(canvas, x + cell.left, y - cell.top - cell.height)
@@ -557,6 +611,22 @@ module HexaPDF
           end
         end
 
+        # Splits all cells in +columns+ and returns the new array.
+        def create_split_row_cells(columns)
+          columns.map.with_index do |cell, col_index|
+            next cell unless cell.column == col_index
+            _, split_box = cell.split
+            if split_box
+              split_box
+            else
+              # Create an empty clone of the fully fit cell
+              empty_cell = cell.send(:create_split_box)
+              empty_cell.instance_variable_set(:@children, nil)
+              empty_cell
+            end
+          end
+        end
+
       end
 
       # The Cells instance containing the data of the table.
@@ -682,6 +752,7 @@ module HexaPDF
         @special_cells_fit_not_successful = false
         [@header_cells, @footer_cells].each do |special_cells|
           next unless special_cells
+          # Ignore split-cells (3rd result element) as not fully-fit headers/footers lead to failure
           special_used_height, last_fitted_row_index = special_cells.fit_rows(0, height, columns, frame)
           height -= special_used_height
           used_height += special_used_height
@@ -689,13 +760,14 @@ module HexaPDF
           return nil if @special_cells_fit_not_successful
         end
 
-        main_used_height, @last_fitted_row_index = @cells.fit_rows(@start_row_index, height, columns, frame)
+        main_used_height, @last_fitted_row_index, @split_row_cells =
+          @cells.fit_rows(@start_row_index, height, columns, frame)
         used_height += main_used_height
 
         update_content_width { columns[-1].sum + rw }
         update_content_height { used_height + rh }
 
-        if @last_fitted_row_index == @cells.number_of_rows - 1
+        if @last_fitted_row_index == @cells.number_of_rows - 1 && !@split_row_cells
           fit_result.success!
         elsif @last_fitted_row_index >= 0
           fit_result.overflow!
@@ -724,8 +796,19 @@ module HexaPDF
       # Splits the content of the table box. This method is called from Box#split.
       def split_content
         box = create_split_box
-        box.instance_variable_set(:@start_row_index, @last_fitted_row_index + 1)
+
+        if @split_row_cells
+          cells = @cells.clone
+          cells.instance_variable_set(:@overridden_row_cells, @split_row_cells)
+          cells.instance_variable_set(:@overridden_row_index, @last_fitted_row_index)
+          box.instance_variable_set(:@cells, cells)
+          box.instance_variable_set(:@start_row_index, @last_fitted_row_index)
+        else
+          box.instance_variable_set(:@start_row_index, @last_fitted_row_index + 1)
+        end
+
         box.instance_variable_set(:@last_fitted_row_index, -1)
+        box.instance_variable_set(:@split_row_cells, nil)
         box.instance_variable_set(:@special_cells_fit_not_successful, nil)
         header_cells = @header ? Cells.new(@header.call(self), cell_style: @cell_style) : nil
         box.instance_variable_set(:@header_cells, header_cells)

data/lib/hexapdf/layout/text_fragment.rb

@@ -111,20 +111,24 @@ module HexaPDF
         font = style.font
         text.each_codepoint do |codepoint|
           glyph = font.decode_codepoint(codepoint)
-          if glyph.valid? || glyph.control_char?
+          if glyph.valid?
             items << glyph
           else
             unless items.empty?
-              result << shaper.shape_text(new(items, style))
+              result.append(*shaper.shape_text(new(items, style)))
               items = []
             end
-            fallback = yield(codepoint, glyph)
-            unless fallback.empty?
-              result << shaper.shape_text(new(fallback, styles[fallback.first.font_wrapper]))
+            if glyph.control_char?
+              result.append(new([glyph], style))
+            else
+              fallback = yield(codepoint, glyph)
+              unless fallback.empty?
+                result.append(*shaper.shape_text(new(fallback, styles[fallback.first.font_wrapper])))
+              end
             end
           end
         end
-        result << shaper.shape_text(new(items, style)) unless items.empty?
+        result.append(*shaper.shape_text(new(items, style))) unless items.empty?
         result
       end
 
@@ -251,7 +255,9 @@ module HexaPDF
         tx = x - tlm.e
         ty = y - tlm.f
         if tx.abs < PRECISION
-          if (ty + canvas.graphics_state.leading).abs < PRECISION
+          if ty.abs < PRECISION
+            # do nothing
+          elsif (ty + canvas.graphics_state.leading).abs < PRECISION
             canvas.move_text_cursor
           else
             canvas.move_text_cursor(offset: [0, ty], absolute: false)

data/lib/hexapdf/layout/text_shaper.rb

@@ -34,8 +34,71 @@
 # commercial licenses are available at <https://gettalong.at/hexapdf/>.
 #++
 
+require 'hexapdf/error'
 require 'hexapdf/layout/numeric_refinements'
 
+HARFBUZZ_AVAILABLE = begin
+                       require 'harfbuzz'
+                       true
+                     rescue LoadError
+                     end
+
+if HARFBUZZ_AVAILABLE
+  class HarfBuzz::Buffer #:nodoc:
+
+    GLYPH_INFO_SIZE = HarfBuzz::C::HbGlyphInfoT.size
+    GLYPH_INFO_CODEPOINT_OFFSET = HarfBuzz::C::HbGlyphInfoT.offset_of(:codepoint)
+    GLYPH_INFO_CLUSTER_OFFSET = HarfBuzz::C::HbGlyphInfoT.offset_of(:cluster)
+    GLYPH_POS_SIZE  = HarfBuzz::C::HbGlyphPositionT.size
+    GLYPH_POS_XADVANCE_OFFSET = HarfBuzz::C::HbGlyphPositionT.offset_of(:x_advance)
+    GLYPH_POS_YADVANCE_OFFSET = HarfBuzz::C::HbGlyphPositionT.offset_of(:y_advance)
+    GLYPH_POS_XOFFSET_OFFSET = HarfBuzz::C::HbGlyphPositionT.offset_of(:x_offset)
+    GLYPH_POS_YOFFSET_OFFSET = HarfBuzz::C::HbGlyphPositionT.offset_of(:y_offset)
+
+    # Iterates efficiently over the shaping result without creating intermediary objects.
+    def each_result
+      return enum_for(__method__) unless block_given?
+
+      length_ptr = FFI::MemoryPointer.new(:uint)
+      infos_ptr = HarfBuzz::C.hb_buffer_get_glyph_infos(@ptr, length_ptr)
+      length_ptr = FFI::MemoryPointer.new(:uint)
+      positions_ptr = HarfBuzz::C.hb_buffer_get_glyph_positions(@ptr, length_ptr)
+      length = length_ptr.read_uint
+
+      return if infos_ptr.null? || positions_ptr.null? || length.zero?
+
+      last_info_cluster_offset = (length - 1) * GLYPH_INFO_SIZE + GLYPH_INFO_CLUSTER_OFFSET
+      i = 0
+      while i < length
+        info_offset = i * GLYPH_INFO_SIZE
+        pos_offset  = i * GLYPH_POS_SIZE
+
+        glyph_id = infos_ptr.get_uint32(info_offset + GLYPH_INFO_CODEPOINT_OFFSET)
+        cluster  = infos_ptr.get_uint32(info_offset + GLYPH_INFO_CLUSTER_OFFSET)
+
+        next_cluster = nil
+        tmp_offset = info_offset + GLYPH_INFO_CLUSTER_OFFSET + GLYPH_INFO_SIZE
+        while tmp_offset <= last_info_cluster_offset &&
+              (next_cluster = infos_ptr.get_uint32(tmp_offset)) == cluster
+          tmp_offset += GLYPH_INFO_SIZE
+          next_cluster = nil
+        end
+
+        x_advance = positions_ptr.get_int32(pos_offset + GLYPH_POS_XADVANCE_OFFSET)
+        y_advance = positions_ptr.get_int32(pos_offset + GLYPH_POS_YADVANCE_OFFSET)
+        x_offset = positions_ptr.get_int32(pos_offset + GLYPH_POS_XOFFSET_OFFSET)
+        y_offset = positions_ptr.get_int32(pos_offset + GLYPH_POS_YOFFSET_OFFSET)
+
+        yield(glyph_id, cluster, next_cluster, x_advance, y_advance, x_offset, y_offset)
+
+        i += 1
+      end
+
+      self
+    end
+  end
+end
+
 module HexaPDF
   module Layout
 
@@ -44,23 +107,33 @@ module HexaPDF
     # This class is used to perform text shaping, i.e. changing the position of glyphs (e.g. for
     # kerning) or substituting one or more glyphs for other glyphs (e.g. for ligatures).
     #
-    # Status of the implementation:
+    # The class contains two shaping engines: A very limited custom one and one based on
+    # HarfBuzz. Which one is used for shaping can be selected via the Style#shaping_engine property.
     #
-    # * All text shaping functionality possible for Type1 fonts is implemented, i.e. kerning and
-    #   ligature substitution.
+    # The custom implementation is always used for Type1 fonts and supports kerning and ligature
+    # substitution. It also supports the 'kern' table for TrueType fonts if HarfBuzz is not used.
     #
-    # * For TrueType fonts only kerning via the 'kern' table is implemented.
+    # For complex scripts or the need of special font features it is recommended to use the shaping
+    # engine based on HarfBuzz, even though it is slightly slower. For it to work the
+    # +harfbuzz-ruby+ gem needs to be installed. OpenType features can be activated and deactivated
+    # using Style#font_features.
     class TextShaper
 
-      # Shapes the given text fragment in-place.
+      # Shapes the given text fragment. Returns either the in-place modified fragment or, for
+      # complex shaping, an array of fragments.
       #
-      # The following shaping options, retrieved from the text fragment's Style#font_features, are
-      # supported:
-      #
-      # :kern:: Pair-wise kerning.
-      # :liga:: Ligature substitution.
+      # The style properties Style#shaping_engine, Style#font_features, Style#font_script,
+      # Style#language and Style#direction are used for shaping.
       def shape_text(text_fragment)
         font = text_fragment.style.font
+        if text_fragment.style.shaping_engine == :harfbuzz && font.font_type == :TrueType
+          unless HARFBUZZ_AVAILABLE
+            raise HexaPDF::Error, "Shaping engine harfbuzz required but the needed Rubygem " \
+              "harfbuzz-ruby is not available"
+          end
+          return harfbuzz_shape_text(text_fragment)
+        end
+
         if text_fragment.style.font_features[:liga] && font.wrapped_font.features.include?(:liga)
           if font.font_type == :Type1
             process_type1_ligatures(text_fragment)
@@ -76,11 +149,90 @@ module HexaPDF
           end
           text_fragment.clear_cache
         end
+
         text_fragment
       end
 
       private
 
+      # Shapes the text fragment with HarfBuzz.
+      def harfbuzz_shape_text(text_fragment, text = nil)
+        text ||= text_fragment.items.map(&:str).join
+        style = text_fragment.style
+
+        # Cache the used main Harfbuzz font objects
+        hb_font = style.font.pdf_object.document.cache('harfbuzz', style.font.filename) do
+          blob = HarfBuzz::Blob.from_file!(style.font.filename)
+          face = HarfBuzz::Face.new(blob, 0)
+          HarfBuzz::Font.new(face)
+        end
+
+        # Prepare the buffer and then shape the text. We are using cluster level 1 as this is the
+        # recommended level.
+        buffer = HarfBuzz::Buffer.new
+        buffer.add_utf8(text)
+        buffer.cluster_level = 1
+        buffer.direction = style.direction
+        buffer.script = style.font_script if style.font_script?
+        buffer.language = style.language if style.language?
+        buffer.guess_segment_properties
+        HarfBuzz.shape(hb_font, buffer, HarfBuzz::Feature.from_hash(style.font_features))
+
+        # Prepare the iteration over the shaping result. The final output will either be
+        # +text_fragment+ (no non-zero y_offsets) or +result+ containing at least two TextFragment
+        # instances.
+        result = nil
+        font = style.font
+        fragment = text_fragment
+        fragment.clear_cache
+        items = text_fragment.items.clear
+        last_cluster = nil
+        last_y_offset = 0
+        buffer.each_result do |glyph_id, cluster, next_cluster, x_advance, y_advance, x_offset, y_offset|
+          advance = (x_advance - x_offset) * font.scaling_factor
+
+          # 1. Determine the source characters for each glyph via their cluster numbers. If two or
+          # more glyphs have the same cluster number, the first gets the resulting string while the
+          # rest map to an empty string. Otherwise copying from the PDF would result in multiple
+          # copies of the resulting string.
+          str = (cluster == last_cluster ? '' : text.byteslice(cluster...(next_cluster || text.bytesize)))
+
+          # 2. Handle invalid glyphs with id=0 by mapping them to an InvalidGlyph instance
+          if glyph_id.zero?
+            glyph = font.decode_codepoint(str.ord)
+            advance = glyph.width
+          else
+            glyph = font.glyph(glyph_id, str)
+          end
+
+          # 3. Handle differing y_offsets by creating TextFragment instances with appropriate text
+          # rise properties.
+          if y_offset != last_y_offset
+            (result ||= []) << fragment
+            items = []
+            if y_offset.zero?
+              fragment = text_fragment.dup_attributes(items)
+            else
+              fragment = TextFragment.new(items, style.dup, properties: text_fragment.properties)
+              fragment.style.text_rise += y_offset * font.scaling_factor * fragment.style.font_size *
+                                          fragment.style.font.pdf_object.glyph_scaling_factor
+            end
+          end
+
+          # 4. Handle the correct x-positioning using x_offset. Also addjust the horizontal advance
+          # based on the glyph's fixed advance width as well as x_advance and x_offset (via
+          # +advance+).
+          items << -x_offset * font.scaling_factor unless x_offset.zero?
+          items << glyph
+          items << glyph.width - advance if glyph.width - advance != 0
+
+          last_cluster = cluster
+          last_y_offset = y_offset
+        end
+
+        result ? result.append(fragment) : text_fragment
+      end
+
       # Processes the text fragment and substitutes ligatures.
       def process_type1_ligatures(text_fragment)
         items = text_fragment.items

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

@@ -77,6 +77,7 @@ module HexaPDF
           when :Circle then create_square_circle_appearance(:circle)
           when :Polygon then create_polygon_polyline_appearance(:polygon)
           when :PolyLine then create_polygon_polyline_appearance(:polyline)
+          when :Ink then create_ink_appearance
           else
             raise HexaPDF::Error, "Appearance regeneration for #{@annot[:Subtype]} not yet supported"
           end
@@ -362,6 +363,47 @@ module HexaPDF
 
         end
 
+        # Creates the appropriate appearance for an ink annotation.
+        #
+        # See: HexaPDF::Type::Annotations::Ink
+        def create_ink_appearance
+          # Prepare the annotation
+          form = (@annot[:AP] ||= {})[:N] ||=
+            @document.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, 0, 0]})
+          form.contents = ""
+          @annot.flag(:print)
+          @annot.unflag(:hidden)
+
+          # Get all needed values from the annotation
+          paths = @annot.paths
+          border_style = @annot.border_style
+          opacity = @annot.opacity
+
+          # Calculate the annotation's rectangle as well as the form bounding box
+          x_coords = []
+          y_coords = []
+          paths.each do |path|
+            path.each_with_index {|coord, index| (index.even? ? x_coords : y_coords) << coord }
+          end
+          min_x, max_x = x_coords.minmax
+          min_y, max_y = y_coords.minmax
+          padding = 4 * border_style.width
+          rect = [min_x - padding, min_y - padding, max_x + padding, max_y + padding]
+          @annot[:Rect] = rect
+          form[:BBox] = rect.dup
+
+          # Set the appropriate graphics state
+          canvas = form.canvas(translate: false)
+          canvas.opacity(**opacity.to_h)
+          canvas.stroke_color(border_style.color) if border_style.color
+          canvas.line_width(border_style.width)
+          canvas.line_dash_pattern(border_style.style) if border_style.style.kind_of?(Array)
+
+          # Draw the polylines
+          paths.each {|path| canvas.polyline(*path) }
+          border_style.color ? canvas.stroke : canvas.end_path
+        end
+
         # Calculates the padding needed around the line endings based on the line ending +style+ and
         # the +border_width+.
         def calculate_line_ending_padding(style, border_width)

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

@@ -0,0 +1,107 @@
+# -*- 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-2026 Thomas Leitner
+#
+# HexaPDF is free software: you can redistribute it and/or modify it
+# under the terms of the GNU Affero General Public License version 3 as
+# published by the Free Software Foundation with the addition of the
+# following permission added to Section 15 as permitted in Section 7(a):
+# FOR ANY PART OF THE COVERED WORK IN WHICH THE COPYRIGHT IS OWNED BY
+# THOMAS LEITNER, THOMAS LEITNER DISCLAIMS THE WARRANTY OF NON
+# INFRINGEMENT OF THIRD PARTY RIGHTS.
+#
+# HexaPDF is distributed in the hope that it will be useful, but WITHOUT
+# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
+# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Affero General Public
+# License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with HexaPDF. If not, see <http://www.gnu.org/licenses/>.
+#
+# The interactive user interfaces in modified source and object code
+# versions of HexaPDF must display Appropriate Legal Notices, as required
+# under Section 5 of the GNU Affero General Public License version 3.
+#
+# In accordance with Section 7(b) of the GNU Affero General Public
+# License, a covered work must retain the producer line in every PDF that
+# is created or manipulated using HexaPDF.
+#
+# If the GNU Affero General Public License doesn't fit your need,
+# commercial licenses are available at <https://gettalong.at/hexapdf/>.
+#++
+
+require 'hexapdf/type/annotation'
+
+module HexaPDF
+  module Type
+    module Annotations
+
+      # An ink annotation is a markup annotation that displays a freehand "scribble" composed of one
+      # or more disjoint paths.
+      #
+      # The convenience method #add_path can be used to add paths to the annotation.
+      #
+      # The style of the scribble can be customized using the convenience methods Annotation#opacity
+      # and BorderStyling#border_style (note that only a simple line dash pattern is supported).
+      #
+      # Example:
+      #
+      #   #>pdf-small
+      #   doc.annotations.create_scribble(doc.pages[0]).
+      #     add_path(10, 10, 50, 40, 40, 80, 80, 60).
+      #     add_path(5, 90, 20, 90, 15, 50, 80, 5).
+      #     border_style(color: "hp-blue", width: 2, style: [3, 1]).
+      #     regenerate_appearance
+      #
+      # See: PDF2.0 s12.5.6.13, HexaPDF::Type::MarkupAnnotation
+      class Ink < MarkupAnnotation
+
+        include BorderStyling
+
+        define_field :Subtype, type: Symbol, required: true, default: :Ink
+        define_field :InkList, type: PDFArray, required: true
+        define_field :BS,      type: :Border
+        define_field :Path,    type: PDFArray, version: '2.0'
+
+        # :call-seq:
+        #   annot.paths   => [[x00, y00, x01, y01, ...], [x10, y10, x11, y11, ...], ...]
+        #
+        # Returns an array with all the paths of this annotation.
+        def paths
+          self[:InkList].to_a
+        end
+
+        # :call-seq:
+        #   annot.add_path            => [x0, y0, x1, y1, ...]
+        #   annot.add_path(*points)   => annot
+        #
+        # Adds the path consisting of the given +points+ to the list of paths and returns self.
+        #
+        # Adding at least one path is required. Note, however, that without setting the appearance
+        # style through convenience methods like #border_style nothing will be shown.
+        #
+        # Example:
+        #
+        #   #>pdf-small
+        #   doc.annotations.create_scribble(doc.pages[0]).
+        #     add_path(10, 10, 40, 60, 90, 90).
+        #     regenerate_appearance
+        def add_path(*points)
+          if points.length % 2 != 0
+            raise ArgumentError, "An even number of arguments must be provided"
+          else
+            self[:InkList] ||= []
+            self[:InkList] << points
+            self
+          end
+        end
+
+      end
+
+    end
+  end
+end

data/lib/hexapdf/type/annotations.rb

@@ -60,6 +60,7 @@ module HexaPDF
       autoload(:PolygonPolyline, 'hexapdf/type/annotations/polygon_polyline')
       autoload(:Polygon, 'hexapdf/type/annotations/polygon')
       autoload(:Polyline, 'hexapdf/type/annotations/polyline')
+      autoload(:Ink, 'hexapdf/type/annotations/ink')
 
     end
 

data/lib/hexapdf/version.rb

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