Text
In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine to edit ranges within text blocks.
Setup#
This example uses the headless CreativeEngine. See the Setup article for a detailed guide.
To get started right away, you can also access the block
API within a running CE.SDK instance via cesdk.engine.block
.
Check out the APIs Overview to see that illustrated in more detail.
replaceText(id: DesignBlockId, text: string, from?: number, to?: number): void
Inserts the given text into the selected range of the text block. Required scope: 'text/edit'
block
: The text block into which to insert the given text.text
: The text which should replace the selected range in the block.from
: The start index of the UTF-16 range that should be replaced. If the value is negative, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme that should be replaced by the inserted text. Iffrom
andto
are negative, a this will fall back to the end of the entire text range, so the entire text will be replaced. Ifto
is negative butfrom
is greater than or equal to 0, the text will be inserted at the index defined byfrom
.
removeText(id: DesignBlockId, from?: number, to?: number): void
Removes selected range of text of the given text block. Required scope: 'text/edit'
block
: The text block from which the selected text should be removed.from
: The start index of the UTF-16 range that should be removed. If the value is negative, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme that should be removed. If the value is negative, this will fall back to the end of the entire text range.
setTextColor(id: DesignBlockId, color: Color, from?: number, to?: number): void
Changes the color of the text in the selected range to the given color. Required scope: 'text/edit'
block
: The text block whose color should be changed.color
: The new color of the selected text range.from
: The start index of the UTF-16 range whose color should be changed. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme whose color should be changed. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
getTextColors(id: DesignBlockId, from?: number, to?: number): Array<Color>
Returns the ordered unique list of colors of the text in the selected range.
block
: The text block whose colors should be returned.from
: The start index of the UTF-16 range whose colors should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme whose colors should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
getTextFontWeights(id: DesignBlockId, from?: number, to?: number): FontWeight[]
Returns the ordered unique list of font weights of the text in the selected range.
block
: The text block whose font weights should be returned.from
: The start index of the UTF-16 range whose font weights should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme whose font weights should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
getTextFontStyles(id: DesignBlockId, from?: number, to?: number): FontStyle[]
Returns the ordered unique list of font styles of the text in the selected range.
block
: The text block whose font styles should be returned.from
: The start index of the UTF-16 range whose font weights should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme whose font styles should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
setTextCase(id: DesignBlockId, textCase: TextCase, from?: number, to?: number): void
Sets the given text case for the selected range of text. Required scope: 'text/edit'
id
: The text block whose text case should be changed.textCase
: The new text case value.from
: The start index of the UTF-16 range whose text cases should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme whose text cases should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
getTextCases(id: DesignBlockId, from?: number, to?: number): TextCase[]
Returns the ordered list of text cases of the text in the selected range.
block
: The text block whose text cases should be returned.from
: The start index of the UTF-16 range whose text cases should be returned. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme whose text cases should be returned. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
canToggleBoldFont(id: DesignBlockId, from?: number, to?: number): boolean
Returns whether the font weight of the given text block can be toggled between bold and normal. If any part of the selected range is not already bold and the necessary bold font is available, then this function returns true.
id
: The text block whose font weight should be toggled.from
: The start index of the UTF-16 range whose font weight should be toggled. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme whose font weight should be toggled. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.- Returns Whether the font weight of the given block can be toggled between bold and normal.
canToggleItalicFont(id: DesignBlockId, from?: number, to?: number): boolean
Toggles the bold font style of the given text block. If any part of the selected range is not already italic and the necessary italic font is available, then this function returns true.
id
: The text block whose font style should be toggled.from
: The start index of the UTF-16 range whose font style should be toggled. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme whose font style should be toggled. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.- Returns Whether the font style of the given block can be toggled between italic and normal.
toggleBoldFont(id: DesignBlockId, from?: number, to?: number): void
Toggles the font weight of the given text block between bold and normal. If any part of the selected range is not already bold, all of the selected range will become bold. Only if the entire range is already bold will this function toggle it all back to normal.
id
: The text block whose font weight should be toggled.from
: The start index of the UTF-16 range whose font weight should be toggled. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme whose font weight should be toggled. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
toggleItalicFont(id: DesignBlockId, from?: number, to?: number): void
Toggles the font style of the given text block between italic and normal. If any part of the selected range is not already italic, all of the selected range will become italic. Only if the entire range is already italic will this function toggle it all back to normal.
id
: The text block whose font style should be toggled.from
: The start index of the UTF-16 range whose font style should be toggled. If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.to
: The UTF-16 index after the last grapheme whose font style should be toggled. If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range. If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
setFont(id: DesignBlockId, fontFileUri: string, typeface: Typeface): void
Sets the given font and typeface for the text block.
id
: The text block whose font should be changed.fontFileUri
: The URI of the new font file.typeface
: The typeface of the new font.
getTypeface(id: DesignBlockId): Typeface
Returns the current typeface of the given text block.
id
: The text block whose typeface should be queried.- Returns The typeface of the text block.
- Throws An error if the block does not have a valid typeface.
getTextCursorRange(): Range
Returns the UTF-16 indices of the selected range of the text block that is currently being edited. If both the start and end index of the returned range have the same value, then the text cursor is positioned at that index.
- Returns The selected UTF-16 range or { from: -1, to: -1 } if no text block is currently being edited.