Text layouter is used for laying out text to a constrained area. More...

#include <system/debug/kzs_error.h>
#include <system/kzs_types.h>
#include <system/kzs_header.h>

Enumerations
enum	KzuTextHorizontalAlignment { KZU_TEXT_HORIZONTAL_ALIGNMENT_LEFT, KZU_TEXT_HORIZONTAL_ALIGNMENT_RIGHT, KZU_TEXT_HORIZONTAL_ALIGNMENT_CENTER }
	Horizontal alignment options for text layout. More...

enum	KzuTextVerticalAlignment { KZU_TEXT_VERTICAL_ALIGNMENT_TOP, KZU_TEXT_VERTICAL_ALIGNMENT_BASELINE, KZU_TEXT_VERTICAL_ALIGNMENT_CENTER, KZU_TEXT_VERTICAL_ALIGNMENT_BOTTOM }
	Vertical alignment options for text layout. More...

Functions
kzsError	kzuTextLayouterCreate (const struct KzcMemoryManager memoryManager, struct KzuFont font, struct KzuTextLayouter **out_textLayouter)
	Creates a text layouter with the given font. More...

kzsError	kzuTextLayouterDelete (struct KzuTextLayouter *textLayouter)
	Deletes the text layouter. More...

void	kzuTextLayouterSetMaximumWidth (struct KzuTextLayouter *textLayouter, kzFloat width)
	Sets the maximum width in pixels for the text layout area. More...

void	kzuTextLayouterSetMaximumCharactersPerLine (struct KzuTextLayouter *textLayouter, kzUint charactersPerLine)
	Sets the maximum number of characters per line for the text layout area. More...

void	kzuTextLayouterSetMaximumHeight (struct KzuTextLayouter *textLayouter, kzFloat height)
	Sets the maximum height in pixels for the layout. More...

void	kzuTextLayouterSetMaximumLines (struct KzuTextLayouter *textLayouter, kzUint maximumLines)
	Sets the maximum number of lines for the layout. More...

kzsError	kzuTextLayouterSetTerminator (struct KzuTextLayouter *textLayouter, kzString terminator)
	Sets the terminator string used when both horizontal and vertical space is running out for the text layout. More...

void	kzuTextLayouterSetHorizontalAlignment (struct KzuTextLayouter *textLayouter, enum KzuTextHorizontalAlignment alignment)
	Sets the horizontal alignment of the text. More...

void	kzuTextLayouterSetVerticalAlignment (struct KzuTextLayouter *textLayouter, enum KzuTextVerticalAlignment alignment)
	Sets the vertical alignment of the text. More...

void	kzuTextLayouterSetLineSpacing (struct KzuTextLayouter *textLayouter, kzFloat lineSpacing)
	Sets the line spacing. More...

void	kzuTextLayouterSetCharacterSpacing (struct KzuTextLayouter *textLayouter, kzFloat characterSpacing)
	Sets the character spacing. More...

void	kzuTextLayouterSetFixedCharacterWidth (struct KzuTextLayouter *textLayouter, kzFloat fixedCharacterWidth)
	Sets the fixed character width. More...

void	kzuTextLayouterDisableFixedCharacterWidth (struct KzuTextLayouter *textLayouter)
	Disables the fixed character width. More...

void	kzuTextLayouterSetBidiShapingEnabled (struct KzuTextLayouter *textLayouter, kzBool bidiShapingEnabled)
	Sets whether support for complex scripts is enabled. More...

kzsError	kzuTextLayouterCreateLayout (const struct KzuTextLayouter textLayouter, const struct KzcMemoryManager memoryManager, kzString text, struct KzuTextLayout **out_textLayout)
	Lays out the given text using the given text layouter. More...

kzsError	kzuTextLayouterDrawText (const struct KzuTextLayouter textLayouter, const struct KzcMemoryManager memoryManager, struct KzcRenderer *renderer, kzString text, kzFloat x, kzFloat y)
	Helper function for performing the layout and drawing the result on the screen. More...

kzsError	kzuTextLayouterDrawText3D (const struct KzuTextLayouter textLayouter, const struct KzcMemoryManager memoryManager, struct KzcRenderer *renderer, kzString text)
	Helper function for performing the layout and drawing the result to 3D space. More...

struct KzuFont *	kzuTextLayoutGetFont (const struct KzuTextLayout *textLayout)
	Gets the font used for the text layout. More...

kzsError	kzuTextLayoutDelete (struct KzuTextLayout *textLayout)
	Deletes the text layout. More...

Detailed Description

Text layouter is used for laying out text to a constrained area.

The text is splitted to several lines when necessary.

Below is a common use scenario for the text layouting. initialization: result = kzuBasicTextLayouterCreate(memoryManager, font, &textLayouter); kzsErrorForward(result);

Optionally set text layout parameters such as alignment and maximum bounds

when the text has changed or in initialization for static text: result = kzuTextLayouterCreateLayout(textLayouter, memoryManager, text, &textLayout); kzsErrorForward(result);

result = kzuFontPrepareTextLayout(textLayout, renderer); kzsErrorForward(result);

rendering: result = kzuFontDrawTextLayout(textLayout, renderer, x, y); kzsErrorForward(result);

uninitialization: result = kzuTextLayoutDelete(textLayout); kzsErrorForward(result);

result = kzuTextLayouterDelete(textLayouter); kzsErrorForward(result); Text layouter can also be deleted already right after the text layout is created.

Enumeration Type Documentation

enum KzuTextHorizontalAlignment

Horizontal alignment options for text layout.

Enumerator
KZU_TEXT_HORIZONTAL_ALIGNMENT_LEFT	Text is aligned right.
KZU_TEXT_HORIZONTAL_ALIGNMENT_RIGHT	Text is aligned left.
KZU_TEXT_HORIZONTAL_ALIGNMENT_CENTER	Text is centered horizontally.

enum KzuTextVerticalAlignment

Vertical alignment options for text layout.

Enumerator
KZU_TEXT_VERTICAL_ALIGNMENT_TOP	Text is aligned top.
KZU_TEXT_VERTICAL_ALIGNMENT_BASELINE	Text is aligned on the baseline of the first line of text.
KZU_TEXT_VERTICAL_ALIGNMENT_CENTER	Text is centered vertically.
KZU_TEXT_VERTICAL_ALIGNMENT_BOTTOM	Text is aligned bottom.

Function Documentation

kzsError kzuTextLayouterCreate	(	const struct KzcMemoryManager *	memoryManager,
		struct KzuFont *	font,
		struct KzuTextLayouter **	out_textLayouter
	)

Creates a text layouter with the given font.

kzsError kzuTextLayouterDelete ( struct KzuTextLayouter * textLayouter)

Deletes the text layouter.

void kzuTextLayouterSetMaximumWidth	(	struct KzuTextLayouter *	textLayouter,
		kzFloat	width
	)

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

Note that at least one character per line will always be layouted. Use KZS_INFINITY for unlimited width.

void kzuTextLayouterSetMaximumCharactersPerLine	(	struct KzuTextLayouter *	textLayouter,
		kzUint	charactersPerLine
	)

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

void kzuTextLayouterSetMaximumHeight	(	struct KzuTextLayouter *	textLayouter,
		kzFloat	height
	)

Sets the maximum height in pixels for the layout.

Note that at least one line will always be layouted. Use KZS_INFINITY for unlimited height.

void kzuTextLayouterSetMaximumLines	(	struct KzuTextLayouter *	textLayouter,
		kzUint	maximumLines
	)

Sets the maximum number of lines for the layout.

kzsError kzuTextLayouterSetTerminator	(	struct KzuTextLayouter *	textLayouter,
		kzString	terminator
	)

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

void kzuTextLayouterSetHorizontalAlignment	(	struct KzuTextLayouter *	textLayouter,
		enum KzuTextHorizontalAlignment	alignment
	)

Sets the horizontal alignment of the text.

void kzuTextLayouterSetVerticalAlignment	(	struct KzuTextLayouter *	textLayouter,
		enum KzuTextVerticalAlignment	alignment
	)

Sets the vertical alignment of the text.

void kzuTextLayouterSetLineSpacing	(	struct KzuTextLayouter *	textLayouter,
		kzFloat	lineSpacing
	)

Sets the line spacing.

The value is relative to the font height, for example 1 is normal spacing and 2 is double spacing.

void kzuTextLayouterSetCharacterSpacing	(	struct KzuTextLayouter *	textLayouter,
		kzFloat	characterSpacing
	)

Sets the character spacing.

The value is relative to the character advance, for example 1 is the normal advance and 2 is double advance.

void kzuTextLayouterSetFixedCharacterWidth	(	struct KzuTextLayouter *	textLayouter,
		kzFloat	fixedCharacterWidth
	)

Sets the fixed character width.

void kzuTextLayouterDisableFixedCharacterWidth ( struct KzuTextLayouter * textLayouter)

Disables the fixed character width.

void kzuTextLayouterSetBidiShapingEnabled	(	struct KzuTextLayouter *	textLayouter,
		kzBool	bidiShapingEnabled
	)

Sets whether support for complex scripts is enabled.

This includes support for bi-directional text and languages that require ligatures.

kzsError kzuTextLayouterCreateLayout	(	const struct KzuTextLayouter *	textLayouter,
		const struct KzcMemoryManager *	memoryManager,
		kzString	text,
		struct KzuTextLayout **	out_textLayout
	)

Lays out the given text using the given text layouter.

The returned text layout can be directly rendered with the associated font or the layout information can be read from the structure.

kzsError kzuTextLayouterDrawText	(	const struct KzuTextLayouter *	textLayouter,
		const struct KzcMemoryManager *	memoryManager,
		struct KzcRenderer *	renderer,
		kzString	text,
		kzFloat	x,
		kzFloat	y
	)

Helper function for performing the layout and drawing the result on the screen.

If the same text is rendered more than once, the layout and drawing should be done separately. Parameters x and y specifies where the text layout is drawn and depends on the specified alignments of the text layouter.

kzsError kzuTextLayouterDrawText3D	(	const struct KzuTextLayouter *	textLayouter,
		const struct KzcMemoryManager *	memoryManager,
		struct KzcRenderer *	renderer,
		kzString	text
	)

Helper function for performing the layout and drawing the result to 3D space.

If the same text is rendered more than once, the layout and drawing should be done separately.

struct KzuFont* kzuTextLayoutGetFont ( const struct KzuTextLayout * textLayout)

Gets the font used for the text layout.

kzsError kzuTextLayoutDelete ( struct KzuTextLayout * textLayout)

Deletes the text layout.

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

Function Documentation