prawn 2.4.0 → 2.5.0

data/manual/graphics/blend_mode.rb

@@ -1,52 +0,0 @@
-# frozen_string_literal: true
-
-# Blend modes can be used to change the way two layers (images, graphics,
-# text, etc.) are blended together. The <code>blend_mode</code> method
-# accepts a single blend mode or an array of blend modes. PDF viewers should
-# blend the layers based on the first recognized blend mode.
-#
-# Valid blend modes in v1.4 of the PDF spec include :Normal, :Multiply, :Screen,
-# :Overlay, :Darken, :Lighten, :ColorDodge, :ColorBurn, :HardLight, :SoftLight,
-# :Difference, :Exclusion, :Hue, :Saturation, :Color, and :Luminosity.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  start_new_page
-
-  # https://commons.wikimedia.org/wiki/File:Blend_modes_2.-bottom-layer.jpg#/media/File:Blend_modes_2.-bottom-layer.jpg
-  bottom_layer = "#{Prawn::DATADIR}/images/blend_modes_bottom_layer.jpg"
-
-  # https://commons.wikimedia.org/wiki/File:Blend_modes_1.-top-layer.jpg#/media/File:Blend_modes_1.-top-layer.jpg
-  top_layer = "#{Prawn::DATADIR}/images/blend_modes_top_layer.jpg"
-
-  blend_modes = %i[
-    Normal Multiply Screen Overlay Darken Lighten ColorDodge
-    ColorBurn HardLight SoftLight Difference Exclusion Hue
-    Saturation Color Luminosity
-  ]
-  blend_modes.each_with_index do |blend_mode, index|
-    x = index % 4 * 135
-    y = cursor - (index / 4 * 200)
-
-    image bottom_layer, at: [x, y], fit: [125, 125]
-    blend_mode(blend_mode) do
-      image top_layer, at: [x, y], fit: [125, 125]
-    end
-
-    y -= 130
-
-    fill_color '009ddc'
-    fill_rectangle [x, y], 75, 25
-    blend_mode(blend_mode) do
-      fill_color 'fdb827'
-      fill_rectangle [x + 50, y], 75, 25
-    end
-
-    y -= 30
-
-    fill_color '000000'
-    text_box blend_mode.to_s, at: [x, y]
-  end
-end

data/manual/graphics/circle_and_ellipse.rb

@@ -1,21 +0,0 @@
-# frozen_string_literal: true
-
-# To define a <code>circle</code> all you need is the center point and the
-# radius.
-#
-# To define an <code>ellipse</code> you provide the center point and two radii
-# (or axes) values. If the second radius value is ommitted, both radii will be
-# equal and you will end up drawing a circle.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  stroke_circle [100, 300], 100
-
-  fill_ellipse [200, 100], 100, 50
-
-  fill_ellipse [400, 100], 50
-end

data/manual/graphics/color.rb

@@ -1,22 +0,0 @@
-# frozen_string_literal: true
-
-# We can change the stroke and fill colors providing an HTML rgb 6 digit color
-# code string ("AB1234") or 4 values for CMYK.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  # Fill with Yellow using RGB (Unlike css, there is no leading #)
-  fill_color 'FFFFCC'
-  fill_polygon [50, 150], [150, 200], [250, 150], [250, 50], [150, 0], [50, 50]
-
-  # Stroke with Purple using CMYK
-  stroke_color 50, 100, 0, 0
-  stroke_rectangle [300, 300], 200, 100
-
-  # Both together
-  fill_and_stroke_circle [400, 100], 50
-end

data/manual/graphics/common_lines.rb

@@ -1,29 +0,0 @@
-# frozen_string_literal: true
-
-# Prawn provides helpers for drawing some commonly used lines:
-#
-# <code>vertical_line</code> and <code>horizontal_line</code> do just what their
-# names imply. Specify the start and end point at a fixed coordinate to define
-# the line.
-#
-# <code>horizontal_rule</code> draws a horizontal line on the current bounding
-# box from border to border, using the current y position.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  stroke_color 'ff0000'
-
-  stroke do
-    # just lower the current y position
-    move_down 50
-    horizontal_rule
-
-    vertical_line 100, 300, at: 50
-
-    horizontal_line 200, 500, at: 150
-  end
-end

data/manual/graphics/fill_and_stroke.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-# There are two drawing primitives in Prawn: <code>fill</code> and
-# <code>stroke</code>.
-#
-# These are the methods that actually draw stuff on the document. All the other
-# drawing shapes like <code>rectangle</code>, <code>circle</code> or
-# <code>line_to</code> define drawing paths. These paths need to be either
-# stroked or filled to gain form on the document.
-#
-# Calling these methods without a block will act on the drawing path that
-# has been defined prior to the call.
-#
-# Calling with a block will act on the drawing path set within the
-# block.
-#
-# Most of the methods which define drawing paths have methods of the same name
-# starting with stroke_ and fill_ which create the drawing path and then stroke
-# or fill it.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  # No block
-  line [0, 200], [100, 150]
-  stroke
-
-  rectangle [0, 100], 100, 100
-  fill
-
-  # With block
-  stroke { line [200, 200], [300, 150] }
-  fill { rectangle [200, 100], 100, 100 }
-
-  # Method hook
-  stroke_line [400, 200], [500, 150]
-  fill_rectangle [400, 100], 100, 100
-end

data/manual/graphics/fill_rules.rb

@@ -1,38 +0,0 @@
-# frozen_string_literal: true
-
-# Prawn's fill operators (<code>fill</code> and <code>fill_and_stroke</code>
-# both accept a <code>:fill_rule</code> option. These rules determine which
-# parts of the page are counted as "inside" vs. "outside" the path. There are
-# two fill rules:
-#
-# * <code>:nonzero_winding_number</code> (default): a point is inside the path
-# if a ray from that point to infinity crosses a nonzero "net number" of path
-# segments, where path segments intersecting in one direction are counted as
-# positive and those in the other direction negative.
-#
-# * <code>:even_odd</code>: A point is inside the path if a ray from that point
-# to infinity crosses an odd number of path segments, regardless of direction.
-#
-# The differences between the fill rules only come into play with complex
-# paths; they are identical for simple shapes.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  pentagram = [[181, 95], [0, 36], [111, 190], [111, 0], [0, 154]]
-
-  stroke_color 'ff0000'
-  line_width 2
-
-  text_box 'Nonzero Winding Number',
-    at: [50, 215],
-    width: 170,
-    align: :center
-  polygon(*pentagram.map { |x, y| [x + 50, y] })
-  fill_and_stroke
-
-  text_box 'Even-Odd', at: [330, 215], width: 170, align: :center
-  polygon(*pentagram.map { |x, y| [x + 330, y] })
-  fill_and_stroke(fill_rule: :even_odd)
-end

data/manual/graphics/gradients.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-# Note that because of the way PDF renders radial gradients in order to get
-# solid fill your start circle must be fully inside your end circle.
-# Otherwise you will get triangle fill like illustrated in the example below.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  self.line_width = 10
-
-  # Linear Gradients
-  fill_gradient [0, 250], [100, 150], 'ff0000', '0000ff'
-  fill_rectangle [0, 250], 100, 100
-
-  stroke_gradient [150, 150], [250, 250], '00ffff', 'ffff00'
-  stroke_rectangle [150, 250], 100, 100
-
-  fill_gradient [300, 250], [400, 150], 'ff0000', '0000ff'
-  stroke_gradient [300, 150], [400, 250], '00ffff', 'ffff00'
-  fill_and_stroke_rectangle [300, 250], 100, 100
-
-  rotate 45, origin: [500, 200] do
-    stops = { 0 => 'ff0000', 0.6 => '999900', 0.8 => '00cc00', 1 => '4444ff' }
-    fill_gradient from: [460, 240], to: [540, 160], stops: stops
-    fill_rectangle [460, 240], 80, 80
-  end
-
-  # Radial gradients
-  fill_gradient [50, 50], 0, [50, 50], 70.71, 'ff0000', '0000ff'
-  fill_rectangle [0, 100], 100, 100
-
-  stroke_gradient [200, 50], 45, [200, 50], 70.71, '00ffff', 'ffff00'
-  stroke_rectangle [150, 100], 100, 100
-
-  stroke_gradient [350, 50], 45, [350, 50], 70.71, '00ffff', 'ffff00'
-  fill_gradient [350, 50], 0, [350, 50], 70.71, 'ff0000', '0000ff'
-  fill_and_stroke_rectangle [300, 100], 100, 100
-
-  fill_gradient [500, 100], 50, [500, 0], 0, 'ff0000', '0000ff'
-  fill_rectangle [450, 100], 100, 100
-end

data/manual/graphics/graphics.rb

@@ -1,64 +0,0 @@
-# frozen_string_literal: true
-
-# Examples for the Graphics package.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename, page_size: 'FOLIO') do
-  package 'graphics' do |p|
-    p.section 'Basics' do |s|
-      s.example 'helper'
-      s.example 'fill_and_stroke'
-    end
-
-    p.section 'Shapes' do |s|
-      s.example 'lines_and_curves'
-      s.example 'common_lines'
-      s.example 'rectangle'
-      s.example 'polygon'
-      s.example 'circle_and_ellipse'
-    end
-
-    p.section 'Fill and Stroke settings' do |s|
-      s.example 'line_width'
-      s.example 'stroke_cap'
-      s.example 'stroke_join'
-      s.example 'stroke_dash'
-      s.example 'color'
-      s.example 'gradients'
-      s.example 'transparency'
-      s.example 'soft_masks'
-      s.example 'blend_mode'
-      s.example 'fill_rules'
-    end
-
-    p.section 'Transformations' do |s|
-      s.example 'rotate'
-      s.example 'translate'
-      s.example 'scale'
-    end
-
-    p.intro do
-      prose <<-TEXT
-        Here we show all the drawing methods provided by Prawn. Use them to draw
-        the most beautiful imaginable things.
-
-        Most of the content that you'll add to your pdf document will use the
-        graphics package. Even text is rendered on a page just like a rectangle
-        so even if you never use any of the shapes described here you should at
-        least read the basic examples.
-
-        The examples show:
-      TEXT
-
-      list(
-        'All the possible ways that you can fill or stroke shapes on a page',
-        'How to draw all the shapes that Prawn has to offer from a measly '\
-          'line to a mighty polygon or ellipse',
-        'The configuration options for stroking lines and filling shapes',
-        'How to apply transformations to your drawing space'
-      )
-    end
-  end
-end

data/manual/graphics/helper.rb

@@ -1,34 +0,0 @@
-# frozen_string_literal: true
-
-# To produce this manual we use the <code>stroke_axis</code> helper method
-# within the examples.
-#
-# <code>stroke_axis</code> prints the x and y axis for the current bounding box
-# with markers in 100 increments. The defaults can be changed with various
-# options.
-#
-# Note that the examples define a custom <code>:height</code> option so that
-# only the example canvas is used (as seen with the output of the first line of
-# the example code).
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-  stroke_axis(
-    at: [70, 70],
-    height: 200,
-    step_length: 50,
-    negative_axes_length: 5,
-    color: '0000FF'
-  )
-  stroke_axis(
-    at: [140, 140],
-    width: 200,
-    height: cursor.to_i - 140,
-    step_length: 20,
-    negative_axes_length: 40,
-    color: 'FF0000'
-  )
-end

data/manual/graphics/line_width.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-# The <code>line_width=</code> method sets the stroke width for subsequent
-# stroke calls.
-#
-# Since Ruby assumes that an unknown variable on the left hand side of an
-# assignment is a local temporary, rather than a setter method, if you are using
-# the block call to <code>Prawn::Document.generate</code> without passing params
-# you will need to call <code>line_width</code> on self.
-
-# rubocop: disable Lint/UselessAssignment
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  y = 250
-
-  3.times do |i|
-    case i
-    when 0 then line_width = 10 # This call will have no effect
-    when 1 then self.line_width = 10
-    when 2 then self.line_width = 25
-    end
-
-    stroke do
-      horizontal_line 50, 150, at: y
-      rectangle [275, y + 25], 50, 50
-      circle [500, y], 25
-    end
-
-    y -= 100
-  end
-end
-# rubocop: enable Lint/UselessAssignment

data/manual/graphics/lines_and_curves.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-# Prawn supports drawing both lines and curves starting either at the current
-# position, or from a specified starting position.
-#
-# <code>line_to</code> and <code>curve_to</code> set the drawing path from the
-# current drawing position to the specified point. The initial drawing position
-# can be set with <code>move_to</code>. They are useful when you want to chain
-# successive calls because the drawing position will be set to the specified
-# point afterwards.
-#
-# <code>line</code> and <code>curve</code> set the drawing path between the two
-# specified points.
-#
-# Both curve methods define a Bezier curve bounded by two aditional points
-# provided as the <code>:bounds</code> param.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  # line_to and curve_to
-  stroke do
-    move_to 0, 0
-
-    line_to 100, 100
-    line_to 0, 100
-
-    curve_to [150, 250], bounds: [[20, 200], [120, 200]]
-    curve_to [200, 0], bounds: [[150, 200], [450, 10]]
-  end
-
-  # line and curve
-  stroke do
-    line [300, 200], [400, 50]
-    curve [500, 0], [400, 200], bounds: [[600, 300], [300, 390]]
-  end
-end

data/manual/graphics/polygon.rb

@@ -1,27 +0,0 @@
-# frozen_string_literal: true
-
-# Drawing polygons in Prawn is easy, just pass a sequence of points to one of
-# the polygon family of methods.
-#
-# Just like <code>rounded_rectangle</code> we also have
-# <code>rounded_polygon</code>. The only difference is the radius param comes
-# before the polygon points.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  # Triangle
-  stroke_polygon [50, 200], [50, 300], [150, 300]
-
-  # Hexagon
-  fill_polygon [50, 150], [150, 200], [250, 150], [250, 50], [150, 0], [50, 50]
-
-  # Pentagram
-  pentagon_points = [500, 100], [430, 5], [319, 41], [319, 159], [430, 195]
-  pentagram_points = [0, 2, 4, 1, 3].map { |i| pentagon_points[i] }
-
-  stroke_rounded_polygon(20, *pentagram_points)
-end

data/manual/graphics/rectangle.rb

@@ -1,20 +0,0 @@
-# frozen_string_literal: true
-
-# To draw a rectangle, just provide the upper-left corner, width and height to
-# the <code>rectangle</code> method.
-#
-# There's also <code>rounded_rectangle</code>. Just provide an additional radius
-# value for the rounded corners.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  stroke do
-    rectangle [100, 300], 100, 200
-
-    rounded_rectangle [300, 300], 100, 200, 20
-  end
-end

data/manual/graphics/rotate.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-# This transformation is used to rotate the user space. Give it an angle
-# and an <code>:origin</code> point about which to rotate and a block.
-# Everything inside the block will be drawn with the rotated coordinates.
-#
-# The angle is in degrees.
-#
-# If you omit the <code>:origin</code> option the page origin will be used.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  fill_circle [250, 200], 2
-
-  12.times do |i|
-    rotate(i * 30, origin: [250, 200]) do
-      stroke_rectangle [350, 225], 100, 50
-      draw_text "Rotated #{i * 30}°", size: 10, at: [360, 205]
-    end
-  end
-end

data/manual/graphics/scale.rb

@@ -1,42 +0,0 @@
-# frozen_string_literal: true
-
-# This transformation is used to scale the user space. Give it an scale factor
-# and an <code>:origin</code> point and everything inside the block will be
-# scaled using the origin point as reference.
-#
-# If you omit the <code>:origin</code> option the page origin will be used.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  width = 100
-  height = 50
-
-  x = 50
-  y = 200
-
-  stroke_rectangle [x, y], width, height
-  text_box 'reference rectangle', at: [x + 10, y - 10], width: width - 20
-
-  scale(2, origin: [x, y]) do
-    stroke_rectangle [x, y], width, height
-    text_box 'rectangle scaled from upper-left corner',
-      at: [x, y - height - 5],
-      width: width
-  end
-
-  x = 350
-
-  stroke_rectangle [x, y], width, height
-  text_box 'reference rectangle', at: [x + 10, y - 10], width: width - 20
-
-  scale(2, origin: [x + width / 2, y - height / 2]) do
-    stroke_rectangle [x, y], width, height
-    text_box 'rectangle scaled from center',
-      at: [x, y - height - 5],
-      width: width
-  end
-end

data/manual/graphics/soft_masks.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-# Soft masks are used for more complex alpha channel manipulations. You can use
-# arbitrary drawing functions for creation of soft masks. The resulting alpha
-# channel is made of greyscale version of the drawing (luminosity channel to be
-# precise). So while you can use any combination of colors for soft masks it's
-# easier to use greyscales. Black will result in full transparency and white
-# will make region fully opaque.
-#
-# Soft mask is a part of page graphic state. So if you want to apply soft mask
-# only to a part of page you need to enclose drawing instructions in
-# <code>save_graphics_state</code> block.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  save_graphics_state do
-    soft_mask do
-      0.upto 15 do |i|
-        fill_color 0, 0, 0, 100.0 / 16.0 * (15 - i)
-        fill_circle [75 + i * 25, 100], 60
-      end
-    end
-
-    fill_color '009ddc'
-    fill_rectangle [0, 60], 600, 20
-
-    fill_color '963d97'
-    fill_rectangle [0, 80], 600, 20
-
-    fill_color 'e03a3e'
-    fill_rectangle [0, 100], 600, 20
-
-    fill_color 'f5821f'
-    fill_rectangle [0, 120], 600, 20
-
-    fill_color 'fdb827'
-    fill_rectangle [0, 140], 600, 20
-
-    fill_color '61bb46'
-    fill_rectangle [0, 160], 600, 20
-  end
-end

data/manual/graphics/stroke_cap.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-# The cap style defines how the edge of a line or curve will be drawn. There are
-# three types: <code>:butt</code> (the default), <code>:round</code> and
-# <code>:projecting_square</code>
-#
-# The difference is better seen with thicker lines. With <code>:butt</code>
-# lines are drawn starting and ending at the exact points provided. With both
-# <code>:round</code> and <code>:projecting_square</code> the line is projected
-# beyond the start and end points.
-#
-# Just like <code>line_width=</code> the <code>cap_style=</code> method needs an
-# explicit receiver to work.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  self.line_width = 25
-
-  %i[butt round projecting_square].each_with_index do |cap, i|
-    self.cap_style = cap
-
-    y = 250 - i * 100
-    stroke_horizontal_line 100, 300, at: y
-    stroke_circle [400, y], 15
-  end
-end

data/manual/graphics/stroke_dash.rb

@@ -1,47 +0,0 @@
-# frozen_string_literal: true
-
-# This sets the dashed pattern for lines and curves. The (dash) length defines
-# how long each dash will be.
-#
-# The <code>:space</code> option defines the length of the space between the
-# dashes.
-#
-# The <code>:phase</code> option defines the start point of the sequence of
-# dashes and spaces.
-#
-# Complex dash patterns can be specified by using an array with alternating
-# dash/gap lengths for the first parameter (note that the <code>:space</code>
-# option is ignored in this case).
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  stroke_axis
-
-  dash([1, 2, 3, 2, 1, 5], phase: 6)
-  stroke_horizontal_line 50, 500, at: 230
-  dash([1, 2, 3, 4, 5, 6, 7, 8])
-  stroke_horizontal_line 50, 500, at: 220
-
-  base_y = 210
-
-  24.times do |i|
-    length = (i / 4) + 1
-    space = length # space between dashes same length as dash
-    phase = 0 # start with dash
-
-    case i % 4
-    when 0 then base_y -= 5
-    when 1 then phase = length # start with space between dashes
-    when 2 then space = length * 0.5 # space between dashes half as long as dash
-    when 3
-      space = length * 0.5 # space between dashes half as long as dash
-      phase = length # start with space between dashes
-    end
-    base_y -= 5
-
-    dash(length, space: space, phase: phase)
-    stroke_horizontal_line 50, 500, at: base_y - (2 * i)
-  end
-end