Class: PDF::Writer

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

### Methods

add_content add_destination add_info add_internal_link add_link add_object add_outline_item add_text add_text_wrap append_page bleed_box check_all_here close_object cm2pts cm2pts columns? compressed? current_font! current_page_number encrypt encrypted? escape font_descender font_height in2pts in2pts insert_mode insert_page insert_position lines_remaining margins_cm margins_in margins_mm margins_pt mm2pts mm2pts move_pointer new new_page open_at open_here open_new_object open_object page_mode= prepress render reopen_object restore_state save_as save_state select_font size start_columns start_new_page start_page_numbering stop_columns stop_object stop_page_numbering text text_line_width text_width to_s trim_box viewer_preferences which_page_number

### 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.3' |  | 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

cm2pts(x)

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

escape(text)

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

in2pts(x)

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

mm2pts(x)

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

new(options = {}) {|self if block_given?| ...}

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.

prepress(options = { }) {|pdf if block_given?| ...}

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

add_content(cc)

add content to the currently active object

add_destination(label, style, *params)

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_info(label, value = 0)

Add content to the documents info object.

add_internal_link(label, x0, y0, x1, y1)

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

add_link(uri, x0, y0, x1, y1)

Add a link in the document to an external URL.

add_object(id, where = :this_page)

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

add_outline_item(label, title = label)

Add an outline item (Bookmark).

add_text(x, y, text, size = nil, angle = 0, word_space_adjust = 0)

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_wrap(x, y, width, text, size = nil, justification = :left, angle = 0, test = false)

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

append_page()

Changes the insert_page property to append to the page set.

bleed_box(x0, y0, x1, y1)

Sets the bleed box area.

check_all_here()

should be used for internal checks, not implemented as yet

close_object()

Close an object for writing.

cm2pts(x)

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

columns?()

Indicates if columns are currently on.

compressed?()

Returns `true` if the document is compressed.

current_font!()

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.

current_page_number()

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

encrypt(user_pass = nil, owner_pass = nil, permissions = [])

Encrypts the document. This will set the user and owner passwords that will be used to access the document and set the permissions the user has with the document. The passwords are limited to 32 characters.

The permissions provided are an array of symbols, allowing identified users to perform particular actions:

`:print`: | Print.
`:modify`: | Modify text or objects.
`:copy`: | Copy text or objects.
`:add`: | Add text or objects.

encrypted?()
font_descender(size = nil)

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.

font_height(size = nil)

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

in2pts(x)

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

insert_mode(options = {})

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)

insert_page(page = nil)

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

insert_position(position = nil)

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

lines_remaining(font_size = nil)

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

margins_cm(top, left = top, bottom = top, right = left)

Define the margins in centimetres.

margins_in(top, left = top, bottom = top, right = left)

Define the margins in inches.

margins_mm(top, left = top, bottom = top, right = left)

Define the margins in millimetres.

margins_pt(top, left = top, bottom = top, right = left)

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

mm2pts(x)

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

move_pointer(dy, make_space = false)

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.

new_page(insert = false, page = nil, pos = :after)

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.

open_at(page, style, *params)

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.

open_here(style, *params)

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.

open_new_object()

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.

open_object() {|@current_contents if block_given?| ...}

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.

page_mode=(mode)

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.

render(debug = false)

Return the PDF stream as a string.

reopen_object(id)

Opens an existing object for editing.

restore_state()

Restore a previously saved state.

save_as(name)

Save the PDF as a file to disk.

save_state()

Saves the state.

select_font(font, encoding = nil)

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 }`.

size()

The number of PDF objects in the document

start_columns(size = 2, gutter = 10)

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`.

start_new_page(force = 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.

start_page_numbering(x, y, size, pos = nil, pattern = nil, starting = nil)

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>".

If `starting` is non-nil, this is the first page number. The number of total pages will be adjusted to account for this.

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

stop_columns()

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_object(id)

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

stop_page_numbering(stop_total = false, stop_at = :current, scheme = 0)

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.

text(text, options = {})

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.

text_line_width(text, size = nil)

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.

text_width(text, size = nil)

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

trim_box(x0, y0, x1, y1)

Sets the trim box area.

viewer_preferences(label, value = 0)

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

which_page_number(page_num, scheme = 0)

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]