hexapdf 0.17.1 → 0.17.2

data/examples/011-text_layouter_line_wrapping.rb

@@ -0,0 +1,57 @@
+# # Text Layouter - Line Wrapping
+#
+# The [HexaPDF::Layout::TextLayouter] class can be used to easily lay out text,
+# automatically wrapping it appropriately.
+#
+# Text is broken only at certain characters:
+#
+# * The most important break points are **spaces**.
+#
+# * Lines can be broken at **tabulators** which represent eight spaces.
+#
+# * **Newline characters** are respected when wrapping and introduce a line
+#   break. They have to be removed beforehand if this is not wanted. All Unicode
+#   newline separators are recognized.
+#
+# * **Hyphens** are used as break points, possibly breaking just after them.
+#
+# * In addition to hyphens, **soft-hyphens** can be used to indicate break
+#   points. In contrast to hyphens, soft-hyphens won't be visible unless a line
+#   is broken at its position.
+#
+# * **Zero-width spaces** can be used to indicate break points at any position.
+#
+# * **Non-breaking spaces** can be used to prohibit a break between two words.
+#   It has the same appearance as a space in the PDF.
+#
+# This example shows all these specially handled characters in action, e.g. a
+# hard line break after "Fly-fishing", soft-hyphen in "wandering", tabulator
+# instead of space after "wandering", zero-width space in "fantastic" and
+# non-breaking spaces in "1 0 1".
+#
+# Usage:
+# : `ruby text_layout_line_wrapping.rb`
+#
+
+require 'hexapdf'
+
+doc = HexaPDF::Document.new
+canvas = doc.pages.add([0, 0, 180, 230]).canvas
+canvas.font("Times", size: 10, variant: :bold)
+
+text = "Hello! Fly-fishing\nand wand\u{00AD}ering\taround - fanta\u{200B}stic" \
+  " 1\u{00A0}0\u{00A0}1"
+
+x = 10
+y = 220
+frag = HexaPDF::Layout::TextFragment.create(text, font: doc.fonts.add("Times"))
+layouter = HexaPDF::Layout::TextLayouter.new
+[30, 60, 100, 160].each do |width|
+  result = layouter.fit([frag], width, 400)
+  result.draw(canvas, x, y)
+  canvas.stroke_color(255, 0, 0).line_width(0.2)
+  canvas.rectangle(x, y, width, -result.height).stroke
+  y -= result.height + 5
+end
+
+doc.write("text_layouter_line_wrapping.pdf", optimize: true)

data/examples/012-text_layouter_styling.rb

@@ -0,0 +1,122 @@
+# # Text Layouter - Styling
+#
+# The text used as part of a [HexaPDF::Layout::TextLayouter] class can be styled
+# using [HexaPDF::Layout::Style]. To do this [HexaPDF::Layout::TextFragment]
+# objects have to be created with the needed styling and then added to a text
+# layout object. In addition the style objects can be used for customizing the
+# text layouts themselves.
+#
+# This example shows how to do this and shows off the various styling option,
+# including using callbacks to further customize the appearance.
+#
+# Usage:
+# : `ruby text_layouter_styling.rb [FONT_FILE]`
+#
+
+require 'hexapdf'
+
+include HexaPDF::Layout
+
+sample_text = "Lorem ipsum dolor sit amet, consectetur adipiscing elit,
+sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
+enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut
+aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit
+in voluptate velit esse cillum dolore eu fugiat nulla pariatur.".tr("\n", ' ')
+
+# Wraps the text in a TextFragment using the given style.
+def fragment(text, style)
+  TextFragment.create(text, style)
+end
+
+# Draws the text at the given [x, y] position onto the canvas and returns the
+# new y position.
+def draw_text(result, canvas, x, y)
+  raise "Error" unless result.remaining_items.empty?
+  result.draw(canvas, x, y)
+  y - result.height
+end
+
+doc = HexaPDF::Document.new
+canvas = doc.pages.add.canvas
+
+base_font = doc.fonts.add(ARGV[0] || "Times")
+base_style = {font: base_font, font_size: 12, text_indent: 20}
+styles = {
+  "Fonts | Font Sizes | Colors" => [
+    {font: doc.fonts.add("Times", variant: :italic),
+     font_size: 12, fill_color: [0, 0, 255]},
+    {font: doc.fonts.add("Courier"), font_size: 14,
+     fill_color: [0, 255, 0]},
+    {font: doc.fonts.add("Helvetica", variant: :bold),
+     font_size: 20, fill_alpha: 0.5},
+  ],
+  "Character Spacing | Word Spacing | Horizontal Scaling" => [
+    {**base_style, character_spacing: 3},
+    {**base_style, horizontal_scaling: 150},
+    {**base_style, word_spacing: 15},
+  ],
+  "Text Rise" => [
+    {**base_style, text_rise: 5},
+    {**base_style, text_rise: -3},
+  ],
+  "Subscript | Superscript" => [
+    {**base_style, font_size: 15, subscript: true},
+    {**base_style, font_size: 15, superscript: true},
+  ],
+  "Underline | Strikeout" => [
+    {**base_style, underline: true, strikeout: true},
+    {**base_style, underline: true, strikeout: true, text_rise: 5},
+    {**base_style, underline: true, strikeout: true, subscript: true},
+  ],
+  "Text Rendering Mode" => [
+    {**base_style, text_rendering_mode: :stroke,
+     stroke_width: 0.1},
+    {**base_style, font_size: 20, text_rendering_mode: :fill_stroke,
+     stroke_color: [0, 255, 0], stroke_width: 0.7,
+     stroke_dash_pattern: [0.5, 1, 1.5], stroke_cap_style: :round},
+  ],
+  "Underlays | Overlays" => [
+    {**base_style, underlays: [lambda do |canv, box|
+       canv.fill_color(240, 240, 0).opacity(fill_alpha: 0.5).
+         rectangle(0, 0, box.width, box.height).fill
+      end]},
+    {**base_style, overlays: [lambda do |canv, box|
+       canv.line_width(1).stroke_color([0, 255, 0]).
+         line(0, -box.y_min, box.width, box.y_max - box.y_min).stroke
+      end]},
+  ],
+  "Links" => [
+    {**base_style, overlays: [
+      [:link, dest: [canvas.context, :FitR, 100, 300, 200, 400]],
+    ]},
+    {**base_style, overlays: [
+      [:link, uri: "https://hexapdf.gettalong.org",
+       border: [0, 0, 2, [3, 3]], border_color: [89, 150, 220]],
+    ]},
+    {**base_style, overlays: [
+      [:link, file: "text_layouter_styling.pdf", border: true],
+    ]},
+  ],
+}
+
+y = 800
+left = 50
+width = 500
+layouter = TextLayouter.new(base_style)
+styles.each do |desc, variations|
+  items = sample_text.split(/(Lorem ipsum dolor|\b\w{2,5}\b)/).map do |str|
+    if str.length >= 3 && str.length <= 5
+      fragment(str, variations[str.length % variations.length])
+    elsif str.length == 2
+      fragment(str, variations.first)
+    elsif str =~ /Lorem/
+      fragment(str, variations.last)
+    else
+      fragment(str, base_style)
+    end
+  end
+  items.unshift(fragment(desc + ": ", fill_color: [255, 0, 0], **base_style))
+  y = draw_text(layouter.fit(items, width, 400), canvas, left, y) - 20
+end
+
+doc.write("text_layouter_styling.pdf", optimize: true)

data/examples/013-text_layouter_shapes.rb

@@ -0,0 +1,176 @@
+# # Text Layouter - Shapes
+#
+# The [HexaPDF::Layout::TextLayouter] class can be used to easily lay out text,
+# not limiting the area to a rectangle but any shape. There is only one
+# restriction: In the case of arbitrary shapes the vertical alignment has to be
+# "top".
+#
+# Arbitrary shapes boil down to varying line widths and horizontal offsets from
+# left. Imagine a circle: If text is fit in a circle, the line widths start at
+# zero, getting larger and larger until the middle of the cirle. And then they
+# get smaller until zero again. The x-values of the left half circle determine
+# the horizontal offsets.
+#
+# Both, the line widths and the horizontal offsets can be calculated given a
+# certain height, and this is exactly what HexaPDF uses. If the `width` argument
+# to [HexaPDF::Layout::TextLayouter#fit] is an object responding to #call (e.g.
+# a lambda), it is used for determining the line widths and offsets.
+#
+# This example shows text layed out in various shapes, using the above mentioned
+# techniques.
+#
+# Usage:
+# : `ruby text_layouter_shapes.rb`
+#
+
+require 'hexapdf'
+
+include HexaPDF::Layout
+
+doc = HexaPDF::Document.new
+page = doc.pages.add
+canvas = page.canvas
+canvas.font("Times", size: 10, variant: :bold)
+canvas.stroke_color(255, 0, 0).line_width(0.2)
+font = doc.fonts.add("Times")
+
+sample_text = "Lorem ipsum dolor sit amet, con\u{00AD}sectetur
+adipis\u{00AD}cing elit, sed do eiusmod tempor incididunt ut labore et
+dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation
+ullamco laboris nisi ut aliquip ex ea commodo consequat.
+".tr("\n", ' ') * 10
+
+items = [TextFragment.create(sample_text, font: font)]
+layouter = TextLayouter.new
+
+########################################################################
+# Circly things on the top
+radius = 100
+circle_top = 840
+half_circle_width = lambda do |height, line_height|
+  sum = height + line_height
+  if sum <= radius * 2
+    [Math.sqrt(radius**2 - (radius - height)**2),
+     Math.sqrt([radius**2 - (radius - sum)**2, 0].max)].min
+  else
+    0
+  end
+end
+circle = lambda do |height, line_height|
+  w = half_circle_width.call(height, line_height)
+  [radius - w, 2 * w]
+end
+left_half_circle = lambda do |height, line_height|
+  w = half_circle_width.call(height, line_height)
+  [radius - w, w]
+end
+
+# Left: right half circle
+result = layouter.fit(items, half_circle_width, radius * 2)
+result.draw(canvas, 0, circle_top)
+canvas.circle(0, circle_top - radius, radius).stroke
+
+# Center: full circle
+layouter.style.align = :justify
+result = layouter.fit(items, circle, radius * 2)
+result.draw(canvas, page.box(:media).width / 2.0 - radius, circle_top)
+canvas.circle(page.box(:media).width / 2.0, circle_top - radius, radius).stroke
+
+# Right: left half circle
+layouter.style.align = :right
+result = layouter.fit(items, left_half_circle, radius * 2)
+result.draw(canvas, page.box(:media).width - radius, circle_top)
+canvas.circle(page.box(:media).width, circle_top - radius, radius).stroke
+
+
+########################################################################
+# Pointy, diamondy things in the middle
+
+diamond_width = 100
+diamond_top = circle_top - 2 * radius - 10
+half_diamond_width = lambda do |height, line_height|
+  sum = height + line_height
+  if sum < diamond_width
+    height
+  else
+    [diamond_width * 2 - sum, 0].max
+  end
+end
+full_diamond = lambda do |height, line_height|
+  w = half_diamond_width.call(height, line_height)
+  [diamond_width - w, 2 * w]
+end
+left_half_diamond = lambda do |height, line_height|
+  w = half_diamond_width.call(height, line_height)
+  [diamond_width - w, w]
+end
+
+# Left: right half diamond
+layouter.style.align = :left
+result = layouter.fit(items, half_diamond_width, 2 * diamond_width)
+result.draw(canvas, 0, diamond_top)
+canvas.polyline(0, diamond_top, diamond_width, diamond_top - diamond_width,
+                0, diamond_top - 2 * diamond_width).stroke
+
+# Center: full diamond
+layouter.style.align = :justify
+result = layouter.fit(items, full_diamond, 2 * diamond_width)
+left = page.box(:media).width / 2.0 - diamond_width
+result.draw(canvas, left, diamond_top)
+canvas.polyline(left + diamond_width, diamond_top,
+                left + 2 * diamond_width, diamond_top - diamond_width,
+                left + diamond_width, diamond_top - 2 * diamond_width,
+                left, diamond_top - diamond_width).close_subpath.stroke
+
+# Right: left half diamond
+layouter.style.align = :right
+result = layouter.fit(items, left_half_diamond, 2 * diamond_width)
+middle = page.box(:media).width
+result.draw(canvas, middle - diamond_width, diamond_top)
+canvas.polyline(middle, diamond_top,
+                middle - diamond_width, diamond_top - diamond_width,
+                middle, diamond_top - 2 * diamond_width).stroke
+
+
+########################################################################
+# Sine wave thing next
+
+sine_wave_height = 200.0
+sine_wave_top = diamond_top - 2 * diamond_width - 10
+sine_wave = lambda do |height, line_height|
+  offset = [40 * Math.sin(2 * Math::PI * (height / sine_wave_height)),
+            40 * Math.sin(2 * Math::PI * (height + line_height) / sine_wave_height)].max
+  [offset, sine_wave_height + 100 + offset * -2]
+end
+layouter.style.align = :justify
+result = layouter.fit(items, sine_wave, sine_wave_height)
+middle = page.box(:media).width / 2.0
+result.draw(canvas, middle - (sine_wave_height + 100) / 2, sine_wave_top)
+
+########################################################################
+# And finally a house
+
+house_top = sine_wave_top - sine_wave_height - 10
+outer_width = 300.0
+inner_width = 100.0
+house = lambda do |height, line_height|
+  sum = height + line_height
+  first_part = (outer_width / 2 - inner_width / 2)
+  if (0..first_part).cover?(sum)
+    [-height, outer_width + height * 2]
+  elsif (first_part..(first_part + inner_width)).cover?(height) ||
+      (first_part..(first_part + inner_width)).cover?(sum)
+    [0, first_part, inner_width, first_part]
+  elsif sum <= outer_width
+    outer_width
+  else
+    0
+  end
+end
+layouter.style.align = :justify
+result = layouter.fit(items, house, 200)
+
+middle = page.box(:media).width / 2.0
+result.draw(canvas, middle - (outer_width / 2), house_top)
+
+doc.write("text_layouter_shapes.pdf", optimize: true)

data/examples/014-text_in_polygon.rb

@@ -0,0 +1,60 @@
+# # Text in Polygon
+#
+# While creating width specifications for the [HexaPDF::Layout::TextLayouter]
+# class by hand is possible, the [HexaPDF::Layout::WidthFromPolygon] class
+# provides an easier way by using polygons.
+#
+# Most of the times text is laid out within polygonal shapes, so direct support
+# for these makes text layout in HexaPDF easier.
+#
+# This example shows how much easier text layout is by re-doing the "house"
+# example from the [Text Layouter - Shapes example](text_layouter_shapes.html).
+# Additionally, there is an example using a complex polygon with a hole inside.
+#
+# Usage:
+# : `ruby text_in_polygon.rb`
+#
+
+require 'hexapdf'
+require 'geom2d'
+
+include HexaPDF::Layout
+
+doc = HexaPDF::Document.new
+canvas = doc.pages.add.canvas
+
+sample_text = "Lorem ipsum dolor sit amet, con\u{00AD}sectetur
+adipis\u{00AD}cing elit, sed do eiusmod tempor incididunt ut labore et
+dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation
+ullamco laboris nisi ut aliquip ex ea commodo consequat.
+".tr("\n", ' ') * 12
+items = [TextFragment.create(sample_text, font: doc.fonts.add("Times"))]
+layouter = TextLayouter.new
+layouter.style.align = :justify
+
+# The house example
+house = Geom2D::Polygon([100, 200], [400, 200], [500, 100], [400, 100], [400, 0],
+                        [300, 0], [300, 100], [200, 100], [200, 0], [100, 0],
+                        [100, 100], [0, 100])
+width_spec = WidthFromPolygon.new(house)
+result = layouter.fit(items, width_spec, house.bbox.height)
+result.draw(canvas, 50, 750)
+
+# A more complex example
+polygon = Geom2D::PolygonSet(
+  Geom2D::Polygon([150, 450], [145, 198], [160, 196],
+                  [200, 220], [200, 300], [300, 300], [400, 0],
+                  [200, 0], [200, 100], [100, 100], [100, 0],
+                  [-100, 0], [0, 300], [-50, 300], [100, 330]),
+  Geom2D::Polygon([50, 120], [250, 120], [250, 180], [50, 180]),
+  Geom2D::Polygon([60, 130], [240, 130], [240, 170], [60, 170])
+)
+width_spec = WidthFromPolygon.new(polygon)
+result = layouter.fit(items, width_spec, polygon.bbox.height)
+result.draw(canvas, 150, 550)
+canvas.translate(150, 100).
+  stroke_color(255, 0, 0).opacity(stroke_alpha: 0.5).
+  line_width(0.5).
+  draw(:geom2d, object: polygon)
+
+doc.write("text_in_polygon.pdf", optimize: true)

data/examples/015-boxes.rb

@@ -0,0 +1,76 @@
+# # Boxes
+#
+# The [HexaPDF::Layout::Box] class is used as the basis for all document layout
+# features.
+#
+# This example shows the basic properties that are available for all boxes, like
+# paddings, borders and and background color. It is also possible to use the
+# underlay and overlay callbacks with boxes.
+#
+# Usage:
+# : `ruby boxes.rb`
+#
+
+require 'hexapdf'
+
+doc = HexaPDF::Document.new
+
+annotate_box = lambda do |canvas, box|
+  text = ""
+  canvas.font("Times", size: 6).leading(7)
+
+  if (data = box.style.padding)
+    text << "Padding (TRBL): #{data.top}, #{data.right}, #{data.bottom}, #{data.left}\n"
+  end
+  unless box.style.border.none?
+    data = box.style.border.width
+    text << "Border Width (TRBL): #{data.top}, #{data.right}, #{data.bottom}, #{data.left}\n"
+    data = box.style.border.color
+    text << "Border Color (TRBL):\n* #{data.top}\n* #{data.right}\n* #{data.bottom}\n* #{data.left}\n"
+    data = box.style.border.style
+    text << "Border Style (TRBL):\n* #{data.top}\n* #{data.right}\n* #{data.bottom}\n* #{data.left}\n"
+  end
+
+  canvas.line_width(0.1).rectangle(0, 0, box.content_width, box.content_height).stroke
+  canvas.text(text, at: [0, box.content_height - 10])
+end
+
+canvas = doc.pages.add.canvas
+
+[[1, 140], [5, 190], [15, 240]].each_with_index do |(width, red), row|
+  [[:solid, 140], [:dashed, 177], [:dashed_round, 207],
+   [:dotted, 240]].each_with_index do |(style, green), column|
+    box = HexaPDF::Layout::Box.create(
+      width: 100, height: 100, content_box: true,
+      border: {width: width, style: style},
+      background_color: [red, green, 0],
+      &annotate_box)
+    box.draw(canvas, 20 + 140 * column, 700 - 150 * row)
+  end
+end
+
+# The whole kitchen sink
+box = HexaPDF::Layout::Box.create(
+  width: 470, height: 200, content_box: true,
+  padding: [20, 5, 10, 15],
+  border: {width: [20, 40, 30, 15],
+           color: [[46, 185, 206], [206, 199, 46], [188, 46, 206], [59, 206, 46]],
+           style: [:solid, :dashed, :dashed_round, :dotted]},
+  background_color: [255, 255, 180],
+  underlays: [
+    lambda do |canv, _|
+      canv.stroke_color([255, 0, 0]).line_width(10).line_cap_style(:butt).
+        line(0, 0, box.width, box.height).line(0, box.height, box.width, 0).
+        stroke
+    end
+  ],
+  overlays: [
+    lambda do |canv, _|
+      canv.stroke_color([0, 0, 255]).line_width(5).
+        rectangle(10, 10, box.width - 20, box.height - 20).stroke
+    end
+  ],
+  &annotate_box)
+box.draw(canvas, 20, 100)
+
+doc.write("boxes.pdf", optimize: true)

data/examples/016-frame_automatic_box_placement.rb

@@ -0,0 +1,90 @@
+# # Frame - Automatic Box Placement
+#
+# The [HexaPDF::Layout::Frame] class is used for placing rectangular boxes.
+#
+# This example shows how to create a frame and how different box styles can be
+# used to specify where a box should be placed. After each box is drawn, the
+# frame's shape is drawn and then a new page is started. This is done to easily
+# compare the changes after each added box.
+#
+# Note how the absolutely positioned box cuts a hole into the frame's shape and
+# how that influences the positioning.
+#
+# Usage:
+# : `ruby frame_automatic_box_placement.rb`
+#
+
+require 'hexapdf'
+
+include HexaPDF::Layout
+
+doc = HexaPDF::Document.new
+page = doc.pages.add
+media_box = page.box(:media)
+canvas = page.canvas
+
+frame = Frame.new(media_box.left + 20, media_box.bottom + 20,
+                  media_box.width - 40, media_box.height - 40)
+
+box_counter = 1
+draw_box = lambda do |**args|
+  b = Box.create(**args, border: {width: 1, color: [[255, 0, 0]]}) do |canv, box|
+    canv.save_graphics_state do
+      canv.stroke_color(255, 0, 0)
+      canv.line(0, 0, box.content_width, box.content_height).
+        line(0, box.content_height, box.content_width, 0).
+        stroke
+    end
+    text = box_counter.to_s << "\n" + args.map {|k, v| "#{k}: #{v}"}.join("\n")
+    canv.font("Times", size: 15).leading(15).
+      text(text, at: [10, box.content_height - 20])
+    box_counter += 1
+  end
+
+  drawn = false
+  until drawn
+    drawn = frame.draw(canvas, b)
+    frame.find_next_region unless drawn
+  end
+
+  canvas.line_width(3).draw(:geom2d, object: frame.shape)
+  canvas = doc.pages.add.canvas
+end
+
+# Absolutely positioned box with margin
+draw_box.call(width: 100, height: 100, position: :absolute, margin: 10,
+              position_hint: [250, 250])
+
+# Fixed sized box with automatic width
+draw_box.call(height: 100)
+
+# Fixed sized box
+draw_box.call(width: 100, height: 100)
+
+# Fixed sized box, placed below the other because the space to the right can't
+# be used
+draw_box.call(width: 100, height: 100)
+
+# Fixed sized floating box, space to the right can be used
+draw_box.call(width: 100, height: 100, position: :float, position_hint: :left)
+
+# Fixed sized floating box again, floating to the right
+draw_box.call(width: 100, height: 100, position: :float, position_hint: :right)
+
+# Fixed sized floating box again, floating to the left with margin
+draw_box.call(width: 100, height: 100, position: :float, position_hint: :left,
+              margin: [0, 10])
+
+# Fixed sized box, no floating
+draw_box.call(width: 100, height: 100)
+
+# Fixed sized box, center aligned in the available space
+draw_box.call(width: 100, height: 100, position_hint: :center)
+
+# Fixed sized box, right aligned in the available space
+draw_box.call(width: 100, height: 100, position_hint: :right)
+
+# Fixed sized box, consuming the whole remaining available space
+draw_box.call
+
+doc.write("frame_automatic_box_placement.pdf", optimize: true)

data/examples/017-frame_text_flow.rb

@@ -0,0 +1,60 @@
+# # Frame - Text Flow
+#
+# This example shows how [HexaPDF::Layout::Frame] and [HexaPDF::Layout::TextBox]
+# can be used to flow text around objects.
+#
+# Three boxes are placed repeatedly onto the frame until it is filled: two
+# floating boxes (one left, one right) and a text box. The text box is styled to
+# flow its content around the other two boxes.
+#
+# Usage:
+# : `ruby frame_text_flow.rb`
+#
+
+require 'hexapdf'
+require 'hexapdf/utils/graphics_helpers'
+
+include HexaPDF::Layout
+include HexaPDF::Utils::GraphicsHelpers
+
+doc = HexaPDF::Document.new
+
+sample_text = "Lorem ipsum dolor sit amet, con\u{00AD}sectetur
+adipis\u{00AD}cing elit, sed do eiusmod tempor incididunt ut labore et
+dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation
+ullamco laboris nisi ut aliquip ex ea commodo consequat.
+".tr("\n", ' ') * 10
+items = [TextFragment.create(sample_text, font: doc.fonts.add("Times"))]
+
+page = doc.pages.add
+media_box = page.box(:media)
+canvas = page.canvas
+frame = Frame.new(media_box.left + 20, media_box.bottom + 20,
+                  media_box.width - 40, media_box.height - 40)
+
+image = doc.images.add(File.join(__dir__, 'machupicchu.jpg'))
+iw, ih = calculate_dimensions(image.width, image.height, rwidth: 100)
+
+boxes = []
+boxes << Box.create(width: iw, height: ih,
+                    margin: [10, 30], position: :float) do |canv, box|
+  canv.image(image, at: [0, 0], width: 100)
+end
+boxes << Box.create(width: 50, height: 50, margin: 20,
+                    position: :float, position_hint: :right,
+                    border: {width: 1, color: [[255, 0, 0]]})
+boxes << TextBox.new(items, style: {position: :flow, align: :justify})
+
+i = 0
+frame_filled = false
+until frame_filled
+  box = boxes[i]
+  drawn = false
+  until drawn || frame_filled
+    drawn = frame.draw(canvas, box)
+    frame_filled = !frame.find_next_region unless drawn
+  end
+  i = (i + 1) % boxes.length
+end
+
+doc.write("frame_text_flow.pdf", optimize: true)

data/examples/018-composer.rb

@@ -0,0 +1,44 @@
+# # Composer
+#
+# This example shows how [HexaPDF::Composer] simplifies the creation of PDF
+# documents by providing a high-level interface to the box layouting engine.
+#
+# Basic style properties can be set on the [HexaPDF::Composer#base_style] style.
+# These properties are reused by every box and can be adjusted on a box-by-box
+# basis.
+#
+# Various methods allow the easy creation of boxes, for example, text and image
+# boxes. All these boxes are automatically drawn on the page. If the page has
+# not enough room left for a box, the box is split across pages (which are
+# automatically created) if possible or just drawn on the new page.
+#
+# Usage:
+# : `ruby composer.rb`
+#
+
+require 'hexapdf'
+
+lorem_ipsum = "Lorem ipsum dolor sit amet, con\u{00AD}sectetur
+adipis\u{00AD}cing elit, sed do eiusmod tempor incidi\u{00AD}dunt ut labore et
+dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exer\u{00AD}citation
+ullamco laboris nisi ut aliquip ex ea commodo consequat. ".tr("\n", " ")
+
+HexaPDF::Composer.create('composer.pdf') do |pdf|
+  pdf.base_style.update(line_spacing: {type: :proportional, value: 1.5},
+                        last_line_gap: true, align: :justify)
+  image_style = pdf.base_style.dup.update(border: {width: 1}, padding: 5, margin: 10)
+  link_style = pdf.base_style.dup.update(fill_color: [6, 158, 224], underline: true)
+  image = File.join(__dir__, 'machupicchu.jpg')
+
+  pdf.text(lorem_ipsum * 2)
+  pdf.image(image, style: image_style, width: 200, position: :float)
+  pdf.image(image, style: image_style, width: 200, position: :absolute,
+            position_hint: [200, 300])
+  pdf.text(lorem_ipsum * 20, position: :flow)
+
+  pdf.formatted_text(["Produced by ",
+                      {link: "https://hexapdf.gettalong.org", text: "HexaPDF",
+                       style: link_style},
+                      " via HexaPDF::Composer"],
+                      font_size: 15, align: :center, padding: 15)
+end