Module: Prawn::Graphics

Includes:
CapStyle, Color, Dash, Gradient, JoinStyle, Transformation, Transparency
Included in:
Document
Defined in:
lib/prawn/graphics.rb,
lib/prawn/graphics/dash.rb,
lib/prawn/graphics/color.rb,
lib/prawn/graphics/gradient.rb,
lib/prawn/graphics/cap_style.rb,
lib/prawn/graphics/join_style.rb,
lib/prawn/graphics/transparency.rb,
lib/prawn/graphics/transformation.rb

Overview

Implements the drawing facilities for Prawn::Document. Use this to draw the most beautiful imaginable things.

This file lifts and modifies several of PDF::Writer's graphics functions ruby-pdf.rubyforge.org

Defined Under Namespace

Modules: CapStyle, Color, Dash, Gradient, JoinStyle, Transformation, Transparency

Constant Summary

KAPPA =

This constant is used to approximate a symmetrical arc using a cubic Bezier curve.

4.0 * ((Math.sqrt(2) - 1.0) / 3.0)

Constants included from JoinStyle

JoinStyle::JOIN_STYLES

Constants included from CapStyle

CapStyle::CAP_STYLES

Constants included from Color

Color::COLOR_SPACES

Instance Method Summary (collapse)

Methods included from Gradient

#fill_gradient, #stroke_gradient

Methods included from Transformation

#rotate, #scale, #transformation_matrix, #translate

Methods included from Transparency

#transparent

Methods included from JoinStyle

#join_style

Methods included from CapStyle

#cap_style

Methods included from Dash

#dash, #dashed?, #undash, #write_stroke_dash

Methods included from Color

#fill_color, #hex2rgb, #rgb2hex, #stroke_color

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

- (Object) method_missing(id, *args, &block)

Provides the following shortcuts:

stroke_some_method(*args) #=> some_method(*args); stroke
fill_some_method(*args) #=> some_method(*args); fill
fill_and_stroke_some_method(*args) #=> some_method(*args); fill_and_stroke


346
347
348
349
350
351
352
353
354
355
356
357
 
# File 'lib/prawn/graphics.rb', line 346

def method_missing(id,*args,&block)
  case(id.to_s)
  when /^fill_and_stroke_(.*)/
    send($1,*args,&block); fill_and_stroke
  when /^stroke_(.*)/
    send($1,*args,&block); stroke
  when /^fill_(.*)/
    send($1,*args,&block); fill
  else
    super
  end
end

Instance Method Details

- (Object) circle(center, radius)

Draws a circle of radius radius with the centre-point at point as a complete subpath. The drawing point will be moved to the centre-point upon completion of the drawing the circle.

pdf.circle [100,100], 25


197
198
199
 
# File 'lib/prawn/graphics.rb', line 197

def circle(center, radius)
  ellipse(center, radius, radius)
end

- (Object) circle_at(point, options)

DEPRECATED: Please use circle instead.



185
186
187
188
189
 
# File 'lib/prawn/graphics.rb', line 185

def circle_at(point, options)
  warn "[DEPRECATION] 'circle_at' is deprecated in favor of 'circle'. " +
       "'circle_at' will be removed in release 1.1"
  circle(point, options[:radius])
end

- (Object) close_and_stroke

Closes and strokes the current path. If a block is provided, yields to the block before closing the path. See Graphics::Color for color details.



297
298
299
300
 
# File 'lib/prawn/graphics.rb', line 297

def close_and_stroke
  yield if block_given?
  add_content "s"
end

- (Object) close_path

Closes the current path.



336
337
338
 
# File 'lib/prawn/graphics.rb', line 336

def close_path
  add_content "h"
end

- (Object) curve(origin, dest, options = {})

Draws a Bezier curve between two points, bounded by two additional points

pdf.curve [50,100], [100,100], :bounds => [[90,90],[75,75]]


174
175
176
177
 
# File 'lib/prawn/graphics.rb', line 174

def curve(origin,dest, options={})
  move_to(*origin)
  curve_to(dest,options)
end

- (Object) curve_to(dest, options = {})

Draws a Bezier curve from the current drawing position to the specified point, bounded by two additional points.

pdf.curve_to [100,100], :bounds => [[90,90],[75,75]]


66
67
68
69
70
71
72
73
74
 
# File 'lib/prawn/graphics.rb', line 66

def curve_to(dest,options={})
   options[:bounds] or raise Prawn::Errors::InvalidGraphicsPath,
     "Bounding points for bezier curve must be specified "+
     "as :bounds => [[x1,y1],[x2,y2]]"

   curve_points = (options[:bounds] << dest).map { |e| map_to_absolute(e) }
   add_content("%.3f %.3f %.3f %.3f %.3f %.3f c" %
                 curve_points.flatten )
end

- (Object) ellipse(point, r1, r2 = r1)

Draws an ellipse of x radius r1 and y radius r2 with the centre-point at point as a complete subpath. The drawing point will be moved to the centre-point upon completion of the drawing the ellipse.

# draws an ellipse with x-radius 25 and y-radius 50
pdf.ellipse [100,100], 25, 50


216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/prawn/graphics.rb', line 216

def ellipse(point, r1, r2 = r1)
  x, y = point
  l1 = r1 * KAPPA
  l2 = r2 * KAPPA

  move_to(x + r1, y)

  # Upper right hand corner
  curve_to [x,  y + r2],
    :bounds => [[x + r1, y + l2], [x + l1, y + r2]]

  # Upper left hand corner
  curve_to [x - r1, y],
    :bounds => [[x - l1, y + r2], [x - r1, y + l2]]

  # Lower left hand corner
  curve_to [x, y - r2],
    :bounds => [[x - r1, y - l2], [x - l1, y - r2]]

  # Lower right hand corner
  curve_to [x + r1, y],
    :bounds => [[x + l1, y - r2], [x + r1, y - l2]]

  move_to(x, y)
end

- (Object) ellipse_at(point, r1, r2 = r1)

DEPRECATED: Please use ellipse instead.



202
203
204
205
206
 
# File 'lib/prawn/graphics.rb', line 202

def ellipse_at(point, r1, r2=r1)
  warn "[DEPRECATION] 'ellipse_at' is deprecated in favor of 'ellipse'. " +
       "'ellipse_at' will be removed in release 1.1"
  ellipse(point, r1, r2)
end

- (Object) fill(options = {})

Closes and fills the current path. See Graphics::Color for color details.

If the option :fill_rule => :even_odd is specified, Prawn will use the even-odd rule to fill the path. Otherwise, the nonzero winding number rule will be used. See the PDF reference, "Graphics -> Path Construction and Painting -> Clipping Path Operators" for details on the difference.



315
316
317
318
 
# File 'lib/prawn/graphics.rb', line 315

def fill(options={})
  yield if block_given?
  add_content(options[:fill_rule] == :even_odd ? "f*" : "f")
end

- (Object) fill_and_stroke(options = {})

Closes, fills, and strokes the current path. If a block is provided, yields to the block before closing the path. See Graphics::Color for color details.

If the option :fill_rule => :even_odd is specified, Prawn will use the even-odd rule to fill the path. Otherwise, the nonzero winding number rule will be used. See the PDF reference, "Graphics -> Path Construction and Painting -> Clipping Path Operators" for details on the difference.



329
330
331
332
 
# File 'lib/prawn/graphics.rb', line 329

def fill_and_stroke(options={})
  yield if block_given?
  add_content(options[:fill_rule] == :even_odd ? "b*" : "b")
end

- (Object) horizontal_line(x1, x2, options = {})

Draws a horizontal line from x1 to x2 at the current y position, or the position specified by the :at option.

# draw a line from [25, 75] to [100, 75]
horizontal_line 25, 100, :at => 75


143
144
145
146
147
148
149
150
151
 
# File 'lib/prawn/graphics.rb', line 143

def horizontal_line(x1,x2,options={})
  if options[:at]
    y1 = options[:at]
  else
    y1 = y - bounds.absolute_bottom
  end
  
  line(x1,y1,x2,y1)
end

- (Object) horizontal_rule

Draws a horizontal line from the left border to the right border of the bounding box at the current y position.



156
157
158
 
# File 'lib/prawn/graphics.rb', line 156

def horizontal_rule
  horizontal_line(bounds.left, bounds.right)
end

- (Object) line(*points)

Draws a line from one point to another. Points may be specified as tuples or flattened argument list:

pdf.line [100,100], [200,250]
pdf.line(100,100,200,250)


131
132
133
134
135
 
# File 'lib/prawn/graphics.rb', line 131

def line(*points)
  x0,y0,x1,y1 = points.flatten
  move_to(x0, y0)
  line_to(x1, y1)
end

- (Object) line_to(*point)

Draws a line from the current drawing position to the specified point. The destination may be described as a tuple or a flattened list:

pdf.line_to [50,50]
pdf.line_to(50,50)


56
57
58
59
 
# File 'lib/prawn/graphics.rb', line 56

def line_to(*point)
  x,y = map_to_absolute(point)
  add_content("%.3f %.3f l" % [ x, y ])
end

- (Object) line_width(width = nil)

When called without an argument, returns the current line thickness. When called with an argument, sets the line thickness to the specified value (in PDF points)

pdf.line_width #=> 1
pdf.line_width(5)
pdf.line_width #=> 5


117
118
119
120
121
122
123
 
# File 'lib/prawn/graphics.rb', line 117

def line_width(width=nil)
  if width
    self.line_width = width
  else
    current_line_width
  end
end

- (Object) line_width=(width)

Sets line thickness to the width specified.



104
105
106
107
 
# File 'lib/prawn/graphics.rb', line 104

def line_width=(width)
  self.current_line_width = width
  write_line_width
end

- (Object) move_to(*point)

Moves the drawing position to a given point. The point can be specified as a tuple or a flattened argument list

pdf.move_to [100,50]
pdf.move_to(100,50)


45
46
47
48
 
# File 'lib/prawn/graphics.rb', line 45

def move_to(*point)
  x,y = map_to_absolute(point)
  add_content("%.3f %.3f m" % [ x, y ])
end

- (Object) polygon(*points)

Draws a polygon from the specified points.

# draws a snazzy triangle
pdf.polygon [100,100], [100,200], [200,200]


247
248
249
250
251
252
253
254
 
# File 'lib/prawn/graphics.rb', line 247

def polygon(*points)
  move_to points[0]
  (points[1..-1] << points[0]).each do |point|
    line_to(*point)
  end
  # close the path
  add_content "h"
end

- (Object) rectangle(point, width, height)

Draws a rectangle given point, width and height. The rectangle is bounded by its upper-left corner.

pdf.rectangle [300,300], 100, 200


81
82
83
84
 
# File 'lib/prawn/graphics.rb', line 81

def rectangle(point,width,height)
  x,y = map_to_absolute(point)
  add_content("%.3f %.3f %.3f %.3f re" % [ x, y - height, width, height ])
end

- (Object) rounded_polygon(radius, *points)

Draws a rounded polygon from specified points using the radius to define bezier curves

# draws a rounded filled in polygon
 pdf.fill_and_stroke_rounded_polygon(10, [100, 250], [200, 300], [300, 250],
               [300, 150], [200, 100], [100, 150])


261
262
263
264
265
266
267
268
269
270
 
# File 'lib/prawn/graphics.rb', line 261

def rounded_polygon(radius, *points)
  move_to point_on_line(radius, points[1], points[0])
  sides = points.size
  points << points[0] << points[1]
  (sides).times do |i|
    rounded_vertex(radius, points[i], points[i + 1], points[i + 2])
  end
  # close the path
  add_content "h"
end

- (Object) rounded_rectangle(point, width, height, radius)

Draws a rounded rectangle given point, width and height and radius for the rounded corner. The rectangle is bounded by its upper-left corner.

pdf.rounded_rectangle [300,300], 100, 200, 10


92
93
94
95
 
# File 'lib/prawn/graphics.rb', line 92

def rounded_rectangle(point,width,height,radius)
  x, y = point
  rounded_polygon(radius, point, [x + width, y], [x + width, y - height], [x, y - height])
end

- (Object) rounded_vertex(radius, *points)

Creates a rounded vertex for a line segment used for building a rounded polygon requires a radius to define bezier curve and three points. The first two points define the line segment and the third point helps define the curve for the vertex.



276
277
278
279
280
281
282
283
284
 
# File 'lib/prawn/graphics.rb', line 276

def rounded_vertex(radius, *points)
  x0,y0,x1,y1,x2,y2 = points.flatten
  radial_point_1 = point_on_line(radius, points[0], points[1])
  bezier_point_1 = point_on_line((radius - radius*KAPPA), points[0], points[1] )
  radial_point_2 = point_on_line(radius, points[2], points[1])
  bezier_point_2 = point_on_line((radius - radius*KAPPA), points[2], points[1])
  line_to(radial_point_1)
  curve_to(radial_point_2, :bounds => [bezier_point_1, bezier_point_2])
end

- (Object) stroke

Strokes the current path. If a block is provided, yields to the block before closing the path. See Graphics::Color for color details.



289
290
291
292
 
# File 'lib/prawn/graphics.rb', line 289

def stroke
  yield if block_given?
  add_content "S"
end

- (Object) stroke_bounds

Draws and strokes a rectangle represented by the current bounding box



304
305
306
 
# File 'lib/prawn/graphics.rb', line 304

def stroke_bounds
  stroke_rectangle bounds.top_left, bounds.width, bounds.height
end

- (Object) vertical_line(y1, y2, params)

Draws a vertical line at the x cooordinate given by :at from y1 to y2.

# draw a line from [25, 100] to [25, 300]
vertical_line 100, 300, :at => 25


165
166
167
 
# File 'lib/prawn/graphics.rb', line 165

def vertical_line(y1,y2,params)
  line(params[:at],y1,params[:at],y2)
end