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.

JavaScript


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. If from and to are negative, a this will fall back to the end of the entire text range, so the entire text will be replaced. If to is negative but from is greater than or equal to 0, the text will be inserted at the index defined by from.

JavaScript


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.

JavaScript


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.

JavaScript


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.

JavaScript


setTextFontWeight(id: DesignBlockId, fontWeight: FontWeight, from?: number, to?: number): void

Changes the weight of the text in the selected range to the given weight. Required scope: 'text/edit'

block: The text block whose weight should be changed.
fontWeight: The new weight of the selected text range.
from: The start index of the UTF-16 range whose weight 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 weight 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.

JavaScript


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.

JavaScript


setTextFontSize(id: DesignBlockId, fontSize: number, from?: number, to?: number): void

Sets the given font size for the text block. If the font size is applied to the entire text block, its font size property will be updated. Required scope: 'text/character'

block: The text block whose font size should be changed.
fontSize: The new font size.
from: The start index of the UTF-16 range whose font size 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 font size 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.

JavaScript


getTextFontSizes(id: DesignBlockId, from?: number, to?: number): number[]

Returns the ordered unique list of font sizes of the text in the selected range.

block: The text block whose font sizes should be returned.
from: The start index of the grapheme range whose font sizes 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 sizes 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.

JavaScript


setTextFontStyle(id: DesignBlockId, fontStyle: FontStyle, from?: number, to?: number): void

Changes the style of the text in the selected range to the given style. Required scope: 'text/edit'

block: The text block whose style should be changed.
fontStyle: The new style of the selected text range.
from: The start index of the UTF-16 range whose style 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 style 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.

JavaScript


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 styles 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.

JavaScript


setTextCase(id: DesignBlockId, textCase: TextCase, from?: number, to?: number): void

Sets the given text case for the selected range of text. Required scope: 'text/character'

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.

JavaScript


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.

JavaScript


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.

JavaScript


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.

JavaScript


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. Required scope: 'text/character'

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.

JavaScript


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. Required scope: 'text/character'

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.

JavaScript


setFont(id: DesignBlockId, fontFileUri: string, typeface: Typeface): void

Sets the given font and typeface for the text block. Existing formatting is reset. Required scope: 'text/character'

id: The text block whose font should be changed.
fontFileUri: The URI of the new font file.
typeface: The typeface of the new font.

JavaScript


setTypeface(id: DesignBlockId, typeface: Typeface, from?: number, to?: number): void

Sets the given typeface for the text block. The current formatting, e.g., bold or italic, is retained as far as possible. Some formatting might change if the new typeface does not support it, e.g. thin might change to light, bold to normal, and/or italic to non-italic. If the typeface is applied to the entire text block, its typeface property will be updated. If a run does not support the new typeface, it will fall back to the default typeface from the typeface property. Required scope: 'text/character'

id: The text block whose font should be changed.
typeface: The new typeface.
from: The start index of the UTF-16 range whose typeface 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 typeface 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.

JavaScript


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 property of the text block. Does not return the typefaces of the text runs.
Throws An error if the block does not have a valid typeface.

JavaScript


getTypefaces(id: DesignBlockId, from?: number, to?: number): Typeface[]

Returns the current typefaces of the given text block.

id: The text block whose typefaces should be queried.
from: The start index of the grapheme range whose typefaces 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 typefaces 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.
Returns The typefaces of the text block.
Throws An error if the block does not have a valid typeface.

JavaScript


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.


const text = engine.block.create('text');

engine.block.replaceText(text, 'Hello World');
engine.block.removeText(text, 0, 6);
engine.block.setTextColor(text, { r: 0.0, g: 0.0, b: 0.0, a: 1.0 }, 1, 4);
const colorsInRange = engine.block.getTextColors(text, 2, 5);
engine.block.setTextFontWeight(text, "bold", 0, 5);
const fontWeights = engine.block.getTextFontWeights(text);
engine.block.setTextFontSize(text, 12, 0, 5);
const fontSizes = engine.block.getTextFontSizes(text);
engine.block.setTextFontStyle(text, "italic", 0, 5);
const fontStyles = engine.block.getTextFontStyles(text);
engine.block.setTextCase(text, 'Titlecase');
const textCases = engine.block.getTextCases(text);
const canToggleBold = engine.block.canToggleBoldFont(text);
const canToggleItalic = engine.block.canToggleItalicFont(text);
engine.block.toggleBoldFont(text);
engine.block.toggleItalicFont(text);
const typefaceAssetResults = await engine.asset.findAssets('ly.img.typeface', {
  query: 'Open Sans',
  page: 0,
  perPage: 100
});
const typeface = typefaceAssetResults.assets[0].payload.typeface;
const font = typeface.fonts.find((font) => font.subFamily === 'Bold');
engine.block.setFont(text, font.uri, typeface);
engine.block.setTypeface(text, typeface, 2, 5);
engine.block.setTypeface(text, typeface);
const defaultTypeface = engine.block.getTypeface(text);
const typeface = engine.block.getTypefaces(text);
const selectedRange = engine.block.getTextCursorRange();