module CombinePDF::Page_Methods

This module injects page editing methods into existing page objects and the PDFWriter objects.

Constants

CONTENT_CONTAINER_END

holds the string that ends a PDF graphic state container - used for wrapping malformed PDF content streams.

CONTENT_CONTAINER_MIDDLE

holds the string that ends a PDF graphic state container - used for wrapping malformed PDF content streams.

CONTENT_CONTAINER_START

holds the string that starts a PDF graphic state container - used for wrapping malformed PDF content streams.

Public Instance Methods

<<(obj) click to toggle source

the injection method

# File lib/combine_pdf/page_methods.rb, line 46
def <<(obj)
  inject_page obj, true
end
>>(obj) click to toggle source
# File lib/combine_pdf/page_methods.rb, line 50
def >>(obj)
  inject_page obj, false
end
copy(secure = false) click to toggle source

creates a copy of the page. if the :secure flag is set to true, the resource indentifiers (fonts etc') will be renamed in order to secure their uniqueness.

# File lib/combine_pdf/page_methods.rb, line 633
def copy(secure = false)
  # since only the Content streams are modified (Resource hashes are created anew),
  # it should be safe (and a lot faster) to create a deep copy only for the content hashes and streams.
  delete :Parent
  prep_content_array
  page_copy = clone
  page_copy[:Contents] = page_copy[:Contents].map do |obj|
    obj = obj.dup
    obj[:referenced_object] = obj[:referenced_object].dup if obj[:referenced_object]
    obj[:referenced_object][:raw_stream_content] = obj[:referenced_object][:raw_stream_content].dup if obj[:referenced_object] && obj[:referenced_object][:raw_stream_content]
    obj
  end
  if page_copy[:Resources]
    page_res = page_copy[:Resources] = page_copy[:Resources].dup
    page_res = page_copy[:Resources][:referenced_object] = page_copy[:Resources][:referenced_object].dup if page_copy[:Resources][:referenced_object]
    page_res.each do |k, v|
      v = page_res[k] = v.dup if v.is_a?(Array) || v.is_a?(Hash)
      v = v[:referenced_object] = v[:referenced_object].dup if v.is_a?(Hash) && v[:referenced_object]
    end
  end
  page_copy.instance_exec(secure || @secure_injection) { |s| secure_for_copy if s; init_contents; self }
end
crop(new_size = nil) click to toggle source

crops the page using a relative size.

`crop` will crop the page by updating it's MediaBox property using a relative crop box. i.e., when cropping a page with {#page_size} of [10,10,900,900] to [5,5,500,500], the resulting page size should be [15, 15, 510, 510] - allowing you to ignore a page's initial XY starting point when cropping.

for an absolute cropping, simpy use the {#mediabox=} or {#cropbox=} methods, setting their value to the new {page_size}.

accepts:

new_size

an Array with four elements: [X0, Y0, X_max, Y_max]. For example, inch4(width)x6(length): `[200, 200, 488, 632]`

# File lib/combine_pdf/page_methods.rb, line 471
def crop(new_size = nil)
  # no crop box? clear any cropping.
  return page_size unless new_size
  # type safety
  raise TypeError, "pdf.page\#crop expeceted an Array (or nil)" unless Array === new_size

  # set the MediaBox to the existing page size
  self[:MediaBox] = page_size
  # clear the CropBox
  self[:CropBox] = nil
  # update X0
  self[:MediaBox][0] += new_size[0]
  # update Y0
  self[:MediaBox][1] += new_size[1]
  # update X max IF the value is smaller then the existing value
  self[:MediaBox][2] = (self[:MediaBox][0] + new_size[2] - new_size[0]) if (self[:MediaBox][0] + new_size[2] - new_size[0])  < self[:MediaBox][2]
  # update Y max IF the value is smaller then the existing value
  self[:MediaBox][3] = (self[:MediaBox][1] + new_size[3] - new_size[1]) if (self[:MediaBox][1] + new_size[3] - new_size[1])  < self[:MediaBox][3]
  # return self for chaining
  self
end
cropbox() click to toggle source

accessor (getter) for the :CropBox element of the page

# File lib/combine_pdf/page_methods.rb, line 132
def cropbox
  actual_object self[:CropBox]
end
cropbox=(dimensions = [0.0, 0.0, 612.0, 792.0]) click to toggle source

accessor (setter) for the :CropBox element of the page

dimensions

an Array consisting of four numbers (can be floats) setting the size of the media box.

# File lib/combine_pdf/page_methods.rb, line 127
def cropbox=(dimensions = [0.0, 0.0, 612.0, 792.0])
  self[:CropBox] = dimensions
end
dimensions_of(text, fonts, size = 1000) click to toggle source

gets the dimentions (width and height) of the text, as it will be printed in the PDF.

text

the text to measure

font

a font name or an Array of font names. Font names should be registered fonts. The 14 standard fonts are pre regitered with the font library.

size

the size of the font (defaults to 1000 points).

# File lib/combine_pdf/page_methods.rb, line 371
def dimensions_of(text, fonts, size = 1000)
  Fonts.dimensions_of text, fonts, size
end
fit_text(text, font, length, height = 10_000_000) click to toggle source

this method returns the size for which the text fits the requested metrices the size is type Float and is rather exact if the text cannot fit such a small place, returns zero (0). maximum font size possible is set to 100,000 - which should be big enough for anything

text

the text to fit

font

the font name. @see font

length

the length to fit

height

the height to fit (optional - normally length is the issue)

# File lib/combine_pdf/page_methods.rb, line 383
def fit_text(text, font, length, height = 10_000_000)
  size = 100_000
  size_array = [size]
  metrics = Fonts.dimensions_of text, font, size
  size_array << size * length / metrics[0] if metrics[0] > length
  size_array << size * height / metrics[1] if metrics[1] > height
  size_array.min
end
fix_rotation() click to toggle source

This method moves the Page property into the page's data stream, so that “what you see is what you get”.

After using thie method, {#orientation} should return the absolute orientation rather than only the data's orientation (unless `:Rotate` is changed).

This is usful in cases where there might be less control over the source PDF files, and the user assums that the PDF page's data is the same as the PDF's pages on screen display (Rotate rotates a page but leaves the data in the original orientation).

The method returns the page object, thus allowing method chaining (i.e. `page = 90; page.textbox('hello!').fix_rotation.textbox('hello!')`)

# File lib/combine_pdf/page_methods.rb, line 402
def fix_rotation
  return self if self[:Rotate].to_f == 0.0 || mediabox.nil?
  # calculate the rotation
  r = (360.0 - self[:Rotate].to_f) * Math::PI / 180
  s = Math.sin(r).round 6
  c = Math.cos(r).round 6
  ctm = [c, s, -s, c]
  # calculate the translation (move the origin of x,y to the new origin).
  x = mediabox[2] - mediabox[0]
  y = mediabox[3] - mediabox[1]
  ctm.push(((x * c).abs - x * c + (y * s).abs + y * s) / 2, ((x * s).abs - x * s + (y * c).abs - y * c) / 2)

  # insert the rotation stream into the current content stream
  insert_content "q\n#{ctm.join ' '} cm\n", 0
  # close the rotation stream
  insert_content CONTENT_CONTAINER_END
  # reset the mediabox and cropbox values - THIS IS ONLY FOR ORIENTATION CHANGE...
  if (self[:Rotate].to_f / 90).to_i.odd?
    self[:MediaBox] = self[:MediaBox].values_at(1, 0, 3, 2)
    self[:CropBox] = self[:CropBox].values_at(1, 0, 3, 2) if self[:CropBox]
  end
  # reset the Rotate property
  delete :Rotate
  # disconnect the content stream, so that future inserts aren't rotated
  @contents = false # init_contents

  # always return self, for chaining.
  self
end
inject_page(obj, top = true) click to toggle source
# File lib/combine_pdf/page_methods.rb, line 54
def inject_page(obj, top = true)
  raise TypeError, "couldn't inject data, expecting a PDF page (Hash type)" unless obj.is_a?(Page_Methods)

  obj = obj.copy(should_secure?(obj)) # obj.copy(secure_injection)

  # following the reference chain and assigning a pointer to the correct Resouces object.
  # (assignments of Strings, Arrays and Hashes are pointers in Ruby, unless the .dup method is called)

  # setup references to avoid method calls.
  local_res = resources
  local_val = nil
  # # setup references to avoid method calls.
  # remote_res = obj.resources
  # remote_val = nil

  # add each of the new resources in the uncoming Page to the local resource Hash
  obj.resources.each do |key, new_val|
    # keep CombinePDF structural data intact.
    next if PDF::PRIVATE_HASH_KEYS.include?(key)
    # review
    if local_res[key].nil?
      # no local data, adopt data from incoming page
      local_res[key] = new_val
      # go back to looping, no need to parse the rest of the Ruby
      next
    elsif (local_val = actual_object(local_res[key])).is_a?(Hash) && (new_val = actual_object(new_val)).is_a?(Hash)
      # marge data with priority to the incoming page's data
      new_val.update local_val # make sure the old values are respected
      local_val.update new_val # transfer old and new values to the injected page
    end # Do nothing if array or anything else
  end

  # concat the Annots array? (what good are named links if the names are in the unaccessible Page Catalog?)
  # if obj[:Annots]
  #   if (local_val = actual_object(self[:Annots])).nil?
  #     self[:Annots] = obj[:Annots]
  #   elsif local_val.is_a?(Array) && (remote_val = actual_object(obj[:Annots])).is_a?(Array)
  #     local_val.concat remote_val
  #   end
  # end

  # set ProcSet to recommended value
  resources[:ProcSet] ||= [:PDF, :Text, :ImageB, :ImageC, :ImageI] # this was recommended by the ISO. 32000-1:2008

  if top # if this is a stamp (overlay)
    insert_content CONTENT_CONTAINER_START, 0
    insert_content CONTENT_CONTAINER_MIDDLE
    self[:Contents].concat obj[:Contents]
    insert_content CONTENT_CONTAINER_END
  else # if this was a watermark (underlay? would be lost if the page was scanned, as white might not be transparent)
    insert_content CONTENT_CONTAINER_MIDDLE, 0
    insert_content CONTENT_CONTAINER_START, 0
    self[:Contents].insert 1, *obj[:Contents]
    insert_content CONTENT_CONTAINER_END
  end
  init_contents

  self
end
make_secure() click to toggle source

sets secure_injection to `true` and returns self, allowing for chaining methods

# File lib/combine_pdf/page_methods.rb, line 32
def make_secure
  warn "**Deprecation Warning**: the `Page_Methods#secure_injection`, `Page_Methods#make_unsecure` and `Page_Methods#make_secure` methods are deprecated. Use `Page_Methods#copy(true)` for safeguarding against font/resource conflicts when 'stamping' one PDF page over another."
  @secure_injection = true
  self
end
make_unsecure() click to toggle source

sets secure_injection to `false` and returns self, allowing for chaining methods

# File lib/combine_pdf/page_methods.rb, line 39
def make_unsecure
  warn "**Deprecation Warning**: the `Page_Methods#secure_injection`, `Page_Methods#make_unsecure` and `Page_Methods#make_secure` methods are deprecated. Use `Page_Methods#copy(true)` for safeguarding against font/resource conflicts when 'stamping' one PDF page over another."
  @secure_injection = false
  self
end
mediabox() click to toggle source

accessor (getter) for the :MediaBox element of the page

# File lib/combine_pdf/page_methods.rb, line 121
def mediabox
  actual_object self[:MediaBox]
end
mediabox=(dimensions = [0.0, 0.0, 612.0, 792.0]) click to toggle source

accessor (setter) for the :MediaBox element of the page

dimensions

an Array consisting of four numbers (can be floats) setting the size of the media box.

# File lib/combine_pdf/page_methods.rb, line 116
def mediabox=(dimensions = [0.0, 0.0, 612.0, 792.0])
  self[:MediaBox] = dimensions
end
orientation(force = nil, clockwise = true) click to toggle source

get or set (by clockwise rotation) the page's data orientation.

note that the data's orientation is the way data is oriented on the page. The display orientati0n (which might different) is controlled by the `:Rotate` property. see {#fix_orientation} for more details.

accepts one optional parameter:

force

to get the orientation, pass nil. to set the orientatiom, set fource to either :portrait or :landscape. defaults to nil (get orientation).

clockwise

sets the rotation directions. defaults to true (clockwise rotation).

returns the current orientation (:portrait or :landscape) if used to get the orientation. otherwise, if used to set the orientation, returns the page object to allow method chaining.

  • Notice: a square page always returns the :portrait value and is ignored when trying to set the orientation.

# File lib/combine_pdf/page_methods.rb, line 524
def orientation(force = nil, clockwise = true)
  a = page_size
  return (a[2] - a[0] > a[3] - a[1]) ? :landscape : :portrait unless force
  unless orientation == force || (a[2] - a[0] == a[3] - a[1])
    self[:Rotate] = 0
    clockwise ? rotate_right : rotate_left
  end
  self
end
page_size() click to toggle source

get page size

# File lib/combine_pdf/page_methods.rb, line 137
def page_size
  cropbox || mediabox
end
resize(new_size = nil, conserve_aspect_ratio = true) click to toggle source

resizes the page relative to it's current viewport (either the cropbox or the mediabox), setting the new viewport to the requested size.

accepts:

new_size

an Array with four elements: [X0, Y0, X_max, Y_max]. For example, A4: `[0, 0, 595, 842]`. It is important that the first two numbers are 0 unless a special effect is attempted. If the first two numbers change, the final result might not be the size requested, but the nearest possible transformation (calling the method again will allow a better resizing).

conserve_aspect_ratio

whether to keep the current content in the same aspect ratio or to allow streaching. Defaults to true - so that although the content is resized, it might not fill the new size completely.

# File lib/combine_pdf/page_methods.rb, line 437
def resize(new_size = nil, conserve_aspect_ratio = true)
  return page_size unless new_size
  c_mediabox = mediabox
  c_cropbox = cropbox
  c_size = c_cropbox || c_mediabox
  x_ratio = 1.0 * (new_size[2] - new_size[0]) / (c_size[2]) #-c_size[0])
  y_ratio = 1.0 * (new_size[3] - new_size[1]) / (c_size[3]) #-c_size[1])
  x_move = new_size[0] - c_size[0]
  y_move = new_size[1] - c_size[1]
  # puts "ctm will be: #{x_ratio.round(4)} 0 0 #{y_ratio.round(4)} #{x_move} #{y_move}"
  self[:MediaBox] = [(c_mediabox[0] + x_move), (c_mediabox[1] + y_move), ((c_mediabox[2] * x_ratio) + x_move), ((c_mediabox[3] * y_ratio) + y_move)]
  self[:CropBox] = [(c_cropbox[0] + x_move), (c_cropbox[1] + y_move), ((c_cropbox[2] * x_ratio) + x_move), ((c_cropbox[3] * y_ratio) + y_move)] if c_cropbox
  x_ratio = y_ratio = [x_ratio, y_ratio].min if conserve_aspect_ratio
  # insert the rotation stream into the current content stream
  # insert_content "q\n#{x_ratio.round(4).to_s} 0 0 #{y_ratio.round(4).to_s} 0 0 cm\n1 0 0 1 #{x_move} #{y_move} cm\n", 0
  insert_content "q\n#{x_ratio.round(4)} 0 0 #{y_ratio.round(4)} #{x_move} #{y_move} cm\n", 0
  # close the rotation stream
  insert_content CONTENT_CONTAINER_END
  # disconnect the content stream, so that future inserts aren't rotated
  @contents = false # init_contents

  # always return self, for chaining.
  self
end
resources() click to toggle source

accessor (getter) for the :Resources element of the page

# File lib/combine_pdf/page_methods.rb, line 142
def resources
  self[:Resources] ||= {}
  self[:Resources][:referenced_object] || self[:Resources]
end
rotate_180() click to toggle source

rotate the page by 180 degrees

# File lib/combine_pdf/page_methods.rb, line 506
def rotate_180
  self[:Rotate] = (self[:Rotate].to_f() + 180)
  fix_rotation
end
rotate_left() click to toggle source

rotate the page 90 degrees counter clockwise

# File lib/combine_pdf/page_methods.rb, line 494
def rotate_left
  self[:Rotate] = (self[:Rotate].to_f() + 90)
  fix_rotation
end
rotate_right() click to toggle source

rotate the page 90 degrees clockwise

# File lib/combine_pdf/page_methods.rb, line 500
def rotate_right
  self[:Rotate] = (self[:Rotate].to_f() - 90)
  fix_rotation
end
secure_injection() click to toggle source

accessor (getter) for the secure_injection setting

# File lib/combine_pdf/page_methods.rb, line 20
def secure_injection
  warn "**Deprecation Warning**: the `Page_Methods#secure_injection`, `Page_Methods#make_unsecure` and `Page_Methods#make_secure` methods are deprecated. Use `Page_Methods#copy(true)` for safeguarding against font/resource conflicts when 'stamping' one PDF page over another."
  @secure_injection
end
secure_injection=(safe) click to toggle source

accessor (setter) for the secure_injection setting

# File lib/combine_pdf/page_methods.rb, line 26
def secure_injection=(safe)
  warn "**Deprecation Warning**: the `Page_Methods#secure_injection`, `Page_Methods#make_unsecure` and `Page_Methods#make_secure` methods are deprecated. Use `Page_Methods#copy(true)` for safeguarding against font/resource conflicts when 'stamping' one PDF page over another."
  @secure_injection = safe
end
textbox(text, properties = {}) click to toggle source

This method adds a simple text box to the Page represented by the PDFWriter class. This function takes two values:

text

the text to write in the box.

properties

a Hash of box properties.

the symbols and values in the properties Hash could be any or all of the following:

x

the left position of the box.

y

the BOTTOM position of the box.

width

the width/length of the box. negative values will be computed from edge of page. defaults to 0 (end of page).

height

the height of the box. negative values will be computed from edge of page. defaults to 0 (end of page).

text_align

symbol for horizontal text alignment, can be “:center” (default), “:right”, “:left”

text_valign

symbol for vertical text alignment, can be “:center” (default), “:top”, “:bottom”

text_padding

a Float between 0 and 1, setting the padding for the text. defaults to 0.05 (5%).

font

a registered font name or an Array of names. defaults to “:Helvetica”. The 14 standard fonts names are:

  • :“Times-Roman”

  • :“Times-Bold”

  • :“Times-Italic”

  • :“Times-BoldItalic”

  • :Helvetica

  • :“Helvetica-Bold”

  • :“Helvetica-BoldOblique”

  • :“Helvetica- Oblique”

  • :Courier

  • :“Courier-Bold”

  • :“Courier-Oblique”

  • :“Courier-BoldOblique”

  • :Symbol

  • :ZapfDingbats

font_size

an Integer for the font size, or :fit_text to fit the text in the box. defaults to “:fit_text”

max_font_size

if font_size is set to :fit_text, this will be the maximum font size. defaults to nil (no maximum)

font_color

text color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be “[0.5, 0.5, 0.5]”). defaults to black.

stroke_color

text stroke color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be “[0.5, 0.5, 0.5]”). defounlts to nil (no stroke).

stroke_width

text stroke width in PDF units. defaults to 0 (none).

box_color

box fill color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be “[0.5, 0.5, 0.5]”). defaults to nil (none).

border_color

box border color in [R, G, B], an array with three floats, each in a value between 0 to 1 (gray will be “[0.5, 0.5, 0.5]”). defaults to nil (none).

border_width

border width in PDF units. defaults to nil (none).

box_radius

border radius in PDF units. defaults to 0 (no corner rounding).

opacity

textbox opacity, a float between 0 (transparent) and 1 (opaque)

ctm

A PDF complient CTM data array that will manipulate the axis and allow transformations. i.e. `[1,0,0,1,0,0]`

# File lib/combine_pdf/page_methods.rb, line 185
def textbox(text, properties = {})
  options = {
    x: page_size[0],
    y: page_size[1],
    width: 0,
    height: -1,
    text_align: :center,
    text_valign: :center,
    text_padding: 0.1,
    font: nil,
    font_size: :fit_text,
    max_font_size: nil,
    font_color: [0, 0, 0],
    stroke_color: nil,
    stroke_width: 0,
    box_color: nil,
    border_color: nil,
    border_width: 0,
    box_radius: 0,
    opacity: 1,
    ctm: nil # ~= [1,0,0,1,0,0]
  }
  options.update properties
  # reset the length and height to meaningful values, if negative
  options[:width] = mediabox[2] - options[:x] + options[:width] if options[:width] <= 0
  options[:height] = mediabox[3] - options[:y] + options[:height] if options[:height] <= 0

  # reset the padding value
  options[:text_padding] = 0 if options[:text_padding].to_f >= 1

  # create box stream
  box_stream = ''
  # set graphic state for box
  if options[:box_color] || (options[:border_width].to_i > 0 && options[:border_color])
    # compute x and y position for text
    x = options[:x]
    y = options[:y]

    # set graphic state for the box
    box_stream << "q\n"
    box_stream << "#{options[:ctm].join ' '} cm\n" if options[:ctm]
    box_graphic_state = { ca: options[:opacity], CA: options[:opacity], LW: options[:border_width], LC: 0, LJ: 0, LD: 0 }
    if options[:box_radius] != 0 # if the text box has rounded corners
      box_graphic_state[:LC] = 2
      box_graphic_state[:LJ] = 1
    end
    box_graphic_state = graphic_state box_graphic_state # adds the graphic state to Resources and gets the reference
    box_stream << "#{object_to_pdf box_graphic_state} gs\n"

    # the following line was removed for Acrobat Reader compatability
    # box_stream << "DeviceRGB CS\nDeviceRGB cs\n"

    box_stream << "#{options[:box_color].join(' ')} rg\n" if options[:box_color]
    if options[:border_width].to_i > 0 && options[:border_color]
      box_stream << "#{options[:border_color].join(' ')} RG\n"
    end
    # create the path
    radius = options[:box_radius]
    half_radius = (radius.to_f / 2).round 4
    ## set starting point
    box_stream << "#{options[:x] + radius} #{options[:y]} m\n"
    ## bottom and right corner - first line and first corner
    box_stream << "#{options[:x] + options[:width] - radius} #{options[:y]} l\n" # bottom
    if options[:box_radius] != 0 # make first corner, if not straight.
      box_stream << "#{options[:x] + options[:width] - half_radius} #{options[:y]} "
      box_stream << "#{options[:x] + options[:width]} #{options[:y] + half_radius} "
      box_stream << "#{options[:x] + options[:width]} #{options[:y] + radius} c\n"
    end
    ## right and top-right corner
    box_stream << "#{options[:x] + options[:width]} #{options[:y] + options[:height] - radius} l\n"
    if options[:box_radius] != 0
      box_stream << "#{options[:x] + options[:width]} #{options[:y] + options[:height] - half_radius} "
      box_stream << "#{options[:x] + options[:width] - half_radius} #{options[:y] + options[:height]} "
      box_stream << "#{options[:x] + options[:width] - radius} #{options[:y] + options[:height]} c\n"
    end
    ## top and top-left corner
    box_stream << "#{options[:x] + radius} #{options[:y] + options[:height]} l\n"
    if options[:box_radius] != 0
      box_stream << "#{options[:x] + half_radius} #{options[:y] + options[:height]} "
      box_stream << "#{options[:x]} #{options[:y] + options[:height] - half_radius} "
      box_stream << "#{options[:x]} #{options[:y] + options[:height] - radius} c\n"
    end
    ## left and bottom-left corner
    box_stream << "#{options[:x]} #{options[:y] + radius} l\n"
    if options[:box_radius] != 0
      box_stream << "#{options[:x]} #{options[:y] + half_radius} "
      box_stream << "#{options[:x] + half_radius} #{options[:y]} "
      box_stream << "#{options[:x] + radius} #{options[:y]} c\n"
    end
    # fill / stroke path
    box_stream << "h\n"
    if options[:box_color] && options[:border_width].to_i > 0 && options[:border_color]
      box_stream << "B\n"
    elsif options[:box_color] # fill if fill color is set
      box_stream << "f\n"
    elsif options[:border_width].to_i > 0 && options[:border_color] # stroke if border is set
      box_stream << "S\n"
    end

    # exit graphic state for the box
    box_stream << "Q\n"
  end
  contents << box_stream

  # reset x,y by text alignment - x,y are calculated from the bottom left
  # each unit (1) is 1/72 Inch
  # create text stream
  text_stream = ''
  if !text.to_s.empty? && options[:font_size] != 0 && (options[:font_color] || options[:stroke_color])
    # compute x and y position for text
    x = options[:x] + (options[:width] * options[:text_padding])
    y = options[:y] + (options[:height] * options[:text_padding])

    # set the fonts (fonts array, with :Helvetica as fallback).
    fonts = [*options[:font], :Helvetica]
    # fit text in box, if requested
    font_size = options[:font_size]
    if options[:font_size] == :fit_text
      font_size = fit_text text, fonts, (options[:width] * (1 - options[:text_padding])), (options[:height] * (1 - options[:text_padding]))
      font_size = options[:max_font_size] if options[:max_font_size] && font_size > options[:max_font_size]
    end

    text_size = dimensions_of text, fonts, font_size

    if options[:text_align] == :center
      x = ((options[:width] * (1 - (2 * options[:text_padding]))) - text_size[0]) / 2 + x
    elsif options[:text_align] == :right
      x = ((options[:width] * (1 - (1.5 * options[:text_padding]))) - text_size[0]) + x
    end
    if options[:text_valign] == :center
      y = ((options[:height] * (1 - (2 * options[:text_padding]))) - text_size[1]) / 2 + y
    elsif options[:text_valign] == :top
      y = (options[:height] * (1 - (1.5 * options[:text_padding]))) - text_size[1] + y
    end

    # set graphic state for text
    text_stream << "q\n"
    text_stream << "#{options[:ctm].join ' '} cm\n" if options[:ctm]
    text_graphic_state = graphic_state(ca: options[:opacity], CA: options[:opacity], LW: options[:stroke_width].to_f, LC: 2, LJ: 1, LD: 0)
    text_stream << "#{object_to_pdf text_graphic_state} gs\n"

    # the following line was removed for Acrobat Reader compatability
    # text_stream << "DeviceRGB CS\nDeviceRGB cs\n"

    # set text render mode
    if options[:font_color]
      text_stream << "#{options[:font_color].join(' ')} rg\n"
    end
    if options[:stroke_width].to_i > 0 && options[:stroke_color]
      text_stream << "#{options[:stroke_color].join(' ')} RG\n"
      if options[:font_color]
        text_stream << "2 Tr\n"
      else
        final_stream << "1 Tr\n"
      end
    elsif options[:font_color]
      text_stream << "0 Tr\n"
    else
      text_stream << "3 Tr\n"
    end
    # format text object(s)
    # text_stream << "#{options[:font_color].join(' ')} rg\n" # sets the color state
    encode_text(text, fonts).each do |encoded|
      text_stream << "BT\n" # the Begine Text marker
      text_stream << format_name_to_pdf(set_font(encoded[0])) # Set font name
      text_stream << " #{font_size.round 3} Tf\n" # set font size and add font operator
      text_stream << "#{x.round 4} #{y.round 4} Td\n" # set location for text object
      text_stream << (encoded[1]) # insert the encoded string to the stream
      text_stream << " Tj\n" # the Text object operator and the End Text marker
      text_stream << "ET\n" # the Text object operator and the End Text marker
      x += encoded[2] / 1000 * font_size # update text starting point
      y -= encoded[3] / 1000 * font_size # update text starting point
    end
    # exit graphic state for text
    text_stream << "Q\n"
  end
  contents << text_stream

  self
end
write_table(options = {}) click to toggle source

Writes a table to the current page, removing(!) the written rows from the table_data Array.

since the table_data Array is updated, it is possible to call this method a few times, each time creating or moving to the next page, until table_data.empty? returns true.

accepts a Hash with any of the following keys as well as any of the PDFWriter#textbox options:

headers

an Array of strings with the headers (will be repeated every page).

table_data

as Array of Arrays, each containing a string for each column. the first row sets the number of columns. extra columns will be ignored.

font

a registered or standard font name (see PDFWriter). defaults to nil (:Helvetica).

header_font

a registered or standard font name for the headers (see PDFWriter). defaults to nil (the font for all the table rows).

max_font_size

the maximum font size. if the string doesn't fit, it will be resized. defaults to 14.

column_widths

an array of relative column widths ([1,2] will display only the first two columns, the second twice as big as the first). defaults to nil (even widths).

header_color

the header color. defaults to [0.8, 0.8, 0.8] (light gray).

main_color

main row color. defaults to nil (transparent / white).

alternate_color

alternate row color. defaults to [0.95, 0.95, 0.95] (very light gray).

font_color

font color. defaults to [0,0,0] (black).

border_color

border color. defaults to [0,0,0] (black).

border_width

border width in PDF units. defaults to 1.

header_align

the header text alignment within each column (:right, :left, :center). defaults to :center.

row_align

the row text alignment within each column. defaults to :left (:right for RTL table).

direction

the table's writing direction (:ltr or :rtl). this reffers to the direction of the columns and doesn't effect text (rtl text is automatically recognized). defaults to :ltr.

max_rows

the maximum number of rows to actually draw, INCLUDING the header row. deafults to 25.

xy

an Array specifying the top-left corner of the table. defaulte to [page_width*0.1, page_height*0.9].

size

an Array specifying the height and the width of the table. defaulte to [page_width*0.8, page_height*0.8].

# File lib/combine_pdf/page_methods.rb, line 558
def write_table(options = {})
  defaults = {
    headers: nil,
    table_data: [[]],
    font: nil,
    header_font: nil,
    max_font_size: 14,
    column_widths: nil,
    header_color: [0.8, 0.8, 0.8],
    main_color: nil,
    alternate_color: [0.95, 0.95, 0.95],
    font_color: [0, 0, 0],
    border_color: [0, 0, 0],
    border_width: 1,
    header_align: :center,
    row_align: nil,
    direction: :ltr,
    max_rows: 25,
    xy: nil,
    size: nil
  }
  options = defaults.merge options
  raise 'method call error! not enough rows allowed to create table' if (options[:max_rows].to_i < 1 && options[:headers]) || (options[:max_rows].to_i <= 0)
  options[:header_font] ||= options[:font]
  options[:row_align] ||= ((options[:direction] == :rtl) ? :right : :left)
  options[:xy] ||= [((page_size[2] - page_size[0]) * 0.1), ((page_size[3] - page_size[1]) * 0.9)]
  options[:size] ||= [((page_size[2] - page_size[0]) * 0.8), ((page_size[3] - page_size[1]) * 0.8)]
  # assert table_data is an array of arrays
  return false unless (options[:table_data].select { |r| !r.is_a?(Array) }).empty?
  # compute sizes
  top = options[:xy][1]
  height = options[:size][1] / options[:max_rows]
  from_side = options[:xy][0]
  width = options[:size][0]
  columns = options[:table_data][0].length
  column_widths = []
  columns.times { |_i| column_widths << (width / columns) }
  if options[:column_widths]
    scale = 0
    options[:column_widths].each { |w| scale += w }
    column_widths = []
    options[:column_widths].each { |w| column_widths << (width * w / scale) }
  end
  column_widths = column_widths.reverse if options[:direction] == :rtl
  # set count and start writing the data
  row_number = 1

  until options[:table_data].empty? || row_number > options[:max_rows]
    # add headers
    if options[:headers] && row_number == 1
      x = from_side
      headers = options[:headers]
      headers = headers.reverse if options[:direction] == :rtl
      column_widths.each_index do |i|
        text = headers[i].to_s
        textbox text, { x: x, y: (top - (height * row_number)), width: column_widths[i], height: height, box_color: options[:header_color], text_align: options[:header_align] }.merge(options).merge(font: options[:header_font])
        x += column_widths[i]
      end
      row_number += 1
    end
    x = from_side
    row_data = options[:table_data].shift
    row_data = row_data.reverse if options[:direction] == :rtl
    column_widths.each_index do |i|
      text = row_data[i].to_s
      box_color = (options[:alternate_color] && ((row_number.odd? && options[:headers]) || row_number.even?)) ? options[:alternate_color] : options[:main_color]
      textbox text, { x: x, y: (top - (height * row_number)), width: column_widths[i], height: height, box_color: box_color, text_align: options[:row_align] }.merge(options)
      x += column_widths[i]
    end
    row_number += 1
  end
  self
end

Protected Instance Methods

base_font_name() click to toggle source

returns the basic font name used internally

# File lib/combine_pdf/page_methods.rb, line 711
def base_font_name
  @base_font_name ||= 'Writer' + SecureRandom.hex(7) + 'PDF'
end
contents() click to toggle source

accessor (getter) for the stream in the :Contents element of the page after getting the string object, you can operate on it but not replace it (use << or other String methods).

# File lib/combine_pdf/page_methods.rb, line 663
def contents
  @contents ||= init_contents
end
encode_text(text, fonts) click to toggle source

encodes the text in an array of [:font_name, <PDFHexString>] for use in textbox

# File lib/combine_pdf/page_methods.rb, line 771
def encode_text(text, fonts)
  # text must be a unicode string and fonts must be an array.
  # this is an internal method, don't perform tests.
  fonts_array = []
  fonts.each do |name|
    f = Fonts.get_font name
    fonts_array << f if f
  end

  # before starting, we should reorder any RTL content in the string
  text = reorder_rtl_content text

  out = []
  text.chars.each do |c|
    fonts_array.each_index do |i|
      next unless fonts_array[i].cmap.nil? || (fonts_array[i].cmap && fonts_array[i].cmap[c])
      # add to array
      if out.last.nil? || out.last[0] != fonts[i]
        out.last[1] << '>' unless out.last.nil?
        out << [fonts[i], '<', 0, 0]
      end
      out.last[1] << (fonts_array[i].cmap.nil? ? (c.unpack('H*')[0]) : fonts_array[i].cmap[c])
      if fonts_array[i].metrics[c]
        out.last[2] += fonts_array[i].metrics[c][:wx].to_f
        out.last[3] += fonts_array[i].metrics[c][:wy].to_f
      end
      break
    end
  end
  out.last[1] << '>' if out.last
  out
end
graphic_state(graphic_state_dictionary = {}) click to toggle source

register or get a registered graphic state dictionary. the method returns the name of the graphos state, for use in a content stream.

# File lib/combine_pdf/page_methods.rb, line 753
def graphic_state(graphic_state_dictionary = {})
  # if the graphic state exists, return it's name
  resources[:ExtGState] ||= {}
  gs_res = resources[:ExtGState][:referenced_object] || resources[:ExtGState]
  gs_res.each do |k, v|
    return k if v.is_a?(Hash) && v == graphic_state_dictionary
  end
  # set graphic state type
  graphic_state_dictionary[:Type] = :ExtGState
  # set a secure name for the graphic state
  name = SecureRandom.hex(9).to_sym
  # add object to reasource
  gs_res[name] = graphic_state_dictionary
  # return name
  name
end
init_contents() click to toggle source

initializes the content stream in case it was not initialized before

# File lib/combine_pdf/page_methods.rb, line 668
def init_contents
  self[:Contents] = self[:Contents][:referenced_object][:indirect_without_dictionary] if self[:Contents].is_a?(Hash) && self[:Contents][:referenced_object] && self[:Contents][:referenced_object].is_a?(Hash) && self[:Contents][:referenced_object][:indirect_without_dictionary]
  self[:Contents] = [self[:Contents]] unless self[:Contents].is_a?(Array)
  self[:Contents].delete(is_reference_only: true, referenced_object: { indirect_reference_id: 0, raw_stream_content: '' })
  # un-nest any referenced arrays
  self[:Contents].map! { |s| actual_value(s).is_a?(Array) ? actual_value(s) : s }
  self[:Contents].flatten!
  self[:Contents].compact!
  # wrap content streams
  insert_content 'q', 0
  insert_content 'Q'

  # Prep content
  @contents = ''
  insert_content @contents
  @contents
end
insert_content(object, location = -1) click to toggle source

adds a string or an object to the content stream, at the location indicated

accepts:

object

can be a string or a hash object

location

can be any numeral related to the possition in the :Contents array. defaults to -1 == insert at the end.

# File lib/combine_pdf/page_methods.rb, line 691
def insert_content(object, location = -1)
  object = { is_reference_only: true, referenced_object: { indirect_reference_id: 0, raw_stream_content: object } } if object.is_a?(String)
  raise TypeError, 'expected a String or Hash object.' unless object.is_a?(Hash)
  prep_content_array
  self[:Contents].insert location, object
  self[:Contents].flatten!
  self
end
prep_content_array() click to toggle source
# File lib/combine_pdf/page_methods.rb, line 700
def prep_content_array
  return self if self[:Contents].is_a?(Array)
  init_contents
  # self[:Contents] = self[:Contents][:referenced_object] if self[:Contents].is_a?(Hash) && self[:Contents][:referenced_object] && self[:Contents][:referenced_object].is_a?(Array)
  # self[:Contents] = self[:Contents][:indirect_without_dictionary] if self[:Contents].is_a?(Hash) && self[:Contents][:indirect_without_dictionary] && self[:Contents][:indirect_without_dictionary].is_a?(Array)
  # self[:Contents] = [self[:Contents]] unless self[:Contents].is_a?(Array)
  # self[:Contents].compact!
  self
end
reorder_rtl_content(text) click to toggle source

a very primitive text reordering algorithm… I was lazy… …still, it works (I think).

# File lib/combine_pdf/page_methods.rb, line 806
def reorder_rtl_content(text)
  rtl_characters = "\u05d0-\u05ea\u05f0-\u05f4\u0600-\u06ff\u0750-\u077f"
  rtl_replaces = { '(' => ')', ')' => '(',
                   '[' => ']', ']' => '[',
                   '{' => '}', '}' => '{',
                   '<' => '>', '>' => '<' }
  return text unless text =~ /[#{rtl_characters}]/

  out = []
  scanner = StringScanner.new text
  until scanner.eos?
    if scanner.scan(/[#{rtl_characters} ]/)
      out.unshift scanner.matched
    elsif scanner.scan(/[^#{rtl_characters}]+/)
      if out.empty? && scanner.matched.match(/[\s]$/) && !scanner.eos?
        white_space_to_move = scanner.matched.match(/[\s]+$/).to_s
        out.unshift scanner.matched[0..-1 - white_space_to_move.length]
        out.unshift white_space_to_move
      elsif scanner.matched =~ /^[\(\)\[\]\{\}\<\>]$/
        out.unshift rtl_replaces[scanner.matched]
      else
        out.unshift scanner.matched
      end
    end
  end
  out.join.strip
end
secure_for_copy() click to toggle source

copy_and_secure_for_injection(page)

  • page is a page in the pages array, i.e. pdf.pages

takes a page object and:

makes a deep copy of the page (Ruby defaults to pointers, so this will copy the memory).

then it will rewrite the content stream with renamed resources, so as to avoid name conflicts.

# File lib/combine_pdf/page_methods.rb, line 842
def secure_for_copy
  # initiate dictionary from old names to new names
  names_dictionary = {}

  # travel every dictionary to pick up names (keys), change them and add them to the dictionary
  res = resources
  res.each do |k, v|
    next unless actual_value(v).is_a?(Hash)
    # if k == :XObject
    #       self[:Resources][k] = v.dup
    #       next
    # end
    new_dictionary = {}
    new_name = 'Combine' + SecureRandom.hex(7) + 'PDF'
    i = 1
    actual_value(v).each do |old_key, value|
      new_key = (new_name + i.to_s).to_sym
      names_dictionary[old_key] = new_key
      new_dictionary[new_key] = value
      i += 1
    end
    res[k] = new_dictionary
  end

  # now that we have replaced the names in the resources dictionaries,
  # it is time to replace the names inside the stream
  # we will need to make sure we have access to the stream injected
  # we will user PDFFilter.inflate_object
  self[:Contents].each do |c|
    stream = actual_value(c)
    PDFFilter.inflate_object stream
    names_dictionary.each do |old_key, new_key|
      stream[:raw_stream_content].gsub! object_to_pdf(old_key), object_to_pdf(new_key) ##### PRAY(!) that the parsed datawill be correctly reproduced!
    end
    # # # the following code isn't needed now that we wrap both the existing and incoming content streams.
    # # patch back to PDF defaults, for OCRed PDF files.
    # stream[:raw_stream_content] = "q\n0 0 0 rg\n0 0 0 RG\n0 Tr\n1 0 0 1 0 0 cm\n%s\nQ\n" % stream[:raw_stream_content]
  end
  self
end
set_font(font = :Helvetica) click to toggle source

creates a font object and adds the font to the resources dictionary returns the name of the font for the content stream.

font

a Symbol of one of the fonts registered in the library, or:

  • :“Times-Roman”

  • :“Times-Bold”

  • :“Times-Italic”

  • :“Times-BoldItalic”

  • :Helvetica

  • :“Helvetica-Bold”

  • :“Helvetica-BoldOblique”

  • :“Helvetica- Oblique”

  • :Courier

  • :“Courier-Bold”

  • :“Courier-Oblique”

  • :“Courier-BoldOblique”

  • :Symbol

  • :ZapfDingbats

# File lib/combine_pdf/page_methods.rb, line 732
def set_font(font = :Helvetica)
  # if the font exists, return it's name
  resources[:Font] ||= {}
  fonts_res = resources[:Font][:referenced_object] || resources[:Font]
  fonts_res.each do |k, v|
    return k if v.is_a?(Fonts::Font) && v.name && v.name == font
  end
  # set a secure name for the font
  name = (base_font_name + (fonts_res.length + 1).to_s).to_sym
  # get font object
  font_object = Fonts.get_font(font)
  # return false if the font wan't found in the library.
  return false unless font_object
  # add object to reasource
  fonts_res[name] = font_object
  # return name
  name
end
should_secure?(page) click to toggle source

@return [true, false] returns true if there are two different resources sharing the same named reference.

# File lib/combine_pdf/page_methods.rb, line 884
def should_secure?(page)
  # travel every dictionary to pick up names (keys), change them and add them to the dictionary
  res = actual_value(resources)
  foreign_res = actual_value(page.resources)
  tmp = nil
  res.each do |k, v|
    next unless (v = actual_value(v)).is_a?(Hash) && (tmp = actual_value(foreign_res[k])).is_a?(Hash)
    v.keys.each do |name|
      return true if tmp[name] && tmp[name] != v[name]
    end # else # Do nothing, this is taken care of elseware
  end
  false
end