prawn 2.4.0 → 2.5.0

data/manual/repeatable_content/alternate_page_numbering.rb

@@ -1,36 +0,0 @@
-# frozen_string_literal: true
-
-# Below is the code to generate page numbers that alternate being rendered
-# on the right and left side of the page. The first page will have a "1" in
-# the bottom right corner. The second page will have a "2" in the bottom
-# left corner of the page. The third a "3" in the bottom right, etc.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  text 'This is the first page!'
-
-  10.times do
-    start_new_page
-    text 'Here comes yet another page.'
-  end
-
-  string = '<page>'
-  odd_options = {
-    at: [bounds.right - 150, 0],
-    width: 150,
-    align: :right,
-    page_filter: :odd,
-    start_count_at: 1
-  }
-  even_options = {
-    at: [0, bounds.left],
-    width: 150,
-    align: :left,
-    page_filter: :even,
-    start_count_at: 2
-  }
-  number_pages string, odd_options
-  number_pages string, even_options
-end

data/manual/repeatable_content/page_numbering.rb

@@ -1,55 +0,0 @@
-# frozen_string_literal: true
-
-# The <code>number_pages</code> method is a simple way to number the pages of
-# your document. It should be called towards the end of the document since
-# pages created after the call won't be numbered.
-#
-# It accepts a string and a hash of options:
-#
-# <code>start_count_at</code> is the value from which to start numbering pages
-#
-# <code>total_pages</code> If provided, will replace <code>total</code> with
-# the value given.  Useful for overriding the total number of pages when using
-# the start_count_at option.
-#
-# <code>page_filter</code>, which is one of: <code>:all</code>,
-# <code>:odd</code>, <code>:even</code>, an array, a range, or a Proc that
-# receives the page number as an argument and should return true if the page
-# number should be printed on that page.
-#
-# <code>color</code> which accepts the same values as <code>fill_color</code>
-#
-# As well as any option accepted by <code>text_box</code>
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  text 'This is the first page!'
-
-  10.times do
-    start_new_page
-    text 'Here comes yet another page.'
-  end
-
-  string = 'page <page> of <total>'
-  # Green page numbers 1 to 7
-  options = {
-    at: [bounds.right - 150, 0],
-    width: 150,
-    align: :right,
-    page_filter: (1..7),
-    start_count_at: 1,
-    color: '007700'
-  }
-  number_pages string, options
-
-  # Gray page numbers from 8 on up
-  options[:page_filter] = ->(pg) { pg > 7 }
-  options[:start_count_at] = 8
-  options[:color] = '333333'
-  number_pages string, options
-
-  start_new_page
-  text "See. This page isn't numbered and doesn't count towards the total."
-end

data/manual/repeatable_content/repeatable_content.rb

@@ -1,35 +0,0 @@
-# frozen_string_literal: true
-
-# Examples for stamps and repeaters.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename, page_size: 'FOLIO') do
-  package 'repeatable_content' do |p|
-    p.example 'repeater', eval_source: false
-    p.example 'stamp'
-    p.example 'page_numbering', eval_source: false
-    p.example 'alternate_page_numbering', eval_source: false
-
-    p.intro do
-      prose <<-TEXT
-        Prawn offers two ways to handle repeatable content blocks. Repeater is
-        useful for content that gets repeated at well defined intervals while
-        Stamp is more appropriate if you need better control of when to repeat
-        it.
-
-        There is also one very specific helper for numbering pages.
-
-        The examples show:
-      TEXT
-
-      list(
-        'How to repeat content on several pages with a single invocation',
-        'How to create a new Stamp',
-        'How to "stamp" the content block on the page',
-        'How to number the document pages with one simple call'
-      )
-    end
-  end
-end

data/manual/repeatable_content/repeater.rb

@@ -1,54 +0,0 @@
-# frozen_string_literal: true
-
-# The <code>repeat</code> method is quite versatile when it comes to define
-# the intervals at which the content block should repeat.
-#
-# The interval may be a symbol (<code>:all</code>, <code>:odd</code>,
-# <code>:even</code>), an array listing the pages, a range or a
-# <code>Proc</code> that receives the page number as an argument and should
-# return true if the content is to be repeated on the given page.
-#
-# You may also pass an option <code>:dynamic</code> to reevaluate the code block
-# on every call which is useful when the content changes based on the page
-# number.
-#
-# It is also important to say that no matter where you define the repeater it
-# will be applied to all matching pages.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  repeat(:all) do
-    draw_text 'All pages', at: bounds.top_left
-  end
-
-  repeat(:odd) do
-    draw_text 'Only odd pages', at: [0, 0]
-  end
-
-  repeat(:even) do
-    draw_text 'Only even pages', at: [0, 0]
-  end
-
-  repeat([1, 3, 7]) do
-    draw_text 'Only on pages 1, 3 and 7', at: [100, 0]
-  end
-
-  repeat(2..4) do
-    draw_text 'From the 2nd to the 4th page', at: [300, 0]
-  end
-
-  repeat(->(pg) { (pg % 3).zero? }) do
-    draw_text 'Every third page', at: [250, 20]
-  end
-
-  repeat(:all, dynamic: true) do
-    draw_text page_number, at: [500, 0]
-  end
-
-  10.times do
-    start_new_page
-    draw_text 'A wonderful page', at: [400, 400]
-  end
-end

data/manual/repeatable_content/stamp.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-# Stamps should be used when you have content that will be included multiple
-# times in a document. Its advantages over creating the content anew each time
-# are:
-#   1.  Faster document creation
-#   2.  Smaller final document
-#   3.  Faster display on subsequent displays of the repeated
-# element because the viewer application can cache the rendered
-# results
-#
-# The <code>create_stamp</code> method does just what it says. Pass it a block
-# with the content that should be generated and the stamp will be created.
-#
-# There are two methods to render the stamp on a page <code>stamp</code> and
-# <code>stamp_at</code>. The first will render the stamp as is while the
-# second accepts a point to serve as an offset to the stamp content.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  create_stamp('approved') do
-    rotate(30, origin: [-5, -5]) do
-      stroke_color 'FF3333'
-      stroke_ellipse [0, 0], 29, 15
-      stroke_color '000000'
-
-      fill_color '993333'
-      font('Times-Roman') do
-        draw_text 'Approved', at: [-23, -3]
-      end
-      fill_color '000000'
-    end
-  end
-
-  stamp 'approved'
-
-  stamp_at 'approved', [200, 200]
-end

data/manual/security/encryption.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-# The <code>encrypt_document</code> method, as you might have already guessed,
-# is used to encrypt the PDF document.
-#
-# Once encrypted whoever is using the document will need the user password to
-# read the document. This password can be set with the
-# <code>:user_password</code> option. If this is not set the document will be
-# encrypted but a password will not be needed to read the document.
-#
-# There are some caveats when encrypting your PDFs. Be sure to read the source
-# documentation (you can find it here:
-# https://github.com/prawnpdf/prawn/blob/master/lib/prawn/security.rb ) before
-# using this for anything super serious.
-
-require_relative '../example_helper'
-
-# Bare encryption. No password needed.
-Prawn::ManualBuilder::Example.generate('bare_encryption.pdf') do
-  text 'See, no password was asked but the document is still encrypted.'
-  encrypt_document
-end
-
-# Simple password. All permissions granted.
-Prawn::ManualBuilder::Example.generate('simple_password.pdf') do
-  text 'You was asked for a password.'
-  encrypt_document(user_password: 'foo', owner_password: 'bar')
-end

data/manual/security/permissions.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-# Some permissions may be set for the regular user with the following options:
-# <code>:print_document</code>, <code>:modify_contents</code>,
-# <code>:copy_contents</code>, <code>:modify_annotations</code>. All this
-# options default to true, so if you'd like to revoke just set them to false.
-#
-# A user may bypass all permissions if he provides the owner password which
-# may be set with the <code>:owner_password</code> option. This option may be
-# set to <code>:random</code> so that users will never be able to bypass
-# permissions.
-#
-# There are some caveats when encrypting your PDFs. Be sure to read the source
-# documentation (you can find it here:
-# https://github.com/prawnpdf/prawn/blob/master/lib/prawn/security.rb ) before
-# using this for anything super serious.
-
-require_relative '../example_helper'
-
-# User cannot print the document.
-Prawn::ManualBuilder::Example.generate('cannot_print.pdf') do
-  text "If you used the user password you won't be able to print the doc."
-  encrypt_document(
-    user_password: 'foo',
-    owner_password: 'bar',
-    permissions: { print_document: false }
-  )
-end
-
-# All permissions revoked and owner password set to random
-Prawn::ManualBuilder::Example.generate('no_permissions.pdf') do
-  text "You may only view this and won't be able to use the owner password."
-  encrypt_document(
-    user_password: 'foo',
-    owner_password: :random,
-    permissions: {
-      print_document: false,
-      modify_contents: false,
-      copy_contents: false,
-      modify_annotations: false
-    }
-  )
-end

data/manual/security/security.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-# Examples for document encryption.
-
-require_relative '../example_helper'
-
-Prawn::ManualBuilder::Example.generate('security.pdf', page_size: 'FOLIO') do
-  package 'security' do |p|
-    p.example 'encryption', eval_source: false, full_source: true
-    p.example 'permissions', eval_source: false, full_source: true
-
-    p.intro do
-      prose <<-TEXT
-        Security lets you control who can read the document by defining
-        a password.
-
-        The examples include:
-      TEXT
-
-      list(
-        'How to encrypt the document without the need for a password',
-        'How to configure the regular user permissions',
-        'How to require a password for the regular user',
-        'How to set a owner password that bypass the document permissions'
-      )
-    end
-  end
-end

data/manual/table.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-require_relative 'example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-
-Prawn::ManualBuilder::Example.generate(filename) do
-  header('Prawn::Table')
-
-  prose <<-END_TEXT
-    As of Prawn 1.2.0, Prawn::Table has been extracted into its own
-    semi-officially supported gem.
-
-    Please see https://github.com/prawnpdf/prawn-table for more details.
-  END_TEXT
-end

data/manual/text/alignment.rb

@@ -1,43 +0,0 @@
-# frozen_string_literal: true
-
-# Horizontal text alignment can be achieved by supplying the <code>:align</code>
-# option to the text methods. Available options are <code>:left</code>
-# (default), <code>:right</code>, <code>:center</code>, and
-# <code>:justify</code>.
-#
-# Vertical text alignment can be achieved using the <code>:valign</code> option
-# with the text methods. Available options are <code>:top</code> (default),
-# <code>:center</code>, and <code>:bottom</code>.
-#
-# Both forms of alignment will be evaluated in the context of the current
-# bounding_box.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  text 'This text should be left aligned'
-  text 'This text should be centered', align: :center
-  text 'This text should be right aligned', align: :right
-
-  bounding_box([0, 220], width: 250, height: 220) do
-    text 'This text is flowing from the left. ' * 4
-
-    move_down 15
-    text 'This text is flowing from the center. ' * 3, align: :center
-
-    move_down 15
-    text 'This text is flowing from the right. ' * 4, align: :right
-
-    move_down 15
-    text 'This text is justified. ' * 6, align: :justify
-    transparent(0.5) { stroke_bounds }
-  end
-
-  bounding_box([300, 220], width: 250, height: 220) do
-    text 'This text should be vertically top aligned'
-    text 'This text should be vertically centered', valign: :center
-    text 'This text should be vertically bottom aligned', valign: :bottom
-    transparent(0.5) { stroke_bounds }
-  end
-end

data/manual/text/color.rb

@@ -1,24 +0,0 @@
-# frozen_string_literal: true
-
-# The <code>:color</code> attribute can give a block of text a default color,
-# in RGB hex format or 4-value CMYK.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  text 'Default color is black'
-  move_down 25
-
-  text 'Changed to red', color: 'FF0000'
-  move_down 25
-
-  text 'CMYK color', color: [22, 55, 79, 30]
-  move_down 25
-
-  text(
-    "Also works with <color rgb='ff0000'>inline</color> formatting",
-    color: '0000FF',
-    inline_format: true
-  )
-end

data/manual/text/column_box.rb

@@ -1,30 +0,0 @@
-# frozen_string_literal: true
-
-# The <code>column_box</code> method allows you to define columns that flow
-# their contents from one section to the next. You can have a number of columns
-# on the page, and only when the last column overflows will a new page be
-# created.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  text 'The Prince', align: :center, size: 18
-  text 'Niccolò Machiavelli', align: :center, size: 14
-  move_down 12
-
-  column_box([0, cursor], columns: 2, width: bounds.width) do
-    text("#{<<~TEXT.gsub(/\s+/, ' ')}\n\n" * 3)
-      All the States and Governments by which men are or ever have been ruled,
-      have been and are either Republics or Princedoms. Princedoms are either
-      hereditary, in which the sovereignty is derived through an ancient line
-      of ancestors, or they are new. New Princedoms are either wholly new, as
-      that of Milan to Francesco Sforza; or they are like limbs joined on to
-      the hereditary possessions of the Prince who acquires them, as the
-      Kingdom of Naples to the dominions of the King of Spain. The States thus
-      acquired have either been used to live under a Prince or have been free;
-      and he who acquires them does so either by his own arms or by the arms of
-      others, and either by good fortune or by merit.
-    TEXT
-  end
-end

data/manual/text/fallback_fonts.rb

@@ -1,41 +0,0 @@
-# frozen_string_literal: true
-
-# Prawn enables the declaration of fallback fonts for those glyphs that may not
-# be present in the desired font. Use the <code>:fallback_fonts</code> option
-# with any of the text or text box methods, or set fallback_fonts document-wide.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  file = "#{Prawn::DATADIR}/fonts/gkai00mp.ttf"
-  font_families['Kai'] = {
-    normal: { file: file, font: 'Kai' }
-  }
-
-  file = "#{Prawn::DATADIR}/fonts/Panic+Sans.dfont"
-  font_families['Panic Sans'] = {
-    normal: { file: file, font: 'PanicSans' }
-  }
-
-  font('Panic Sans') do
-    text(
-      'When fallback fonts are included, each glyph will be rendered ' \
-      'using the first font that includes the glyph, starting with the ' \
-      'current font and then moving through the fallback fonts from left ' \
-      'to right.' \
-      "\n\n" \
-      "hello ƒ 你好\n再见 ƒ goodbye",
-      fallback_fonts: %w[Times-Roman Kai]
-    )
-  end
-  move_down 20
-
-  formatted_text(
-    [
-      { text: 'Fallback fonts can even override' },
-      { text: 'fragment fonts (你好)', font: 'Times-Roman' }
-    ],
-    fallback_fonts: %w[Times-Roman Kai]
-  )
-end

data/manual/text/font.rb

@@ -1,40 +0,0 @@
-# frozen_string_literal: true
-
-# The <code>font</code> method can be used in three different ways.
-#
-# If we don't pass it any arguments it will return the current font being used
-# to render text.
-#
-# If we just pass it a font name it will use that font for rendering text
-# through the rest of the document.
-#
-# It can also be used by passing a font name and a block. In this case the
-# specified font will only be used to render text inside the block.
-#
-# The default font is Helvetica.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  text "Let's see which font we are using: #{font.inspect}"
-
-  move_down 20
-  font 'Times-Roman'
-  text 'Written in Times.'
-
-  move_down 20
-  font('Courier') do
-    text 'Written in Courier because we are inside the block.'
-  end
-
-  move_down 20
-  text 'Written in Times again as we left the previous block.'
-
-  move_down 20
-  text "Let's see which font we are using again: #{font.inspect}"
-
-  move_down 20
-  font 'Helvetica'
-  text 'Back to normal.'
-end

data/manual/text/font_size.rb

@@ -1,44 +0,0 @@
-# frozen_string_literal: true
-
-# The <code>font_size</code> method works just like the <code>font</code>
-# method.
-#
-# In fact we can even use <code>font</code> with the <code>:size</code> option
-# to declare which size we want.
-#
-# Another way to change the font size is by supplying the <code>:size</code>
-# option to the text methods.
-#
-# The default font size is <code>12</code>.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  text "Let's see which is the current font_size: #{font_size.inspect}"
-
-  move_down 10
-  font_size 16
-  text 'Yeah, something bigger!'
-
-  move_down 10
-  font_size(25) { text 'Even bigger!' }
-
-  move_down 10
-  text 'Back to 16 again.'
-
-  move_down 10
-  text 'Single line on 20 using the :size option.', size: 20
-
-  move_down 10
-  text 'Back to 16 once more.'
-
-  move_down 10
-  font('Courier', size: 10) do
-    text 'Yeah, using Courier 10 courtesy of the font method.'
-  end
-
-  move_down 10
-  font('Helvetica', size: 12)
-  text 'Back to normal'
-end

data/manual/text/font_style.rb

@@ -1,25 +0,0 @@
-# frozen_string_literal: true
-
-# Most font families come with some styles other than normal. Most common are
-# <code>bold</code>, <code>italic</code> and <code>bold_italic</code>.
-#
-# The style can be set the using the <code>:style</code> option, with either the
-# <code>font</code> method which will set the font and style for rest of the
-# document, or with the inline text methods.
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  fonts = %w[Courier Helvetica Times-Roman]
-  styles = %i[bold bold_italic italic normal]
-
-  fonts.each do |example_font|
-    move_down 20
-
-    styles.each do |style|
-      font example_font, style: style
-      text "I'm writing in #{example_font} (#{style})"
-    end
-  end
-end

data/manual/text/formatted_callbacks.rb

@@ -1,70 +0,0 @@
-# frozen_string_literal: true
-
-# The <code>:callback</code> option is also available for the formatted text
-# methods.
-#
-# This option accepts an object (or array of objects) on which two methods
-# will be called if defined: <code>render_behind</code> and
-# <code>render_in_front</code>. They are called before and after rendering the
-# text fragment and are passed the fragment as an argument.
-#
-# This example defines two new callback classes and provide callback objects
-# for the formatted_text
-
-require_relative '../example_helper'
-
-filename = File.basename(__FILE__).gsub('.rb', '.pdf')
-Prawn::ManualBuilder::Example.generate(filename) do
-  class HighlightCallback
-    def initialize(options)
-      @color = options[:color]
-      @document = options[:document]
-    end
-
-    def render_behind(fragment)
-      original_color = @document.fill_color
-      @document.fill_color = @color
-      @document.fill_rectangle(
-        fragment.top_left,
-        fragment.width,
-        fragment.height
-      )
-      @document.fill_color = original_color
-    end
-  end
-
-  class ConnectedBorderCallback
-    def initialize(options)
-      @radius = options[:radius]
-      @document = options[:document]
-    end
-
-    def render_in_front(fragment)
-      @document.stroke_polygon(
-        fragment.top_left,
-        fragment.top_right,
-        fragment.bottom_right,
-        fragment.bottom_left
-      )
-
-      @document.fill_circle(fragment.top_left, @radius)
-      @document.fill_circle(fragment.top_right, @radius)
-      @document.fill_circle(fragment.bottom_right, @radius)
-      @document.fill_circle(fragment.bottom_left, @radius)
-    end
-  end
-
-  highlight = HighlightCallback.new(color: 'ffff00', document: self)
-  border = ConnectedBorderCallback.new(radius: 2.5, document: self)
-
-  formatted_text(
-    [
-      { text: 'hello', callback: highlight },
-      { text: '     ' },
-      { text: 'world', callback: border },
-      { text: '     ' },
-      { text: 'hello world', callback: [highlight, border] }
-    ],
-    size: 20
-  )
-end