Module: PDF::Core::Text
- Defined in:
- lib/pdf/core/text.rb
Overview
Low-level text rendering.
Defined Under Namespace
Classes: BadFontFamily
Constant Summary collapse
- VALID_OPTIONS =
Valid options of text drawing. These should be used as a base. Extensions may build on this list
%i[kerning size style].freeze
- MODES =
text rendering modes
{ fill: 0, stroke: 1, fill_stroke: 2, invisible: 3, fill_clip: 4, stroke_clip: 5, fill_stroke_clip: 6, clip: 7, }.freeze
Instance Attribute Summary collapse
-
#skip_encoding ⇒ Object
readonly
deprecated
Deprecated.
Instance Method Summary collapse
-
#add_text_content(text, x, y, options) ⇒ Object
Add a text object to content stream.
-
#character_spacing(amount = nil) { ... } ⇒ Numeric, void
Increases or decreases the space between characters.
-
#default_kerning(value) ⇒ void
(also: #default_kerning=)
Call with a boolean to set the document-wide kerning setting.
-
#default_kerning? ⇒ Boolean
Retrieve the current default kerning setting.
-
#default_leading(number = nil) ⇒ Numeric
(also: #default_leading=)
Call with no argument to retrieve the current default leading.
-
#fallback_fonts(fallback_fonts = nil) ⇒ Array<String>
(also: #fallback_fonts=)
Call with no argument to retrieve the current fallback fonts.
-
#forget_text_rendering_mode! ⇒ void
Forget previously set text rendering mode.
-
#horizontal_text_scaling(amount = nil) { ... } ⇒ Numeric, void
Set the horizontal scaling.
-
#process_text_options(options) ⇒ void
Low level call to set the current font style and extract text options from an options hash.
-
#rise(amount = nil) { ... } ⇒ Numeric, void
Move the baseline up or down from its default location.
-
#text_direction(direction = nil) ⇒ :ltr, :rtl
(also: #text_direction=)
Call with no argument to retrieve the current text direction.
-
#text_rendering_mode(mode = nil) { ... } ⇒ Symbol, void
Call with no argument to retrieve the current text rendering mode.
-
#word_spacing(amount = nil) { ... } ⇒ Numeric, void
Increases or decreases the space between words.
Instance Attribute Details
#skip_encoding ⇒ Object (readonly)
Source Code
37 | def skip_encoding |
38 | @skip_encoding
|
39 | end
|
Instance Method Details
#add_text_content(text, x, y, options) ⇒ Object
Add a text object to content stream.
Source Code
332 | def add_text_content(text, x, y, options) |
333 | chunks = font.encode_text(text, options) |
334 | |
335 | add_content("\nBT") |
336 | |
337 | if options[:rotate] |
338 | rad = Float(options[:rotate]) * Math::PI / 180 |
339 | array = [ |
340 | Math.cos(rad), |
341 | Math.sin(rad), |
342 | -Math.sin(rad), |
343 | Math.cos(rad), |
344 | x, y, |
345 | ]
|
346 | add_content("#{PDF::Core.real_params(array)} Tm") |
347 | else
|
348 | add_content("#{PDF::Core.real(x)} #{PDF::Core.real(y)} Td") |
349 | end
|
350 | |
351 | chunks.each do |(subset, string)| |
352 | font.add_to_current_page(subset) |
353 | add_content( |
354 | [
|
355 | PDF::Core.pdf_object(font.identifier_for(subset), true), |
356 | PDF::Core.pdf_object(font_size, true), |
357 | 'Tf', |
358 | ].join(' '), |
359 | )
|
360 | |
361 | operation = options[:kerning] && string.is_a?(Array) ? 'TJ' : 'Tj' |
362 | add_content("#{PDF::Core.pdf_object(string, true)} #{operation}") |
363 | end
|
364 | |
365 | add_content("ET\n") |
366 | end
|
#character_spacing(amount = nil) { ... } ⇒ Numeric, void
Increases or decreases the space between characters. For horizontal text, a positive value will increase the space. For vertical text, a positive value will decrease the space.
Call with no arguments to retrieve current character spacing.
Source Code
254 | def character_spacing(amount = nil, &block) |
255 | if amount.nil? |
256 | return (defined?(@character_spacing) && @character_spacing) || 0 |
257 | end
|
258 | |
259 | if character_spacing == amount |
260 | yield
|
261 | else
|
262 | wrap_and_restore_character_spacing(amount, &block) |
263 | end
|
264 | end
|
#default_kerning(value) ⇒ void Also known as: default_kerning=
This method returns an undefined value.
Call with a boolean to set the document-wide kerning setting. This can be overridden using the :kerning text option when drawing text or a text box.
Source Code
84 | def default_kerning(value) |
85 | @default_kerning = value |
86 | end
|
#default_kerning? ⇒ Boolean
Retrieve the current default kerning setting.
Defaults to true
.
Source Code
67 | def default_kerning? |
68 | return true unless defined?(@default_kerning) |
69 | |
70 | @default_kerning
|
71 | end
|
#default_leading(number = nil) ⇒ Numeric Also known as: default_leading=
Call with no argument to retrieve the current default leading.
Call with a number to set the document-wide text leading. This can be overridden using the :leading text option when drawing text or a text box.
Defaults to 0.
Source Code
105 | def default_leading(number = nil) |
106 | if number.nil? |
107 | (defined?(@default_leading) && @default_leading) || 0 |
108 | else
|
109 | @default_leading = number |
110 | end
|
111 | end
|
#fallback_fonts(fallback_fonts = nil) ⇒ Array<String> Also known as: fallback_fonts=
Call with no argument to retrieve the current fallback fonts.
Call with an array of font names. Each name must be the name of an AFM font or the name that was used to register a family of TTF fonts (see Prawn::Document#font_families). If present, then each glyph will be rendered using the first font that includes the glyph, starting with the current font and then moving through :fallback_fonts from left to right.
Call with an empty array to turn off fallback fonts.
Side effects:
- Increased overhead when fallback fonts are declared as each glyph is checked to see whether it exists in the current font
Source Code
184 | def fallback_fonts(fallback_fonts = nil) |
185 | if fallback_fonts.nil? |
186 | (defined?(@fallback_fonts) && @fallback_fonts) || [] |
187 | else
|
188 | @fallback_fonts = fallback_fonts |
189 | end
|
190 | end
|
#forget_text_rendering_mode! ⇒ void
This method returns an undefined value.
Forget previously set text rendering mode.
Source Code
240 | def forget_text_rendering_mode! |
241 | @text_rendering_mode = :unknown |
242 | end
|
#horizontal_text_scaling(amount = nil) { ... } ⇒ Numeric, void
Set the horizontal scaling.
Source Code
292 | def horizontal_text_scaling(amount = nil, &block) |
293 | if amount.nil? |
294 | return (defined?(@horizontal_text_scaling) && @horizontal_text_scaling) || 100 |
295 | end
|
296 | |
297 | if horizontal_text_scaling == amount |
298 | yield
|
299 | else
|
300 | wrap_and_restore_horizontal_text_scaling(amount, &block) |
301 | end
|
302 | end
|
#process_text_options(options) ⇒ void
This method returns an undefined value.
Low level call to set the current font style and extract text options from an options hash. Should be called from within a save_font block
Source Code
47 | def process_text_options(options) |
48 | if options[:style] |
49 | raise BadFontFamily unless font.family |
50 | |
51 | font(font.family, style: options[:style]) |
52 | end
|
53 | |
54 | # must compare against false to keep kerning on as default
|
55 | unless options[:kerning] == false |
56 | options[:kerning] = font.has_kerning_data? |
57 | end
|
58 | |
59 | options[:size] ||= font_size |
60 | end
|
#rise(amount = nil) { ... } ⇒ Numeric, void
Move the baseline up or down from its default location. Positive values move the baseline up, negative values move it down, and a zero value resets the baseline to its default location.
Source Code
312 | def rise(amount = nil, &block) |
313 | if amount.nil? |
314 | return (defined?(@rise) && @rise) || 0 |
315 | end
|
316 | |
317 | if rise == amount |
318 | yield
|
319 | else
|
320 | wrap_and_restore_rise(amount, &block) |
321 | end
|
322 | end
|
#text_direction(direction = nil) ⇒ :ltr, :rtl Also known as: text_direction=
Call with no argument to retrieve the current text direction.
Call with a symbol to set the document-wide text direction. This can be overridden using the :direction text option when drawing text or a text box.
Valid directions are:
:ltr
– left-to-right (default):rtl
– right-to-left
Side effects:
- When printing left-to-right, the default text alignment is
:left
- When printing right-to-left, the default text alignment is
:right
Source Code
139 | def text_direction(direction = nil) |
140 | if direction.nil? |
141 | (defined?(@text_direction) && @text_direction) || :ltr |
142 | else
|
143 | @text_direction = direction |
144 | end
|
145 | end
|
#text_rendering_mode(mode = nil) { ... } ⇒ Symbol, void
Call with no argument to retrieve the current text rendering mode.
Call with a symbol and block to temporarily change the current text rendering mode.
Valid modes are:
:fill
- fill text (default):stroke
- stroke text:fill_stroke
- fill, then stroke text:invisible
- invisible text:fill_clip
- fill text then add to path for clipping:stroke_clip
- stroke text then add to path for clipping:fill_stroke_clip
- fill then stroke text, then add to path for clipping:clip
- add text to path for clipping
Source Code
220 | def text_rendering_mode(mode = nil, &block) |
221 | if mode.nil? |
222 | return (defined?(@text_rendering_mode) && @text_rendering_mode) || :fill |
223 | end
|
224 | |
225 | unless MODES.key?(mode) |
226 | raise ArgumentError, |
227 | "mode must be between one of #{MODES.keys.join(', ')} (#{mode})" |
228 | end
|
229 | |
230 | if text_rendering_mode == mode |
231 | yield
|
232 | else
|
233 | wrap_and_restore_text_rendering_mode(mode, &block) |
234 | end
|
235 | end
|
#word_spacing(amount = nil) { ... } ⇒ Numeric, void
Increases or decreases the space between words. For horizontal text, a positive value will increase the space. For vertical text, a positive value will decrease the space.
Call with no arguments to retrieve current word spacing.
Source Code
276 | def word_spacing(amount = nil, &block) |
277 | return (defined?(@word_spacing) && @word_spacing) || 0 if amount.nil? |
278 | |
279 | if word_spacing == amount |
280 | yield
|
281 | else
|
282 | wrap_and_restore_word_spacing(amount, &block) |
283 | end
|
284 | end
|