Module: Prawn::Extras::Box

Included in:
Grid
Defined in:
lib/prawn/extras/box.rb

Instance Method Summary collapse

Instance Method Details

#box(position, width, height, options = {}) ⇒ Object

This method is mostly an alias to Prawn’s default bounding_box method. It passes parameters in a differnt way, but also includes the option to define a padding.

The padding may be a single integer value applied to all sides, or four separate values passed as an array, applied clockwise starting from top.

It also tracks by default which was the last box created (if using this method), so that the next box may be positioned relative to the previous one without the need to assign variables This can be disabled by setting the option :dont_track to any truthy value.

The size parameters can be expressed either as points, which is the default, but also in percentages, both “global” and “local”. To use percentages, the value must be passed as a String, with the % character at the end. The box will be created using “xx%” of the total available space of the current bounds.

There’s also the option to specify the width and height in percentages relative to the remaining space left. For example, if a box is created with its left side at 300, and the page is 600 wide, there’s only 50% of space left, so width may only be 50% or lower. However, if width is passed as “100%l”, with an l at the end, it will occupy “100%” of the remaining available space. This is useful for when a box must fill the remaining of the page but you don’t know exactly where is the cursor.



70
71
72
73
74
75
76
77
 
# File 'lib/prawn/extras/box.rb', line 70

def box(position, width, height, options = {})
  size = build_size_options(position, width, height)
  box = bounding_box(position, size) do
    padding(options[:padding] || [0, 0, 0, 0]) { yield if block_given? }
  end
  @last_created_box = box unless options[:dont_track]
  box
end

#box_below(origin_box, width, height, options = {}, &block) ⇒ Object

Defines a box directly below “origin_box”. The position is calculated relative to “origin_box”, all other parameters are the same as in the “box” method above.

An additional :gutter option may be set. This will add the specified value as space between “origin_box” and the new box.



123
124
125
126
 
# File 'lib/prawn/extras/box.rb', line 123

def box_below(origin_box, width, height, options = {}, &block)
  position = position_below(origin_box, options[:gutter] || 0)
  box(position, width, height, options, &block)
end

#box_below_previous(width, height, opcoes = {}, &block) ⇒ Object

Defines a box directly below the most recent previously created box. The position is calculated relative to it, all other parameters are the same as in the “box” method above.

An additional :gutter option may be set. This will add the specified value as space between the previous and the new box.



135
136
137
 
# File 'lib/prawn/extras/box.rb', line 135

def box_below_previous(width, height, opcoes = {}, &block)
  box_below(last_created_box, width, height, opcoes, &block)
end

#box_beside(origin_box, width, height, options = {}, &block) ⇒ Object

Defines a box directly to the right of “origin_box”. The position is calculated relative to “origin_box”, all other parameters are the same as in the “box” method above.

An additional :gutter option may be set. This will add the specified value as space between “origin_box” and the new box.



100
101
102
103
 
# File 'lib/prawn/extras/box.rb', line 100

def box_beside(origin_box, width, height, options = {}, &block)
  position = position_beside(origin_box, options[:gutter] || 0)
  box(position, width, height, options, &block)
end

#box_beside_previous(width, height, options = {}, &block) ⇒ Object

Defines a box directly to the right of the most recent previously created box. The position is calculated relative to it, all other parameters are the same as in the “box” method above.

An additional :gutter option may be set. This will add the specified value as space between the previous and the new box.



112
113
114
 
# File 'lib/prawn/extras/box.rb', line 112

def box_beside_previous(width, height, options = {}, &block)
  box_beside(last_created_box, width, height, options, &block)
end

#last_created_box ⇒ Object

Returns the most recent created box which was created using the “box” method. It will be nil if no boxes were created or if they were all created with the :dont_track option set to true.



9
10
11
 
# File 'lib/prawn/extras/box.rb', line 9

def last_created_box
  @last_created_box ||= nil
end

#padding(values) ⇒ Object

Sets a padding inside the current bounds. It essentially creates a new bounding_box centered on the current one, smaller in size, to simulate padding.

“values” may be a single integer value applied to all sides, or four separate values passed as an array, applied clockwise starting from top.



86
87
88
89
90
91
 
# File 'lib/prawn/extras/box.rb', line 86

def padding(values)
  values = build_padding_values(values)
  position = padding_position(values)
  width, height = padding_size(values)
  bounding_box(position, width: width, height: height) { yield }
end

#percent_h(value) ⇒ Object

Translates a percentage value to an absolute width value, within the limits of the current bounds (between “bounds.height” and 0).

The value parameter must be an integer between 0 and 100. If a value outside these bounds is provided, it will be clamped.



29
30
31
 
# File 'lib/prawn/extras/box.rb', line 29

def percent_h(value)
  bounds.height * (clamp_percentage(value) / 100.0)
end

#percent_w(value) ⇒ Object

Translates a percentage value to an absolute width value, within the limits of the current bounds (between 0 and “bounds.width”).

The value parameter must be an integer between 0 and 100. If a value outside these bounds is provided, it will be clamped.



19
20
21
 
# File 'lib/prawn/extras/box.rb', line 19

def percent_w(value)
  bounds.width * (clamp_percentage(value) / 100.0)
end

#position_below(origin_box, gutter = 0) ⇒ Object

Returns a two element array defining a position that is directly below “origin_box”. An optional gutter may be passed, and it will be converted to vertical space between the “origin_box” and this new position.



156
157
158
159
160
161
162
 
# File 'lib/prawn/extras/box.rb', line 156

def position_below(origin_box, gutter = 0)
  correct_origin = Array(origin_box).first
  return top_left if correct_origin.nil?
  left = correct_origin.absolute_left - bounds.anchor[0]
  bottom = correct_origin.anchor[1] - bounds.anchor[1]
  [left, bottom - gutter.to_f]
end

#position_beside(origin_box, gutter = 0) ⇒ Object

Returns a two element array defining a position that is directly to the right of “origin_box”. An optional gutter may be passed, and it will be converted to horizontal space between the “origin_box” and this new position.



144
145
146
147
148
149
 
# File 'lib/prawn/extras/box.rb', line 144

def position_beside(origin_box, gutter = 0)
  correct_origin = Array(origin_box).first
  return top_left if origin_box.nil?
  diff = [gutter - bounds.anchor[0], -bounds.anchor[1]]
  sum_dimensions(correct_origin.absolute_top_right, diff)
end

#remaining_height(base_height) ⇒ Object

Returns the absolute height value remaining to the bottom of the current bounds, relative to the provided base_height.

The base_height parameter must be a Prawn::Document::BoundingBox object, and the remaining height is calculated from the bottom side of this object.



40
41
42
 
# File 'lib/prawn/extras/box.rb', line 40

def remaining_height(base_height)
  base_height.anchor[1] - bounds.anchor[1]
end