Class PDF::Writer
In: lib/pdf/writer.rb
lib/pdf/writer/state.rb
Parent: Object

Methods

Included Modules

PDF::Writer::Graphics Transaction::Simple

Classes and Modules

Module PDF::Writer::Graphics
Module PDF::Writer::Lang
Module PDF::Writer::OffsetReader
Class PDF::Writer::ARC4
Class PDF::Writer::Complex
Class PDF::Writer::External
Class PDF::Writer::FontMetrics
Class PDF::Writer::OHash
Class PDF::Writer::Object
Class PDF::Writer::PolygonPoint
Class PDF::Writer::State
Class PDF::Writer::StateStack
Class PDF::Writer::StrokeStyle
Class PDF::Writer::TagAlink
Class PDF::Writer::TagBullet
Class PDF::Writer::TagDisc
Class PDF::Writer::TagIlink
Class PDF::Writer::TagUline

Constants

VERSION = '1.1.8'   The version of PDF::Writer.
FONT_PATH = []   The system font path. The sytem font path will be determined differently for each operating system.
Win32:Uses ENV[‘SystemRoot’]/Fonts as the system font path. There is an extension that will handle this better, but until and unless it is distributed with the standard Ruby Windows installer, PDF::Writer will not depend upon it.
OS X:The fonts are found in /System/Library/Fonts.
Linux:The font path list will be found (usually) in /etc/fonts/fonts.conf or /usr/etc/fonts/fonts.conf. This XML file will be parsed (using REXML) to provide the value for FONT_PATH.
PAGE_SIZES = { # :value {...}: "4A0" => [0, 0, 4767.87, 6740.79], "2A0" => [0, 0, 3370.39, 4767.87], "A0" => [0, 0, 2383.94, 3370.39], "A1" => [0, 0, 1683.78, 2383.94], "A2" => [0, 0, 1190.55, 1683.78], "A3" => [0, 0, 841.89, 1190.55], "A4" => [0, 0, 595.28, 841.89], "A5" => [0, 0, 419.53, 595.28], "A6" => [0, 0, 297.64, 419.53], "A7" => [0, 0, 209.76, 297.64], "A8" => [0, 0, 147.40, 209.76], "A9" => [0, 0, 104.88, 147.40], "A10" => [0, 0, 73.70, 104.88], "B0" => [0, 0, 2834.65, 4008.19], "B1" => [0, 0, 2004.09, 2834.65], "B2" => [0, 0, 1417.32, 2004.09], "B3" => [0, 0, 1000.63, 1417.32], "B4" => [0, 0, 708.66, 1000.63], "B5" => [0, 0, 498.90, 708.66], "B6" => [0, 0, 354.33, 498.90], "B7" => [0, 0, 249.45, 354.33], "B8" => [0, 0, 175.75, 249.45], "B9" => [0, 0, 124.72, 175.75], "B10" => [0, 0, 87.87, 124.72], "C0" => [0, 0, 2599.37, 3676.54], "C1" => [0, 0, 1836.85, 2599.37], "C2" => [0, 0, 1298.27, 1836.85], "C3" => [0, 0, 918.43, 1298.27], "C4" => [0, 0, 649.13, 918.43], "C5" => [0, 0, 459.21, 649.13], "C6" => [0, 0, 323.15, 459.21], "C7" => [0, 0, 229.61, 323.15], "C8" => [0, 0, 161.57, 229.61], "C9" => [0, 0, 113.39, 161.57], "C10" => [0, 0, 79.37, 113.39], "RA0" => [0, 0, 2437.80, 3458.27], "RA1" => [0, 0, 1729.13, 2437.80], "RA2" => [0, 0, 1218.90, 1729.13], "RA3" => [0, 0, 864.57, 1218.90], "RA4" => [0, 0, 609.45, 864.57], "SRA0" => [0, 0, 2551.18, 3628.35], "SRA1" => [0, 0, 1814.17, 2551.18], "SRA2" => [0, 0, 1275.59, 1814.17], "SRA3" => [0, 0, 907.09, 1275.59], "SRA4" => [0, 0, 637.80, 907.09], "LETTER" => [0, 0, 612.00, 792.00], "LEGAL" => [0, 0, 612.00, 1008.00], "FOLIO" => [0, 0, 612.00, 936.00], "EXECUTIVE" => [0, 0, 521.86, 756.00]   Standard page size names. One of these may be provided to PDF::Writer.new as the :paper parameter.

Page sizes supported are:

  • 4A0, 2A0
  • A0, A1 A2, A3, A4, A5, A6, A7, A8, A9, A10
  • B0, B1, B2, B3, B4, B5, B6, B7, B8, B9, B10
  • C0, C1, C2, C3, C4, C5, C6, C7, C8, C9, C10
  • RA0, RA1, RA2, RA3, RA4
  • SRA0, SRA1, SRA2, SRA3, SRA4
  • LETTER
  • LEGAL
  • FOLIO
  • EXECUTIVE
PDF_VERSION_13 = '1.3'
PDF_VERSION_14 = '1.4'
PDF_VERSION_15 = '1.5'
PDF_VERSION_16 = '1.6'
ENCRYPT_OPTIONS = { #:nodoc: :print => 4, :modify => 8, :copy => 16, :add => 32   Standard encryption/DRM options.
TAGS = { :pair => { }, :single => { }, :replace => { }   Callback tag relationships. All relationships are of the form "tagname" => CallbackClass.

There are three types of tag callbacks:

:pair:Paired callbacks, e.g., <c:alink></c:alink>.
:single:Single-tag callbacks, e.g., <C:bullet>.
:replace:Single-tag replacement callbacks, e.g., <r:xref>.

Attributes

absolute_bottom_margin  [R]  Returns the absolute y position of the bottom margin.
absolute_left_margin  [R]  The absolute x position of the left margin.
absolute_right_margin  [R]  The absolute x position of the right margin.
absolute_top_margin  [R]  Returns the absolute y position of the top margin.
absolute_x_middle  [R]  The absolute x middle position.
absolute_y_middle  [R]  The absolute y middle position.
bottom_margin  [RW] 
column_count  [R]  The total number of columns. Returns zero (0) if columns are off.
column_gutter  [R]  The gutter between columns. This will return zero (0) if columns are off.
column_number  [R]  The current column number. Returns zero (0) if columns are off.
column_width  [R]  The width of the currently active column. This will return zero (0) if columns are off.
compressed  [RW]  Sets the document to compressed (true) or uncompressed (false). Defaults to uncompressed. This can ONLY be set once and should be set as early as possible in the document creation process.
current_base_font  [R] 
current_contents  [R]  Returns the current contents object to which raw PDF instructions may be written.
current_font  [R] 
encryption_key  [RW]  The string that will be used to encrypt this PDF document.
first_page  [R]  Allows the user to find out what the ID is of the first page that was created during startup - useful if they wish to add something to it later.
font_families  [R]  Add a new translation table for a font family. A font family will be used to associate a single name and font styles with multiple fonts. A style will be identified with a single-character style identifier or a series of style identifiers. The only styles currently recognised are:
b:Bold (or heavy) fonts. Examples: Helvetica-Bold, Courier-Bold, Times-Bold.
i:Italic (or oblique) fonts. Examples: Helvetica-Oblique, Courier-Oblique, Times-Italic.
bi:Bold italic fonts. Examples Helvetica-BoldOblique, Courier-BoldOblique, Times-BoldItalic.
ib:Italic bold fonts. Generally defined the same as bi font styles. Examples: Helvetica-BoldOblique, Courier-BoldOblique, Times-BoldItalic.

Each font family key is the base name for the font.

font_size  [RW] 
info  [R]  The PDF::Writer::Object::Info info object. This is used to provide certain metadata.
left_margin  [RW] 
margin_height  [R]  The height of the margin area.
margin_width  [R]  The width of the margin area.
margin_x_middle  [R]  The middle of the writing area between the left and right margins.
margin_y_middle  [R]  The middle of the writing area between the top and bottom margins.
page_height  [R] 
page_width  [R] 
pointer  [RW]  The vertical position of the writing point. If the vertical position is outside of the bottom margin, a new page will be created.
right_margin  [RW] 
top_margin  [RW] 
version  [R]  The version of PDF to which this document conforms. Should be one of PDF_VERSION_13, PDF_VERSION_14, PDF_VERSION_15, or PDF_VERSION_16.
y  [RW]  The vertical position of the writing point. The vertical position is constrained between the top and bottom margins. Any attempt to set it outside of those margins will cause the y pointer to be placed absolutely at the margins.

Public Class methods

Convert a measurement in centimetres to points, which are the default PDF userspace units.

Escape the text so that it‘s safe for insertion into the PDF document.

Convert a measurement in inches to points, which are the default PDF userspace units.

Convert a measurement in millimetres to points, which are the default PDF userspace units.

Creates a new PDF document as a writing canvas. It accepts three named parameters:

:paper:Specifies the size of the default page in PDF::Writer. This may be a four-element array of coordinates specifying the lower-left (xll, yll) and upper-right (xur, yur) corners, a two-element array of width and height in centimetres, or a page name as defined in PAGE_SIZES.
:orientation:The orientation of the page, either long (:portrait) or wide (:landscape). This may be used to swap the width and the height of the page.
:version:The feature set available to the document is limited by the PDF version. Setting this version restricts the feature set available to PDF::Writer. PDF::Writer currently supports PDF version 1.3 features and does not yet support advanced features from PDF 1.4, 1.5, or 1.6.

Create the document with prepress options. Uses the same options as PDF::Writer.new (:paper, :orientation, and :version). It also supports the following options:

:left_margin:The left margin.
:right_margin:The right margin.
:top_margin:The top margin.
:bottom_margin:The bottom margin.
:bleed_size:The size of the bleed area in points. Default 12.
:mark_length:The length of the prepress marks in points. Default 18.

The prepress marks are added to the loose objects and will appear on all pages.

Public Instance methods

memory improvement for transaction-simple

add content to the currently active object

Create a labelled destination within the document. The label is the name which will be used for <c:ilink> destinations.

XYZ:The viewport will be opened at position (left, top) with zoom percentage. params must have three values representing left, top, and zoom, respectively. If the values are "null", the current parameter values are unchanged.
Fit:Fit the page to the viewport (horizontal and vertical). params will be ignored.
FitH:Fit the page horizontally to the viewport. The top of the viewport is set to the first value in params.
FitV:Fit the page vertically to the viewport. The left of the viewport is set to the first value in params.
FitR:Fits the page to the provided rectangle. params must have four values representing the left, bottom, right, and top positions, respectively.
FitB:Fits the page to the bounding box of the page. params is ignored.
FitBH:Fits the page horizontally to the bounding box of the page. The top position is defined by the first value in params.
FitBV:Fits the page vertically to the bounding box of the page. The left position is defined by the first value in params.

Add content to the documents info object.

Add a link in the document to an internal destination (ie. within the document)

Add a link in the document to an external URL.

After an object has been created, it will only show if it has been added, using this method.

Add an outline item (Bookmark).

Add text to the document at (x, y) location at size and angle. The word_space_adjust parameter is an internal parameter that should not be used.

As of PDF::Writer 1.1, size and text have been reversed and size is now optional, defaulting to the current font_size if unset.

Add text to the page, but ensure that it fits within a certain width. If it does not fit then put in as much as possible, breaking at word boundaries; return the remainder. justification and angle can also be specified for the text.

This will display the text; if it goes beyond the width width, it will backttrack to the previous space or hyphen and return the remainder of the text.

justification::left, :right, :center, or :full

Changes the insert_page property to append to the page set.

Sets the bleed box area.

should be used for internal checks, not implemented as yet

Close an object for writing.

Convert a measurement in centimetres to points, which are the default PDF userspace units.

Indicates if columns are currently on.

Returns true if the document is compressed.

Selects the current font based on defined font families and the current text state. As noted in font_families, a "bi" font can be defined differently than an "ib" font. It should not be possible to have a "bb" text state, but if one were to show up, an entry for the font_families would have to be defined to select anything other than the default font. This function is to be called whenever the current text state is changed; it will update the current font to whatever the appropriate font defined in the font family.

When the user calls select_font, both the current base font and the current font will be reset; this function only changes the current font, not the current base font.

This will probably not be needed by end users.

Returns the current generic page number. This is based exclusively on the size of the page set.

Return the font descender, this will normally return a negative number. If you add this number to the baseline, you get the level of the bottom of the font it is in the PDF user units. Uses the current font_size if size is not provided.

Return the height in units of the current font in the given size. Uses the current font_size if size is not provided.

Convert a measurement in inches to points, which are the default PDF userspace units.

Changes page insert mode. May be called as follows:

  pdf.insert_mode         # => current insert mode
    # The following four affect the insert mode without changing the
    # insert page or insert position.
  pdf.insert_mode(:on)    # enables insert mode
  pdf.insert_mode(true)   # enables insert mode
  pdf.insert_mode(:off)   # disables insert mode
  pdf.insert_mode(false)  # disables insert mode

    # Changes the insert mode, the insert page, and the insert
    # position at the same time.
  opts = {
    :on       => true,
    :page     => :last,
    :position => :before
  }
  pdf.insert_mode(opts)

Returns or changes the insert page property.

  pdf.insert_page         # => current insert page
  pdf.insert_page(35)     # insert at page 35
  pdf.insert_page(:last)  # insert at the last page

Returns or changes the insert position to be before or after the specified page.

  pdf.insert_position           # => current insert position
  pdf.insert_position(:before)  # insert before #insert_page
  pdf.insert_position(:after)   # insert before #insert_page

Returns the estimated number of lines remaining given the default or specified font size.

Define the margins in points. This will move the y pointer

                                  # T  L  B  R
  pdf.margins_pt(36)              # 36 36 36 36
  pdf.margins_pt(36, 54)          # 36 54 36 54
  pdf.margins_pt(36, 54, 72)      # 36 54 72 54
  pdf.margins_pt(36, 54, 72, 90)  # 36 54 72 90

Convert a measurement in millimetres to points, which are the default PDF userspace units.

Used to change the vertical position of the writing point. The pointer is moved down the page by dy (that is, y is reduced by dy), so if the pointer is to be moved up, a negative number must be used. Moving up the page will not move to the previous page because of limitations in the way that PDF::Writer works. The writing point will be limited to the top margin position.

If make_space is true and a new page is forced, then the pointer will be moved down on the new page. This will allow space to be reserved for graphics.

Add a new page to the document. This also makes the new page the current active object. This allows for mandatory page creation regardless of multi-column output.

For most purposes, start_new_page is preferred.

Specify the Destination object where the document should open when it first starts. style must be one of the following values. The value of style affects the interpretation of params. Uses page as the starting location.

Specify the Destination object where the document should open when it first starts. style must be one of the values detailed for destinations. The value of style affects the interpretation of params. Uses the current page as the starting location.

Opens a new PDF object for operating against. Returns the object‘s identifier. To close the object, you‘ll need to do:

  ob = open_new_object  # Opens the object
    # do stuff here
  close_object          # Closes the PDF document
    # do stuff here
  reopen_object(ob)     # Reopens the custom object.
  close_object          # Closes it.
  restore_state         # Returns full control to the PDF document.

… I think. I haven‘t examined the full details to be sure of what this is doing, but the code works.

Make a loose object. The output will go into this object, until it is closed, then will revert to the current one. This object will not appear until it is included within a page. The function will return the object reference.

Set the page mode of the catalog. Must be one of the following:

UseNone:Neither document outline nor thumbnail images are visible.
UseOutlines:Document outline visible.
UseThumbs:Thumbnail images visible.
FullScreen:Full-screen mode, with no menu bar, window controls, or any other window visible.
UseOC:Optional content group panel is visible.

Return the PDF stream as a string.

Opens an existing object for editing.

Restore a previously saved state.

Save the PDF as a file to disk.

Saves the state.

If the named font is not loaded, then load it and make the required PDF objects to represent the font. If the font is already loaded, then make it the current font.

The parameter encoding applies only when the font is first being loaded; it may not be applied later. It may either be an encoding name or a hash. The Hash must contain two keys:

:encoding:The name of the encoding. Either none, WinAnsiEncoding, MacRomanEncoding, or MacExpertEncoding. For symbolic fonts, an encoding of none is recommended with a differences Hash.
:differences:This Hash value is a mapping between character byte values (0 .. 255) and character names from the AFM file for the font.

The standard PDF encodings are detailed fully in the PDF Reference version 1.6, Appendix D.

Note that WinAnsiEncoding is not the same as Windows code page 1252 (roughly equivalent to latin-1), Most characters map, but not all. The encoding value currently defaults to WinAnsiEncoding.

If the font‘s "natural" encoding is desired, then it is necessary to specify the encoding parameter as { :encoding => nil }.

The number of PDF objects in the document

Starts multi-column output. Creates size number of columns with a gutter PDF unit space between each column.

If columns are already started, this will return false.

Creates a new page. If multi-column output is turned on, this will change the column to the next greater or create a new page as necessary. If force is true, then a new page will be created even if multi-column output is on.

Put page numbers on the pages from the current page. Place them relative to the coordinates (x, y) with the text horizontally relative according to pos, which may be :left, :right, or :center. The page numbers will be written on each page using pattern.

When pattern is rendered, <PAGENUM> will be replaced with the current page number; <TOTALPAGENUM> will be replaced with the total number of pages in the page numbering scheme. The default pattern is "<PAGENUM> of <TOTALPAGENUM>".

Each time page numbers are started, a new page number scheme will be started. The scheme number will be returned.

Turns off multi-column output. If we are in the first column, or the lowest point at which columns were written is higher than the bottom of the page, then the writing pointer will be placed at the lowest point. Otherwise, a new page will be started.

Stop an object from appearing on pages from this point on.

Stop page numbering. Returns false if page numbering is off.

If stop_total is true, then then the totaling of pages for this page numbering scheme will be stopped as well. If stop_at is :current, then the page numbering will stop at this page; otherwise, it will stop at the next page.

This method has been dprecated.

This will add a string of text to the document, starting at the current drawing position. It will wrap to keep within the margins, including optional offsets from the left and the right. The text will go to the start of the next line when a return code "\n" is found.

Possible options are:

:font_size:The font size to be used. If not specified, is either the last font size or the default font size of 12 points. Setting this value changes the current font_size.
:left:number, gap to leave from the left margin
:right:number, gap to leave from the right margin
:absolute_left:number, absolute left position (overrides :left)
:absolute_right:number, absolute right position (overrides :right)
:justification::left, :right, :center, :full
:leading:number, defines the total height taken by the line, independent of the font height.
:spacing:a Floating point number, though usually set to one of 1, 1.5, 2 (line spacing as used in word processing)

Only one of :leading or :spacing should be specified (leading overrides spacing).

If the :test option is true, then this should just check to see if the text is flowing onto a new page or not; returns true or false. Note that the new page test is only sensitive to exceeding the bottom margin of the page. It is not known whether the writing of the text will require a new physical page or whether it will require a new column.

Calculate how wide a given text string will be on a page, at a given size. This may be called externally, but is alse used by text_width. If size is not specified, PDF::Writer will use the current font_size.

The argument list is reversed from earlier versions.

Calculate how wide a given text string will be on a page, at a given size. If size is not specified, PDF::Writer will use the current font_size. The difference between this method and text_line_width is that this method will iterate over lines separated with newline characters.

The argument list is reversed from earlier versions.

to_s(debug = false)

Alias for render

Sets the trim box area.

set the viewer preferences of the document, it is up to the browser to obey these.

Given a particular generic page number page_num (numbered sequentially from the beginning of the page set), return the page number under a particular page numbering scheme (defaults to the first scheme turned on). Returns nil if page numbering is not turned on or if the page is not under the current numbering scheme.

This method has been dprecated.

[Validate]