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< TextLayout >	createLayout (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

◆ TextLayouter()

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

explicit

Constructor.

Parameters

font	Font to use when layouting.

◆ ~TextLayouter()

virtual kanzi::TextLayouter::~TextLayouter ( )

virtual

Destructor.

Member Function Documentation

◆ createLayout()

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

text	Text to layout.

Returns: Layouted text.

◆ setMaximumWidth()

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

width Maximum allowed width in pixels.

◆ getMaximumWidth()

float kanzi::TextLayouter::getMaximumWidth ( ) const

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

Returns: Maximum width for layout area.

◆ setMaximumCharactersPerLine()

void kanzi::TextLayouter::setMaximumCharactersPerLine ( unsigned int charactersPerLine )

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

Parameters

charactersPerLine Characters allowed on a line.

◆ setMaximumHeight()

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

height Maximum allowed height in pixels.

◆ getMaximumHeight()

float kanzi::TextLayouter::getMaximumHeight ( ) const

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

Returns: Maximum height for layout area.

◆ setMaximumLines()

void kanzi::TextLayouter::setMaximumLines ( unsigned int maximumLines )

Sets the maximum number of lines for a layout.

Parameters

maximumLines The maximum number of lines allowed in a layout.

◆ getMaximumLines()

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.

◆ setTerminator()

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

terminator Terminating string to use.

◆ getTerminator()

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.

◆ setHorizontalAlignment()

void kanzi::TextLayouter::setHorizontalAlignment ( TextFormat::TextHorizontalAlignment alignment )

Sets the horizontal alignment of the text.

Parameters

alignment Horizontal alignment to use.

◆ setVerticalAlignment()

void kanzi::TextLayouter::setVerticalAlignment ( TextFormat::TextVerticalAlignment alignment )

Sets the vertical alignment of the text.

Parameters

alignment Vertical alignment to use.

◆ setWhitespacePolicy()

void kanzi::TextLayouter::setWhitespacePolicy ( TextFormat::WhitespacePolicy whitespacePolicy )

Sets the whitespace policy of the text.

Parameters

whitespacePolicy The whitespace policy.

◆ setRemoveSideBearingsEnabled()

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

removeSideBearingsEnabled True to remove side bearings.

◆ getRemoveSideBearingsEnabled()

bool kanzi::TextLayouter::getRemoveSideBearingsEnabled ( ) const

Gets the setting for the side bearing removal of text.

Returns: True if side bearings removal is enabled.

◆ setWordWrap()

void kanzi::TextLayouter::setWordWrap ( bool wordWrapEnabled )

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

Parameters

wordWrapEnabled To wrap long lines of text into multiple lines, set to true. To keep the text in a single line, set to false.

◆ getWordWrap()

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.

◆ setTruncationDirection()

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

truncationDirection The part of the text truncation to set.

Since: Kanzi 3.9.6

◆ getTruncationDirection()

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

◆ setTruncation()

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

value The truncation boundary to set.

Since: Kanzi 3.9.6

◆ getTruncation()

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:

kanzi/core.ui/text/text_layouter.hpp

Classes

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ TextLayouter()

◆ ~TextLayouter()

Member Function Documentation

◆ createLayout()

◆ setMaximumWidth()

◆ getMaximumWidth()

◆ setMaximumCharactersPerLine()

◆ setMaximumHeight()

◆ getMaximumHeight()

◆ setMaximumLines()

◆ getMaximumLines()

◆ setTerminator()

◆ getTerminator()

◆ setHorizontalAlignment()

◆ setVerticalAlignment()

◆ setWhitespacePolicy()

◆ setRemoveSideBearingsEnabled()

◆ getRemoveSideBearingsEnabled()

◆ setWordWrap()

◆ getWordWrap()

◆ setTruncationDirection()

◆ getTruncationDirection()

◆ setTruncation()

◆ getTruncation()