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.

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;

Returns#

void

Signature#

onStateChanged(callback: () => void): () => void

onHistoryUpdated()#

Subscribe to undo/redo history changes.

const unsubscribe = engine.editor.onHistoryUpdated(() => {
  const canUndo = engine.editor.canUndo();
  const canRedo = engine.editor.canRedo();
  console.log("History updated", {canUndo, canRedo});
})

Parameters#

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

Returns#

A method to unsubscribe from the event.

(): void;

Returns#

void

Signature#

onHistoryUpdated(callback: () => void): () => 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;

Returns#

void

Signature#

onSettingsChanged(callback: () => void): () => 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;

Returns#

void

Signature#

onRoleChanged(callback: (role: RoleString) => void): () => 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');

Parameters#

Parameter	Type	Description
`mode`	`EditMode`	”Transform”, “Crop”, “Text”, “Playback”, “Trim” or a custom value.

Returns#

void

Signature#

setEditMode(mode: EditMode): 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” or a custom value.

Signature#

getEditMode(): EditMode

getCursorType()#

Get the cursor type that should be displayed.

Returns#

The cursor type.

Signature#

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

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

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`	`CutoutType`	The cutout type.
`color`	`string`	The spot color name to assign.

Returns#

void

Signature#

setSpotColorForCutoutType(type: CutoutType, color: string): void

getSpotColorForCutoutType()#

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

Parameters#

Parameter	Type	Description
`type`	`CutoutType`	The cutout type.

Returns#

string

The color spot name.

Signature#

getSpotColorForCutoutType(type: CutoutType): 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>

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[]

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.

setSettingBool()#

Set a boolean setting value.

Parameters#

Parameter	Type	Description
`keypath`	`SettingsBool`	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`
`value`	`boolean`

Returns#

void

Deprecated#

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

Signatures#

setSettingBool(keypath: SettingsBool, value: boolean): void

setSettingBool(keypath: "ubq://controlGizmo/showCropHandles" | "ubq://controlGizmo/showCropScaleHandles" | "ubq://controlGizmo/showMoveHandles" | "ubq://controlGizmo/showResizeHandles" | "ubq://controlGizmo/showRotateHandles" | "ubq://controlGizmo/showScaleHandles" | "ubq://doubleClickToCropEnabled" | "ubq://features/singlePageModeEnabled" | "ubq://features/pageCarouselEnabled" | "ubq://features/transformEditsRetainCoverMode" | "ubq://mouse/enableScroll" | "ubq://mouse/enableZoom" | "ubq://page/allowCropInteraction" | "ubq://page/allowMoveInteraction" | "ubq://page/allowResizeInteraction" | "ubq://page/allowRotateInteraction" | "ubq://page/dimOutOfPageAreas" | "ubq://page/restrictResizeInteractionToFixedAspectRatio" | "ubq://page/moveChildrenWhenCroppingFill" | "ubq://page/title/appendPageName" | "ubq://page/title/show" | "ubq://page/title/showOnSinglePage" | "ubq://page/title/showPageTitleTemplate" | "ubq://placeholderControls/showButton" | "ubq://placeholderControls/showOverlay" | "ubq://blockAnimations/enabled" | "ubq://showBuildVersion" | "ubq://touch/dragStartCanSelect" | "ubq://touch/singlePointPanning" | "ubq://useSystemFontFallback" | "ubq://forceSystemEmojis", value: boolean): void

getSettingBool()#

Get a boolean setting value.

Parameters#

Parameter	Type	Description
`keypath`	`SettingsBool`	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`

Returns#

boolean

Deprecated#

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

Signatures#

getSettingBool(keypath: SettingsBool): boolean

getSettingBool(keypath: "ubq://controlGizmo/showCropHandles" | "ubq://controlGizmo/showCropScaleHandles" | "ubq://controlGizmo/showMoveHandles" | "ubq://controlGizmo/showResizeHandles" | "ubq://controlGizmo/showRotateHandles" | "ubq://controlGizmo/showScaleHandles" | "ubq://doubleClickToCropEnabled" | "ubq://features/singlePageModeEnabled" | "ubq://features/pageCarouselEnabled" | "ubq://features/transformEditsRetainCoverMode" | "ubq://mouse/enableScroll" | "ubq://mouse/enableZoom" | "ubq://page/allowCropInteraction" | "ubq://page/allowMoveInteraction" | "ubq://page/allowResizeInteraction" | "ubq://page/allowRotateInteraction" | "ubq://page/dimOutOfPageAreas" | "ubq://page/restrictResizeInteractionToFixedAspectRatio" | "ubq://page/moveChildrenWhenCroppingFill" | "ubq://page/title/appendPageName" | "ubq://page/title/show" | "ubq://page/title/showOnSinglePage" | "ubq://page/title/showPageTitleTemplate" | "ubq://placeholderControls/showButton" | "ubq://placeholderControls/showOverlay" | "ubq://blockAnimations/enabled" | "ubq://showBuildVersion" | "ubq://touch/dragStartCanSelect" | "ubq://touch/singlePointPanning" | "ubq://useSystemFontFallback" | "ubq://forceSystemEmojis"): boolean

setSettingInt()#

Set an integer setting value.

Parameters#

Parameter	Type	Description
`keypath`	`string`	The settings keypath.
`value`	`number`	The integer value to set.

Returns#

void

Throws#

Error if the keypath is invalid.

Signature#

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

getSettingInt()#

Get an integer setting value.

Parameters#

Parameter	Type	Description
`keypath`	`string`	The settings keypath.

Returns#

number

The integer value of the setting.

Throws#

Error if the keypath is invalid.

Signature#

getSettingInt(keypath: string): number

setSettingFloat()#

Set a float setting value.

Parameters#

Parameter	Type	Description
`keypath`	`SettingsFloat`	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`
`value`	`number`

Returns#

void

Deprecated#

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

Signatures#

setSettingFloat(keypath: SettingsFloat, value: number): void

setSettingFloat(keypath: "ubq://controlGizmo/blockScaleDownLimit" | "ubq://positionSnappingThreshold" | "ubq://rotationSnappingThreshold", value: number): void

getSettingFloat()#

Get a float setting value.

Parameters#

Parameter	Type	Description
`keypath`	`SettingsFloat`	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`

Returns#

number

Deprecated#

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

Signatures#

getSettingFloat(keypath: SettingsFloat): number

getSettingFloat(keypath: "ubq://controlGizmo/blockScaleDownLimit" | "ubq://positionSnappingThreshold" | "ubq://rotationSnappingThreshold"): number

setSettingString()#

Set a string setting value.

Parameters#

Parameter	Type	Description
`keypath`	`SettingsString`	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`
`value`	`string`

Returns#

void

Deprecated#

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

Signatures#

setSettingString(keypath: SettingsString, value: string): void

setSettingString(keypath: "ubq://basePath" | "ubq://defaultEmojiFontFileUri" | "ubq://defaultFontFileUri" | "ubq://license" | "ubq://page/title/fontFileUri" | "ubq://page/title/separator" | "ubq://fallbackFontUri", value: string): void

getSettingString()#

Get a string setting value.

Parameters#

Parameter	Type	Description
`keypath`	`SettingsString`	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`

Returns#

string

Deprecated#

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

Signatures#

getSettingString(keypath: SettingsString): string

getSettingString(keypath: "ubq://basePath" | "ubq://defaultEmojiFontFileUri" | "ubq://defaultFontFileUri" | "ubq://license" | "ubq://page/title/fontFileUri" | "ubq://page/title/separator" | "ubq://fallbackFontUri"): string

setSettingColor()#

Set a color setting.

Parameters#

Parameter	Type	Description
`keypath`	`SettingsColor`	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`
`value`	`Color`

Returns#

void

Deprecated#

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

Signatures#

setSettingColor(keypath: SettingsColor, value: Color): void

setSettingColor(keypath: "ubq://borderOutlineColor" | "ubq://clearColor" | "ubq://colorMaskingSettings/maskColor" | "ubq://cropOverlayColor" | "ubq://errorStateColor" | "ubq://highlightColor" | "ubq://page/innerBorderColor" | "ubq://page/marginFillColor" | "ubq://page/marginFrameColor" | "ubq://page/outerBorderColor" | "ubq://page/title/color" | "ubq://placeholderHighlightColor" | "ubq://progressColor" | "ubq://rotationSnappingGuideColor" | "ubq://ruleOfThirdsLineColor" | "ubq://snappingGuideColor" | "ubq://textVariableHighlightColor", value: Color): void

getSettingColor()#

Get a color setting.

Parameters#

Parameter	Type	Description
`keypath`	`SettingsColor`	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`

Returns#

Color

Deprecated#

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

Signatures#

getSettingColor(keypath: SettingsColor): Color

getSettingColor(keypath: "ubq://borderOutlineColor" | "ubq://clearColor" | "ubq://colorMaskingSettings/maskColor" | "ubq://cropOverlayColor" | "ubq://errorStateColor" | "ubq://highlightColor" | "ubq://page/innerBorderColor" | "ubq://page/marginFillColor" | "ubq://page/marginFrameColor" | "ubq://page/outerBorderColor" | "ubq://page/title/color" | "ubq://placeholderHighlightColor" | "ubq://progressColor" | "ubq://rotationSnappingGuideColor" | "ubq://ruleOfThirdsLineColor" | "ubq://snappingGuideColor" | "ubq://textVariableHighlightColor"): Color

setSettingEnum()#

Set an enum setting.

Type Parameters#

Type Parameter
`T` extends keyof `SettingsEnum`

Parameters#

Parameter	Type	Description
`keypath`	`T`	The settings keypath, e.g. `doubleClickSelectionMode`.
`value`	`SettingsEnum`[`T`]	The enum value as string.

Returns#

void

Call Signature#

setSettingEnum<T>(keypath, value): void;

Type Parameters#

Type Parameter
`T` extends keyof `SettingsEnum`

Parameters#

Parameter	Type
`keypath`	`ubq://${T}`
`value`	`SettingsEnum`[`T`]

Returns#

void

Deprecated#

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

Signatures#

setSettingEnum(keypath: T, value: SettingsEnum[T]): void

setSettingEnum(keypath: `ubq://${T}`, value: SettingsEnum[T]): void

getSettingEnum()#

Get an enum setting.

Type Parameters#

Type Parameter
`T` extends keyof `SettingsEnum`

Parameters#

Parameter	Type	Description
`keypath`	`T`	The settings keypath, e.g. `doubleClickSelectionMode`.

Returns#

SettingsEnum[T]

The value as string.

Call Signature#

getSettingEnum<T>(keypath): SettingsEnum[T];

Type Parameters#

Type Parameter
`T` extends keyof `SettingsEnum`

Parameters#

Parameter	Type
`keypath`	`ubq://${T}`

Returns#

SettingsEnum[T]

Deprecated#

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

Signatures#

getSettingEnum(keypath: T): SettingsEnum[T]

getSettingEnum(keypath: `ubq://${T}`): SettingsEnum[T]

getSettingEnumOptions()#

Get the possible enum options for a given enum setting.

Type Parameters#

Type Parameter
`T` extends keyof `SettingsEnum`

Parameters#

Parameter	Type	Description
`keypath`	`T`	The settings keypath, e.g. `doubleClickSelectionMode`.

Returns#

string[]

The possible enum options as strings.

Call Signature#

getSettingEnumOptions<T>(keypath): string[];

Type Parameters#

Type Parameter
`T` extends keyof `SettingsEnum`

Parameters#

Parameter	Type
`keypath`	`ubq://${T}`

Returns#

string[]

Deprecated#

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

Signatures#

getSettingEnumOptions(keypath: T): string[]

getSettingEnumOptions(keypath: `ubq://${T}`): 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 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`	(`URI`, `defaultURIResolver`) => `string`	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: (URI: string, defaultURIResolver: (URI: string) => string) => string): 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.

If a custom resolver has been set with 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.

Parameters#

Parameter	Type	Description
`relativePath`	`string`	A relative path string

Returns#

string

The resolved absolute uri or an error if an invalid path was given.

Signature#

getAbsoluteURI(relativePath: string): 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	Default value	Description
`keypath`		`SettingsColor`	`"ubq://borderOutlineColor"`
`r`	`number`	`undefined`	The red color component in the range of 0 to 1.
`g`	`number`	`undefined`	The green color component in the range of 0 to 1.
`b`	`number`	`undefined`	The blue color component in the range of 0 to 1.
`a`	`number`	`1`	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`		`SettingsColor`

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