class HexaPDF::Layout::TextFragment
A TextFragment
describes an optionally kerned piece of text that shares the same font, font size and other properties.
Its items are either glyph objects of the font or numeric values describing kerning information. All returned measurement values are in text space units. If the items or the style are changed, the clear_cache
has to be called. Otherwise the measurements may not be correct!
The items of a text fragment may be frozen to indicate that the fragment is potentially used multiple times.
The rectangle with the bottom left corner (x_min
, y_min
) and the top right corner (x_max
, y_max
) describes the minimum bounding box of the whole text fragment and is usually not equal to the box (0, 0)-(width
, height
).
Attributes
The items (glyphs and kerning values) of the text fragment.
The style to be applied.
Only the following properties are used:
-
Style#underline
-
Style#strikeout
-
Style#stroke_dash_pattern
-
Style#underlay_callback
-
Style#overlay_callback
Public Class Methods
Creates a new TextFragment
object for the given text, shapes it and returns it.
The needed style of the text fragment can either be specified by the style
argument or via the options
(in which case a new Style
object is created). Regardless of the way, the resulting style object needs at least the font set.
# File lib/hexapdf/layout/text_fragment.rb, line 66 def self.create(text, style = nil, **options) style = (style.nil? ? Style.new(**options) : style) fragment = new(style.font.decode_utf8(text), style) TextShaper.new.shape_text(fragment) end
Creates a new TextFragment
object with the given items and style.
The argument style
can either be a Style
object or a hash of style options.
# File lib/hexapdf/layout/text_fragment.rb, line 106 def initialize(items, style) @items = items @style = (style.kind_of?(Style) ? style : Style.new(**style)) end
Public Instance Methods
Clears all cached values.
This method needs to be called if the fragment's items or attributes are changed!
# File lib/hexapdf/layout/text_fragment.rb, line 267 def clear_cache @x_min = @x_max = @exact_y_min = @exact_y_max = @width = @height = nil self end
Draws the text onto the canvas at the given position.
This method is the main styled text drawing facility and therefore some optimizations are done:
-
The text is drawn using
HexaPDF::Content
;:Canvas#show_glyphs_only which means that the text matrix is not updated. Therefore the caller must not rely on it! -
All text style properties mentioned in the description of
style
are set except ifignore_text_properties
is set totrue
. Note that this only applies to style properties that directly affect text drawing, so, for example, underlays/overlays and underlining/strikeout is always done.The caller should set
ignore_text_properties
totrue
if the graphics state hasn't been changed. This is the case, for example, if the last thing drawn was a text fragment with the same style. -
It is assumed that the text matrix is not rotated, skewed, etc. so that setting the text position can be done using the optimal method.
# File lib/hexapdf/layout/text_fragment.rb, line 133 def draw(canvas, x, y, ignore_text_properties: false) style.underlays.draw(canvas, x, y + y_min, self) if style.underlays? # Set general font related graphics state if necessary unless ignore_text_properties canvas.font(style.font, size: style.calculated_font_size). horizontal_scaling(style.horizontal_scaling). character_spacing(style.character_spacing). word_spacing(style.word_spacing). text_rise(style.calculated_text_rise). text_rendering_mode(style.text_rendering_mode) # Set fill and/or stroke related graphics state canvas.opacity(fill_alpha: style.fill_alpha, stroke_alpha: style.stroke_alpha) trm = canvas.text_rendering_mode if trm.value.even? # text is filled canvas.fill_color(style.fill_color) end if trm == :stroke || trm == :fill_stroke || trm == :stroke_clip || trm == :fill_stroke_clip canvas.stroke_color(style.stroke_color). line_width(style.stroke_width). line_cap_style(style.stroke_cap_style). line_join_style(style.stroke_join_style). miter_limit(style.stroke_miter_limit). line_dash_pattern(style.stroke_dash_pattern) end end canvas.begin_text tlm = canvas.graphics_state.tlm tx = x - tlm.e ty = y - tlm.f if tx.abs < PRECISION if (ty + canvas.graphics_state.leading).abs < PRECISION canvas.move_text_cursor else canvas.move_text_cursor(offset: [0, ty], absolute: false) end elsif ty.abs < PRECISION canvas.move_text_cursor(offset: [tx, 0], absolute: false) else canvas.move_text_cursor(offset: [x, y]) end canvas.show_glyphs_only(items) if style.underline? && style.underline y_offset = style.calculated_underline_position canvas.save_graphics_state do canvas.stroke_color(style.fill_color). line_width(style.calculated_underline_thickness). line_cap_style(:butt). line_dash_pattern(0). line(x, y + y_offset, x + width, y + y_offset). stroke end end if style.strikeout? && style.strikeout y_offset = style.calculated_strikeout_position canvas.save_graphics_state do canvas.stroke_color(style.fill_color). line_width(style.calculated_strikeout_thickness). line_cap_style(:butt). line_dash_pattern(0). line(x, y + y_offset, x + width, y + y_offset). stroke end end style.overlays.draw(canvas, x, y + y_min, self) if style.overlays? end
The maximum y-coordinate of any item.
# File lib/hexapdf/layout/text_fragment.rb, line 232 def exact_y_max @exact_y_max ||= (@items.max_by(&:y_max)&.y_max || 0) * style.calculated_font_size / 1000.0 + style.calculated_text_rise end
The minimum y-coordinate of any item.
# File lib/hexapdf/layout/text_fragment.rb, line 226 def exact_y_min @exact_y_min ||= (@items.min_by(&:y_min)&.y_min || 0) * style.calculated_font_size / 1000.0 + style.calculated_text_rise end
The height of the text fragment.
It is calculated as the difference of the maximum of the y_max
values and the minimum of the y_min
values of the items. However, the text rise value is also taken into account so that the baseline is always inside the bounds. For example, if a large negative text rise value is used, the baseline will be equal to the top boundary; if a large positive value is used, it will be equal to the bottom boundary.
# File lib/hexapdf/layout/text_fragment.rb, line 253 def height @height ||= [y_max, 0].max - [y_min, 0].min end
Returns the vertical alignment inside a line which is always :text for text fragments.
See Line
for details.
# File lib/hexapdf/layout/text_fragment.rb, line 260 def valign :text end
The width of the text fragment.
It is the sum of the widths of its items and is calculated by using the algorithm presented in PDF1.7 s9.4.4. By using kerning values as the first and/or last items, the text contained in the fragment may spill over the left and/or right boundary.
# File lib/hexapdf/layout/text_fragment.rb, line 242 def width @width ||= @items.sum {|item| style.scaled_item_width(item) } end
The maximum x-coordinate of the last glyph.
# File lib/hexapdf/layout/text_fragment.rb, line 211 def x_max @x_max ||= calculate_x_max end
The minimum x-coordinate of the first glyph.
# File lib/hexapdf/layout/text_fragment.rb, line 206 def x_min @x_min ||= calculate_x_min end
The maximum y-coordinate, calculated using the scaled ascender of the font.
# File lib/hexapdf/layout/text_fragment.rb, line 221 def y_max style.scaled_y_max end
The minimum y-coordinate, calculated using the scaled descender of the font.
# File lib/hexapdf/layout/text_fragment.rb, line 216 def y_min style.scaled_y_min end