hexapdf 0.7.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ffd1dd41128f1ef75e1caf26f415e908509f881bfdf1595da9b45c633c26bb59
-  data.tar.gz: ef1ae7147fa94bcf361beae3a340acdd1f6f2a72cc3fdbad0d5e46766957c9b7
+  metadata.gz: 0a7cfa4a446d0ec5c87bc204de8040e8c9671e299592901644a1e1c64b5e69af
+  data.tar.gz: 14e0e42f0d49eb0483be23446b8507d3f3d6e0b724b2c71530ff997bc97f33b3
 SHA512:
-  metadata.gz: dc5242710665cf697db8085fcaf0e5096fce0179308a427e4dccbba3a9067db7713a22f1e83a6732ba943b4aa120eb1df69472b32fdcbae7f430c2cfc7364250
-  data.tar.gz: b700fb5ce735aa6ff38cb33b88f37cb4a7eece29979f0be5abaab884f8aef2f1fcf23336b47e9218ea237d04d27012a46df3fd5154f92b33b6a635d31139a180
+  metadata.gz: c9e582a53eb0a946287a23449a563d7c7b1d29994b7ad799a199fdd23aaca6e01a76c15e35f6c07aaad69407247e859f7ab9501df076c58e9ed515ef6333e43a
+  data.tar.gz: 6c0bf3a0e42a9b7228d2a8939056b3aceb037ff66540e4b6d8b917b1e4eb51d6c9213440278da9980a163067542f73ab874e6c798d0750b938a8afd8977707fd

data/CHANGELOG.md

@@ -1,3 +1,41 @@
+## 0.8.0 - 2018-10-26
+
+### Added
+
+* [HexaPDF::Layout::Frame] for box positioning and easier text layouting
+  inside an arbitrary polygon
+* [HexaPDF::Layout::TextBox] for displaying text in a rectangular and for
+  flowing text inside a frame
+* [HexaPDF::Layout::WidthFromPolygon] for getting a width specification from
+  a polygon for use with the text layouting engine
+* [HexaPDF::Type::Image#width] and [HexaPDF::Type::Image#height] convenience
+  methods
+* [HexaPDF::Type::FontType3] for Type 3 font support
+* [HexaPDF::Content::GraphicObject::Geom2D] for [Geom2D] object drawing support
+* [HexaPDF::Type::Page#orientation] for easy determination of page orientation
+* [HexaPDF::Type::Page#rotate] for rotating a page
+* [HexaPDF::Layout::Style::Quad#set] for setting all values at once
+
+### Changed
+
+* [HexaPDF::Document#validate] to also yield the object that failed validation
+* [HexaPDF::Type::Page#box] to allow setting the value for a box
+* [HexaPDF::Layout::TextLayouter#fit] to allow fitting text into arbitrarily
+  shaped areas
+* [HexaPDF::Layout::TextLayouter] to return a new
+  [HexaPDF::Layout::TextLayouter::Result] structure when `#fit` is called that
+  includes the `#draw` method
+* [HexaPDF::Layout::TextLayouter#fit] to require the height argument
+* Refactored [HexaPDF::Layout::Box] to make using it a bit easier
+
+### Fixed
+
+* Validation and conversion of dictionary fields with multiple possible types
+* Box border drawing when border width is greater than edge length
+
+[geom2d]: https://github.com/gettalong/geom2d
+
+
 ## 0.7.0 - 2018-06-19
 
 ### Changed
@@ -25,7 +63,7 @@
   table directory
 * [HexaPDF::Font::TrueType::Builder] to pad the table data to achieve the
   correct alignment
-* [HexaPDF::Filter::FlateDecode] by removing the Zlib pools since ther were
+* [HexaPDF::Filter::FlateDecode] by removing the Zlib pools since they were
   not thread safe
 * All color space classes to accept the color space definition as argument to
   `::new`

data/CONTRIBUTERS

@@ -1,3 +1,3 @@
   Count Name
 ======= ====
-    928 Thomas Leitner <t_leitner@gmx.at>
+    980 Thomas Leitner <t_leitner@gmx.at>

data/LICENSE

@@ -24,3 +24,6 @@ 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/>.

data/README.md

@@ -93,7 +93,8 @@ So why use HexaPDF?
 
 ## License
 
-See the LICENSE file for licensing details.
+AGPL - see the LICENSE file for licensing details. Commercial licenses are available at
+<https://gettalong.at/hexapdf/>.
 
 Some included files have a different license:
 

data/Rakefile

@@ -65,12 +65,14 @@ namespace :dev do
     s.executables = ['hexapdf']
     s.default_executable = 'hexapdf'
     s.add_dependency('cmdparse', '~> 3.0', '>= 3.0.3')
+    s.add_dependency('geom2d', '~> 0.1')
     s.add_development_dependency('kramdown', '~> 1.0', '>= 1.13.0')
+    s.add_development_dependency('rubocop', '~> 0.58', '>= 0.58.2')
     s.required_ruby_version = '>= 2.4'
 
     s.author = 'Thomas Leitner'
     s.email = 't_leitner@gmx.at'
-    s.homepage = "http://hexapdf.gettalong.org"
+    s.homepage = "https://hexapdf.gettalong.org"
   end
 
   Gem::PackageTask.new(spec) do |pkg|

data/VERSION

@@ -1 +1 @@
-0.7.0
+0.8.0

data/examples/{graphics.rb → 002-graphics.rb}

@@ -3,7 +3,7 @@
 # This example shows many of the operations that the canvas implementation
 # allows.
 #
-# Note that the PDF canvas has its origin in the lower left corner of the page.
+# 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.
 #

data/examples/{arc.rb → 003-arcs.rb}

@@ -4,7 +4,7 @@
 # draw simple pie charts.
 #
 # Usage:
-# : `ruby arc.rb`
+# : `ruby arcs.rb`
 #
 
 require 'hexapdf'
@@ -47,4 +47,4 @@ 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('arc.pdf', optimize: true)
+doc.write('arcs.pdf', optimize: true)

data/examples/{text_layouter_alignment.rb → 009-text_layouter_alignment.rb}

@@ -26,9 +26,9 @@ canvas.font("Times", size: 10, variant: :bold)
 width = 100
 height = 150
 y_base = 800
-tl = HexaPDF::Layout::TextLayouter.create(sample_text, width: width,
-                                          height: height,
+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
@@ -39,7 +39,7 @@ tl = HexaPDF::Layout::TextLayouter.create(sample_text, width: width,
     canvas.text(valign.to_s, at: [20, y - height / 2]) if x_index == 0
 
     tl.style.align(align).valign(valign)
-    tl.draw(canvas, x, y, fit: true)
+    tl.fit([tf], width, height).draw(canvas, x, y)
     canvas.stroke_color(128, 0, 0).rectangle(x, y, width, -height).stroke
   end
 end

data/examples/{text_layouter_inline_boxes.rb → 010-text_layouter_inline_boxes.rb}

@@ -41,16 +41,14 @@ size = 10
 items = sample_text.split(/(:-\)|;-\))/).map do |part|
   case part
   when ':-)'
-    style = {background_color: [162, 234, 247], padding: 2}
-    InlineBox.create(content_width: size * 2, content_height: size * 2,
-                     style: style) do |canvas, box|
+    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 ';-)'
-    style = {padding: 5, margin: [0, 10],
-             border: {width: [1, 2], color: [200, 40]}}
-    InlineBox.create(content_width: size, content_height: size,
-                     valign: :top, style: style) do |canvas, box|
+    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
@@ -58,9 +56,9 @@ items = sample_text.split(/(:-\)|;-\))/).map do |part|
   end
 end
 
-layouter = TextLayouter.new(items: items, width: 500, height: 700)
+layouter = TextLayouter.new
 layouter.style.align = :justify
 layouter.style.line_spacing(:proportional, 1.5)
-layouter.draw(doc.pages.add.canvas, 50, 800)
+layouter.fit(items, 500, 700).draw(doc.pages.add.canvas, 50, 800)
 
 doc.write("text_layouter_inline_boxes.pdf")

data/examples/{text_layouter_line_wrapping.rb → 011-text_layouter_line_wrapping.rb}

@@ -44,13 +44,14 @@ text = "Hello! Fly-fishing\nand wand\u{00AD}ering\taround - fanta\u{200B}stic" \
 
 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|
-  layouter = HexaPDF::Layout::TextLayouter.create(text, width: width,
-                                                  font: doc.fonts.add("Times"))
-  layouter.draw(canvas, x, y)
+  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, -layouter.actual_height).stroke
-  y -= layouter.actual_height + 5
+  canvas.rectangle(x, y, width, -result.height).stroke
+  y -= result.height + 5
 end
 
 doc.write("text_layouter_line_wrapping.pdf", optimize: true)

data/examples/{text_layouter_styling.rb → 012-text_layouter_styling.rb}

@@ -30,11 +30,10 @@ end
 
 # Draws the text at the given [x, y] position onto the canvas and returns the
 # new y position.
-def draw_text(layouter, canvas, x, y)
-  rest, = layouter.fit
-  raise "Error" unless rest.empty?
-  layouter.draw(canvas, x, y)
-  y - layouter.actual_height
+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
@@ -103,7 +102,7 @@ styles = {
 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
@@ -117,8 +116,7 @@ styles.each do |desc, variations|
     end
   end
   items.unshift(fragment(desc + ": ", fill_color: [255, 0, 0], **base_style))
-  layouter = TextLayouter.new(items: items, width: width, style: base_style)
-  y = draw_text(layouter, canvas, left, y) - 20
+  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)