Search Docs
Loading...
Skip to content

Class: EditorAPI

Control the design editor’s behavior and settings.

The EditorAPI provides access to edit modes, history management, editor settings, color management, resource handling, and global scope controls. It serves as the central configuration and control interface for the design editor engine.

Constructors#

Constructor#


EditorAPI

Role & Scope Management#

Manage user roles and global scope permissions.

setRole()#


Set the user role and apply role-dependent defaults.

Automatically configures scopes and settings based on the specified role.

Parameters#

Parameter Type Description
role RoleString The role to assign to the user.

Returns#

void

Signature#

setRole(role: RoleString): void

getRole()#


Get the current user role.

Returns#

RoleString

The current role of the user.

Signature#

getRole(): RoleString

findAllScopes()#


Get all available global scope names.

Returns#

Scope[]

The names of all available global scopes.

Signature#

findAllScopes(): Scope[]

setGlobalScope()#


Set a global scope permission level.

Parameters#

Parameter Type Description
key Scope The scope to configure.
value "Allow" "Deny"

Returns#

void

Signature#

setGlobalScope(key: Scope, value: "Allow" | "Deny" | "Defer"): void

getGlobalScope()#


Get a global scope’s permission level.

Parameters#

Parameter Type Description
key Scope The scope to query.

Returns#

"Allow" | "Deny" | "Defer"

Allow, Deny, or Defer indicating the scope’s permission level.

Signature#

getGlobalScope(key: Scope): "Allow" | "Deny" | "Defer"

Event Subscriptions#

Subscribe to editor state changes, history updates, and role changes.

onStateChanged#


Subscribe to editor state changes.

Parameters#

Parameter Type Description
callback () => void Function called when the editor state changes.

Returns#

A method to unsubscribe from the event.

() => void

onHistoryUpdated#


Subscribe to undo/redo history changes.

Parameters#

Parameter Type Description
callback () => void Function called when the undo/redo history changes.

Returns#

A method to unsubscribe from the event.

() => void

Deprecated#

Use onHistoryUpdatedWithKind instead, which additionally reports a HistoryUpdate describing the kind of update.

onHistoryUpdatedWithKind#


Subscribe to undo/redo history changes.

The callback receives a HistoryUpdate describing what kind of update happened so consumers can distinguish a real change to the active history’s snapshots (e.g. an edit, undo, or redo) from a pure activation via setActiveHistory.

const unsubscribe = engine.editor.onHistoryUpdatedWithKind((kind) => {
  if (kind === 'Activated') {
    // The active history was switched; no scene change happened on this event.
    return;
  }
  const canUndo = engine.editor.canUndo();
  const canRedo = engine.editor.canRedo();
  console.log('History updated', { canUndo, canRedo });
});

Parameters#

Parameter Type Description
callback (kind) => void Function called when the undo/redo history changes. The argument describes the kind of update.

Returns#

A method to unsubscribe from the event.

() => void

onSettingsChanged#


Subscribe to editor settings changes.

Parameters#

Parameter Type Description
callback () => void Function called when editor settings change.

Returns#

A method to unsubscribe from the event.

() => void

onRoleChanged#


Subscribe to editor role changes.

Allows reacting to role changes and updating engine settings accordingly. The callback is triggered immediately after role changes and default settings are applied.

Parameters#

Parameter Type Description
callback (role) => void Function called when the user role changes.

Returns#

A method to unsubscribe from the event.

() => void

Edit Mode Management#

Control the editor’s current editing mode and interaction state.

setEditMode()#


Set the editor’s current edit mode.

Edit modes represent different tools or interaction states within the editor. Common ones, are “Crop” while the crop tool is shown or “Text” when inline-editing text.

engine.editor.setEditMode('Crop');
// With a base mode
engine.editor.setEditMode('CustomMode', 'Crop');

Parameters#

Parameter Type Description
mode EditMode “Transform”, “Crop”, “Text”, “Playback”, “Trim”, “Vector” or a custom value.
baseMode? string Optional base mode from which the custom mode will inherit the settings.

Returns#

void

Signature#

setEditMode(mode: EditMode, baseMode?: string): void

getEditMode()#


Get the editor’s current edit mode.

Edit modes represent different tools or interaction states within the editor. Common ones, are “Crop” while the crop tool is shown or “Text” when inline-editing text.

Returns#

EditMode

“Transform”, “Crop”, “Text”, “Playback”, “Trim”, “Vector” or a custom value.

Signature#

getEditMode(): EditMode

getCursorType()#


Get the cursor type that should be displayed.

Returns#

| "Text" | "Arrow" | "Move" | "MoveNotPermitted" | "Resize" | "Rotate" | "Cell"

The cursor type.

Signature#

getCursorType(): "Text" | "Arrow" | "Move" | "MoveNotPermitted" | "Resize" | "Rotate" | "Cell"

getCursorRotation()#


Get the cursor rotation angle.

Returns#

number

The angle in radians.

Signature#

getCursorRotation(): number

getTextCursorPositionInScreenSpaceX()#


Get the text cursor’s x position in screen space.

Returns#

number

The text cursor’s x position in screen space.

Signature#

getTextCursorPositionInScreenSpaceX(): number

getTextCursorPositionInScreenSpaceY()#


Get the text cursor’s y position in screen space.

Returns#

number

The text cursor’s y position in screen space.

Signature#

getTextCursorPositionInScreenSpaceY(): number

History Management#

Create, manage, and operate on undo/redo history stacks.

createHistory()#


Create a new undo/redo history stack.

Multiple histories can exist, but only one can be active at a time.

const newHistory = engine.editor.createHistory();

Returns#

number

The handle of the created history.

Signature#

createHistory(): number

destroyHistory()#


Destroy a history stack and free its resources.

engine.editor.destroyHistory(oldHistory);

Parameters#

Parameter Type Description
history number The history handle to destroy.

Returns#

void

Throws#

Error if the handle doesn’t refer to a valid history.

Signature#

destroyHistory(history: number): void

setActiveHistory()#


Set a history as the active undo/redo stack.

All other histories lose their active state. Undo/redo operations only apply to the active history.

engine.editor.setActiveHistory(newHistory);

Parameters#

Parameter Type Description
history number The history handle to make active.

Returns#

void

Throws#

Error if the handle doesn’t refer to a valid history.

Signature#

setActiveHistory(history: number): void

getActiveHistory()#


Get the currently active history handle.

Creates a new history if none exists.

const oldHistory = engine.editor.getActiveHistory();

Returns#

number

The handle of the active history.

Signature#

getActiveHistory(): number

addUndoStep()#


Add a new history state to the undo stack.

Only adds a state if undoable changes were made since the last undo step.

  engine.editor.addUndoStep();

Returns#

void

Signature#

addUndoStep(): void

removeUndoStep()#


Remove the last history state from the undo stack.

Removes the most recent undo step if available.

  engine.editor.removeUndoStep();

Returns#

void

Signature#

removeUndoStep(): void

undo()#


Undo one step in the active history if an undo step is available.

engine.editor.undo();

Returns#

void

Signature#

undo(): void

redo()#


Redo one step in the active history if a redo step is available.

engine.editor.redo();

Returns#

void

Signature#

redo(): void

canUndo()#


Check if an undo step is available.

if (engine.editor.canUndo()) {
  engine.editor.undo();
}

Returns#

boolean

True if an undo step is available.

Signature#

canUndo(): boolean

canRedo()#


Check if a redo step is available.

if (engine.editor.canRedo()) {
  engine.editor.redo();
}

Returns#

boolean

True if a redo step is available.

Signature#

canRedo(): boolean

Color Management#

Handle spot colors, color conversion, and color space operations.

findAllSpotColors()#


Get all spot color names currently defined.

Returns#

string[]

The names of all defined spot colors.

Signature#

findAllSpotColors(): string[]

getSpotColorRGBA()#


Queries the RGB representation set for a spot color.

If the value of the queried spot color has not been set yet, returns the default RGB representation (of magenta). The alpha value is always 1.0.

Parameters#

Parameter Type Description
name string The name of a spot color.

Returns#

RGBA

A result holding a float array of the four color components.

Signature#

getSpotColorRGBA(name: string): RGBA

getSpotColorCMYK()#


Queries the CMYK representation set for a spot color.

If the value of the queried spot color has not been set yet, returns the default CMYK representation (of magenta).

Parameters#

Parameter Type Description
name string The name of a spot color.

Returns#

CMYK

A result holding a float array of the four color components.

Signature#

getSpotColorCMYK(name: string): CMYK

setSpotColorRGB()#


Sets the RGB representation of a spot color.

Use this function to both create a new spot color or update an existing spot color.

Parameters#

Parameter Type Description
name string The name of a spot color.
r number The red color component in the range of 0 to 1.
g number The green color component in the range of 0 to 1.
b number The blue color component in the range of 0 to 1.

Returns#

void

Signature#

setSpotColorRGB(name: string, r: number, g: number, b: number): void

setSpotColorCMYK()#


Sets the CMYK representation of a spot color.

Use this function to both create a new spot color or update an existing spot color.

Parameters#

Parameter Type Description
name string The name of a spot color.
c number The cyan color component in the range of 0 to 1.
m number The magenta color component in the range of 0 to 1.
y number The yellow color component in the range of 0 to 1.
k number The key color component in the range of 0 to 1.

Returns#

void

Signature#

setSpotColorCMYK(name: string, c: number, m: number, y: number, k: number): void

removeSpotColor()#


Removes a spot color from the list of set spot colors.

Parameters#

Parameter Type Description
name string The name of a spot color.

Returns#

void

An empty result on success, an error otherwise.

Signature#

removeSpotColor(name: string): void

setSpotColorForCutoutType()#


Set the spot color assign to a cutout type.

All cutout blocks of the given type will be immediately assigned that spot color.

Parameters#

Parameter Type Description
type "Dashed" "Solid"
color string The spot color name to assign.

Returns#

void

Signature#

setSpotColorForCutoutType(type: "Dashed" | "Solid", color: string): void

getSpotColorForCutoutType()#


Get the name of the spot color assigned to a cutout type.

Parameters#

Parameter Type Description
type "Dashed" "Solid"

Returns#

string

The color spot name.

Signature#

getSpotColorForCutoutType(type: "Dashed" | "Solid"): string

convertColorToColorSpace()#


Converts a color to the given color space.

Parameters#
Parameter Type Description
color Color The color to convert.
colorSpace "sRGB" The color space to convert to.
Returns#
RGBAColor

The converted color.

Call Signature#

convertColorToColorSpace(color, colorSpace): CMYKColor;
Parameters#
Parameter Type
color Color
colorSpace "CMYK"
Returns#
CMYKColor

Call Signature#

convertColorToColorSpace(color, colorSpace): never;
Parameters#
Parameter Type
color Color
colorSpace ColorSpace
Returns#

never

Signatures#

convertColorToColorSpace(color: Color, colorSpace: "sRGB"): RGBAColor
convertColorToColorSpace(color: Color, colorSpace: "CMYK"): CMYKColor
convertColorToColorSpace(color: Color, colorSpace: ColorSpace): never

Resource Management#

Manage buffers, URIs, and resource data handling.

createBuffer()#


Create a resizable buffer for arbitrary data.

const buffer = engine.editor.createBuffer();


// Reference the buffer resource from the audio block
engine.block.setString(audioBlock, 'audio/fileURI', buffer);

Returns#

string

A URI to identify the created buffer.

Signature#

createBuffer(): string

destroyBuffer()#


Destroy a buffer and free its resources.

engine.editor.destroyBuffer(buffer);

Parameters#

Parameter Type Description
uri string The URI of the buffer to destroy.

Returns#

void

Signature#

destroyBuffer(uri: string): void

setBufferData()#


Set the data of a buffer at a given offset.

// Generate 10 seconds of stereo 48 kHz audio data
const samples = new Float32Array(10 * 2 * 48000);
for (let i = 0; i < samples.length; i += 2) {
  samples[i] = samples[i + 1] = Math.sin((440 * i * Math.PI) / 48000);
}
// Assign the audio data to the buffer
engine.editor.setBufferData(buffer, 0, new Uint8Array(samples.buffer));

Parameters#

Parameter Type Description
uri string The URI of the buffer to update.
offset number The offset in bytes at which to start writing.
data Uint8Array The data to write.

Returns#

void

Signature#

setBufferData(uri: string, offset: number, data: Uint8Array): void

getBufferData()#


Get the data of a buffer at a given offset.

engine.editor.findAllTransientResources().forEach((resource) => {
  const bufferURI = resource.URL;
  const length = engine.editor.getBufferLength(buffer);
  const data = engine.editor.getBufferData(buffer, 0, length);
  const blob = new Blob([data]);
})

Parameters#

Parameter Type Description
uri string The URI of the buffer to query.
offset number The offset in bytes at which to start reading.
length number The number of bytes to read.

Returns#

Uint8Array

The data at the given offset.

Signature#

getBufferData(uri: string, offset: number, length: number): Uint8Array

setBufferLength()#


Set the length of a buffer.

// Reduce the buffer to half its length
const currentLength = engine.editor.getBufferLength(buffer);
engine.editor.setBufferLength(buffer, currentLength / 2);

Parameters#

Parameter Type Description
uri string The URI of the buffer to update.
length number The new length of the buffer in bytes.

Returns#

void

Signature#

setBufferLength(uri: string, length: number): void

getBufferLength()#


Get the length of a buffer.

const length = engine.editor.getBufferLength(buffer);

Parameters#

Parameter Type Description
uri string The URI of the buffer to query.

Returns#

number

The length of the buffer in bytes.

Signature#

getBufferLength(uri: string): number

getMimeType()#


Get the MIME type of a resource.

Downloads the resource if not already cached.

Parameters#

Parameter Type Description
uri string The URI of the resource.

Returns#

Promise<string>

Promise resolving to the resource’s MIME type.

Throws#

Error if the resource cannot be downloaded or MIME type determined.

Signature#

getMimeType(uri: string): Promise<string>

getFontMetrics()#


Gets the font metrics for a given font file URI.

If the font is not yet loaded, it will be fetched asynchronously. The returned metrics are in the font’s design units coordinate space.

const metrics = await engine.editor.getFontMetrics('/extensions/ly.img.cesdk.fonts/fonts/Roboto/Roboto-Regular.ttf');
console.log(metrics.ascender, metrics.descender, metrics.unitsPerEm);
console.log(metrics.lineGap);
console.log(metrics.capHeight, metrics.xHeight);
console.log(metrics.underlineOffset, metrics.underlineSize, metrics.strikeoutOffset, metrics.strikeoutSize);

Parameters#

Parameter Type Description
fontFileUri string The URI of the font file to get metrics from.

Returns#

Promise<FontMetrics>

A promise resolving to the font metrics.

Signature#

getFontMetrics(fontFileUri: string): Promise<FontMetrics>

findAllTransientResources()#


Get all transient resources that would be lost during export.

Useful for identifying resources that need relocation (e.g., to a CDN) before export, as these resources are not included in the exported scene.

Returns#

TransientResource[]

The URLs and sizes of transient resources.

Signature#

findAllTransientResources(): TransientResource[]

findAllMediaURIs()#


Get all media URIs referenced by blocks in the scene.

Returns URIs from image fills, video fills, and audio blocks, including their source sets. Only returns valid media URIs (http://, https://, file://), excluding transient resources like buffer URIs. Useful for determining which media files are referenced by a scene (e.g., for cleanup operations, CDN management, or file system tracking).

Returns#

string[]

The URLs of all media resources referenced in the scene, deduplicated.

Signature#

findAllMediaURIs(): string[]

getResourceData()#


Provides the data of a resource at the given URL.

Parameters#

Parameter Type Description
uri string The URL of the resource.
chunkSize number The size of the chunks in which the resource data is provided.
onData (result) => boolean The callback function that is called with the resource data or an error if an error occurred. The callback will be called as long as there is data left to provide and the callback returns true.

Returns#

void

Signature#

getResourceData(uri: string, chunkSize: number, onData: (result: Uint8Array) => boolean): void

relocateResource()#


Changes the URL associated with a resource.

This function can be used change the URL of a resource that has been relocated (e.g., to a CDN).

Parameters#

Parameter Type Description
currentUrl string The current URL of the resource.
relocatedUrl string The new URL of the resource.

Returns#

void

Signature#

relocateResource(currentUrl: string, relocatedUrl: string): void

Editor Settings#

Configure editor behavior through typed settings for different data types.

setSetting()#


Set a setting value using the unified API. The value type is automatically validated based on the key.

Type Parameters#

Type Parameter
K extends keyof Settings

Parameters#

Parameter Type Description
keypath OptionalPrefix<K> The setting key from Settings
value SettingValueType<K> The value to set (type-safe based on key)

Returns#

void

Throws#

Error if the keypath is invalid or value type doesn’t match

Example#

// Boolean setting
engine.editor.setSetting('doubleClickToCropEnabled', false);


// Color setting
engine.editor.setSetting('highlightColor', { r: 1, g: 0, b: 1, a: 1 });


// Enum setting
engine.editor.setSetting('doubleClickSelectionMode', 'Direct');

Signature#

setSetting(keypath: OptionalPrefix<K>, value: SettingValueType<K>): void

getSetting()#


Get a setting value using the unified API. The return type is automatically inferred from the key.

Type Parameters#

Type Parameter
K extends keyof Settings

Parameters#

Parameter Type Description
keypath OptionalPrefix<K> The setting key from Settings

Returns#

SettingValueType<K>

The value of the setting (type-safe based on key)

Throws#

Error if the keypath is invalid

Example#

// Boolean setting
const cropEnabled = engine.editor.getSetting('doubleClickToCropEnabled');


// Color setting
const highlight = engine.editor.getSetting('highlightColor');


// Enum setting
const selectionMode = engine.editor.getSetting('doubleClickSelectionMode');

Signature#

getSetting(keypath: OptionalPrefix<K>): SettingValueType<K>

setSettingBool()#


Set a boolean setting value.

Parameters#
Parameter Type Description
keypath SettingBoolPropertyName The settings keypath, e.g. doubleClickToCropEnabled.
value boolean The boolean value to set.
Returns#

void

Throws#

Error if the keypath is invalid.

Call Signature#

setSettingBool(keypath, value): void;
Parameters#
Parameter Type
keypath `ubq://${string & {}}`
value boolean
Returns#

void

Deprecated#

Support for ubq:// prefixed keypaths will be removed in a future release.

Signatures#

setSettingBool(keypath: SettingBoolPropertyName, value: boolean): void
setSettingBool(keypath: `ubq://${string & {}}`, value: boolean): void

getSettingBool()#


Get a boolean setting value.

Parameters#
Parameter Type Description
keypath SettingBoolPropertyName The settings keypath, e.g. doubleClickToCropEnabled.
Returns#

boolean

The boolean value of the setting.

Throws#

Error if the keypath is invalid.

Call Signature#

getSettingBool(keypath): boolean;
Parameters#
Parameter Type
keypath `ubq://${string & {}}`
Returns#

boolean

Deprecated#

Support for ubq:// prefixed keypaths will be removed in a future release.

Call Signature#

getSettingBool(keypath): boolean;

Get a boolean setting value.

Parameters#
Parameter Type Description
keypath SettingBoolPropertyName The settings keypath, e.g. doubleClickToCropEnabled.
Returns#

boolean

The boolean value of the setting.

Throws#

Error if the keypath is invalid.

Signatures#

getSettingBool(keypath: SettingBoolPropertyName): boolean
getSettingBool(keypath: `ubq://${string & {}}`): boolean
getSettingBool(keypath: SettingBoolPropertyName): boolean

setSettingInt()#


Set an integer setting value.

Parameters#
Parameter Type Description
keypath SettingIntPropertyName The settings keypath.
value number The integer value to set.
Returns#

void

Throws#

Error if the keypath is invalid.

Call Signature#

setSettingInt(keypath, value): void;

Set an integer setting value.

Parameters#
Parameter Type Description
keypath SettingIntPropertyName The settings keypath.
value number The integer value to set.
Returns#

void

Throws#

Error if the keypath is invalid.

Signatures#

setSettingInt(keypath: SettingIntPropertyName, value: number): void
setSettingInt(keypath: SettingIntPropertyName, value: number): void

getSettingInt()#


Get an integer setting value.

Parameters#
Parameter Type Description
keypath SettingIntPropertyName The settings keypath.
Returns#

number

The integer value of the setting.

Throws#

Error if the keypath is invalid.

Call Signature#

getSettingInt(keypath): number;

Get an integer setting value.

Parameters#
Parameter Type Description
keypath SettingIntPropertyName The settings keypath.
Returns#

number

The integer value of the setting.

Throws#

Error if the keypath is invalid.

Signatures#

getSettingInt(keypath: SettingIntPropertyName): number
getSettingInt(keypath: SettingIntPropertyName): number

setSettingFloat()#


Set a float setting value.

Parameters#
Parameter Type Description
keypath SettingFloatPropertyName The settings keypath, e.g. positionSnappingThreshold.
value number The float value to set.
Returns#

void

Throws#

Error if the keypath is invalid.

Call Signature#

setSettingFloat(keypath, value): void;
Parameters#
Parameter Type
keypath `ubq://${string & {}}`
value number
Returns#

void

Deprecated#

Support for ubq:// prefixed keypaths will be removed in a future release.

Call Signature#

setSettingFloat(keypath, value): void;

Set a float setting value.

Parameters#
Parameter Type Description
keypath SettingFloatPropertyName The settings keypath, e.g. positionSnappingThreshold.
value number The float value to set.
Returns#

void

Throws#

Error if the keypath is invalid.

Signatures#

setSettingFloat(keypath: SettingFloatPropertyName, value: number): void
setSettingFloat(keypath: `ubq://${string & {}}`, value: number): void
setSettingFloat(keypath: SettingFloatPropertyName, value: number): void

getSettingFloat()#


Get a float setting value.

Parameters#
Parameter Type Description
keypath SettingFloatPropertyName The settings keypath, e.g. positionSnappingThreshold.
Returns#

number

The float value of the setting.

Throws#

Error if the keypath is invalid.

Call Signature#

getSettingFloat(keypath): number;
Parameters#
Parameter Type
keypath `ubq://${string & {}}`
Returns#

number

Deprecated#

Support for ubq:// prefixed keypaths will be removed in a future release.

Call Signature#

getSettingFloat(keypath): number;

Get a float setting value.

Parameters#
Parameter Type Description
keypath SettingFloatPropertyName The settings keypath, e.g. positionSnappingThreshold.
Returns#

number

The float value of the setting.

Throws#

Error if the keypath is invalid.

Signatures#

getSettingFloat(keypath: SettingFloatPropertyName): number
getSettingFloat(keypath: `ubq://${string & {}}`): number
getSettingFloat(keypath: SettingFloatPropertyName): number

setSettingString()#


Set a string setting value.

Parameters#
Parameter Type Description
keypath SettingStringPropertyName The settings keypath, e.g. license.
value string The string value to set.
Returns#

void

Throws#

Error if the keypath is invalid.

Call Signature#

setSettingString(keypath, value): void;
Parameters#
Parameter Type
keypath `ubq://${string & {}}`
value string
Returns#

void

Deprecated#

Support for ubq:// prefixed keypaths will be removed in a future release.

Call Signature#

setSettingString(keypath, value): void;

Set a string setting value.

Parameters#
Parameter Type Description
keypath SettingStringPropertyName The settings keypath, e.g. license.
value string The string value to set.
Returns#

void

Throws#

Error if the keypath is invalid.

Signatures#

setSettingString(keypath: SettingStringPropertyName, value: string): void
setSettingString(keypath: `ubq://${string & {}}`, value: string): void
setSettingString(keypath: SettingStringPropertyName, value: string): void

getSettingString()#


Get a string setting value.

Parameters#
Parameter Type Description
keypath SettingStringPropertyName The settings keypath, e.g. license.
Returns#

string

The string value of the setting.

Throws#

Error if the keypath is invalid.

Call Signature#

getSettingString(keypath): string;
Parameters#
Parameter Type
keypath `ubq://${string & {}}`
Returns#

string

Deprecated#

Support for ubq:// prefixed keypaths will be removed in a future release.

Call Signature#

getSettingString(keypath): string;

Get a string setting value.

Parameters#
Parameter Type Description
keypath SettingStringPropertyName The settings keypath, e.g. license.
Returns#

string

The string value of the setting.

Throws#

Error if the keypath is invalid.

Signatures#

getSettingString(keypath: SettingStringPropertyName): string
getSettingString(keypath: `ubq://${string & {}}`): string
getSettingString(keypath: SettingStringPropertyName): string

setSettingColor()#


Set a color setting.

Parameters#
Parameter Type Description
keypath SettingColorPropertyName The settings keypath, e.g. highlightColor.
value Color The The value to set.
Returns#

void

Call Signature#

setSettingColor(keypath, value): void;
Parameters#
Parameter Type
keypath `ubq://${string & {}}`
value Color
Returns#

void

Deprecated#

Support for ubq:// prefixed keypaths will be removed in a future release.

Call Signature#

setSettingColor(keypath, value): void;

Set a color setting.

Parameters#
Parameter Type Description
keypath SettingColorPropertyName The settings keypath, e.g. highlightColor.
value Color The The value to set.
Returns#

void

Signatures#

setSettingColor(keypath: SettingColorPropertyName, value: Color): void
setSettingColor(keypath: `ubq://${string & {}}`, value: Color): void
setSettingColor(keypath: SettingColorPropertyName, value: Color): void

getSettingColor()#


Get a color setting.

Parameters#
Parameter Type Description
keypath SettingColorPropertyName The settings keypath, e.g. highlightColor.
Returns#
Color
Throws#

An error, if the keypath is invalid.

Call Signature#

getSettingColor(keypath): Color;
Parameters#
Parameter Type
keypath `ubq://${string & {}}`
Returns#
Color
Deprecated#

Support for ubq:// prefixed keypaths will be removed in a future release.

Call Signature#

getSettingColor(keypath): Color;

Get a color setting.

Parameters#
Parameter Type Description
keypath SettingColorPropertyName The settings keypath, e.g. highlightColor.
Returns#
Color
Throws#

An error, if the keypath is invalid.

Signatures#

getSettingColor(keypath: SettingColorPropertyName): Color
getSettingColor(keypath: `ubq://${string & {}}`): Color
getSettingColor(keypath: SettingColorPropertyName): Color

setSettingEnum()#


Set an enum setting.

Type Parameters#
Type Parameter
T extends keyof SettingEnumType
Parameters#
Parameter Type Description
keypath T The settings keypath, e.g. doubleClickSelectionMode.
value SettingEnumType[T] The enum value as string.
Returns#

void

Call Signature#

setSettingEnum(keypath, value): void;

Set an enum setting.

Parameters#
Parameter Type Description
keypath string The settings keypath, e.g. doubleClickSelectionMode.
value string The enum value as string.
Returns#

void

Signatures#

setSettingEnum(keypath: T, value: SettingEnumType[T]): void
setSettingEnum(keypath: string, value: string): void

getSettingEnum()#


Get an enum setting.

Type Parameters#
Type Parameter
T extends keyof SettingEnumType
Parameters#
Parameter Type Description
keypath T The settings keypath, e.g. doubleClickSelectionMode.
Returns#

SettingEnumType[T]

The value as string.

Call Signature#

getSettingEnum(keypath): string;

Get an enum setting.

Parameters#
Parameter Type Description
keypath string The settings keypath, e.g. doubleClickSelectionMode.
Returns#

string

The value as string.

Signatures#

getSettingEnum(keypath: T): SettingEnumType[T]
getSettingEnum(keypath: string): string

getSettingEnumOptions()#


Get the possible enum options for a given enum setting.

Type Parameters#
Type Parameter
T extends keyof SettingEnumType
Parameters#
Parameter Type Description
keypath T The settings keypath, e.g. doubleClickSelectionMode.
Returns#

SettingEnumType[T][]

The possible enum options as strings.

Call Signature#

getSettingEnumOptions(keypath): string[];

Get the possible enum options for a given enum setting.

Parameters#
Parameter Type Description
keypath string The settings keypath, e.g. doubleClickSelectionMode.
Returns#

string[]

The possible enum options as strings.

Signatures#

getSettingEnumOptions(keypath: T): SettingEnumType[T][]
getSettingEnumOptions(keypath: string): string[]

findAllSettings()#


Returns a list of all the settings available.

Returns#

string[]

A list of settings keypaths.

Signature#

findAllSettings(): string[]

getSettingType()#


Returns the type of a setting.

Parameters#

Parameter Type Description
keypath string The settings keypath, e.g. doubleClickSelectionMode.

Returns#

SettingType

The setting type.

Signature#

getSettingType(keypath: string): SettingType

setURIResolver()#


Sets a custom URI resolver.

This function can be called more than once. Subsequent calls will overwrite previous calls. To remove a previously set resolver, pass the value null. The given function must return an absolute path with a scheme and cannot be asynchronous. The input is allowed to be an invalid URI, e.g., due to placeholders.

// Replace all .jpg files with the IMG.LY logo
engine.editor.setURIResolver((uri) => {
  if (uri.endsWith('.jpg')) {
    return 'https://img.ly/static/ubq_samples/imgly_logo.jpg';
  }
  // Make use of the default URI resolution behavior.
  return engine.editor.defaultURIResolver(uri);
});

Parameters#

Parameter Type Description
resolver SyncURIResolver Custom resolution function. The resolution function should not reference variables outside of its scope. It receives the default URI resolver as its second argument

Returns#

void

Signature#

setURIResolver(resolver: SyncURIResolver): void

setURIResolverAsync()#


Sets a custom async URI resolver.

This function can be called more than once. Subsequent calls will overwrite previous calls. To remove a previously set resolver, pass the value null. The given function must return an absolute path with a scheme. The input is allowed to be invalid URI, e.g., due to placeholders.

Parameters#

Parameter Type Description
resolver AsyncURIResolver Custom async resolution function.

Returns#

void

Signature#

setURIResolverAsync(resolver: AsyncURIResolver): void

defaultURIResolver()#


This is the default implementation for the URI resolver.

It resolves the given path relative to the basePath setting.

engine.editor.defaultURIResolver(uri);

Parameters#

Parameter Type Description
relativePath string The relative path that should be resolved.

Returns#

string

The resolved absolute URI.

Signature#

defaultURIResolver(relativePath: string): string

getAbsoluteURI()#


Resolves the given path asynchronously.

If a custom resolver has been set with setURIResolverAsync (or setURIResolver), it invokes it with the given path. Else, it resolves it as relative to the basePath setting. This performs NO validation of whether a file exists at the specified location.

Breaking change: This method now returns a Promise<string> instead of a plain string. Callers must await the result.

Parameters#

Parameter Type Description
relativePath string A relative path string

Returns#

Promise<string>

Promise resolving to the resolved absolute uri or rejecting if an invalid path was given.

Signature#

getAbsoluteURI(relativePath: string): Promise<string>

System Information#

Access memory usage, export limits, and system capabilities.

getAvailableMemory()#


Get the currently available memory.

Returns#

number

The available memory in bytes.

Signature#

getAvailableMemory(): number

getUsedMemory()#


Get the engine’s current memory usage.

Returns#

number

The current memory usage in bytes.

Signature#

getUsedMemory(): number

getMaxExportSize()#


Get the maximum export size limit for the current device.

Exports are only possible when both width and height are below this limit. Note that exports may still fail due to other constraints like memory.

Returns#

number

The upper export size limit in pixels, or maximum 32-bit integer if unlimited.

Signature#

getMaxExportSize(): number

Experimental#

unstable_isInteractionHappening()#

Check if a user interaction is currently happening.

Detects active interactions like resize edits with drag handles or touch gestures.

Returns#

boolean

True if an interaction is happening. This API is experimental and may change or be removed in future versions.

Other#

setSettingColorRGBA()#


Set a color setting.

Parameters#

Parameter Type Description
keypath `ubq://${string & {}}`
r number The red color component in the range of 0 to 1.
g number The green color component in the range of 0 to 1.
b number The blue color component in the range of 0 to 1.
a? number The alpha color component in the range of 0 to 1.

Returns#

void

Deprecated#

Use setSettingColor() instead.

getSettingColorRGBA()#


Get a color setting.

Parameters#

Parameter Type Description
keypath `ubq://${string & {}}`

Returns#

RGBA

A tuple of channels red, green, blue and alpha in the range of 0 to 1.

Deprecated#

Use getSettingColor() instead.

isHighlightingEnabled()#


Checks wether the block has selection and hover highlighting enabled or disabled.

const highlightingIsEnabled = engine.editor.isHighlightingEnabled(block);

Parameters#

Parameter Type Description
id number The block to query.

Returns#

boolean

True if highlighting is enabled, false otherwise.

Signature#

isHighlightingEnabled(id: number): boolean

setHighlightingEnabled()#


Enable or disable selection and hover highlighting for a block.

engine.editor.setHighlightingEnabled(block, true);

Parameters#

Parameter Type Description
id number The block to update.
enabled boolean Whether or not the block should show highlighting when selected or hovered.

Returns#

void

Signature#

setHighlightingEnabled(id: number, enabled: boolean): void

isSelectionEnabled()#


Checks whether the block can currently be selected.

const selectionIsEnabled = engine.editor.isSelectionEnabled(block);

Parameters#

Parameter Type Description
id number The block to query.

Returns#

boolean

True if selection is enabled, false otherwise.

Signature#

isSelectionEnabled(id: number): boolean

setSelectionEnabled()#


Enable or disable selection for a block.

engine.editor.setSelectionEnabled(block, true);

Parameters#

Parameter Type Description
id number The block to update.
enabled boolean Whether the block should be selectable.

Returns#

void

Signature#

setSelectionEnabled(id: number, enabled: boolean): void

setMovementConstraint()#


Set one or more rules that limit how far blocks can be positioned outside their parent page during user interactions (drag, resize, touch gestures, crop). Programmatic API calls are not affected.

overshoot is a non-negative fraction of the moved block’s own size: 0 pins blocks fully inside the page, 0.3 allows 30% to extend past the page bounds. Each rule’s scope is determined by its keys:

  • { overshoot } — scene-wide default for every page in the scene.
  • { overshoot, block } — applies to a specific block. Pages are blocks, so setting this on a page acts as the default for blocks inside that page.
  • { overshoot, blockType } — applies to every block of the given type (e.g. "text" or "//ly.img.ubq/text").

Use removeMovementConstraint to clear a rule.

When multiple rules match a block, the most specific one wins: block \> parent page \> blockType \> scene-wide.

Parameters#

Parameter Type Description
rules MovementConstraintRule MovementConstraintRule[]

Returns#

void

Signature#

setMovementConstraint(rules: MovementConstraintRule | MovementConstraintRule[]): void

getMovementConstraint()#


Get the effective movement constraint for a block, picking the most specific matching rule: block > parent page > blockType > scene-wide.

The returned overshoot is a fraction of the block’s own size.

Parameters#

Parameter Type Description
id number The block to query.

Returns#

object

{ overshoot } with the effective value, or null if unconstrained.

Name Type
overshoot number

Signature#

getMovementConstraint(id: number): object

removeMovementConstraint()#


Remove previously set movement constraints.

  • No argument: removes the scene-wide default.
  • { block } / { blockType } (or an array): removes the matching scope(s).

Removing a scope falls through to the next tier on subsequent resolution.

Parameters#

Parameter Type Description
scopes? MovementConstraintScope MovementConstraintScope[]

Returns#

void

Signature#

removeMovementConstraint(scopes?: MovementConstraintScope | MovementConstraintScope[]): void

Vector Edit#

hasSelectedVectorNode()#


Check whether a vector anchor node is currently selected in vector edit mode.

Returns#

boolean

True if a vector anchor node is selected.

Signature#

hasSelectedVectorNode(): boolean

addVectorNode()#


Add a new vertex by splitting the segment after the currently selected vector node.

Returns#

void

Signature#

addVectorNode(): void

deleteVectorNode()#


Delete the currently selected vector node from the path.

Returns#

void

Signature#

deleteVectorNode(): void

hasSelectedVectorControlPoint()#


Check whether a vector control point handle is currently selected.

Returns#

boolean

Signature#

hasSelectedVectorControlPoint(): boolean

deleteSelectedVectorControlPoints()#


Delete (reset) the currently selected vector control point handles. Removes the bezier handle from the node, converting that side to a straight line. If the node has two handles, only the selected one is removed.

Returns#

void

Signature#

deleteSelectedVectorControlPoints(): void

toggleSelectedVectorNodeSmooth()#


Toggle the currently selected vector node between smooth (bezier handles) and corner (no handles).

Returns#

void

Signature#

toggleSelectedVectorNodeSmooth(): void

setVectorEditBendMode()#


Enable or disable bend mode for vector editing.

When bend mode is active, clicking an anchor node automatically toggles it between smooth (bezier handles) and corner (no handles).

Parameters#

Parameter Type Description
active boolean true to enable bend mode, false to return to normal move mode.

Returns#

void

Signature#

setVectorEditBendMode(active: boolean): void

getVectorEditBendMode()#


Check whether vector edit bend mode is currently active.

Returns#

boolean

true if bend mode is active.

Signature#

getVectorEditBendMode(): boolean

setVectorEditAddMode()#


Enable or disable add mode for vector editing.

When add mode is active, clicking on a path segment inserts a new anchor point at the click position. Mutually exclusive with bend and delete modes.

Parameters#

Parameter Type Description
active boolean true to enable add mode, false to return to normal move mode.

Returns#

void

Signature#

setVectorEditAddMode(active: boolean): void

getVectorEditAddMode()#


Check whether vector edit add mode is currently active.

Returns#

boolean

true if add mode is active.

Signature#

getVectorEditAddMode(): boolean

setVectorEditDeleteMode()#


Enable or disable delete mode for vector editing.

When delete mode is active, clicking an anchor node instantly deletes it from the path. Mutually exclusive with bend and add modes.

Parameters#

Parameter Type Description
active boolean true to enable delete mode, false to return to normal move mode.

Returns#

void

Signature#

setVectorEditDeleteMode(active: boolean): void

getVectorEditDeleteMode()#


Check whether vector edit delete mode is currently active.

Returns#

boolean

true if delete mode is active.

Signature#

getVectorEditDeleteMode(): boolean

setSelectedVectorNodeMirrorMode()#


Set the bezier handle mirror mode for the currently selected vector node.

Mirror modes control how the opposite handle behaves when one handle is dragged:

  • 0 (None): handles move independently
  • 1 (AngleAndLength): the opposite handle mirrors both angle and length
  • 2 (AngleOnly): the opposite handle mirrors the angle but keeps its own length

Parameters#

Parameter Type Description
mode number The mirror mode (0, 1, or 2).

Returns#

void

Signature#

setSelectedVectorNodeMirrorMode(mode: number): void

getSelectedVectorNodeMirrorMode()#


Get the bezier handle mirror mode of the currently selected vector node.

Returns#

number

The mirror mode as a number (0 = None, 1 = AngleAndLength, 2 = AngleOnly).

Throws#

Error if no node is selected or no vector path is being edited.

Signature#

getSelectedVectorNodeMirrorMode(): number

Viewport#

setSafeAreaInsets()#


Set global safe area insets for UI overlays.

Safe area insets define UI-safe regions by specifying padding from screen edges. These insets are automatically applied to all camera operations (zoom, pan, clamping) to ensure important content remains visible when UI elements overlap the viewport edges. Set to zero to disable (default state).

Parameters#

Parameter Type Description
insets { left?: number; top?: number; right?: number; bottom?: number; } The inset values in CSS pixels (device-independent)
insets.left? number -
insets.top? number -
insets.right? number -
insets.bottom? number -

Returns#

void

Signature#

setSafeAreaInsets(insets: object): void

getSafeAreaInsets()#


Get the current global safe area insets configuration.

Returns#

object

The current inset values in CSS pixels (device-independent)

Name Type
left number
top number
right number
bottom number

Signature#

getSafeAreaInsets(): object