Prawn::Document::Internals

This module exposes a few low-level PDF features for those who want to extend Prawn’s core functionality. If you are not comfortable with low level PDF functionality as defined by Adobe’s specification, chances are you won’t need anything you find here.

Public Instance Methods

add_content(str) click to toggle source

Appends a raw string to the current page content.

                              
 # Raw line drawing example:           
 x1,y1,x2,y2 = 100,500,300,550
 pdf.add_content("%.3f %.3f m" % [ x1, y1 ])  # move 
 pdf.add_content("%.3f %.3f l" % [ x2, y2 ])  # draw path
 pdf.add_content("S") # stroke

    # File lib/prawn/document/internals.rb, line 56
56:       def add_content(str)
57:         save_graphics_state if graphic_state.nil?
58:         state.page.content << str << "\n"
59:       end

before_render(&block) click to toggle source

Defines a block to be called just before the document is rendered.

    # File lib/prawn/document/internals.rb, line 77
77:       def before_render(&block)
78:         state.before_render_callbacks << block
79:       end

deref(obj) click to toggle source

At any stage in the object tree an object can be replaced with an indirect reference. To get access to the object safely, regardless of if it’s hidden behind a Prawn::Reference, wrap it in deref().

    # File lib/prawn/document/internals.rb, line 44
44:       def deref(obj)
45:         obj.is_a?(Prawn::Core::Reference) ? obj.data : obj
46:       end

names() click to toggle source

The Name dictionary (PDF spec 3.6.3) for this document. It is lazily initialized, so that documents that do not need a name dictionary do not incur the additional overhead.

    # File lib/prawn/document/internals.rb, line 65
65:       def names
66:         state.store.root.data[:Names] ||= ref!(:Type => :Names)
67:       end

names?() click to toggle source

Returns true if the Names dictionary is in use for this document.

    # File lib/prawn/document/internals.rb, line 71
71:       def names?
72:         state.store.root.data[:Names]
73:       end

on_page_create(&block) click to toggle source

Defines a block to be called just before a new page is started.

    # File lib/prawn/document/internals.rb, line 83
83:       def on_page_create(&block)
84:          if block_given?
85:             state.on_page_create_callback = block
86:          else
87:             state.on_page_create_callback = nil
88:          end
89:       end

ref(data) click to toggle source

Creates a new Prawn::Reference and adds it to the Document’s object list. The data argument is anything that Prawn::PdfObject() can convert.

Returns the identifier which points to the reference in the ObjectStore

    # File lib/prawn/document/internals.rb, line 24
24:       def ref(data)
25:         ref!(data).identifier
26:       end

ref!(data) click to toggle source

Like ref, but returns the actual reference instead of its identifier.

While you can use this to build up nested references within the object tree, it is recommended to persist only identifiers, and them provide helper methods to look up the actual references in the ObjectStore if needed. If you take this approach, Prawn::Document::Snapshot will probably work with your extension

    # File lib/prawn/document/internals.rb, line 36
36:       def ref!(data)
37:         state.store.ref(data)
38:       end

Private Instance Methods

finalize_all_page_contents() click to toggle source

     # File lib/prawn/document/internals.rb, line 105
105:       def finalize_all_page_contents
106:         (1..page_count).each do |i|
107:           go_to_page i
108:           repeaters.each { |r| r.run(i) }
109:           while graphic_stack.present?
110:             restore_graphics_state
111:           end
112:           state.page.finalize
113:         end
114:       end

fresh_content_streams(options={}) click to toggle source

adds a new, empty content stream to each page. Used in templating so that imported content streams can be left pristine

     # File lib/prawn/document/internals.rb, line 96
 96:       def fresh_content_streams(options={})
 97:         (1..page_count).each do |i|
 98:           go_to_page i
 99:           state.page.new_content_stream
100:           apply_margin_options(options)
101:           use_graphic_settings(options[:template])
102:         end
103:       end

min_version(min) click to toggle source

raise the PDF version of the file we’re going to generate. A private method, designed for internal use when the user adds a feature to their document that requires a particular version.

     # File lib/prawn/document/internals.rb, line 120
120:       def min_version(min)
121:         state.version = min if min > state.version
122:       end

render_body(output) click to toggle source

Write out the PDF Body, as per spec 3.4.2

     # File lib/prawn/document/internals.rb, line 138
138:       def render_body(output)
139:         state.render_body(output)
140:       end

render_header(output) click to toggle source

Write out the PDF Header, as per spec 3.4.1

     # File lib/prawn/document/internals.rb, line 126
126:       def render_header(output)
127:         state.before_render_actions(self)
128: 
129:         # pdf version
130:         output << "%PDF-#{state.version}\n"
131: 
132:         # 4 binary chars, as recommended by the spec
133:         output << "%\xFF\xFF\xFF\xFF\n"
134:       end

render_trailer(output) click to toggle source

Write out the PDF Trailer, as per spec 3.4.4

     # File lib/prawn/document/internals.rb, line 157
157:       def render_trailer(output)
158:         trailer_hash = {:Size => state.store.size + 1, 
159:                         :Root => state.store.root,
160:                         :Info => state.store.info}
161:         trailer_hash.merge!(state.trailer) if state.trailer
162: 
163:         output << "trailer\n"
164:         output << Prawn::Core::PdfObject(trailer_hash) << "\n"
165:         output << "startxref\n" 
166:         output << @xref_offset << "\n"
167:         output << "%%EOF" << "\n"
168:       end

render_xref(output) click to toggle source

Write out the PDF Cross Reference Table, as per spec 3.4.3

     # File lib/prawn/document/internals.rb, line 144
144:       def render_xref(output)
145:         @xref_offset = output.size
146:         output << "xref\n"
147:         output << "0 #{state.store.size + 1}\n"
148:         output << "0000000000 65535 f \n"
149:         state.store.each do |ref|
150:           output.printf("%010d", ref.offset)
151:           output << " 00000 n \n"
152:         end
153:       end

Home Classes Methods

In Files

Methods

Files

Class Index

Prawn::Document::Internals

Public Instance Methods

Private Instance Methods