Skip to main content
Platform
Language

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.

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.

Typefaces#

In order to change the font of a text block, you have to call the setFont(id: DesignBlockId, fontFileUri: string, typeface: Typeface) API and provide it with both the uri of the font file to be actively used and the complete typeface definition of the corresponding typeface. Existing formatting of the block is reset.

A typeface definition consists of the unique typeface name (as it is defined within the font files), and a list of all font definitions that belong to this typeface. Each font definition must provide a uri string which points to the font file and a subFamily string which is this font's effective name within its typeface. The subfamily value is typically also defined within the font file. The weight and style properties default to normal, but must be provided in other cases.

For the sake of this example, we define a Roboto typeface with only four fonts: Regular, Bold, Italic, and Bold Italic and we change the font of the text block to the Roboto Regular font.

If the formatting, e.g., bold or italic, of the text should be kept, you have to call the fun setTypeface(block: DesignBlock, fontFileUri: Uri, typeface: Typeface) API and provide it with both the uri of the font file to be used and the complete typeface definition of the corresponding typeface. The font file should be a fallback font, e.g., Regular, from the same typeface. The actual font that matches the formatting is chosen automatically with the current formatting retained as much as possible. If the new typeface does not support the current formatting, the formatting changes to a reasonable close one, e.g. thin might change to light, bold to normal, and/or italic to non-italic. If no reasonable font can be found, the fallback font is used.

You can query the currently used typeface definition of a text block by calling the getTypeface(id: DesignBlockId): Typeface API. It is important to note that new text blocks don't have any explicit typeface set until you call the setFont API. In this case, the getTypeface API will throw an error.

Font Weights and Styles#

Text blocks can also have multiple ranges with different weights and styles.

In order to toggle the text of a text block between the normal and bold font weights, first call the canToggleBoldFont(id: DesignBlockId, from: number = -1, to: number = -1): boolean API to check whether such an edit is possible and if so, call the toggleBoldFont(id: DesignBlockId, from: number = -1, to: number = -1) API to change the weight.

In order to toggle the text of a text block between the normal and italic font styles, first call the canToggleItalicFont(id: DesignBlockId, from: number = -1, to: number = -1): boolean API to check whether such an edit is possible and if so, call the toggleItalicFont(id: DesignBlockId, from: number = -1, to: number = -1) API to change the style.

In order to change the font weight or style, the typeface definition of the text block must include a font definition that corresponds to the requested font weight and style combination. For example, if the text block currently uses a bold font and you want to toggle the font style to italic - such as in the example code - the typeface must contain a font that is both bold and italic.

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 ['bold'].

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 ['italic'].