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 class | Truncation { None , AtCharacter , AtWord } |
Type of truncation boundary for the text that does not fit in the available space. More... | |
enum class | TruncationDirection { Trailing , Center , Leading } |
Part of the text to truncate, if the text does not fit in the available space. More... | |
enum class | WhitespacePolicy { Keep , 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. | |
void | calculateLayout (string_view text) |
Calculates the layout for the given text. | |
void | draw (Renderer3D &renderer, bool twoPass, const Material &material) |
Renders text. | |
void | draw (Renderer3D &renderer, BrushRenderer &brushRenderer, bool twoPass) |
Renders text with a brush renderer that you pass to the function. | |
RectangleFloat | getBoundingRectangle () const |
Gets clipped bounding rectangle for text format. | |
unsigned int | getCharacterCount () const |
Gets the count of characters. | |
const CharacterLayout * | getCharacterLayout (unsigned int index) const |
Gets the layout structure of the given character. | |
FontRuntimeSharedPtr | getFont () const |
Gets the font of the text. | |
float | getFontSize () const |
Gets the font size of the text. | |
TextureSharedPtr | getGlyphTexture () const |
Gets the texture for rendering text format. | |
float | getHeight () const |
Gets the height in pixels of the area that the a text layout uses. | |
TextLayout * | getLayout () const |
Gets the text layout structure. | |
float | getMaximumHeight () const |
Gets the maximum height of the text. | |
unsigned int | getMaximumLines () const |
Gets the maximum number of lines of text that a layout accepts. | |
float | getMaximumWidth () const |
Gets the maximum width of the text. | |
string_view | getOverflow () const |
Gets the text that is shown for the text that does not fit in the layout. | |
bool | getRemoveSideBearingsEnabled () const |
Gets the status of the side bearing removal enabled flag of the text. | |
TextHorizontalAlignment | getTextHorizontalAlignment () const |
Gets the horizontal alignment of the text. | |
TextVerticalAlignment | getTextVerticalAlignment () const |
Gets the vertical alignment of the text. | |
Truncation | getTruncation () const |
Returns the truncation boundary that Kanzi uses to truncate the text that does not fit in the text format. | |
TruncationDirection | getTruncationDirection () const |
Returns the truncation direction of the text format. | |
float | getUnitScale () const |
Gets the X-component of the unit scale used for generating the glyph run. | |
Vector2 | getUnitScaleVector () const |
Gets the unit scale used for generating the glyph run. | |
WhitespacePolicy | getWhitespacePolicy () const |
Returns the whitespace policy of the text format. | |
float | getWidth () const |
Gets the width in pixels of the area that a text layout uses. | |
bool | getWordWrap () const |
Returns whether layout wraps into multiples lines the text that cannot fit into a single line. | |
bool | isPreparedForRendering () const |
Indicates whether Kanzi has prepared text for rendering. | |
bool | isTruncated () const |
Checks whether layouted text did not fit and was truncated. | |
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. | |
void | prepareForRendering2DWithClipping (float unitScale, const RectangleFloat *clippingRectangle, float offsetX, float offsetY) |
Prepares a text layout for rendering in a bounded 2d space. | |
void | prepareForRendering2DWithClipping (Vector2 unitScale, const RectangleFloat *clippingRectangle, float offsetX, float offsetY) |
Prepares a text layout for rendering in a bounded 2d space. | |
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. | |
void | prepareForRendering3DWithClipping (float unitScale, const RectangleFloat *clippingRectangle, float offsetX, float offsetY) |
Prepares a text layout for rendering in a bounded 3d space. | |
void | prepareForRendering3DWithClipping (Vector2 unitScale, const RectangleFloat *clippingRectangle, float offsetX, float offsetY) |
Prepares a text layout for rendering in a bounded 3d space. | |
void | setMaximumLines (unsigned int maximumLines) |
Sets the maximum number of lines for the layout. | |
void | setOverflow (string_view overflowText) |
Sets the text that is shown for the text that does not fit in the layout. | |
void | setRemoveSideBearingsEnabled (bool removeSideBearingsEnabled) |
Sets whether text side bearings removal is enabled. | |
void | setTextHorizontalAlignment (TextHorizontalAlignment alignment) |
Sets the horizontal alignment of the text. | |
void | setTextVerticalAlignment (TextVerticalAlignment alignment) |
Sets the vertical alignment of the text. | |
void | setTruncation (Truncation value) |
Sets the truncation boundary type for the text that does not fit in the text format. | |
void | setTruncationDirection (TruncationDirection truncationDirection) |
Sets the part of the text to truncate, if the text does not fit in the text format. | |
void | setWhitespacePolicy (WhitespacePolicy whitespacePolicy) |
Sets the whitespace policy of the text format. | |
void | setWordWrap (bool wordWrapEnabled) |
Sets whether layout wraps into multiple lines the text that cannot fit into a single line. | |
~TextFormat () | |
Destructor. | |
Static Public Member Functions | |
static TextFormatPtr | create (Domain *domain, FontRuntimeSharedPtr font, float width, float height) |
Create a TextFormat. | |
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:
To render text:
Vertical alignment options for text layout.
kanzi::TextFormat::~TextFormat | ( | ) |
Destructor.
|
static |
Create a TextFormat.
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.
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.
renderer | Renderer to use. |
twoPass | Whether to use two-pass rendering. |
material | The material renderer to use for rendering the text. |
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.
float kanzi::TextFormat::getMaximumWidth | ( | ) | const |
Gets the maximum width of the text.
float kanzi::TextFormat::getMaximumHeight | ( | ) | const |
Gets the maximum height of the text.
FontRuntimeSharedPtr kanzi::TextFormat::getFont | ( | ) | const |
Gets the font of the text.
float kanzi::TextFormat::getFontSize | ( | ) | const |
Gets the font size of the text.
void kanzi::TextFormat::setTextHorizontalAlignment | ( | TextHorizontalAlignment | alignment | ) |
Sets the horizontal alignment of the text.
alignment | Horizontal alignment of the text. |
TextHorizontalAlignment kanzi::TextFormat::getTextHorizontalAlignment | ( | ) | const |
Gets the horizontal alignment of the text.
void kanzi::TextFormat::setTextVerticalAlignment | ( | TextVerticalAlignment | alignment | ) |
Sets the vertical alignment of the text.
alignment | Vertical alignment of the text. |
TextVerticalAlignment kanzi::TextFormat::getTextVerticalAlignment | ( | ) | const |
Gets the vertical alignment of the text.
WhitespacePolicy kanzi::TextFormat::getWhitespacePolicy | ( | ) | const |
Returns the whitespace policy of the text format.
void kanzi::TextFormat::setWhitespacePolicy | ( | WhitespacePolicy | whitespacePolicy | ) |
Sets the whitespace policy of the text format.
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.
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.
void kanzi::TextFormat::setTruncationDirection | ( | TruncationDirection | truncationDirection | ) |
Sets the part of the text to truncate, if the text does not fit in the text format.
truncationDirection | The truncation direction to set. |
TruncationDirection kanzi::TextFormat::getTruncationDirection | ( | ) | const |
Returns the truncation direction of the text format.
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.
value | The truncation boundary type to set. |
Truncation kanzi::TextFormat::getTruncation | ( | ) | const |
Returns the truncation boundary that Kanzi uses to truncate the text that does not fit in the text format.
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.
removeSideBearingsEnabled | True to remove side bearings. |
bool kanzi::TextFormat::getRemoveSideBearingsEnabled | ( | ) | const |
Gets the status of the side bearing removal enabled flag of the text.
Sets whether layout wraps into multiple lines the text that cannot fit into a single line.
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.
Sets the maximum number of lines for the layout.
maximumLines | The maximum number of lines allowed in the layout. |
Gets the maximum number of lines of text that a layout accepts.
void kanzi::TextFormat::calculateLayout | ( | string_view | text | ) |
Calculates the layout for the given text.
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.
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.
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.
index | Index of the character in the text format. |
TextLayout * kanzi::TextFormat::getLayout | ( | ) | const |
Gets the text layout structure.
You must calculate the text layout before calling this function.
Gets the count of characters.
You must calculate the text layout before calling this function.
|
inline |
Gets the X-component of the unit scale used for generating the glyph run.
|
inline |
Gets the unit scale used for generating 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.
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.
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.
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.
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.
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. |
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.
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.
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.
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.
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.