Kanzi  3.9.7
Kanzi Engine API
kanzi::TextLayouter Class Reference

Use the TextLayouter to create layouts for display text strings, including line breaks, bidirectional text shaping, and similar. More...

#include <kanzi/core.ui/text/text_layouter.hpp>

Classes

struct  CharacterInfo
 Intermediate structure for layout of a single character. More...
 
struct  IntermediateLayout
 Intermediate structure for the layout of the text where the characters have not yet been positioned. More...
 
struct  LineInfo
 Structure for holding data about text lines. More...
 

Public Member Functions

unique_ptr< TextLayoutcreateLayout (string_view text)
 Creates layout for the given text. More...
 
float getMaximumHeight () const
 Gets the maximum height in pixels for the text layout area. More...
 
unsigned int getMaximumLines () const
 Gets the maximum number of lines of text that a layout accepts. More...
 
float getMaximumWidth () const
 Gets the maximum width in pixels for the text layout area. More...
 
bool getRemoveSideBearingsEnabled () const
 Gets the setting for the side bearing removal of text. More...
 
string_view getTerminator () const
 Gets the terminator string used when both horizontal and vertical space are running out for the text layout. More...
 
TextFormat::Truncation getTruncation () const
 Returns the truncation boundary that Kanzi uses to truncate the text that does not fit in the text layout. More...
 
TextFormat::TruncationDirection getTruncationDirection () const
 Returns which part of the text the text layout truncates. More...
 
bool getWordWrap () const
 Returns whether layout wraps into multiples lines the text that cannot fit into a single line. More...
 
void setHorizontalAlignment (TextFormat::TextHorizontalAlignment alignment)
 Sets the horizontal alignment of the text. More...
 
void setMaximumCharactersPerLine (unsigned int charactersPerLine)
 Sets the maximum number of characters for each line line for the text layout area. More...
 
void setMaximumHeight (float height)
 Sets the maximum height in pixels for the layout. More...
 
void setMaximumLines (unsigned int maximumLines)
 Sets the maximum number of lines for a layout. More...
 
void setMaximumWidth (float width)
 Sets the maximum width in pixels for the text layout area. More...
 
void setRemoveSideBearingsEnabled (bool removeSideBearingsEnabled)
 Controls text side bearings removal. More...
 
void setTerminator (string_view terminator)
 Sets the terminator string used when both horizontal and vertical space are running out for the text layout. More...
 
void setTruncation (TextFormat::Truncation value)
 Sets how to truncate the text that does not fit in the text layout. More...
 
void setTruncationDirection (TextFormat::TruncationDirection truncationDirection)
 Sets the part of the text to truncate, if the text that does not fit in the layout. More...
 
void setVerticalAlignment (TextFormat::TextVerticalAlignment alignment)
 Sets the vertical alignment of the text. More...
 
void setWhitespacePolicy (TextFormat::WhitespacePolicy whitespacePolicy)
 Sets the whitespace policy of the text. More...
 
void setWordWrap (bool wordWrapEnabled)
 Sets whether layout wraps into multiple lines the text that cannot fit into a single line. More...
 
 TextLayouter (const FontRuntime &font)
 Constructor. More...
 
virtual ~TextLayouter ()
 Destructor. More...
 

Detailed Description

Use the TextLayouter to create layouts for display text strings, including line breaks, bidirectional text shaping, and similar.

Kanzi line breaking and truncation algorithm works as follows:

  • Always break a line on a hard line break.
  • When there is not enough horizontal space to layout an entire line, break the line on a soft line break location. The most common location is at the end of whitespace between words or after specific characters, such as dash (-) and forward slash (/).
  • When a soft line break location is not available, break the line at the last fitting character. Remove all non-fitting whitespace from the end of the line.
  • When there is not enough vertical space, insert at the end of the last line the overflow string.

Constructor & Destructor Documentation

kanzi::TextLayouter::TextLayouter ( const FontRuntime font)
explicit

Constructor.

Parameters
fontFont to use when layouting.
virtual kanzi::TextLayouter::~TextLayouter ( )
virtual

Destructor.

Member Function Documentation

unique_ptr<TextLayout> kanzi::TextLayouter::createLayout ( string_view  text)

Creates layout for the given text.

You can render the returned text layout with the associated font or you can read the layout information from the structure.

Parameters
textText to layout.
Returns
Layouted text.
void kanzi::TextLayouter::setMaximumWidth ( float  width)

Sets the maximum width in pixels for the text layout area.

Note that at least one character for each line is always layouted. For unlimited width use numeric_limits<float>::infinity().

Parameters
widthMaximum allowed width in pixels.
float kanzi::TextLayouter::getMaximumWidth ( ) const

Gets the maximum width in pixels for the text layout area.

Returns
Maximum width for layout area.
void kanzi::TextLayouter::setMaximumCharactersPerLine ( unsigned int  charactersPerLine)

Sets the maximum number of characters for each line line for the text layout area.

Parameters
charactersPerLineCharacters allowed on a line.
void kanzi::TextLayouter::setMaximumHeight ( float  height)

Sets the maximum height in pixels for the layout.

Note that at least one line is always layouted. For unlimited height use numeric_limits<float>::infinity().

Parameters
heightMaximum allowed height in pixels.
float kanzi::TextLayouter::getMaximumHeight ( ) const

Gets the maximum height in pixels for the text layout area.

Returns
Maximum height for layout area.
void kanzi::TextLayouter::setMaximumLines ( unsigned int  maximumLines)

Sets the maximum number of lines for a layout.

Parameters
maximumLinesThe maximum number of lines allowed in a layout.
unsigned int kanzi::TextLayouter::getMaximumLines ( ) const

Gets the maximum number of lines of text that a layout accepts.

Returns
The maximum number of lines into which the layout can wrap text.
void kanzi::TextLayouter::setTerminator ( string_view  terminator)

Sets the terminator string used when both horizontal and vertical space are running out for the text layout.

Parameters
terminatorTerminating string to use.
string_view kanzi::TextLayouter::getTerminator ( ) const

Gets the terminator string used when both horizontal and vertical space are running out for the text layout.

Returns
Terminator string.
void kanzi::TextLayouter::setHorizontalAlignment ( TextFormat::TextHorizontalAlignment  alignment)

Sets the horizontal alignment of the text.

Parameters
alignmentHorizontal alignment to use.
void kanzi::TextLayouter::setVerticalAlignment ( TextFormat::TextVerticalAlignment  alignment)

Sets the vertical alignment of the text.

Parameters
alignmentVertical alignment to use.
void kanzi::TextLayouter::setWhitespacePolicy ( TextFormat::WhitespacePolicy  whitespacePolicy)

Sets the whitespace policy of the text.

Parameters
whitespacePolicyThe whitespace policy.
void kanzi::TextLayouter::setRemoveSideBearingsEnabled ( bool  removeSideBearingsEnabled)

Controls text side bearings removal.

When enabled, removes side bearings for each line separately, making text start right next to the sides.

Parameters
removeSideBearingsEnabledTrue to remove side bearings.
bool kanzi::TextLayouter::getRemoveSideBearingsEnabled ( ) const

Gets the setting for the side bearing removal of text.

Returns
True if side bearings removal is enabled.
void kanzi::TextLayouter::setWordWrap ( bool  wordWrapEnabled)

Sets whether layout wraps into multiple lines the text that cannot fit into a single line.

Parameters
wordWrapEnabledTo wrap long lines of text into multiple lines, set to true. To keep the text in a single line, set to false.
bool kanzi::TextLayouter::getWordWrap ( ) const

Returns whether layout wraps into multiples lines the text that cannot fit into a single line.

Returns
If the layout wraps long lines of text into multiple lines, true, otherwise false.
void kanzi::TextLayouter::setTruncationDirection ( TextFormat::TruncationDirection  truncationDirection)

Sets the part of the text to truncate, if the text that does not fit in the layout.

Parameters
truncationDirectionThe part of the text truncation to set.
Since
Kanzi 3.9.6
TextFormat::TruncationDirection kanzi::TextLayouter::getTruncationDirection ( ) const

Returns which part of the text the text layout truncates.

Returns
The part of the text that the text layout truncates.
Since
Kanzi 3.9.6
void kanzi::TextLayouter::setTruncation ( TextFormat::Truncation  value)

Sets how to truncate the text that does not fit in the text layout.

You can truncate the text character by character or by entire words.

Parameters
valueThe truncation boundary to set.
Since
Kanzi 3.9.6
TextFormat::Truncation kanzi::TextLayouter::getTruncation ( ) const

Returns the truncation boundary that Kanzi uses to truncate the text that does not fit in the text layout.

Returns
The truncation boundary used by the text layout.
Since
Kanzi 3.9.6

The documentation for this class was generated from the following file: