Text format combines the data required for text layouting and the data required for rendering the text. More...

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

Public Types
enum	TextHorizontalAlignment { TextHorizontalAlignmentLeft, TextHorizontalAlignmentRight, TextHorizontalAlignmentCenter }
	Horizontal alignment options for text layout. More...

enum	TextVerticalAlignment { TextVerticalAlignmentTop, TextVerticalAlignmentBaseline, TextVerticalAlignmentCenter, TextVerticalAlignmentBottom }
	Vertical alignment options for text layout. More...

enum	Truncation { Truncation::None, Truncation::AtCharacter, Truncation::AtWord }
	Type of truncation boundary for the text that does not fit in the available space. More...

enum	TruncationDirection { TruncationDirection::Trailing, TruncationDirection::Center, TruncationDirection::Leading }
	Part of the text to truncate, if the text does not fit in the available space. More...

enum	WhitespacePolicy { WhitespacePolicy::Keep, WhitespacePolicy::TrimTrailing }
	Policy applied on trailing or leading whitespaces. More...

Public Member Functions
void	calculateClipping (const RectangleFloat *clippingRectangle)
	Calculates clipped vertex coordinates from the bounding coordinates generated in the preparation function. More...

void	calculateLayout (string_view text)
	Calculates the layout for the given text. More...

void	draw (Renderer3D &renderer, bool twoPass, const Material &material)
	Renders text. More...

void	draw (Renderer3D &renderer, BrushRenderer &brushRenderer, bool twoPass)
	Renders text with a brush renderer that you pass to the function. More...

RectangleFloat	getBoundingRectangle () const
	Gets clipped bounding rectangle for text format. More...

unsigned int	getCharacterCount () const
	Gets the count of characters. More...

const CharacterLayout *	getCharacterLayout (unsigned int index) const
	Gets the layout structure of the given character. More...

FontRuntimeSharedPtr	getFont () const
	Gets the font of the text. More...

float	getFontSize () const
	Gets the font size of the text. More...

TextureSharedPtr	getGlyphTexture () const
	Gets the texture for rendering text format. More...

float	getHeight () const
	Gets the height in pixels of the area that the a text layout uses. More...

TextLayout *	getLayout () const
	Gets the text layout structure. More...

float	getMaximumHeight () const
	Gets the maximum height of the text. 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 of the text. More...

string_view	getOverflow () const
	Gets the text that is shown for the text that does not fit in the layout. More...

bool	getRemoveSideBearingsEnabled () const
	Gets the status of the side bearing removal enabled flag of the text. More...

TextHorizontalAlignment	getTextHorizontalAlignment () const
	Gets the horizontal alignment of the text. More...

TextVerticalAlignment	getTextVerticalAlignment () const
	Gets the vertical alignment of the text. More...

Truncation	getTruncation () const
	Returns the truncation boundary that Kanzi uses to truncate the text that does not fit in the text format. More...

TruncationDirection	getTruncationDirection () const
	Returns the truncation direction of the text format. More...

float	getUnitScale () const
	Gets the X-component of the unit scale used for generating the glyph run. More...

Vector2	getUnitScaleVector () const
	Gets the unit scale used for generating the glyph run. More...

WhitespacePolicy	getWhitespacePolicy () const
	Returns the whitespace policy of the text format. More...

float	getWidth () const
	Gets the width in pixels of the area that a text layout uses. More...

bool	getWordWrap () const
	Returns whether layout wraps into multiples lines the text that cannot fit into a single line. More...

bool	isPreparedForRendering () const
	Indicates whether Kanzi has prepared text for rendering. More...

bool	isTruncated () const
	Checks whether layouted text did not fit and was truncated. More...

void	prepareForRendering2D (float unitScale, float offsetX, float offsetY)
	Prepares a text layout for rendering in 2d space, where x axis coordinates increase to the right and y axis coordinates increase going downward. More...

void	prepareForRendering2DWithClipping (float unitScale, const RectangleFloat *clippingRectangle, float offsetX, float offsetY)
	Prepares a text layout for rendering in a bounded 2d space. More...

void	prepareForRendering2DWithClipping (Vector2 unitScale, const RectangleFloat *clippingRectangle, float offsetX, float offsetY)
	Prepares a text layout for rendering in a bounded 2d space. More...

void	prepareForRendering3D (float unitScale, float offsetX, float offsetY)
	Prepares a text layout for rendering in 3d space, where x axis coordinates increase to the right and y axis coordinates increase going upward. More...

void	prepareForRendering3DWithClipping (float unitScale, const RectangleFloat *clippingRectangle, float offsetX, float offsetY)
	Prepares a text layout for rendering in a bounded 3d space. More...

void	prepareForRendering3DWithClipping (Vector2 unitScale, const RectangleFloat *clippingRectangle, float offsetX, float offsetY)
	Prepares a text layout for rendering in a bounded 3d space. More...

void	setMaximumLines (unsigned int maximumLines)
	Sets the maximum number of lines for the layout. More...

void	setOverflow (string_view overflowText)
	Sets the text that is shown for the text that does not fit in the layout. More...

void	setRemoveSideBearingsEnabled (bool removeSideBearingsEnabled)
	Sets whether text side bearings removal is enabled. More...

void	setTextHorizontalAlignment (TextHorizontalAlignment alignment)
	Sets the horizontal alignment of the text. More...

void	setTextVerticalAlignment (TextVerticalAlignment alignment)
	Sets the vertical alignment of the text. More...

void	setTruncation (Truncation value)
	Sets the truncation boundary type for the text that does not fit in the text format. More...

void	setTruncationDirection (TruncationDirection truncationDirection)
	Sets the part of the text to truncate, if the text does not fit in the text format. More...

void	setWhitespacePolicy (WhitespacePolicy whitespacePolicy)
	Sets the whitespace policy of the text format. More...

void	setWordWrap (bool wordWrapEnabled)
	Sets whether layout wraps into multiple lines the text that cannot fit into a single line. More...

	~TextFormat ()
	Destructor. More...

Static Public Member Functions
static TextFormatPtr	create (Domain *domain, FontRuntimeSharedPtr font, float width, float height)
	Create a TextFormat. More...

Detailed Description

Text format combines the data required for text layouting and the data required for rendering the text.

You can use it to draw text on the screen.

To use TextFormat:

Create a text format. When you create a text format you pass the Font object and available size that you want to use.
Use the available setters to configure the text format according to your needs.
Lay out the text that you want to show using calculateLayout().
Prepare the text for rendering using either prepareForRendering2D() or prepareForRendering3D(), or their variants with clipping support.
If you used clipped versions of preparation functions, call calculateClipping().
Render the text to screen using draw().

Example

To render text:

Create a text format.
// Create a text format.
TextFormatPtr textFormat = TextFormat::create(domain, font, 150.0f, 24.0f);
// Before using text format, set the properties required by the text format.
textFormat->setTextHorizontalAlignment(TextFormat::TextHorizontalAlignmentCenter);
textFormat->setOverflow("...");
Lay out the text and prepare it for rendering.
// Calculate the layout for the text.
textFormat->calculateLayout("Sample text");
// Prepare the text format for rendering.
// If text is clipped, you must call both prepareForRenderingWithClipping and calculateClipping.
// When text changes, you must call both these functions again. When only the clipping rectangle
// changes, you must call only calculateClipping().
const RectangleFloat clippingRectangle(0.0f, -10.0f, 30.0f, 50.0f);
textFormat->prepareForRendering2DWithClipping(1.0f, &clippingRectangle, 0, 0);
textFormat->calculateClipping(&clippingRectangle);
Render the text.
Renderer3D* renderer3D = domain->getRenderer3D();
// Push the new composition state to the composition stack.
CompositionStack& compositionStack = renderer3D->getCompositionStack();
compositionStack.pushComposition(0, Vector2(SCREEN_WIDTH, SCREEN_HEIGHT));
// Apply the default composition state to the renderer.
compositionStack.apply2D(*renderer3D);
// Create a brush renderer for rendering the text.
ColorBrushSharedPtr brush = ColorBrush::create(domain, "colorBrush");
BrushRendererPtr brushRenderer = brush->createBrushRenderer(nullptr);
// Update the brush renderer for rendering.
// This must be called when brush properties change.
// After calling updateRender(), the brush may be used for rendering an arbitrary amount of times.
brushRenderer->updateRender(nullopt, true);
// To draw the text to the desired location, set the translation matrix transformation.
Renderer* renderer = renderer3D->getCoreRenderer();
renderer->setMatrix(FixedMatrixWorld, Matrix4x4::createTranslation(30.0f, 20.0f, 0.0f));
// Render the text.
textFormat->draw(*renderer3D, *brushRenderer, false);
// Clear the composition stack to the previous state.
compositionStack.popComposition();

Member Enumeration Documentation

enum kanzi::TextFormat::TextHorizontalAlignment

Horizontal alignment options for text layout.

Enumerator
TextHorizontalAlignmentLeft	Text is aligned to the left.
TextHorizontalAlignmentRight	Text is aligned to the right.
TextHorizontalAlignmentCenter	Text is centered horizontally.

enum kanzi::TextFormat::TextVerticalAlignment

Vertical alignment options for text layout.

Enumerator
TextVerticalAlignmentTop	Text is aligned to the top.
TextVerticalAlignmentBaseline	Text is aligned to the baseline of the first line of the text.
TextVerticalAlignmentCenter	Text is centered vertically.
TextVerticalAlignmentBottom	Text is aligned to the bottom.

enum kanzi::TextFormat::WhitespacePolicy

strong

Policy applied on trailing or leading whitespaces.

Enumerator
Keep	The trailing and leading whitespaces are kept intact in the formatted text.
TrimTrailing	Trims the trailing whitespaces from the formatted text.

enum kanzi::TextFormat::TruncationDirection

strong

Part of the text to truncate, if the text does not fit in the available space.

Since: Kanzi 3.9.6

Enumerator
Trailing	Truncate the end part of the text.
Center	Truncate the middle part of the text.
Leading	Truncate the beginning part of the text.

enum kanzi::TextFormat::Truncation

strong

Type of truncation boundary for the text that does not fit in the available space.

Since: Kanzi 3.9.6

Enumerator
None	Disable truncation.
AtCharacter	Truncate text character by character.
AtWord	Truncate text by entire words.

Constructor & Destructor Documentation

kanzi::TextFormat::~TextFormat ( )

Destructor.

Member Function Documentation

static TextFormatPtr kanzi::TextFormat::create	(	Domain *	domain,
		FontRuntimeSharedPtr	font,
		float	width,
		float	height
	)

static

Create a TextFormat.

Parameters

domain	The domain to which the text format belongs.
font	Font used by the TextFormat.
width	Width available.
height	Height available.

TextureSharedPtr kanzi::TextFormat::getGlyphTexture ( ) const

Gets the texture for rendering text format.

Returns: Glyph texture.

void kanzi::TextFormat::draw	(	Renderer3D &	renderer,
		bool	twoPass,
		const Material &	material
	)

Renders text.

Use this function to render with a brush or material renderer. This function expects that the shader and glyph texture are bound by brush or material renderer. Before you call this function, you must calculate the text layout and prepare the text format for rendering.

If you enable two-pass rendering, in the first pass the function writes color information with the depth write disabled and in the second pass writes the depth information with the color write disabled. Two-pass rendering is slower than one-pass rendering, but it is required to achieve the correct rendering result when glyph bounds are overlapping.

Parameters

renderer	Renderer to use.
twoPass	Whether to use two-pass rendering.
material	The material renderer to use for rendering the text.

See also: calculateLayout, prepareForRendering3D, prepareForRendering3DWithClipping, prepareForRendering2D, prepareForRendering2DWithClipping

void kanzi::TextFormat::draw	(	Renderer3D &	renderer,
		BrushRenderer &	brushRenderer,
		bool	twoPass
	)

Renders text with a brush renderer that you pass to the function.

Kanzi sets glyph texture of the text format as a context texture for the brushRenderer and binds the brushRenderer to a renderer before rendering the text. Before you call this function, you must calculate the text layout and prepare the text format for rendering.

If you enable two-pass rendering, in the first pass the function writes color information with the depth write disabled and in the second pass writes the depth information with the color write disabled. Two-pass rendering is slower than one-pass rendering, but it is required to achieve the correct rendering result when glyph bounds are overlapping.

Parameters

renderer	Renderer to use.
brushRenderer	Brush renderer to use for rendering the text.
twoPass	Whether to use two-pass rendering.

See also: calculateLayout, prepareForRendering3D, prepareForRendering3DWithClipping, prepareForRendering2D, prepareForRendering2DWithClipping

float kanzi::TextFormat::getMaximumWidth ( ) const

Gets the maximum width of the text.

Returns: Maximum width of the text.

float kanzi::TextFormat::getMaximumHeight ( ) const

Gets the maximum height of the text.

Returns: Maximum height of the text.

FontRuntimeSharedPtr kanzi::TextFormat::getFont ( ) const

Gets the font of the text.

Returns: Font of the text.

float kanzi::TextFormat::getFontSize ( ) const

Gets the font size of the text.

Returns: Font size of the text.

void kanzi::TextFormat::setTextHorizontalAlignment ( TextHorizontalAlignment alignment )

Sets the horizontal alignment of the text.

Parameters

alignment Horizontal alignment of the text.

TextHorizontalAlignment kanzi::TextFormat::getTextHorizontalAlignment ( ) const

Gets the horizontal alignment of the text.

Returns: Horizontal alignment of the text.

void kanzi::TextFormat::setTextVerticalAlignment ( TextVerticalAlignment alignment )

Sets the vertical alignment of the text.

Parameters

alignment Vertical alignment of the text.

TextVerticalAlignment kanzi::TextFormat::getTextVerticalAlignment ( ) const

Gets the vertical alignment of the text.

Returns: Vertical alignment of the text.

WhitespacePolicy kanzi::TextFormat::getWhitespacePolicy ( ) const

Returns the whitespace policy of the text format.

Returns: The whitespace policy. The default is WhitespacePolicy::Keep.

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

Sets the whitespace policy of the text format.

Parameters

whitespacePolicy The whitespace policy of the text format.

void kanzi::TextFormat::setOverflow ( string_view overflowText )

Sets the text that is shown for the text that does not fit in the layout.

Parameters

overflowText Overflow text.

string_view kanzi::TextFormat::getOverflow ( ) const

Gets the text that is shown for the text that does not fit in the layout.

Returns: Overflow text.

void kanzi::TextFormat::setTruncationDirection ( TruncationDirection truncationDirection )

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

Parameters

truncationDirection The truncation direction to set.

Since: Kanzi 3.9.6

TruncationDirection kanzi::TextFormat::getTruncationDirection ( ) const

Returns the truncation direction of the text format.

Returns: The truncation direction used by the text format.

Since: Kanzi 3.9.6

void kanzi::TextFormat::setTruncation ( Truncation value )

Sets the truncation boundary type for the text that does not fit in the text format.

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

Parameters

value The truncation boundary type to set.

Since: Kanzi 3.9.6

Truncation kanzi::TextFormat::getTruncation ( ) const

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

Returns: The truncation boundary type used by the text format.

Since: Kanzi 3.9.6

void kanzi::TextFormat::setRemoveSideBearingsEnabled ( bool removeSideBearingsEnabled )

Sets whether text side bearings removal is enabled.

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

Parameters

removeSideBearingsEnabled True to remove side bearings.

bool kanzi::TextFormat::getRemoveSideBearingsEnabled ( ) const

Gets the status of the side bearing removal enabled flag of the text.

Returns: If removal of side bearings is enabled, true.

void kanzi::TextFormat::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.

bool kanzi::TextFormat::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::TextFormat::setMaximumLines ( unsigned int maximumLines )

Sets the maximum number of lines for the layout.

Parameters

maximumLines The maximum number of lines allowed in the layout.

Since: Kanzi 3.9.0

unsigned int kanzi::TextFormat::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.

Since: Kanzi 3.9.0

void kanzi::TextFormat::calculateLayout ( string_view text )

Calculates the layout for the given text.

Parameters

text	Text for which the layout is calculated.

float kanzi::TextFormat::getWidth ( ) const

Gets the width in pixels of the area that a text layout uses.

You must calculate the text layout before calling this function.

Returns: Width of the layouted text.

float kanzi::TextFormat::getHeight ( ) const

Gets the height in pixels of the area that the a text layout uses.

You must calculate the text layout before calling this function.

Returns: Height of the layouted text.

const CharacterLayout* kanzi::TextFormat::getCharacterLayout ( unsigned int index ) const

Gets the layout structure of the given character.

You must calculate the text layout before calling this function.

Parameters

index Index of the character in the text format.

Returns: Layout structure for the given character.

TextLayout* kanzi::TextFormat::getLayout ( ) const

Gets the text layout structure.

You must calculate the text layout before calling this function.

Returns: Layout for the text.

unsigned int kanzi::TextFormat::getCharacterCount ( ) const

Gets the count of characters.

You must calculate the text layout before calling this function.

Returns: Character count.

float kanzi::TextFormat::getUnitScale ( ) const

inline

Gets the X-component of the unit scale used for generating the glyph run.

Returns: Unit scale X-component for the glyph run.

Vector2 kanzi::TextFormat::getUnitScaleVector ( ) const

inline

Gets the unit scale used for generating the glyph run.

Returns: Unit scale for the glyph run.

bool kanzi::TextFormat::isPreparedForRendering ( ) const

Indicates whether Kanzi has prepared text for rendering.

To prepare text for rendering, lay out the text and then call one of the prepareForRendering functions.

Returns: If the text is prepared for rendering, true.

See also: prepareForRendering3D, prepareForRendering3DWithClipping, prepareForRendering2D, prepareForRendering2DWithClipping

bool kanzi::TextFormat::isTruncated ( ) const

Checks whether layouted text did not fit and was truncated.

You must calculate the text layout before calling this function.

Returns: If the text is truncated, true.

void kanzi::TextFormat::prepareForRendering3D	(	float	unitScale,
		float	offsetX,
		float	offsetY
	)

Prepares a text layout for rendering in 3d space, where x axis coordinates increase to the right and y axis coordinates increase going upward.

The z coordinate of the text is always 0.0f. The pixel size of the text font is multiplied by the scale to get the size of the text in the 3d space.

Parameters

unitScale	Size multiplier for the text.
offsetX	Offset added to text x axis coordinates.
offsetY	Offset added to text y axis coordinates.

void kanzi::TextFormat::prepareForRendering3DWithClipping	(	float	unitScale,
		const RectangleFloat *	clippingRectangle,
		float	offsetX,
		float	offsetY
	)

Prepares a text layout for rendering in a bounded 3d space.

Generates unclipped vertex positions and bounding box coordinates for the clipping function to use.

Parameters

unitScale	Size multiplier for the text.
clippingRectangle	Must be non-null for clipping to work.
offsetX	Offset added to text x axis coordinates.
offsetY	Offset added to text y axis coordinates.

void kanzi::TextFormat::prepareForRendering3DWithClipping	(	Vector2	unitScale,
		const RectangleFloat *	clippingRectangle,
		float	offsetX,
		float	offsetY
	)

Prepares a text layout for rendering in a bounded 3d space.

Generates unclipped vertex positions and bounding box coordinates for the clipping function to use.

Parameters

unitScale	Size multiplier for the text.
clippingRectangle	Must be non-null for clipping to work.
offsetX	Offset added to text x axis coordinates.
offsetY	Offset added to text y axis coordinates.

void kanzi::TextFormat::prepareForRendering2D	(	float	unitScale,
		float	offsetX,
		float	offsetY
	)

Prepares a text layout for rendering in 2d space, where x axis coordinates increase to the right and y axis coordinates increase going downward.

The pixel size of the text font is multiplied by the scale to get the size of the text in the 2d space.

Parameters

unitScale	Size multiplier for the text.
offsetX	Offset added to text x axis coordinates.
offsetY	Offset added to text y axis coordinates.

void kanzi::TextFormat::prepareForRendering2DWithClipping	(	float	unitScale,
		const RectangleFloat *	clippingRectangle,
		float	offsetX,
		float	offsetY
	)

Prepares a text layout for rendering in a bounded 2d space.

Generates unclipped vertex positions and bounding box coordinates for the clipping function to use.

Parameters

unitScale	Size multiplier for the text.
clippingRectangle	Must be non-null for clipping to work.
offsetX	Offset added to text x axis coordinates.
offsetY	Offset added to text y axis coordinates.

void kanzi::TextFormat::prepareForRendering2DWithClipping	(	Vector2	unitScale,
		const RectangleFloat *	clippingRectangle,
		float	offsetX,
		float	offsetY
	)

Prepares a text layout for rendering in a bounded 2d space.

Generates unclipped vertex positions and bounding box coordinates for the clipping function to use.

Parameters

unitScale	Size multiplier for the text.
clippingRectangle	Must be non-null for clipping to work.
offsetX	Offset added to text x axis coordinates.
offsetY	Offset added to text y axis coordinates.

void kanzi::TextFormat::calculateClipping ( const RectangleFloat * clippingRectangle )

Calculates clipped vertex coordinates from the bounding coordinates generated in the preparation function.

Characters that are outside the bounded area are clipped completely, and characters that are on the border of area are clipped so that only part of the character is visible.

Parameters

clippingRectangle The bounds to which the text is clipped.

RectangleFloat kanzi::TextFormat::getBoundingRectangle ( ) const

Gets clipped bounding rectangle for text format.

You must prepare the text format for rendering before calling this function.

Returns: Bounding rectangle for the text.

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

kanzi/core.ui/text/text_format.hpp

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Example

Member Enumeration Documentation

Constructor & Destructor Documentation

Member Function Documentation