Class: Prawn::Text::Box

Inherits:
Object
  • Object
show all
Defined in:
lib/prawn/text/box.rb

Overview

Generally, one would use the text_box convenience method. However, using Text::Box.new in conjunction with render() enables one to do look-ahead calculations prior to placing text on the page, or to determine how much vertical space was consumed by the printed text

Constant Summary collapse

VALID_OPTIONS = 
Prawn::Core::Text::VALID_OPTIONS + 
        [:at, :height, :width, :align, :valign,
:overflow, :min_font_size, :line_wrap,
:leading, :document, :rotate, :rotate_around,
:single_line, :skip_encoding]

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(string, options = {}) ⇒ Box

See Prawn::Text#text_box for valid options



128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
 
# File 'lib/prawn/text/box.rb', line 128

def initialize(string, options={})
  @inked          = false
  Prawn.verify_options(VALID_OPTIONS, options)
  options          = options.dup
  @overflow        = options[:overflow] || :truncate
  @original_string = string
  @text            = nil
  
  @document        = options[:document]
  @at              = options[:at] ||
                     [@document.bounds.left, @document.bounds.top]
  @width           = options[:width] ||
                     @document.bounds.right - @at[0]
  @height          = options[:height] ||
                     @at[1] - @document.bounds.bottom
  @align           = options[:align] || :left
  @vertical_align  = options[:valign] || :top
  @leading         = options[:leading] || 0
  @rotate          = options[:rotate] || 0
  @rotate_around   = options[:rotate_around] || :upper_left
  @single_line     = options[:single_line]
  @skip_encoding   = options[:skip_encoding] || @document.skip_encoding

  if @overflow == :expand
    # if set to expand, then we simply set the bottom
    # as the bottom of the document bounds, since that
    # is the maximum we should expand to
    @height = @at[1] - @document.bounds.bottom
    @overflow = :truncate
  end
  @min_font_size  = options[:min_font_size] || 5
  @line_wrap    = options [:line_wrap] || @document.default_line_wrap
  @options = @document.text_options.merge(:kerning => options[:kerning],
                                          :size    => options[:size],
                                          :style   => options[:style])
end

Instance Attribute Details

#ascender ⇒ Object (readonly)

The height of the ascender of the last line printed



120
121
122
 
# File 'lib/prawn/text/box.rb', line 120

def ascender
  @ascender
end

#at ⇒ Object (readonly)

The upper left corner of the text box



116
117
118
 
# File 'lib/prawn/text/box.rb', line 116

def at
  @at
end

#descender ⇒ Object (readonly)

The height of the descender of the last line printed



122
123
124
 
# File 'lib/prawn/text/box.rb', line 122

def descender
  @descender
end

#leading ⇒ Object (readonly)

The leading used during printing



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

def leading
  @leading
end

#line_height ⇒ Object (readonly)

The line height of the last line printed



118
119
120
 
# File 'lib/prawn/text/box.rb', line 118

def line_height
  @line_height
end

#text ⇒ Object (readonly)

The text that was successfully printed (or, if dry_run was used, the test that would have been successfully printed)



114
115
116
 
# File 'lib/prawn/text/box.rb', line 114

def text
  @text
end

Instance Method Details

#height ⇒ Object

The height actually used during the previous render



203
204
205
206
207
208
209
210
 
# File 'lib/prawn/text/box.rb', line 203

def height
  return 0 if @baseline_y.nil? || @descender.nil?
  # baseline is already pushed down one line below the current
  # line, so we need to subtract line line_height and leading,
  # but we need to add in the descender since baseline is
  # above the descender
  @baseline_y.abs + @descender - @line_height - @leading
end

#render(flags = {}) ⇒ Object

Render text to the document based on the settings defined in initialize.

In order to facilitate look-ahead calculations, render accepts a :dry_run => true option. If provided then everything is executed as if rendering, with the exception that nothing is drawn on the page. Useful for look-ahead computations of height, unprinted text, etc.

Returns any text that did not print under the current settings



175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
 
# File 'lib/prawn/text/box.rb', line 175

def render(flags={})
  # dup because normalize_encoding changes the string
  string = @original_string.dup
  unprinted_text = ''
  @document.save_font do
    process_options

    unless @skip_encoding
      @document.font.normalize_encoding!(string)
    end

    @document.font_size(@font_size) do
      shrink_to_fit(string) if @overflow == :shrink_to_fit
      process_vertical_alignment(string)
      @inked = true unless flags[:dry_run]
      if @rotate != 0 && @inked
        unprinted_text = render_rotated(string)
      else
        unprinted_text = _render(string)
      end
      @inked = false
    end
  end
  unprinted_text
end