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

Instance Method Summary collapse

Instance Attribute Details

#skip_encoding ⇒ Object (readonly)

Deprecated.
Source Code
lib/pdf/core/text.rb, line 37
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.

Parameters:

  • text (String)
  • x (Numeric) —

    horizontal position of the text origin on the page

  • y (Numeric) —

    vertical position of the text origin on the page

  • options (Hash)

Options Hash (options):

  • :rotate (Numeric) —

    text rotation angle in degrees

  • :kerning (Boolean)
Source Code
lib/pdf/core/text.rb, line 332
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.



  





  

Parameters:


    
  
    
  • 
      
        amount
      
      
        (Numeric)
      
      
        (defaults to: nil)
      
      
    
    • 
  




Yields:


    
  
    
  • 
      
      
        
      
      
      
        
        
    Temporarily set character spacing
    

    
      
    
    • 
  



Returns:


    
  
    
  • 
      
      
        (Numeric)
      
      
      
        —
        
    if called without amount
    

    
      
    
    • 
  
    
  • 
      
      
        (void)
      
      
      
        —
        
    otherwise
    

    
      
    
    • 
  







  Source Code
  
lib/pdf/core/text.rb, line 254

  
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.



  





  
  

    
Examples:

    
      
      
pdf.default_kerning = false
pdf.text('hello world')                # text is not kerned
pdf.text('hello world', kerning: true) # text is kerned


    
  



Parameters:


    
  
    
  • 
      
        value
      
      
        (Boolean)
      
      
      
    
    • 
  








  Source Code
  
lib/pdf/core/text.rb, line 84

  
84
def default_kerning(value)

85
  @default_kerning = value

86
end







    
      

  

  
    #default_kerning?  ⇒ Boolean 
  

  

  


  

    
Retrieve the current default kerning setting.



Defaults to true.



  





  


Returns:


    
  
    
  • 
      
      
        (Boolean)
      
      
      
    
    • 
  







  Source Code
  
lib/pdf/core/text.rb, line 67

  
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.



  





  
  

    
Examples:

    
      
      
pdf.default_leading = 7
pdf.text('hello world')             # a leading of 7 is used
pdf.text('hello world', leading: 0) # a leading of 0 is used


    
  



Parameters:


    
  
    
  • 
      
        number
      
      
        (Numeric)
      
      
        (defaults to: nil)
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Numeric)
      
      
      
    
    • 
  







  Source Code
  
lib/pdf/core/text.rb, line 105

  
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
    • 




  





  
  

    
Examples:

    
      
      
file = "#{Prawn::DATADIR}/fonts/gkai00mp.ttf"
font_families['Kai'] = {
  normal: { file: file, font: 'Kai' }
}
file = "#{Prawn::DATADIR}/fonts/Action Man.dfont"
font_families['Action Man'] = {
  normal: { file: file, font: 'ActionMan' },
}
fallback_fonts ['Times-Roman', 'Kai']
font 'Action Man'
text 'hello ƒ 你好'
# hello prints in Action Man
# ƒ prints in Times-Roman
# 你好 prints in Kai

fallback_fonts [] # clears document-wide fallback fonts


    
  



Parameters:


    
  
    
  • 
      
        fallback_fonts
      
      
        (Array<String>)
      
      
        (defaults to: nil)
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (Array<String>)
      
      
      
    
    • 
  







  Source Code
  
lib/pdf/core/text.rb, line 184

  
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
  
lib/pdf/core/text.rb, line 240

  
240
def forget_text_rendering_mode!

241
  @text_rendering_mode = :unknown

242
end







    
      

  

  
    #horizontal_text_scaling(amount = nil) { ... } ⇒ Numeric, void 
  

  

  


  

    
Set the horizontal scaling.



  





  

Parameters:


    
  
    
  • 
      
        amount
      
      
        (Numeric)
      
      
        (defaults to: nil)
      
      
        —
        
    the percentage of the normal width.
    

    
      
    
    • 
  




Yields:


    
  
    
  • 
      
      
        
      
      
      
        
        
    Temporarili set text scaling
    

    
      
    
    • 
  



Returns:


    
  
    
  • 
      
      
        (Numeric)
      
      
      
        —
        
    if called with no arguments
    

    
      
    
    • 
  
    
  • 
      
      
        (void)
      
      
      
        —
        
    otherwise
    

    
      
    
    • 
  







  Source Code
  
lib/pdf/core/text.rb, line 292

  
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



  





  

Parameters:


    
  
    
  • 
      
        options
      
      
        (Hash)
      
      
      
    
    • 
  



  
    
    
    
Options Hash (options):

    
    
      
        
  • 
          :style
          (Symbol, String)
          
            
          
          
        
    • 
      
        
  • 
          :kerning
          (Boolean)
          
            
          
          
        
    • 
      
        
  • 
          :size
          (Numeric)
          
            
          
          
        
    • 
      
    

  






  Source Code
  
lib/pdf/core/text.rb, line 47

  
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.



  





  

Parameters:


    
  
    
  • 
      
        amount
      
      
        (Numeric)
      
      
        (defaults to: nil)
      
      
    
    • 
  




Yields:


    
  
    
  • 
      
      
        
      
      
      
        
        
    Temporarily set text rise
    

    
      
    
    • 
  



Returns:


    
  
    
  • 
      
      
        (Numeric)
      
      
      
        —
        
    if called with no arguments
    

    
      
    
    • 
  
    
  • 
      
      
        (void)
      
      
      
        —
        
    otherwise
    

    
      
    
    • 
  







  Source Code
  
lib/pdf/core/text.rb, line 312

  
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
    • 




  





  
  

    
Examples:

    
      
      
pdf.text_direction = :rtl
pdf.text('hello world')                  # prints 'dlrow olleh'
pdf.text('hello world', direction: :ltr) # prints 'hello world'


    
  



Parameters:


    
  
    
  • 
      
        direction
      
      
        (:ltr, :rtl)
      
      
        (defaults to: nil)
      
      
    
    • 
  




Returns:


    
  
    
  • 
      
      
        (:ltr)
      
      
      
    
    • 
  
    
  • 
      
      
        (:rtl)
      
      
      
    
    • 
  







  Source Code
  
lib/pdf/core/text.rb, line 139

  
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
    • 




  





  
  

    
Examples:

    
      
      
pdf.text_rendering_mode(:stroke) do
  pdf.text('Outlined Text')
end


    
  



Parameters:


    
  
    
  • 
      
        mode
      
      
        (Symbol)
      
      
        (defaults to: nil)
      
      
    
    • 
  




Yields:


    
  
    
  • 
      
      
        
      
      
      
        
        
    Temporariliy set text rendering mode
    

    
      
    
    • 
  



Returns:


    
  
    
  • 
      
      
        (Symbol)
      
      
      
        —
        
    if called withouth mode
    

    
      
    
    • 
  
    
  • 
      
      
        (void)
      
      
      
        —
        
    otherwise
    

    
      
    
    • 
  







  Source Code
  
lib/pdf/core/text.rb, line 220

  
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.



  





  

Parameters:


    
  
    
  • 
      
        amount
      
      
        (Numeric)
      
      
        (defaults to: nil)
      
      
    
    • 
  




Yields:


    
  
    
  • 
      
      
        
      
      
      
        
        
    Temporarily set word spacing
    

    
      
    
    • 
  



Returns:


    
  
    
  • 
      
      
        (Numeric)
      
      
      
        —
        
    if called without amount
    

    
      
    
    • 
  
    
  • 
      
      
        (void)
      
      
      
        —
        
    otherwise
    

    
      
    
    • 
  







  Source Code
  
lib/pdf/core/text.rb, line 276

  
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