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"

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



64
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
 
# File 'lib/pdf/quickref.rb', line 64

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



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

def body_font
  @body_font
end

#body_font_encoding ⇒ Object

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



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

def body_font_encoding
  @body_font_encoding
end

#body_font_size ⇒ Object

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



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

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



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

def code_font
  @code_font
end

#code_font_encoding ⇒ Object

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



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

def code_font_encoding
  @code_font_encoding
end

#h1_font_size ⇒ Object

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



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

def h1_font_size
  @h1_font_size
end

#h2_font_size ⇒ Object

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



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

def h2_font_size
  @h2_font_size
end

#h3_font_size ⇒ Object

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



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

def h3_font_size
  @h3_font_size
end

#h4_font_size ⇒ Object

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



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

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.



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

def heading_font
  @heading_font
end

#heading_font_encoding ⇒ Object

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



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

def heading_font_encoding
  @heading_font_encoding
end

#pdf ⇒ Object (readonly)

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



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

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.



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

def title_font
  @title_font
end

#title_font_encoding ⇒ Object

The font encoding for #title text.



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

def title_font_encoding
  @title_font_encoding
end

#title_font_size ⇒ Object

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



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

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



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

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.



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

def render
  @pdf.render
end

#save_as(filename) ⇒ Object

Writes the Quick Reference to disk.



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

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.



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

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.



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

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.



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

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



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

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.



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

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