Reading and modifying text properties in the Headless CreativeEngine
In this example, we want to show how to read and modify the text block's contents via the API in the Headless CreativeEngine.
Explore a full code sample on Stackblitz or view the code on Github.
Editing the Text String#
You can edit the text string contents of a text block using the replaceText(id: DesignBlockId, text: string, from: number = -1, to: number = -1) and removeText(id: DesignBlockId, from: number = -1, to: number = -1) APIs.
The range of text that should be edited is defined using the UTF-16 indices [from, to).
When omitting both the from and to arguments, the entire existing string is replaced.
When only specifying the from index, the new text is inserted at this index.
When both from and to indices are specified, then that range of text is replaced with the new text.
Similarly, the removeText API can be called to remove either a specific range or the entire text.
Text Colors#
Text blocks in the CreativeEngine allow different ranges to have multiple colors.
Use the setTextColor(id: DesignBlockId, color: RGBAColor | SpotColor, from: number = -1, to: number = -1) API to change either the color of the entire text
or only that of a range. After these two calls, the text "Alex!" now starts with one yellow character, followed by three black characters and two more yellow ones.
The getTextColors(id: DesignBlockId, from: number = -1, to: number = -1): Array<RGBAColor | SpotColor> API returns an ordered list of unique colors in the requested range. Here, allColors will be an array containing the colors yellow and black (in this order).
When only the colors in the UTF-16 range from 2 to 5 are requested, the result will be an array containing black and then yellow, since black appears first in the requested range.
Font Weights and Styles#
Text blocks can also have multiple ranges with different weights and styles. These can currently only be edited by the user directly on the canvas but APIs for changing these values programmatically will be added in the future. The current APIs allow you to query the current weights and styles in the text block.
The getTextFontWeights(id: DesignBlockId, from: number = -1, to: number = -1): FontWeight[] API returns an ordered list of unique font weights in the requested range, similar to the getTextColors API described above. For this example text, the result will be ['normal'].
The getTextFontStyles(id: DesignBlockId, from: number = -1, to: number = -1): FontStyle[] API returns an ordered list of unique font styles in the requested range, similar to the getTextColors API described above. For this example text, the result will be ['normal'].
Text Case#
You can apply text case modifications to ranges of text in order to display them in upper case, lower case or title case. It is important to note that these modifiers do not change the text string value of the text block but are only applied when the block is rendered.
By default, the text case of all text within a text block is set to Normal, which does not modify the appearance of the text at all.
The setTextCase(id: DesignBlockId, textCase: TextCase, from: number = -1, to: number = -1): void API sets the given text case for the selected range of text.
Possible values for TextCase are:
Normal: The text string is rendered without modifications.Uppercase: All characters are rendered in upper case.Lowercase: All characters are rendered in lower case.Titlecase: The first character of each word is rendered in upper case.
The getTextCases(id: DesignBlockId, from: number = -1, to: number = -1): TextCase[] API returns the ordered list of text cases of the text in the selected range.