Kanzi  3.9.9
Kanzi Engine C++ API
kanzi::TextFormat Class Reference

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 CharacterLayoutgetCharacterLayout (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...
 
TextLayoutgetLayout () 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:

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

Example

To render text:

  1. 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("...");
  2. 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);
  3. 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 requirements for using content texture change.
    // Calling updateRender() selects the material (shader) used for rendering.
    // After calling updateRender(), the brush may be used for rendering an arbitrary amount of times.
    brushRenderer->updateRender();
    // 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

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.

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.

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.

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.

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
domainThe domain to which the text format belongs.
fontFont used by the TextFormat.
widthWidth available.
heightHeight 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
rendererRenderer to use.
twoPassWhether to use two-pass rendering.
materialThe 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
rendererRenderer to use.
brushRendererBrush renderer to use for rendering the text.
twoPassWhether 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
alignmentHorizontal 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
alignmentVertical 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
whitespacePolicyThe 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
overflowTextOverflow 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
truncationDirectionThe 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
valueThe 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
removeSideBearingsEnabledTrue 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
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::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
maximumLinesThe 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
textText 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
indexIndex 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
unitScaleSize multiplier for the text.
offsetXOffset added to text x axis coordinates.
offsetYOffset 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
unitScaleSize multiplier for the text.
clippingRectangleMust be non-null for clipping to work.
offsetXOffset added to text x axis coordinates.
offsetYOffset 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
unitScaleSize multiplier for the text.
clippingRectangleMust be non-null for clipping to work.
offsetXOffset added to text x axis coordinates.
offsetYOffset 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
unitScaleSize multiplier for the text.
offsetXOffset added to text x axis coordinates.
offsetYOffset 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
unitScaleSize multiplier for the text.
clippingRectangleMust be non-null for clipping to work.
offsetXOffset added to text x axis coordinates.
offsetYOffset 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
unitScaleSize multiplier for the text.
clippingRectangleMust be non-null for clipping to work.
offsetXOffset added to text x axis coordinates.
offsetYOffset 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
clippingRectangleThe 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: