TSdlTtfText
A text string to render with a TTF text engine. Note that this object works with 8-bit UTF-8 strings instead of 16-bit Unicode strings.
Definition
Unit: Neslib.Sdl3.Ttf
Properties
| Name | Description |
|---|---|
| Color | The color of the text object. |
| ColorFloat | The color of the text object. |
| Direction | The direction to be used for text shaping this text object. |
| Engine | The text engine used by this text object. |
| Font | The font used by the text object. |
| IsWrapWhitespaceVisible | Whether whitespace should be visible when wrapping the text object. |
| NumLines | The number of lines in the text, 0 if it's empty |
| Position | The position of the text object. |
| Properties | The properties associated with this text object. |
| Script | The script to be used for text shaping the text object, as an ISO 15924 code. |
| Size | The size of a text object, in pixels. |
| Text | The text this object represents, useful for layout, debugging and retrieving substring text. This is updated when the text object is modified. |
| WrapWidth | Controls wrapping for this text object. |
Operators
| Name | Description |
|---|---|
| Equal(TSdlTtfText, TSdlTtfText) | Used to compare against another TSdlTtfText. |
| Equal(TSdlTtfText, Pointer) | Used to compare against nil. |
| Implicit | Used to set the value to nil. |
| NotEqual(TSdlTtfText, TSdlTtfText) | Used to compare against another TSdlTtfText. |
| NotEqual(TSdlTtfText, Pointer) | Used to compare against nil. |
Methods
| Name | Description |
|---|---|
| Append | Append text to the text object. |
| Delete | Delete text from the text object. |
| Free | Destroy this text object. |
| GetGpuDrawData | Get the geometry data needed for drawing the text. |
| Insert | Insert text into the text object. |
| NextSubString | Get the next substring in the text object |
| PreviousSubString | Get the previous substring in the text object |
| SetColor | Set the color of the text object. |
| SetColorFloat | Set the color of the text object. |
| SetPosition | Set the position of the text object. |
| SubString | Get the substring of the text object that surrounds a text offset. |
| SubStringForLine | Get the substring of the text object that contains the given line. |
| SubStringForPoint(TSdlPoint) | Get the portion of a text string that is closest to a point. |
| SubStringForPoint(Integer, Integer) | Get the portion of a text string that is closest to a point. |
| SubStringsForRange | Get the substrings of a text object that contain a range of text. |
| Update | Update the layout of a text object. |
Property Descriptions
Color
The color of the text object.
The default text color is white (255, 255, 255, 255).
property Color: TSdlColor read GetColor write SetColor
Type: TSdlColor
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should be used on the thread that created the text.
ColorFloat
The color of the text object.
The default text color is white (1.0, 1.0, 1.0, 1.0).
property ColorFloat: TSdlColorF read GetColorFloat write SetColorFloat
Type: TSdlColorF
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should be used on the thread that created the text.
Direction
The direction to be used for text shaping this text object.
This defaults to the direction of the font used by the text object.
This property only supports left-to-right text shaping if SDL_ttf was not built with HarfBuzz support.
property Direction: TSdlTtfDirection read GetDirection write SetDirection
Type: TSdlTtfDirection
Exceptions
ESdlError: Raised on failure.
Remarks
This property should be used on the thread that created the text.
Engine
The text engine used by this text object.
Updating this property may cause the internal text representation to be rebuilt.
property Engine: TSdlTtfTextEngine read GetEngine write SetEngine
Type: TSdlTtfTextEngine
Exceptions
ESdlError: Raised on failure.
Remarks
This property should be used on the thread that created the text.
Font
The font used by the text object.
When a text object has a font, any changes to the font will automatically regenerate the text. If you set the font to nil, the text will continue to render but changes to the font will no longer affect the text.
Updating this property may cause the internal text representation to be rebuilt.
property Font: TSdlTtfFont read GetFont write SetFont
Type: TSdlTtfFont
Exceptions
ESdlError: Raised on failure.
Remarks
This property should be used on the thread that created the text.
IsWrapWhitespaceVisible
Whether whitespace should be visible when wrapping the text object.
If the whitespace is visible, it will take up space for purposes of alignment and wrapping. This is good for editing, but looks better when centered or aligned if whitespace around line wrapping is hidden. This defaults False.
Updating this property may cause the internal text representation to be rebuilt.
property IsWrapWhitespaceVisible: Boolean read GetIsWrapWhitespaceVisible write SetIsWrapWhitespaceVisible
Type: Boolean
Exceptions
ESdlError: Raised on failure.
Remarks
This property should be used on the thread that created the text.
NumLines
The number of lines in the text, 0 if it's empty
property NumLines: Integer read GetNumLines
Type: Integer
Position
The position of the text object.
This can be used to position multiple text objects within a single wrapping text area.
Updating this property may cause the internal text representation to be rebuilt.
property Position: TSdlPoint read GetPosition write SetPosition
Type: TSdlPoint
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should be used on the thread that created the text.
Properties
The properties associated with this text object.
property Properties: TSdlProperties read GetProperties
Type: TSdlProperties
Exceptions
ESdlError: Raised on failure.
Remarks
This property should be used on the thread that created the text.
Script
The script to be used for text shaping the text object, as an ISO 15924 code.
This defaults to the script of the font used by the text object. Returns 0 if a script hasn't been set on either the text object or the font.
Fails if SDL_ttf isn't built with HarfBuzz support.
property Script: Cardinal read GetScript write SetScript
Type: Cardinal
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should be used on the thread that created the text.
Size
The size of a text object, in pixels.
The size of the text may change when the font or font style and size change.
property Size: TSdlSize read GetSize
Type: TSdlSize
Exceptions
ESdlError: Raised on failure.
Remarks
This property should be used on the thread that created the text.
Text
The text this object represents, useful for layout, debugging and retrieving substring text. This is updated when the text object is modified.
Updating this property may cause the internal text representation to be rebuilt.
property Text: UTF8String read GetText write SetText
Type: UTF8String
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should be used on the thread that created the text.
WrapWidth
Controls wrapping for this text object.
Set to 0 to wrap on newline characters only, or a value > 0 to set the maximum width in pixels.
Updating this property may cause the internal text representation to be rebuilt.
property WrapWidth: Integer read GetWrapWidth write SetWrapWidth
Type: Integer
Exceptions
ESdlError: Raised on failure.
Remarks
This property should be used on the thread that created the text.
Operator Descriptions
Equal(TSdlTtfText, TSdlTtfText)
Used to compare against another TSdlTtfText.
class operator Equal(const ALeft, ARight: TSdlTtfText): Boolean; inline; static
Parameters
ALeft: TSdlTtfText
ARight: TSdlTtfText
Returns
Boolean
Equal(TSdlTtfText, Pointer)
Used to compare against nil.
class operator Equal(const ALeft: TSdlTtfText; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlTtfText
ARight: Pointer
Returns
Boolean
Implicit(Pointer)
Used to set the value to nil.
class operator Implicit(const AValue: Pointer): TSdlTtfText; inline; static
Parameters
AValue: Pointer
Returns
NotEqual(TSdlTtfText, TSdlTtfText)
Used to compare against another TSdlTtfText.
class operator NotEqual(const ALeft, ARight: TSdlTtfText): Boolean; inline; static
Parameters
ALeft: TSdlTtfText
ARight: TSdlTtfText
Returns
Boolean
NotEqual(TSdlTtfText, Pointer)
Used to compare against nil.
class operator NotEqual(const ALeft: TSdlTtfText; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlTtfText
ARight: Pointer
Returns
Boolean
Method Descriptions
Append(UTF8String)
Append text to the text object.
This method may cause the internal text representation to be rebuilt.
procedure Append(const AString: UTF8String); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AString: UTF8String
: The text to insert.
See Also
Remarks
This method should be called on the thread that created the text.
Delete(Integer, Integer)
Delete text from the text object.
This method may cause the internal text representation to be rebuilt.
procedure Delete(const AOffset, ALength: Integer); inline
Parameters
AOffset: Integer
: The offset, in bytes (8-bit UTF-8 characters), from the beginning of the string if >= 0, the offset from the end of the string if
ALength: Integer
Free
Destroy this text object.
procedure Free; inline
Remarks
This method should be called on the thread that created the text.
GetGpuDrawData
Get the geometry data needed for drawing the text.
This text must have been created using a TSdlTtfGpuTextEngine.
The positive X-axis is taken towards the right and the positive Y-axis is taken upwards for both the vertex and the texture coordinates, i.e, it follows the same convention used by the SDL_GPU API. If you want to use a different coordinate system you will need to transform the vertices yourself.
If the text looks blocky use linear filtering.
function GetGpuDrawData: TSdlTtfGpuAtlasDrawSequence; inline
Exceptions
ESdlError: Raised on failure.
Returns
TSdlTtfGpuAtlasDrawSequence: A nil terminated linked list of TSdlTtfGpuAtlasDrawSequence or nil if the passed text is empty.
Remarks
This method should be called on the thread that created the text.
Insert(Integer, UTF8String)
Insert text into the text object.
This method may cause the internal text representation to be rebuilt.
procedure Insert(const AOffset: Integer; const AString: UTF8String); inline
Parameters
AOffset: Integer
: Offset, in bytes (8-bit UTF-8 characters), from the beginning of the string if >= 0, the offset from the end of the string if
AString: UTF8String
NextSubString(TSdlTtfSubString)
Get the next substring in the text object
If called at the end of the text, this will return a zero length substring with the TSdlTtfSubStringFlag.TextEnd flag set.
function NextSubString(const ASubString: TSdlTtfSubString): TSdlTtfSubString; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ASubString: TSdlTtfSubString
: The substring to query.
Returns
TSdlTtfSubString: The substring after ASubString.
Remarks
This method should be called on the thread that created the text.
PreviousSubString(TSdlTtfSubString)
Get the previous substring in the text object
If called at the start of the text, this will return a zero length substring with the TSdlTtfSubStringFlag.TextStart flag set.
function PreviousSubString(const ASubString: TSdlTtfSubString): TSdlTtfSubString; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ASubString: TSdlTtfSubString
: The substring to query.
Returns
TSdlTtfSubString: The substring before ASubString.
Remarks
This method should be called on the thread that created the text.
SetColor(Byte, Byte, Byte, Byte)
Set the color of the text object.
The default text color is white (255, 255, 255, 255).
procedure SetColor(const AR, AG, AB: Byte; const AA: Byte = 255); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AR: Byte
: The red color value in the range of 0-255.
AG: Byte
: The green color value in the range of 0-255.
AB: Byte
: The blue color value in the range of 0-255.
AA: Byte = 255
: (Optional) alpha value in the range of 0-255. Defaults to 255.
See Also
Remarks
This method should be called on the thread that created the text.
SetColorFloat(Single, Single, Single, Single)
Set the color of the text object.
The default text color is white (1.0, 1.0, 1.0, 1.0).
procedure SetColorFloat(const AR, AG, AB: Single; const AA: Single = 1); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AR: Single
: The red color value, normally in the range of 0-1.
AG: Single
: The green color value, normally in the range of 0-1.
AB: Single
: The blue color value, normally in the range of 0-1.
AA: Single = 1
: (Optional) alpha value in the range of 0-1. Defaults to 1.
See Also
Remarks
This method should be called on the thread that created the text.
SetPosition(Integer, Integer)
Set the position of the text object.
This can be used to position multiple text objects within a single wrapping text area.
This method may cause the internal text representation to be rebuilt.
procedure SetPosition(const AX, AY: Integer); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AX: Integer
: The x offset of the upper left corner of this text in pixels.
AY: Integer
: The y offset of the upper left corner of this text in pixels.
See Also
Remarks
This method should be called on the thread that created the text.
SubString(Integer)
Get the substring of the text object that surrounds a text offset.
If AOffset is less than 0, this will return a zero length substring at the beginning of the text with the TSdlTtfSubStringFlag.TextStart flag set. If AOffset is greater than or equal to the length of the text string, this will return a zero length substring at the end of the text with the TSdlTtfSubStringFlag.TextEnd flag set.
function SubString(const AOffset: Integer): TSdlTtfSubString; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AOffset: Integer
: A byte offset into the text string.
Returns
TSdlTtfSubString: The substring containing the offset.
Remarks
This method should be called on the thread that created the text.
SubStringForLine(Integer)
Get the substring of the text object that contains the given line.
If ALine is less than 0, this will return a zero length substring at the beginning of the text with the TSdlTtfSubStringFlag.TextStart flag set. If ALine is greater than or equal to NumLines this will return a zero length substring at the end of the text with the TSdlTtfSubStringFlag.TextEnd flag set.
function SubStringForLine(const ALine: Integer): TSdlTtfSubString; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ALine: Integer
: A zero-based line index, in the range [0..NumLines-1].
Returns
TSdlTtfSubString: The substring containing the line.
Remarks
This method should be called on the thread that created the text.
SubStringForPoint(TSdlPoint)
Get the portion of a text string that is closest to a point.
This will return the closest substring of text to the given point.
function SubStringForPoint(const APoint: TSdlPoint): TSdlTtfSubString; overload
Exceptions
ESdlError: Raised on failure.
Parameters
APoint: TSdlPoint
: The coordinate relative to the top-left side of the text, may be outside the bounds of the text area.
Returns
TSdlTtfSubString: The closest substring of text to the given point.
Remarks
This method should be called on the thread that created the text.
SubStringForPoint(Integer, Integer)
Get the portion of a text string that is closest to a point.
This will return the closest substring of text to the given point.
function SubStringForPoint(const AX, AY: Integer): TSdlTtfSubString; overload
Exceptions
ESdlError: Raised on failure.
Parameters
AX: Integer
: The x coordinate relative to the left side of the text, may be outside the bounds of the text area.
AY: Integer
: The y coordinate relative to the top side of the text, may be outside the bounds of the text area.
Returns
TSdlTtfSubString: The closest substring of text to the given point.
Remarks
This method should be called on the thread that created the text.
SubStringsForRange(Integer, Integer)
Get the substrings of a text object that contain a range of text.
function SubStringsForRange(const AOffset, ALength: Integer): TArray<TSdlTtfSubString>
Exceptions
ESdlError: Raised on failure.
Parameters
AOffset: Integer
: A byte offset into the text string.
ALength: Integer
: The length of the range being queried, in bytes, or -1 for the remainder of the string.
Returns
TArray<TSdlTtfSubString>: An array of substrings.
Remarks
This method should be called on the thread that created the text.
Update
Update the layout of a text object.
This is automatically done when the layout is requested or the text is rendered, but you can call this if you need more control over the timing of when the layout and text engine representation are updated.
procedure Update; inline
Exceptions
ESdlError: Raised on failure.
Remarks
This method should be called on the thread that created the text.