hexapdf 0.17.1 → 0.17.2

data/examples/002-graphics.rb

@@ -0,0 +1,275 @@
+# # Graphics Primitives
+#
+# This example shows many of the operations that the canvas implementation
+# allows.
+#
+# Note that the PDF canvas has its origin in the bottom left corner of the page.
+# This means the coordinate (100, 50) is 100 PDF points from the left side and
+# 50 PDF points from the bottom. One PDF point is equal to 1/72 inch.
+#
+# Usage:
+# : `ruby graphics.rb`
+#
+
+require 'hexapdf'
+
+doc = HexaPDF::Document.new
+page = doc.pages.add
+canvas = page.canvas
+
+# Draws the shape that is used to showcase the transformations in the given
+# color.
+def transformation_shape(canvas, *color)
+  canvas.stroke_color(*color)
+  canvas.polygon(0, 0, 0, 80, 30, 50, 60, 80, 60, 0, 30, 30)
+  canvas.line(-30, 0, 30, 0)
+  canvas.line(0, 30, 0, -30)
+  canvas.stroke
+end
+
+# Basic transformations: translate, scale, rotate, skew
+canvas.translate(0, 710) do
+  normal_color = [0.7, 0.7, 0.3]
+  transformed_color = [0.3, 0.7, 0.7]
+
+  canvas.translate(50, 0) do
+    transformation_shape(canvas, normal_color)
+    canvas.translate(40, 40) { transformation_shape(canvas, transformed_color) }
+  end
+
+  canvas.translate(180, 0) do
+    transformation_shape(canvas, normal_color)
+    canvas.scale(1.7, 1.3) { transformation_shape(canvas, transformed_color) }
+  end
+
+  canvas.translate(330, 0) do
+    transformation_shape(canvas, normal_color)
+    canvas.rotate(30) { transformation_shape(canvas, transformed_color) }
+  end
+
+  canvas.translate(430, 0) do
+    transformation_shape(canvas, normal_color)
+    canvas.skew(15, 30) { transformation_shape(canvas, transformed_color) }
+  end
+end
+
+# Draws a thin white line over a thick black line.
+def dual_lines(canvas)
+  canvas.stroke_color(0)
+  canvas.line_width = 15
+  yield
+  canvas.stroke
+  canvas.stroke_color(1.0)
+  canvas.line_width = 1
+  yield
+  canvas.stroke
+end
+
+# Graphics state: line width, line cap style, line join style, miter limit,
+# line dash pattern
+canvas.translate(0, 550) do
+  canvas.translate(50, 0) do
+    [1, 5, 10, 15].each_with_index do |i, index|
+      canvas.stroke_color(0)
+      canvas.line_width(i)
+      canvas.line(20 * index, 0, 20 * index, 100)
+      canvas.stroke
+    end
+  end
+
+  canvas.translate(150, 0) do
+    0.upto(2) do |i|
+      canvas.line_cap_style = i
+      dual_lines(canvas) { canvas.line(20 * i, 0, 20 * i, 100) }
+    end
+  end
+
+  canvas.translate(230, 0) do
+    0.upto(2) do |i|
+      canvas.line_join_style = i
+      dual_lines(canvas) { canvas.polyline(0, 30 * i, 40, 50 + 30 * i, 80, 30 * i) }
+    end
+  end
+
+  canvas.translate(350, 0) do
+    canvas.line_join_style = :miter
+    canvas.miter_limit = 1
+    dual_lines(canvas) { canvas.polyline(0, 0, 20, 80, 40, 0) }
+    canvas.miter_limit = 10
+    dual_lines(canvas) { canvas.polyline(60, 0, 80, 80, 100, 0) }
+  end
+
+  canvas.translate(490, 0) do
+    canvas.line_width(1)
+    [[[1, 1]],
+     [[3, 1]],
+     [[3, 3]],
+     [[5, 1, 1, 1, 1, 1]],
+     [[3, 5], 6]].each_with_index do |(value, phase), index|
+      canvas.line_dash_pattern(value, phase || 0)
+      canvas.line(20 * index, 0, 20 * index, 100)
+      canvas.stroke
+    end
+  end
+end
+
+# Basic shapes: line, polyline, (rounded) rectangle, (rounded) polygon, circle, ellipse
+canvas.translate(0, 420) do
+  canvas.line(50, 0, 50, 100)
+  canvas.polyline(80, 0, 80, 20, 70, 30, 90, 40, 70, 50, 90, 60, 70, 70, 80, 80, 80, 100)
+  canvas.rectangle(110, 0, 50, 100)
+  canvas.rectangle(180, 0, 50, 100, radius: 20)
+  canvas.polygon(250, 0, 250, 100, 280, 70, 310, 100, 310, 0, 280, 30)
+  canvas.polygon(330, 0, 330, 100, 360, 70, 390, 100, 390, 0, 360, 30, radius: 20)
+  canvas.circle(440, 50, 30)
+  canvas.ellipse(520, 50, a: 30, b: 15, inclination: 45)
+  canvas.stroke
+end
+
+# Various arcs w/wo filling, using the Canvas#arc method as well as directly
+# working with the arc objects
+canvas.translate(0, 320) do
+  canvas.arc(50, 50, a: 10, start_angle: -60, end_angle: 115)
+  canvas.arc(100, 50, a: 40, b: 20, start_angle: -60, end_angle: 115)
+  canvas.arc(180, 50, a: 40, b: 20, start_angle: -60, end_angle: 115, inclination: 45)
+  canvas.stroke
+
+  canvas.fill_color(0.4, 0.3, 0.4)
+  canvas.arc(250, 50, a: 10, start_angle: -60, end_angle: 115)
+  canvas.arc(300, 50, a: 40, b: 20, start_angle: -60, end_angle: 115)
+  canvas.arc(380, 50, a: 40, b: 20, start_angle: -60, end_angle: 115, inclination: 45)
+  canvas.fill
+
+  arc = canvas.graphic_object(:arc, cx: 450, cy: 50, a: 30, b: 30,
+                              start_angle: -30, end_angle: 105)
+  canvas.fill_color(0.4, 0.3, 0.4)
+  canvas.move_to(450, 50)
+  canvas.line_to(*arc.start_point)
+  arc.curves.each {|x, y, hash| canvas.curve_to(x, y, **hash)}
+  canvas.fill
+  arc.configure(start_angle: 105, end_angle: -30)
+  canvas.fill_color(0.3, 0.7, 0.7)
+  canvas.move_to(450, 50)
+  canvas.line_to(*arc.start_point)
+  arc.curves.each {|x, y, hash| canvas.curve_to(x, y, **hash)}
+  canvas.fill
+
+  arc = canvas.graphic_object(:arc, cx: 530, cy: 50, a: 40, b: 20,
+                              start_angle: -30, end_angle: 105)
+  canvas.fill_color(0.4, 0.3, 0.4)
+  canvas.move_to(530, 50)
+  canvas.line_to(*arc.start_point)
+  arc.curves.each {|x, y, hash| canvas.curve_to(x, y, **hash)}
+  canvas.fill
+  arc.configure(start_angle: 105, end_angle: -30)
+  canvas.fill_color(0.7, 0.7, 0.3)
+  canvas.move_to(530, 50)
+  canvas.line_to(*arc.start_point)
+  arc.curves.each {|x, y, hash| canvas.curve_to(x, y, **hash)}
+  canvas.fill
+end
+
+# Draws a circle and two half circles inside with different directions.
+def shapes_to_paint(canvas)
+  canvas.line_width = 2
+  canvas.arc(50, 50, a: 50)
+  canvas.arc(50, 60, a: 25, end_angle: 180, clockwise: false)
+  canvas.arc(50, 40, a: 25, end_angle: 180, clockwise: true)
+end
+
+# Draws arrows showing the direction of the #shapes_to_paint
+def arrows(canvas)
+  canvas.line_width = 1
+  canvas.polyline(95, 45, 100, 50, 105, 45)
+  canvas.polyline(55, 105, 50, 100, 55, 95)
+  canvas.polyline(-5, 55, 0, 50, 5, 55)
+  canvas.polyline(45, 5, 50, 0, 45, -5)
+  canvas.polyline(55, 90, 50, 85, 55, 80)
+  canvas.polyline(55, 20, 50, 15, 55, 10)
+  canvas.stroke
+end
+
+# Path painting and clipping operations: stroke, close and stroke, fill nonzero,
+# fill even-odd, fill nonzero and stroke, fill even-odd and stroke, close and
+# fill nonzero and stroke, close fill even-odd and stroke, clip even-odd, clip
+# nonzero
+canvas.translate(0, 190) do
+  canvas.fill_color(0.3, 0.7, 0.7)
+
+  [
+    [:stroke], [:close_stroke], [:fill, :nonzero], [:fill, :even_odd],
+    [:fill_stroke, :nonzero], [:fill_stroke, :even_odd],
+    [:close_fill_stroke, :nonzero], [:close_fill_stroke, :even_odd]
+  ].each_with_index do |op, index|
+    row = (1 - (index / 4))
+    column = index % 4
+    x = 50 + 80 * column
+    y = 80 * row
+    canvas.transform(0.6, 0, 0, 0.6, x, y) do
+      shapes_to_paint(canvas)
+      canvas.send(*op)
+      arrows(canvas)
+    end
+  end
+
+  canvas.fill_color(0.7, 0.7, 0.3)
+
+  [:even_odd, :nonzero].each_with_index do |op, index|
+    canvas.translate(370 + 110 * index, 20) do
+      canvas.circle(50, 50, 50)
+      canvas.circle(50, 50, 20)
+      canvas.clip_path(op)
+      canvas.end_path
+      canvas.rectangle(0, 0, 100, 100, radius: 100)
+      canvas.fill_stroke
+    end
+  end
+end
+
+# Some composite shapes, an image and a form XObject
+canvas.translate(0, 80) do
+  canvas.fill_color(0.3, 0.7, 0.7)
+  canvas.rectangle(50, 0, 80, 80, radius: 80)
+  canvas.fill
+
+  solid = canvas.graphic_object(:solid_arc, cx: 190, cy: 40, inner_a: 20, inner_b: 15,
+                                outer_a: 40, outer_b: 30, start_angle: 10, end_angle: 130)
+
+  canvas.line_width(0.5)
+  canvas.opacity(fill_alpha: 0.5, stroke_alpha: 0.2) do
+    canvas.fill_color('AA8888').draw(solid).fill_stroke
+    canvas.fill_color('88AA88').draw(solid, start_angle: 130, end_angle: 220).fill_stroke
+    canvas.fill_color('8888AA').draw(solid, start_angle: 220, end_angle: 10).fill_stroke
+
+    solid.configure(inner_a: 0, inner_b: 0, outer_a: 40, outer_b: 40, cx: 290)
+    canvas.fill_color('AA8888').draw(solid, start_angle: 10, end_angle: 130).fill_stroke
+    canvas.fill_color('88AA88').draw(solid, start_angle: 130, end_angle: 220).fill_stroke
+    canvas.fill_color('8888AA').draw(solid, start_angle: 220, end_angle: 10).fill_stroke
+
+    canvas.image(File.join(__dir__, 'machupicchu.jpg'), at: [350, 0], height: 80)
+  end
+end
+
+# A simple rainbow color band
+canvas.translate(0, 20) do
+  canvas.line_width = 6
+  freq = 0.1
+  0.upto(100) do |i|
+    r = Math.sin(freq * i) * 127 + 128
+    g = Math.sin(freq * i + 2) * 127 + 128
+    b = Math.sin(freq * i + 4) * 127 + 128
+    canvas.stroke_color(r.to_i, g.to_i, b.to_i)
+    canvas.line(50 + i * 5, 0, 50 + i * 5, 40)
+    canvas.stroke
+  end
+end
+
+# Reusing the already draw graphics for an XObject
+# Note that converting the page to a form XObject automatically closes all open
+# graphics states, therefore this can't be inside the above Canvas#translate
+# call
+form = doc.add(page.to_form_xobject(reference: false))
+canvas.rectangle(480, 80, form.box.width * (100 / form.box.height.to_f), 100).stroke
+canvas.xobject(form, at: [480, 80], height: 100)
+
+doc.write('graphics.pdf', optimize: true)

data/examples/003-arcs.rb

@@ -0,0 +1,50 @@
+# # Arcs and Solid Arcs
+#
+# This example shows how to use the graphic objects `:arc` and `:solid_arc` to
+# draw simple pie charts.
+#
+# Usage:
+# : `ruby arcs.rb`
+#
+
+require 'hexapdf'
+
+doc = HexaPDF::Document.new
+page = doc.pages.add
+canvas = page.canvas
+
+radius = 75
+
+# Left pie chart
+center = [page.box.width * 0.25, page.box.height * 0.85]
+pie = canvas.graphic_object(:solid_arc, cx: center[0], cy: center[1],
+                            outer_a: radius, outer_b: radius)
+canvas.fill_color('ddddff')
+canvas.draw(pie, start_angle: 30, end_angle: 110).fill
+canvas.fill_color('ffdddd')
+canvas.draw(pie, start_angle: 110, end_angle: 130).fill
+canvas.fill_color('ddffdd')
+canvas.draw(pie, start_angle: 130, end_angle: 30).fill
+
+arc = canvas.graphic_object(:arc, cx: center[0], cy: center[1],
+                            a: radius, b: radius)
+canvas.stroke_color('0000ff')
+canvas.draw(arc, start_angle: 30, end_angle: 110).stroke
+canvas.stroke_color('ff0000')
+canvas.draw(arc, start_angle: 110, end_angle: 130).stroke
+canvas.stroke_color('00ff00')
+canvas.draw(arc, start_angle: 130, end_angle: 30).stroke
+
+# Right pie chart
+center = [page.box.width * 0.75, page.box.height * 0.85]
+canvas.stroke_color('777777')
+pie = canvas.graphic_object(:solid_arc, cx: center[0], cy: center[1],
+                            outer_a: radius, outer_b: radius)
+canvas.fill_color('ddddff')
+canvas.draw(pie, start_angle: 30, end_angle: 110).fill_stroke
+canvas.fill_color('ffdddd')
+canvas.draw(pie, start_angle: 110, end_angle: 130).fill_stroke
+canvas.fill_color('ddffdd')
+canvas.draw(pie, start_angle: 130, end_angle: 30).fill_stroke
+
+doc.write('arcs.pdf', optimize: true)

data/examples/004-optimizing.rb

@@ -0,0 +1,23 @@
+# # Optimizing a PDF File
+#
+# This example shows how to read a PDF file, optimize it and write it
+# out again.
+#
+# The heavy work is done by the `:optimize` task which allows control
+# over which aspects should be optimized. See [HexaPDF::Task::Optimize]
+# for detailed information.
+#
+# The hexapdf binary provides an optimization command which does some
+# additional operations like optimizing the page tree.
+#
+# Usage:
+# : `ruby optimizing.rb INPUT.PDF`
+#
+
+require 'hexapdf'
+
+HexaPDF::Document.open(ARGV.shift) do |doc|
+  doc.task(:optimize, compact: true, object_streams: :generate,
+           compress_pages: false)
+  doc.write('optimizing.pdf')
+end

data/examples/005-merging.rb

@@ -0,0 +1,27 @@
+# # Merging PDF Files
+#
+# Merging of PDF files can be done in various ways of sophistication.
+#
+# The easiest way, which this example shows, just imports the pages of
+# the source files into the target file. This preserves the page
+# contents themselves but nothing else.
+#
+# For example, named destinations are not properly handled by the code.
+# Sometimes other things like attached files or a document outline
+# should also be preserved.
+#
+# The hexapdf binary provides a command for merging files which does
+# the merging in a more sophisticated way.
+#
+# Usage:
+# : `ruby merging.rb INPUT1.PDF INPUT2.PDF ...`
+#
+
+require 'hexapdf'
+
+target = HexaPDF::Document.new
+ARGV.each do |file|
+  pdf = HexaPDF::Document.open(file)
+  pdf.pages.each {|page| target.pages << target.import(page)}
+end
+target.write("2.merging.pdf", optimize: true)

data/examples/006-standard_pdf_fonts.rb

@@ -0,0 +1,73 @@
+# # Standard PDF Fonts
+#
+# This example shows all characters that are available in the standard 14 PDF
+# fonts.
+#
+# The standard 14 PDF fonts are those fonts that all PDF reading/viewing
+# applications need to support. They only provide a limited set of glyphs but
+# have the advantage that they don't need to be embedded.
+#
+# Usage:
+# : `ruby standard_pdf_fonts.rb`
+#
+
+require 'hexapdf'
+
+def base_encoding_for_font(font)
+  case font.font_name
+  when 'Symbol', 'ZapfDingbats'
+    font.encoding
+  else
+    HexaPDF::Font::Encoding.for_name(:WinAnsiEncoding)
+  end
+end
+
+doc = HexaPDF::Document.new
+
+HexaPDF::FontLoader::Standard14::MAPPING.each do |font_name, mapping|
+  mapping.each_key do |variant|
+    canvas = doc.pages.add.canvas
+    canvas.font("Helvetica", size: 14)
+    canvas.text("#{font_name} #{variant != :none ? variant : ''}", at: [100, 800])
+
+    canvas.font(font_name, size: 14, variant: variant)
+    canvas.leading = 20
+    font = canvas.font
+    encoding = base_encoding_for_font(font.wrapped_font)
+    used_glyphs = []
+
+    # Showing the glyphs of the WinAnsi or built-in encoding
+    canvas.move_text_cursor(offset: [100, 750])
+    (2..15).each do |y|
+      data = []
+      (0..15).each do |x|
+        code = y * 16 + x
+        glyph = font.glyph(encoding.name(code))
+        glyph = font.glyph(:space) if glyph.id == font.wrapped_font.missing_glyph_id
+        used_glyphs << glyph.name
+        data << glyph << -(2000 - glyph.width)
+      end
+      canvas.show_glyphs(data)
+      canvas.move_text_cursor
+    end
+
+    # Showing the remaining glyphs
+    canvas.move_text_cursor(offset: [0, -40], absolute: false)
+    glyphs = font.wrapped_font.metrics.character_metrics.keys.select do |k|
+      Symbol === k
+    end.sort - used_glyphs
+    canvas.font(font_name, size: 14, variant: variant, custom_encoding: true)
+    font = canvas.font
+    glyphs.each_slice(16).with_index do |slice, index|
+      data = []
+      slice.each do |name|
+        glyph = font.glyph(name)
+        data << glyph << -(2000 - glyph.width)
+      end
+      canvas.show_glyphs(data)
+      canvas.move_text_cursor
+    end
+  end
+end
+
+doc.write("standard_pdf_fonts.pdf", optimize: true)

data/examples/007-truetype.rb

@@ -0,0 +1,42 @@
+# # TrueType Fonts
+#
+# This example displays all glyphs of a TrueType font and shows that using a
+# TrueType font with HexaPDF is very similar to using one of the standard PDF
+# fonts.
+#
+# Before a TrueType font can be used, HexaPDF needs to be made aware of it. This
+# is done by setting the configuration option 'font.map'. For one-off usage of a
+# font file, the file name itself can also be used.
+#
+# Once that is done the [HexaPDF::Content::Canvas#font] method can be used as
+# usual.
+#
+# Usage:
+# : `ruby truetype.rb [FONT_FILE]`
+#
+
+require 'hexapdf'
+
+doc = HexaPDF::Document.new
+font_file = ARGV.shift || File.join(__dir__, '../test/data/fonts/Ubuntu-Title.ttf')
+wrapper = doc.fonts.add(font_file)
+max_gid = wrapper.wrapped_font[:maxp].num_glyphs
+
+255.times do |page|
+  break unless page * 256 < max_gid
+  canvas = doc.pages.add.canvas
+  canvas.font("Helvetica", size: 10)
+  canvas.text("Font: #{wrapper.wrapped_font.full_name}", at: [50, 825])
+
+  canvas.font(font_file, size: 15)
+  16.times do |y|
+    canvas.move_text_cursor(offset: [50, 800 - y * 50], absolute: true)
+    canvas.show_glyphs((0..15).map do |i|
+      gid = page * 256 + y * 16 + i
+      glyph = wrapper.glyph(gid)
+      gid >= max_gid ? [] : [glyph, -(2000 - glyph.width)]
+    end.flatten!)
+  end
+end
+
+doc.write("truetype.pdf", optimize: true)

data/examples/008-show_char_bboxes.rb

@@ -0,0 +1,55 @@
+# # Show Character Bounding Boxes
+#
+# This examples shows how to process the contents of a page. It finds all
+# characters on a page and surrounds them with their bounding box. Additionally,
+# all consecutive text runs are also surrounded by a box.
+#
+# The code provides two ways of generating the boxes. The commented part of
+# `ShowTextProcessor#show_text` uses a polyline since some characters may be
+# transforemd (rotated or skewed). The un-commented part uses rectangles which
+# is faster and correct for most but not all cases.
+#
+# Usage:
+# : `ruby show_char_boxes.rb INPUT.PDF`
+#
+
+require 'hexapdf'
+
+class ShowTextProcessor < HexaPDF::Content::Processor
+
+  def initialize(page)
+    super()
+    @canvas = page.canvas(type: :overlay)
+  end
+
+  def show_text(str)
+    boxes = decode_text_with_positioning(str)
+    return if boxes.string.empty?
+
+    @canvas.line_width = 1
+    @canvas.stroke_color(224, 0, 0)
+    # Polyline for transformed characters
+    #boxes.each {|box| @canvas.polyline(*box.points).close_subpath.stroke}
+    # Using rectangles is faster but not 100% correct
+    boxes.each do |box|
+      x, y = *box.lower_left
+      tx, ty = *box.upper_right
+      @canvas.rectangle(x, y, tx - x, ty - y).stroke
+    end
+
+    @canvas.line_width = 0.5
+    @canvas.stroke_color(0, 224, 0)
+    @canvas.polyline(*boxes.lower_left, *boxes.lower_right,
+                     *boxes.upper_right, *boxes.upper_left).close_subpath.stroke
+  end
+  alias :show_text_with_positioning :show_text
+
+end
+
+doc = HexaPDF::Document.open(ARGV.shift)
+doc.pages.each_with_index do |page, index|
+  puts "Processing page #{index + 1}"
+  processor = ShowTextProcessor.new(page)
+  page.process_contents(processor)
+end
+doc.write('show_char_boxes.pdf', optimize: true)

data/examples/009-text_layouter_alignment.rb

@@ -0,0 +1,47 @@
+# # Text Layouter - Alignment
+#
+# The [HexaPDF::Layout::TextLayouter] class can be used to easily lay out text
+# inside a rectangular area, with various horizontal and vertical alignment
+# options.
+#
+# The text can be aligned horizontally by setting [HexaPDF::Layout::Style#align]
+# and vertically by [HexaPDF::Layout::Style#valign]. In this example, a sample
+# text is laid out in all possible combinations.
+#
+# Usage:
+# : `ruby text_layouter_alignment.rb`
+#
+
+require 'hexapdf'
+
+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. at".tr("\n", ' ')
+
+doc = HexaPDF::Document.new
+canvas = doc.pages.add.canvas
+canvas.font("Times", size: 10, variant: :bold)
+
+width = 100
+height = 150
+y_base = 800
+tf = HexaPDF::Layout::TextFragment.create(sample_text,
+                                          font: doc.fonts.add("Times"))
+tl = HexaPDF::Layout::TextLayouter.new
+
+[:left, :center, :right, :justify].each_with_index do |align, x_index|
+  x = x_index * (width + 20) + 70
+  canvas.text(align.to_s, at: [x + 40, y_base + 15])
+
+  [:top, :center, :bottom].each_with_index do |valign, y_index|
+    y = y_base - (height + 30) * y_index
+    canvas.text(valign.to_s, at: [20, y - height / 2]) if x_index == 0
+
+    tl.style.align(align).valign(valign)
+    tl.fit([tf], width, height).draw(canvas, x, y)
+    canvas.stroke_color(128, 0, 0).rectangle(x, y, width, -height).stroke
+  end
+end
+
+doc.write("text_layouter_alignment.pdf", optimize: true)

data/examples/010-text_layouter_inline_boxes.rb

@@ -0,0 +1,64 @@
+# # Text Layouter - Inline Boxes
+#
+# The [HexaPDF::Layout::TextLayouter] class can be used to easily lay out text
+# mixed with inline boxes.
+#
+# Inline boxes are used for showing graphics that follow the flow of the text.
+# This means that their horizontal and their general vertical position is
+# determined by the text layout functionality. However, inline boxes may be
+# vertically aligned to various positions, like the baseline, the top/bottom of
+# the text and the top/bottom of the line.
+#
+# This example shows some text containing emoticons that are replaced with their
+# graphical representation, with normal smileys being aligned to the baseline
+# and winking smileys to the top of the line.
+#
+# An inline box is a simple wrapper around a generic box that adheres to the
+# necessary interface. Therefore they don't do any drawing operations themselves
+# but delegate to their wrapped box. This means, for example, that inline boxes
+# can use background colors or borders without doing anything special.
+#
+# Usage:
+# : `ruby text_layouter_inline_boxes.rb`
+#
+
+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", ' ') * 4
+
+doc = HexaPDF::Document.new
+emoji_smile = doc.images.add(File.join(__dir__, "emoji-smile.png"))
+emoji_wink = doc.images.add(File.join(__dir__, "emoji-wink.png"))
+size = 10
+
+items = sample_text.split(/(:-\)|;-\))/).map do |part|
+  case part
+  when ':-)'
+    InlineBox.create(width: size * 2, height: size * 2, content_box: true,
+                     background_color: [162, 234, 247], padding: 2) do |canvas, box|
+      canvas.image(emoji_smile, at: [0, 0], width: box.content_width)
+    end
+  when ';-)'
+    InlineBox.create(width: size, height: size, content_box: true,
+                     valign: :top, padding: 5, margin: [0, 10],
+                     border: {width: [1, 2], color: [200, 40]}) do |canvas, box|
+      canvas.image(emoji_wink, at: [0, 0], width: box.content_width)
+    end
+  else
+    TextFragment.create(part, font: doc.fonts.add("Times"), font_size: 18)
+  end
+end
+
+layouter = TextLayouter.new
+layouter.style.align = :justify
+layouter.style.line_spacing(:proportional, 1.5)
+layouter.fit(items, 500, 700).draw(doc.pages.add.canvas, 50, 800)
+
+doc.write("text_layouter_inline_boxes.pdf")