module Prawn::Graphics
Implements the drawing facilities for {Prawn::Document}. Use this to draw the most beautiful imaginable things.
Constants
- KAPPA
-
This constant is used to approximate a symmetrical arc using a cubic Bezier curve.
Public Instance Methods
Source
# File lib/prawn/graphics.rb, line 261 def circle(center, radius) ellipse(center, radius, radius) end
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.
@example
pdf.circle [100, 100], 25
@param center [Array(Number, Number)] @param radius [Number] @return [void]
Source
# File lib/prawn/graphics.rb, line 389 def close_and_stroke yield if block_given? renderer.add_content('s') end
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.
@yield @return [void]
Source
# File lib/prawn/graphics.rb, line 510 def close_path renderer.add_content('h') end
Closes the current path.
Source
# File lib/prawn/graphics.rb, line 242 def curve(origin, dest, options = {}) move_to(*origin) curve_to(dest, options) end
Draws a Bezier curve between two points, bounded by two additional points
@example
pdf.curve [50, 100], [100, 100], bounds: [[90, 90], [75, 75]]
@param origin [Array(Number, Number)] @param dest [Array(Number, Number)] @param options [Hash] @option options :bounds [Array(Array(Number, Number), Array(Number, Number))] @return [void]
Source
# File lib/prawn/graphics.rb, line 85 def curve_to(dest, options = {}) options[:bounds] || raise( Prawn::Errors::InvalidGraphicsPath, 'Bounding points for bezier curve must be specified as :bounds => [[x1,y1],[x2,y2]]', ) curve_points = PDF::Core.real_params( (options[:bounds] << dest).flat_map { |e| map_to_absolute(e) }, ) renderer.add_content("#{curve_points} c") end
Draws a Bezier curve from the current drawing position to the specified point, bounded by two additional points.
@example
pdf.curve_to [100, 100], bounds: [[90, 90], [75, 75]]
@param dest [Array(Number, Number)] @param options [Hash] @option options :bounds [Array(Array(Number, Number), Array(Number, Number))] @return [void]
Source
# File lib/prawn/graphics.rb, line 276 def ellipse(point, radius1, radius2 = radius1) x, y = point l1 = radius1 * KAPPA l2 = radius2 * KAPPA move_to(x + radius1, y) # Upper right hand corner curve_to( [x, y + radius2], bounds: [[x + radius1, y + l2], [x + l1, y + radius2]], ) # Upper left hand corner curve_to( [x - radius1, y], bounds: [[x - l1, y + radius2], [x - radius1, y + l2]], ) # Lower left hand corner curve_to( [x, y - radius2], bounds: [[x - radius1, y - l2], [x - l1, y - radius2]], ) # Lower right hand corner curve_to( [x + radius1, y], bounds: [[x + l1, y - radius2], [x + radius1, y - l2]], ) move_to(x, y) end
Draws an ellipse of ‘x` radius `radius1` and `y` radius `radius2` 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.
@example Draws an ellipse with x-radius 25 and y-radius 50
pdf.ellipse [100, 100], 25, 50
@param point [Array(Number, Number)] @param radius1 [Number] @param radius2 [Number] @return [void]
Source
# File lib/prawn/graphics.rb, line 485 def fill(options = {}) yield if block_given? renderer.add_content(options[:fill_rule] == :even_odd ? 'f*' : 'f') end
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.
@param options [Hash] @option options :fill_rule [Symbol] @yield @return [void]
Source
# File lib/prawn/graphics.rb, line 503 def fill_and_stroke(options = {}) yield if block_given? renderer.add_content(options[:fill_rule] == :even_odd ? 'b*' : 'b') end
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.
@param options [Hash] @option options :fill_rule [Symbol] @yield @return [void]
Source
# File lib/prawn/graphics.rb, line 202 def horizontal_line(x1, x2, options = {}) y1 = options[:at] || (y - bounds.absolute_bottom) line(x1, y1, x2, y1) end
Draws a horizontal line from ‘x1` to `x2` at the current {Document#y} position, or the position specified by the `:at` option.
@example Draw a line from ‘[25, 75]` to `[100, 75]`
horizontal_line 25, 100, at: 75
@param x1 [Number] @param x2 [Number] @param options [Hash] @option options :at [Number] @return [void]
Source
# File lib/prawn/graphics.rb, line 212 def horizontal_rule horizontal_line(bounds.left, bounds.right) end
Draws a horizontal line from the left border to the right border of the bounding box at the current {Document#y} position.
@return [void]
Source
# File lib/prawn/graphics.rb, line 185 def line(*points) x0, y0, x1, y1 = points.flatten move_to(x0, y0) line_to(x1, y1) end
Draws a line from one point to another. Points may be specified as tuples or flattened argument list.
@example
pdf.line [100, 100], [200, 250] pdf.line(100, 100, 200, 250)
@overload line(point1, point2)
@param point1 [Array(Number, Number)] @param point2 [Array(Number, Number)] @return [void]
@overload line(x1, y1, x2, y2)
@param x1 [Number] @param y1 [Number] @param x2 [Number] @param y2 [Number] @return [void]
Source
# File lib/prawn/graphics.rb, line 70 def line_to(*point) xy = PDF::Core.real_params(map_to_absolute(point)) renderer.add_content("#{xy} l") end
Draws a line from the current drawing position to the specified point. The destination may be described as a tuple or a flattened list:
@example
pdf.line_to [50, 50] pdf.line_to(50, 50)
@overload line_to(point)
@param point [Array(Number, Number)] @return [void]
@overload line_to(x, y)
@param x [Number] @param y [Number] @return [void]
Source
# File lib/prawn/graphics.rb, line 160 def line_width(width = nil) if width self.line_width = width else current_line_width end end
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).
@example
pdf.line_width #=> 1 pdf.line_width(5) pdf.line_width #=> 5
@overload line_width()
@return [Number]
@overload line_width(width)
@param width [Number] @return [void]
Source
# File lib/prawn/graphics.rb, line 141 def line_width=(width) self.current_line_width = width write_line_width end
Sets line thickness to the ‘width` specified.
@param width [Number] @return [void]
Source
# File lib/prawn/graphics.rb, line 51 def move_to(*point) xy = PDF::Core.real_params(map_to_absolute(point)) renderer.add_content("#{xy} m") end
Moves the drawing position to a given point. The point can be specified as a tuple or a flattened argument list.
@example
pdf.move_to [100, 50] pdf.move_to(100, 50)
@overload move_to(point)
@param point [Array(Number, Number)] @return [void]
@overload move_to(x, y)
@param x [Number] @param y [Number] @return [void]
Source
# File lib/prawn/graphics.rb, line 317 def polygon(*points) move_to(points[0]) (points[1..] << points[0]).each do |point| line_to(*point) end # close the path renderer.add_content('h') end
Draws a polygon from the specified points.
@example Draws a snazzy triangle
pdf.polygon [100,100], [100,200], [200,200]
@param points [Array<Array(Number, Number)>] @return [void]
Source
# File lib/prawn/graphics.rb, line 108 def rectangle(point, width, height) x, y = map_to_absolute(point) box = PDF::Core.real_params([x, y - height, width, height]) renderer.add_content("#{box} re") end
Draws a rectangle given ‘point`, `width and `height`. The rectangle is bounded by its upper-left corner.
@example
pdf.rectangle [300, 300], 100, 200
@param point [Array(Number, Number)] @param width [Number] @param height [Number] @return [void]
Source
# File lib/prawn/graphics.rb, line 338 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 renderer.add_content('h') end
Draws a rounded polygon from specified points using the radius to define bezier curves.
@example 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] )
@param radius [Number] @param points [Array<Array(Number, Number)>] @return [void]
Source
# File lib/prawn/graphics.rb, line 126 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
Draws a rounded rectangle given ‘point`, `width`, `height`, and `radius` for the rounded corner. The rectangle is bounded by its upper-left corner.
@example
pdf.rounded_rectangle [300, 300], 100, 200, 10
@param point [Array(Number, Number)] @param width [Number] @param height [Number] @param radius [Number] @return [void]
Source
# File lib/prawn/graphics.rb, line 357 def rounded_vertex(radius, *points) radial_point1 = point_on_line(radius, points[0], points[1]) bezier_point1 = point_on_line( (radius - (radius * KAPPA)), points[0], points[1], ) radial_point2 = point_on_line(radius, points[2], points[1]) bezier_point2 = point_on_line( (radius - (radius * KAPPA)), points[2], points[1], ) line_to(radial_point1) curve_to(radial_point2, bounds: [bezier_point1, bezier_point2]) end
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.
@param radius [Number] @param points [Array(Array(Number, Number), Array(Number, Number), Array(Number, Number))] @return [void]
Source
# File lib/prawn/graphics.rb, line 379 def stroke yield if block_given? renderer.add_content('S') end
Strokes the current path. If a block is provided, yields to the block before closing the path. See {Graphics::Color} for color details.
@yield @return [void]
Source
# File lib/prawn/graphics.rb, line 418 def stroke_axis(options = {}) options = { at: [0, 0], height: bounds.height - (options[:at] || [0, 0])[1], width: bounds.width - (options[:at] || [0, 0])[0], step_length: 100, negative_axes_length: 20, color: '000000', }.merge(options) Prawn.verify_options( %i[at width height step_length negative_axes_length color], options, ) save_graphics_state do fill_color(options[:color]) stroke_color(options[:color]) dash(1, space: 4) stroke_horizontal_line( options[:at][0] - options[:negative_axes_length], options[:at][0] + options[:width], at: options[:at][1], ) stroke_vertical_line( options[:at][1] - options[:negative_axes_length], options[:at][1] + options[:height], at: options[:at][0], ) undash fill_circle(options[:at], 1) (options[:step_length]..options[:width]) .step(options[:step_length]) do |point| fill_circle([options[:at][0] + point, options[:at][1]], 1) draw_text( point, at: [options[:at][0] + point - 5, options[:at][1] - 10], size: 7, ) end (options[:step_length]..options[:height]) .step(options[:step_length]) do |point| fill_circle([options[:at][0], options[:at][1] + point], 1) draw_text( point, at: [options[:at][0] - 17, options[:at][1] + point - 2], size: 7, ) end end end
Draws and strokes X and Y axes rulers beginning at the current bounding box origin (or at a custom location).
@param options [Hash] @option options :at [Array(Number, Number)] ([0, 0], origin of the bounding box)
Origin of the X and Y axes.
@option options :width [Number] (width of the bounding box)
Length of the X axis.
@option options :height [Number] (height of the bounding box)
Length of the Y axis.
@option options :step_length [Number] (100)
Length of the step between markers.
@option options :negative_axes_length [Number] (20)
Length of the negative parts of the axes.
@option options :color [String, Array<Number>]
The color of the axes and the text.
@return [void]
Source
# File lib/prawn/graphics.rb, line 397 def stroke_bounds stroke_rectangle(bounds.top_left, bounds.width, bounds.height) end
Draws and strokes a rectangle represented by the current bounding box.
@return [void]
Source
# File lib/prawn/graphics.rb, line 227 def vertical_line(y1, y2, params) line(params[:at], y1, params[:at], y2) end
Draws a vertical line at the x coordinate given by ‘:at` from `y1` to `y2`.
@example Draw a line from ‘[25, 100]` to `[25, 300]`
vertical_line 100, 300, at: 25
@param y1 [Number] @param y2 [Number] @param params [Hash] @option params :at [Number] @return [void]