module Prawn::Graphics::Dash

Public Instance Methods

dash(length = nil, options = {}) click to toggle source

Sets the dash pattern for stroked lines and curves or return the current dash pattern setting if length is nil.

There are two ways to set the dash pattern:

  • If the parameter length is an Integer/Float, it specifies the length of the dash and of the gap. The length of the gap can be customized by setting the :space option.

    Examples:

    length = 3
      3 on, 3 off, 3 on, 3 off, ...
    length = 3, :space =2
      3 on, 2 off, 3 on, 2 off, ...
  • If the parameter length is an array, it specifies the lengths of alternating dashes and gaps. The numbers must be non-negative and not all zero. The :space option is ignored in this case.

    Examples:

    length = [2, 1]
      2 on, 1 off, 2 on, 1 off, ...
    length = [3, 1, 2, 3]
      3 on, 1 off, 2 on, 3 off, 3 on, 1 off, ...
    length = [3, 0, 1]
      3 on, 0 off, 1 on, 3 off, 0 on, 1 off, ...

Options may contain the keys :space and :phase

:space

The space between the dashes (only used when length is not an array)

:phase

The distance into the dash pattern at which to start the dash. For example, a phase of 0 starts at the beginning of the dash; whereas, if the phase is equal to the length of the dash, then stroking will begin at the beginning of the space. Default is 0.

Integers or Floats may be used for length and the option values. Dash units are in PDF points (1/72 inch).

# File lib/prawn/graphics/dash.rb, line 58
def dash(length = nil, options = {})
  return current_dash_state if length.nil?

  length = Array(length)

  if length.all?(&:zero?)
    raise ArgumentError,
      'Zero length dashes are invalid. Call #undash to disable dashes.'
  elsif length.any?(&:negative?)
    raise ArgumentError,
      'Negative numbers are not allowed for dash lengths.'
  end

  length = length.first if length.length == 1

  self.current_dash_state = {
    dash: length,
    space: length.is_a?(Array) ? nil : options[:space] || length,
    phase: options[:phase] || 0
  }

  write_stroke_dash
end
Also aliased as: dash=
dash=(length = nil, options = {})
Alias for: dash
dashed?() click to toggle source

Returns when stroke is dashed, false otherwise

# File lib/prawn/graphics/dash.rb, line 93
def dashed?
  current_dash_state != undashed_setting
end
undash() click to toggle source

Stops dashing, restoring solid stroked lines and curves

# File lib/prawn/graphics/dash.rb, line 86
def undash
  self.current_dash_state = undashed_setting
  write_stroke_dash
end

Private Instance Methods

current_dash_state() click to toggle source
# File lib/prawn/graphics/dash.rb, line 111
def current_dash_state
  graphic_state.dash
end
current_dash_state=(dash_options) click to toggle source
# File lib/prawn/graphics/dash.rb, line 107
def current_dash_state=(dash_options)
  graphic_state.dash = dash_options
end
dash_setting() click to toggle source
# File lib/prawn/graphics/dash.rb, line 115
def dash_setting
  graphic_state.dash_setting
end
undashed_setting() click to toggle source
# File lib/prawn/graphics/dash.rb, line 103
def undashed_setting
  { dash: nil, space: nil, phase: 0 }
end
write_stroke_dash() click to toggle source
# File lib/prawn/graphics/dash.rb, line 99
def write_stroke_dash
  renderer.add_content dash_setting
end