HomeExamplesDocsCodeNews
Home  »  Docs  »  API Reference  »  HexaPDF  »  Layout  »  HexaPDF::Layout::TextFragment

Classes and Modules

class HexaPDF::Layout::TextFragment

Parent Object

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

items[RW]

The items (glyphs and kerning values) of the text fragment.

Public Class Methods

create(text, style)

Creates a new TextFragment object for the given text, shapes it and returns it.

The needed style of the text fragment is specified by the style argument (see Style::create for details). Note that the resulting style object needs at least the font set.

create_with_fallback_glyphs(text, style) → [frag]
create_with_fallback_glyphs(text, style) {|codepoint| block } → [frag1, frag2, ...]

Creates one or more TextFragment objects for the given text - possibly using glyphs from fallback fonts -, shapes them and returns them.

If no block is given, the method works like create but returns the text fragment inside an array.

If a block is given, the text is split on codepoints for which there is no glyph in the style’s font. For the parts with valid glyphs TextFragment objects are created like with create. Each codepoint without a valid glyph is yielded to the given block together with the associated HexaPDF::Font::InvalidGlyph object as arguments. The block needs to return an array of either HexaPDF::Font::Type1Wrapper::Glyph or HexaPDF::Font::TrueTypeWrapper::Glyph objects. This array is then used for creating a TextFragment object.

The needed style of the text fragments is specified by the style argument (see Style::create for details). Note that the resulting style object needs at least the font set.

new(items, style, properties: nil)

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 properties, see Style::create for details.

Public Instance Methods

attributes_hash()

Returns the value that should be used as hash key when only the fragment’s attributes - without the items - should play a role.

clear_cache()

Clears all cached values.

This method needs to be called if the fragment’s items or attributes are changed!

draw(canvas, x, y, ignore_text_properties: false)

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 if ignore_text_properties is set to true. 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 to true 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.

dup_attributes(items)

Creates a new TextFragment with the same style and custom properties as this one but with the given items.

exact_y_max()

The maximum y-coordinate of any item.

exact_y_min()

The minimum y-coordinate of any item.

fill_horizontal!(width)

Creates a new text fragment that repeats this fragment’s items and applies the necessary spacing so that the returned text fragment fills the given width completely.

If the given width is less than the fragment’s width, self is returned.

height()

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.

properties()

Returns the custom properties hash for the text fragment.

See Box#properties for usage details.

text()

Returns the text of the fragment.

valign()

Returns the vertical alignment inside a line which is always :text for text fragments.

See Line for details.

width()

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 PDF2.0 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.

x_max()

The maximum x-coordinate of the last glyph.

x_min()

The minimum x-coordinate of the first glyph.

y_max()

The maximum y-coordinate, calculated using the scaled ascender of the font.

y_min()

The minimum y-coordinate, calculated using the scaled descender of the font.