Class: PDF::QuickRef

Inherits:
Object
  • Object
show all
Defined in:
lib/pdf/quickref.rb

Overview

QuickRef

A formatting language to create a quick reference sheet. This is a multi-column page in landscape mode that generally has three or four columns. This format may also be used for brochures, but brochure creation requires a bit of management to create properly.

Reference Sheets

A three-column reference sheet is generally in the form of:

Page 1:

column 1 | column 2 | column 3

Page 2:

column 4 | column 5 | column 6

The formatting language provided in QuickRef is based around this text flow. The title of the quick reference sheet is in column 1. The two pages are intended to be printed on both sides of pieces of paper so that columns 1 and 6 are matched. This will use a Z-fold that places columns 5 and 6 face to face and columns 2 and 3 face to face. In the folded reference sheet, columns 1 and 4 will be facing out.

Brochures

In contrast, brochures differ vastly in their design, although the common brochure is also three columns and either follows the same layout as a reference sheet or uses an overlapping fold.

When an overlapping fold is used, the title is typically on column 6 (assuming a left-to-right reading order). A short summary will appear on column 4. Contact information about the maker of the brochure is typically in column 5. Columns 1, 2, and 3 will contain the main body of the brochure. The brochure will be folded so that columns 2 and 3 are face to face. After this, column 1 will face column 4 (exposed by the first fold). In the folded brochure, columns 5 and 6 are facing out.

Usage

qr = PDF::QuickRef.new # 3-column LETTER
qr.title "My QuickRef"
qr.h1 "H1 Text"
qr.lines "Text to put after the header."
qr.save_as "MyQuickRef.pdf"

Constant Summary collapse

VERSION = 
'1.2.0'

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(paper = "LETTER", columns = 3, column_separators_visible = true) {|_self| ... } ⇒ QuickRef

Create the quick reference document. paper is passed unchanged to the PDF::Writer.new; the page is always created landscape. Margins are initialized to 18 points. After some additional initialization is performed, the quick reference document is yielded to an optional block for further configuration. All of this is done before the columns are started.

After the columns are started, lines will be drawn between column positions.

Yields:

  • (_self)

Yield Parameters:

  • _self (PDF::QuickRef) —

    the object that the method was called on



65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
 
# File 'lib/pdf/quickref.rb', line 65

def initialize(paper = "LETTER", columns = 3, column_separators_visible = true)
  @pdf  = PDF::Writer.new(:paper => paper, :orientation => :landscape)
  @pdf.margins_pt 18
  @pdf.y = @pdf.absolute_top_margin

  @title_font       = "Times-Roman"
  @heading_font     = "Times-Roman"
  @body_font        = "Times-Roman"
  @code_font        = "Courier"
  @title_font_size = 14
  @h1_font_size    = 11
  @h2_font_size    =  9
  @h3_font_size    =  8
  @h4_font_size    =  7
  @body_font_size  =  6

  @ptab = PDF::SimpleTable.new do |tab|
    tab.column_order.replace %w(one two)

    tab.font_size     = @body_font_size
    tab.show_lines    = :none
    tab.show_headings = false
    tab.orientation   = :center
    tab.position      = :center
  end
  @ltab = PDF::SimpleTable.new do |tab|
    tab.column_order.replace %w(line)

    tab.font_size     = @body_font_size
    tab.show_lines    = :none
    tab.show_headings = false
    tab.orientation   = :center
    tab.position      = :center
  end

  yield self if block_given?

  @pdf.start_columns columns

  @ptab.font_size = @body_font_size
  @ltab.font_size = @body_font_size

  @ptab.maximum_width = @pdf.column_width - 10
  @ltab.maximum_width = @pdf.column_width - 10

  if column_separators_visible
    # Put lines between the columns.
    all = @pdf.open_object
    @pdf.save_state
    @pdf.stroke_color! Color::RGB::Black
    @pdf.stroke_style  PDF::Writer::StrokeStyle::DEFAULT
    (1 .. (columns - 1)).each do |ii|
      x = @pdf.left_margin + (@pdf.column_width * ii)
      x += (@pdf.column_gutter * (ii - 0.5))
      @pdf.line(x, @pdf.page_height - @pdf.top_margin, x, @pdf.bottom_margin)
      @pdf.stroke
    end
    @pdf.restore_state
    @pdf.close_object
    @pdf.add_object(all, :all_pages)
  end
end

Instance Attribute Details

#body_font ⇒ Object

The name of the font that will be used for #body, #lines, and #pairs text. The default is ‘Times-Roman’.



155
156
157
 
# File 'lib/pdf/quickref.rb', line 155

def body_font
  @body_font
end

#body_font_encoding ⇒ Object

The font encoding for #body, #lines, and #pairs text.



157
158
159
 
# File 'lib/pdf/quickref.rb', line 157

def body_font_encoding
  @body_font_encoding
end

#body_font_size ⇒ Object

The size #body and #code text. The default is 7 points.



165
166
167
 
# File 'lib/pdf/quickref.rb', line 165

def body_font_size
  @body_font_size
end

#code_font ⇒ Object

The name of the font that will be used for #code, #codelines, and #codepairs text; this is generally a fixed-pitch font. The default is ‘Courier’.



161
162
163
 
# File 'lib/pdf/quickref.rb', line 161

def code_font
  @code_font
end

#code_font_encoding ⇒ Object

The font encoding for #code, #codelines, and #codepairs text.



163
164
165
 
# File 'lib/pdf/quickref.rb', line 163

def code_font_encoding
  @code_font_encoding
end

#h1_font_size ⇒ Object

The size #h1 text. The default is 11 points.



145
146
147
 
# File 'lib/pdf/quickref.rb', line 145

def h1_font_size
  @h1_font_size
end

#h2_font_size ⇒ Object

The size #h2 text. The default is 9 points.



147
148
149
 
# File 'lib/pdf/quickref.rb', line 147

def h2_font_size
  @h2_font_size
end

#h3_font_size ⇒ Object

The size #h3 text. The default is 8 points.



149
150
151
 
# File 'lib/pdf/quickref.rb', line 149

def h3_font_size
  @h3_font_size
end

#h4_font_size ⇒ Object

The size #h4 text. The default is 7 points.



151
152
153
 
# File 'lib/pdf/quickref.rb', line 151

def h4_font_size
  @h4_font_size
end

#heading_font ⇒ Object

The name of the font that will be used for #h1, #h2, #h3, and #h4 text. The default is Times-Roman.



141
142
143
 
# File 'lib/pdf/quickref.rb', line 141

def heading_font
  @heading_font
end

#heading_font_encoding ⇒ Object

The font encoding for #h1, #h2, #h3, and #h4 text.



143
144
145
 
# File 'lib/pdf/quickref.rb', line 143

def heading_font_encoding
  @heading_font_encoding
end

#pdf ⇒ Object (readonly)

Access to the raw PDF canvas for normal PDF::Writer configuration.



129
130
131
 
# File 'lib/pdf/quickref.rb', line 129

def pdf
  @pdf
end

#title_font ⇒ Object

The name of the font that will be used for #title text. The default font is Times-Roman.



133
134
135
 
# File 'lib/pdf/quickref.rb', line 133

def title_font
  @title_font
end

#title_font_encoding ⇒ Object

The font encoding for #title text.



135
136
137
 
# File 'lib/pdf/quickref.rb', line 135

def title_font_encoding
  @title_font_encoding
end

#title_font_size ⇒ Object

The size #title text. The default is 14 points.



137
138
139
 
# File 'lib/pdf/quickref.rb', line 137

def title_font_size
  @title_font_size
end

Class Method Details

.make(*args, &block) ⇒ Object

Creates a QuickRef document and then calls #instance_eval on the document. This allows for a more natural use of the QuickRef class as a DSL for creating these documents.

Using #make

PDF::QuickRef.make do # 3-column LETTER
  title "My QuickRef"
  h1 "H1 Text"
  lines "Text to put after the header."
  save_as "MyQuickRef.pdf"
end



329
330
331
332
 
# File 'lib/pdf/quickref.rb', line 329

def self.make(*args, &block)
  qr = PDF::QuickRef.new(*args)
  qr.__send__(:instance_eval, &block)
end

Instance Method Details

#body(text) ⇒ Object

Writes body text. Paragraphs will be reflowed for optimal placement of text. Text separated by two line separators (e.g., nn, although the separator is platform dependent). The text will be placed with full justification.



276
277
278
279
280
281
282
283
 
# File 'lib/pdf/quickref.rb', line 276

def body(text)
    # Transform the text a little.
  paras = text.split(%r(#{$/}{2}))
  paras.map! { |para| para.split($/).join(" ").squeeze(" ") }
  text = paras.join("\n\n")

  @pdf.text "#{text}\n", :font_size => @body_font_size, :justification => :full
end

#codelines(text) ⇒ Object

Creates a one-column zebra-striped table using the #code font. Each line of the text is a separate row.



203
204
205
206
207
208
209
210
 
# File 'lib/pdf/quickref.rb', line 203

def codelines(text)
  data = text.split($/).map { |line| { "line" => line } }
  @ltab.data.replace data
  use_code_font
  @ltab.render_on(@pdf)
  use_body_font
  @pdf.text "\n", :font_size => @body_font_size
end

#codepairs(text) ⇒ Object

Creates a two-column zebra-striped table using the #code font. Each line of the text is a separate row; the two columns are separated by tab characters.



182
183
184
185
186
187
188
189
190
191
192
 
# File 'lib/pdf/quickref.rb', line 182

def codepairs(text)
  data = text.split($/).map do |line|
    one, two = line.split(/\t/)
    { 'one' => one, 'two' => two }
  end
  @ptab.data.replace data
  use_code_font
  @ptab.render_on(@pdf)
  use_body_font
  @pdf.text "\n", :font_size => @body_font_size
end

#h1(text) ⇒ Object

Writes the text with the #heading_font and #h1_font_size left justified in the column. The font is set to #body_font after the heading is drawn.



243
244
245
246
247
 
# File 'lib/pdf/quickref.rb', line 243

def h1(text)
  use_heading_font
  @pdf.text text, :font_size => @h1_font_size
  use_body_font
end

#h2(text) ⇒ Object

Writes the text with the #heading_font and #h2_font_size left justified in the column. The font is set to #body_font after the heading is drawn.



251
252
253
254
255
 
# File 'lib/pdf/quickref.rb', line 251

def h2(text)
  use_heading_font
  @pdf.text "<i>#{text}</i>", :font_size => @h2_font_size
  use_body_font
end

#h3(text) ⇒ Object

Writes the text with the #heading_font and #h3_font_size left justified in the column. The font is set to #body_font after the heading is drawn.



259
260
261
262
263
 
# File 'lib/pdf/quickref.rb', line 259

def h3(text)
  use_heading_font
  @pdf.text "<i>#{text}</i>", :font_size => @h3_font_size
  use_body_font
end

#h4(text) ⇒ Object

Writes the text with the #heading_font and #h4_font_size left justified in the column. The font is set to #body_font after the heading is drawn.



267
268
269
270
271
 
# File 'lib/pdf/quickref.rb', line 267

def h4(text)
  use_heading_font
  @pdf.text "<b><i>#{text}</i></b>", :font_size => @h4_font_size
  use_body_font
end

#hline(style = PDF::Writer::StrokeStyle::DEFAULT, color = Color::RGB::Black) ⇒ Object

Draws a horizontal line with the specified style and colour.



292
293
294
295
296
297
298
299
300
301
302
303
304
 
# File 'lib/pdf/quickref.rb', line 292

def hline(style = PDF::Writer::StrokeStyle::DEFAULT,
          color = Color::RGB::Black)
  @pdf.y -= 2.5
  @pdf.save_state
  @pdf.stroke_style  style
  @pdf.stroke_color! color
  x0 = @pdf.left_margin
  x1 = @pdf.left_margin + pdf.column_width
  @pdf.line(x0, @pdf.y, x1, @pdf.y)
  @pdf.stroke
  @pdf.restore_state
  @pdf.y -= 2.5
end

#lines(text) ⇒ Object

Creates a one-column zebra-striped table using the #body font. Each line of the text is a separate row.



195
196
197
198
199
200
 
# File 'lib/pdf/quickref.rb', line 195

def lines(text)
  data = text.split($/).map { |line| { "line" => line } }
  @ltab.data.replace data
  @ltab.render_on(@pdf)
  @pdf.text "\n", :font_size => @body_font_size
end

#pairs(text) ⇒ Object

Creates a two-column zebra-striped table using the #body font. Each line of the text is a separate row; the two columns are separated by tab characters.



170
171
172
173
174
175
176
177
178
 
# File 'lib/pdf/quickref.rb', line 170

def pairs(text)
  data = text.split($/).map do |line|
    one, two = line.split(/\t/)
    { 'one' => one, 'two' => two }
  end
  @ptab.data.replace data
  @ptab.render_on(@pdf)
  @pdf.text "\n", :font_size => @body_font_size
end

#pre(text) ⇒ Object

Writes code text. Newlines and spaces will be preserved.



285
286
287
288
289
 
# File 'lib/pdf/quickref.rb', line 285

def pre(text)
  use_code_font
  @pdf.text "#{text}\n", :font_size => @body_font_size
  use_body_font
end

#render ⇒ Object Also known as: to_s

Generates the PDF document as a string.



312
313
314
 
# File 'lib/pdf/quickref.rb', line 312

def render
  @pdf.render
end

#save_as(filename) ⇒ Object

Writes the Quick Reference to disk.



307
308
309
 
# File 'lib/pdf/quickref.rb', line 307

def save_as(filename)
  @pdf.save_as(filename)
end

#title(text) ⇒ Object

Writes the text with the #title_font and #title_font_size centered in the column. After the title has been written, an #hline will be drawn under the title. The font is set to #body_font after the title is drawn.



234
235
236
237
238
239
 
# File 'lib/pdf/quickref.rb', line 234

def title(text)
  use_title_font
  @pdf.text text, :font_size => @title_font_size, :justification => :center
  use_body_font
  hline
end

#use_body_font ⇒ Object

Change the current font to the #body font.



222
223
224
 
# File 'lib/pdf/quickref.rb', line 222

def use_body_font
  @pdf.select_font @body_font, @body_font_encoding
end

#use_code_font ⇒ Object

Change the current font to the #code font.



226
227
228
 
# File 'lib/pdf/quickref.rb', line 226

def use_code_font
  @pdf.select_font @code_font, @code_font_encoding
end

#use_heading_font ⇒ Object

Change the current font to the heading font (used normally by #h1, #h2, #h3, and #h4|).



218
219
220
 
# File 'lib/pdf/quickref.rb', line 218

def use_heading_font
  @pdf.select_font @heading_font, @heading_font_encoding
end

#use_title_font ⇒ Object

Change the current font to the #title font.



213
214
215
 
# File 'lib/pdf/quickref.rb', line 213

def use_title_font
  @pdf.select_font @title_font, @title_font_encoding
end