Class: BlockAPI | cesdk-js

Create, manipulate, and query the building blocks of your design.

This is the primary interface for all block-level operations. Use it to manage the entire lifecycle of blocks from creation and serialization to destruction. You can precisely control a block’s appearance by modifying its fills, strokes, and effects, or transform its position, size, and rotation. The API also includes powerful features for managing complex content like text and video, organizing blocks into groups and hierarchies, and exporting final designs to various formats.

Block Lifecycle#

Manage the complete lifecycle: create, find, duplicate, destroy, and serialize blocks.

loadFromString()#

Loads blocks from a serialized string.

The blocks are not attached by default and won’t be visible until attached to a page or the scene. The UUID of the loaded blocks is replaced with a new one.

Parameters#

Parameter	Type	Description
`content`	`string`	A string representing the given blocks.

Returns#

Promise<number[]>

A promise that resolves with a list of handles representing the found blocks or an error.

Example#

const serializedBlocks = await engine.block.saveToString([pageBlockId]);
// Later, load those blocks
const loadedBlocks = await engine.block.loadFromString(serializedBlocks);
// Attach the first loaded block to the scene
engine.block.appendChild(sceneBlockId, loadedBlocks[0]);

Signature#

loadFromString(content: string): Promise<number[]>

loadFromArchiveURL()#

Loads blocks from a remote archive URL.

The blocks are not attached by default and won’t be visible until attached to a page or the scene. The UUID of the loaded blocks is replaced with a new one.

Parameters#

Parameter	Type	Description
`url`	`string`	The URL to load the blocks from.

Returns#

Promise<number[]>

A promise that resolves with a list of handles representing the found blocks or an error.

Example#

// Load blocks from a remote archive
const loadedBlocks = await engine.block.loadFromArchiveURL('https://example.com/blocks.zip');
// Attach the first loaded block to the scene
engine.block.appendChild(sceneBlockId, loadedBlocks[0]);

Signature#

loadFromArchiveURL(url: string): Promise<number[]>

saveToString()#

Saves the given blocks to a serialized string.

If a page with multiple children is given, the entire hierarchy is saved.

Parameters#

Parameter	Type	Description
`blocks`	`number`[]	The blocks to save.
`allowedResourceSchemes`	`string`[]	The resource schemes to allow in the saved string. Defaults to [‘buffer’, ‘http’, ‘https’].

Returns#

Promise<string>

A promise that resolves to a string representing the blocks or an error.

Example#

// Create a page with a text element
const page = engine.block.create('page');
const text = engine.block.create('text');
engine.block.appendChild(page, text);

// Save the whole page hierarchy to a string
const serialized = await engine.block.saveToString([page]);

Signature#

saveToString(blocks: number[], allowedResourceSchemes?: string[]): Promise<string>

saveToArchive()#

Saves the given blocks and their assets to a zip archive.

The archive contains all assets that were accessible when this function was called. Blocks in the archived scene reference assets relative to the location of the scene file.

Parameters#

Parameter	Type	Description
`blocks`	`number`[]	The blocks to save.

Returns#

Promise<Blob>

A promise that resolves with a Blob on success or an error on failure.

Signature#

saveToArchive(blocks: number[]): Promise<Blob>

create()#

Creates a new block of a given type.

// Create a new text block
const text = engine.block.create('text');
const page = engine.scene.getCurrentPage();
engine.block.appendChild(page, text);

// Create a new image block
const image = engine.block.create('graphic');
engine.block.setShape(image, engine.block.createShape('rect'));
const imageFill = engine.block.createFill('image');
engine.block.setFill(image, imageFill);
engine.block.setString(imageFill, 'fill/image/imageFileURI', 'https://img.ly/static/ubq_samples/sample_1.jpg');
engine.block.appendChild(page, image);

// Create a new video block
const video = engine.block.create('graphic');
engine.block.setShape(video, engine.block.createShape('rect'));
const videoFill = engine.block.createFill('video');
engine.block.setString(videoFill, 'fill/video/fileURI', 'https://cdn.img.ly/assets/demo/v2/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4');
engine.block.setFill(video, videoFill);
engine.block.appendChild(page, video);

Parameters#

Parameter	Type	Description
`type`	`DesignBlockType`	The type of the block that shall be created.

Returns#

number

The created block’s handle.

Signature#

create(type: DesignBlockType): number

duplicate()#

Duplicates a block and its children.

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The block to duplicate.
`attachToParent`	`boolean`	`true`	Whether the duplicated block should be attached to the original’s parent. Defaults to true.

Returns#

number

The handle of the duplicate.

Signature#

duplicate(id: number, attachToParent?: boolean): number

destroy()#

Destroys a block and its children.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to destroy.

Returns#

void

Signature#

destroy(id: number): void

forceLoadResources()#

Forces the loading of resources for a set of blocks and their children.

This is useful for preloading resources. If a resource failed to load previously, it will be reloaded.

Parameters#

Parameter	Type	Description
`ids`	`number`[]	The blocks whose resources should be loaded.

Returns#

Promise<void>

A Promise that resolves once all resources have finished loading.

Signature#

forceLoadResources(ids: number[]): Promise<void>

Block Exploration#

Find blocks by properties like name, type, or kind.

findByName()#

Finds all blocks with a given name.

Parameters#

Parameter	Type	Description
`name`	`string`	The name to search for.

Returns#

number[]

A list of block ids.

Signature#

findByName(name: string): number[]

findByType()#

Finds all blocks with a given type.

Parameters#

Parameter	Type	Description
`type`	`ObjectType`	The type to search for.

Returns#

number[]

A list of block ids.

Signature#

findByType(type: ObjectType): number[]

findByKind()#

Finds all blocks with a given kind.

const allTitles = engine.block.findByKind('title');

Parameters#

Parameter	Type	Description
`kind`	`string`	The kind to search for.

Returns#

number[]

A list of block ids.

Signature#

findByKind(kind: string): number[]

findAll()#

Finds all blocks known to the engine.

Returns#

number[]

A list of block ids.

Signature#

findAll(): number[]

findAllPlaceholders()#

Finds all placeholder blocks in the current scene.

Returns#

number[]

A list of block ids.

Signature#

findAllPlaceholders(): number[]

Block Export#

Export blocks to various formats like images, videos, and audio.

export()#

Exports a design block to a Blob.

Performs an internal update to resolve the final layout for the blocks.

Parameters#

Parameter	Type	Description
`handle`	`number`	The design block element to export.
`options?`	`EngineExportOptions`	The options for exporting the block type, including mime type and export settings.

Returns#

Promise<Blob>

A promise that resolves with the exported image or is rejected with an error.

Call Signature#

export(
   handle,
   mimeType?,
options?): Promise<Blob>;

Exports a design block to a Blob.

Performs an internal update to resolve the final layout for the blocks.

Parameters#

Parameter	Type	Description
`handle`	`number`	The design block element to export.
`mimeType?`		`"application/octet-stream"`
`options?`	`Omit`<`EngineExportOptions`, `"mimeType"`>	The options for exporting the block type

Returns#

Promise<Blob>

A promise that resolves with the exported image or is rejected with an error.

Deprecated#

Use the new export signature instead

Example#

// Before migration
const blob = await cesdk.block.export(blockId, MimeType.Png, { pngCompressionLevel: 5 })
// After migration
const blob = await cesdk.block.export(blockId, { mimeType: 'image/png', pngCompressionLevel: 5 })

Signatures#

export(handle: number, options?: ExportOptions): Promise<Blob>

export(handle: number, mimeType?: "application/octet-stream" | "application/pdf" | ImageMimeType, options?: Omit<ExportOptions, "mimeType">): Promise<Blob>

exportWithColorMask()#

Exports a design block and a color mask to two separate Blobs.

Performs an internal update to resolve the final layout for the blocks.

Parameters#

Parameter	Type	Description
`handle`	`number`	The design block element to export.
`maskColorR`	`number`	The red component of the special color mask color.
`maskColorG`	`number`	The green component of the special color mask color.
`maskColorB`	`number`	The blue component of the special color mask color.
`options?`	`EngineExportOptions`	The options for exporting the block type

Returns#

Promise<Blob[]>

A promise that resolves with an array of the exported image and mask or is rejected with an error.

Call Signature#

exportWithColorMask(
   handle,
   mimeType,
   maskColorR,
   maskColorG,
   maskColorB,
options?): Promise<Blob[]>;

Exports a design block and a color mask to two separate Blobs.

Performs an internal update to resolve the final layout for the blocks. Removes all pixels that exactly match the given RGB color and replaces them with transparency. The output includes two files: the masked image and the mask itself.

Parameters#

Parameter	Type	Description
`handle`	`number`	The design block element to export.
`mimeType`		`undefined`
`maskColorR`	`number`	The red component of the special color mask color.
`maskColorG`	`number`	The green component of the special color mask color.
`maskColorB`	`number`	The blue component of the special color mask color.
`options?`	`Omit`<`EngineExportOptions`, `"mimeType"`>	The options for exporting the block type

Returns#

Promise<Blob[]>

A promise that resolves with an array of the exported image and mask or is rejected with an error.

Deprecated#

Use the new exportWithColorMask signature instead

Example#

// Before migration
const blob = await cesdk.block.exportWithColorMask(
   blockId,
   MimeType.Png,
   0.5,
   0,
   0,
   {
     pngCompressionLevel: 5
   }
);
// After migration
const blob = await cesdk.block.exportWithColorMask(
   blockId,
   0.5,
   0,
   0,
   {
     mimeType: 'image/png',
     pngCompressionLevel: 5
   }
);

Signatures#

exportWithColorMask(handle: number, maskColorR: number, maskColorG: number, maskColorB: number, options?: ExportOptions): Promise<Blob[]>

exportWithColorMask(handle: number, mimeType: undefined | "application/octet-stream" | "application/pdf" | ImageMimeType, maskColorR: number, maskColorG: number, maskColorB: number, options?: Omit<ExportOptions, "mimeType">): Promise<Blob[]>

exportVideo()#

Exports a design block as a video file.

Note: The export will run across multiple iterations of the update loop. In each iteration a frame is scheduled for encoding.

Parameters#

Parameter	Type	Description
`handle`	`number`	The design block element to export. Currently, only page blocks are supported.
`options?`	`VideoExportOptions`	The options for exporting the video, including mime type, h264 profile, level, bitrate, time offset, duration, framerate, target width and height.

Returns#

Promise<Blob>

A promise that resolves with a video blob or is rejected with an error.

Example#

const page = engine.block.create('page');
// Set up a progress tracking function
const progressTracker = (renderedFrames, encodedFrames, totalFrames) => {
  console.log(`Progress: ${Math.round((encodedFrames / totalFrames) * 100)}%`);
};
const videoOptions = { framerate: 30, duration: 5 };
const videoBlob = await engine.block.exportVideo(page, MimeType.Mp4, progressTracker, videoOptions);

Call Signature#

exportVideo(
   handle,
   mimeType?,
   progressCallback?,
options?): Promise<Blob>;

Exports a design block as a video file.

Note: The export will run across multiple iterations of the update loop. In each iteration a frame is scheduled for encoding.

Parameters#

Parameter	Type	Description
`handle`	`number`	The design block element to export. Currently, only page blocks are supported.
`mimeType?`	`VideoMimeType`	The MIME type of the output video file.
`progressCallback?`	(`numberOfRenderedFrames`, `numberOfEncodedFrames`, `totalNumberOfFrames`) => `void`	A callback which reports on the progress of the export.
`options?`	`Omit`<`VideoExportOptions`, `"mimeType"`	`"onProgress"`>

Returns#

Promise<Blob>

A promise that resolves with a video blob or is rejected with an error.

Deprecated#

Use the new exportVideo signature instead

Example#

// Before migration
const blob = await cesdk.block.exportVideo(blockId, 'video/mp4', handleProgress, {
  targetWidth: 1920,
  targetHeight: 1080,
})
// After migration
const blob = await cesdk.block.exportVideo(blockId, {
  mimeType: 'video/mp4',
  progressCallback: handleProgress,
  targetWidth: 1920,
  targetHeight: 1080,
})

Signatures#

exportVideo(handle: number, options?: VideoExportOptions): Promise<Blob>

exportVideo(handle: number, mimeType?: VideoMimeType, progressCallback?: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void, options?: Omit<VideoExportOptions, "mimeType" | "onProgress">): Promise<Blob>

unstable_exportAudio()#

Exports a design block as an audio file.

Parameters#

Parameter	Type	Description
`handle`	`number`	The design block element to export. Currently, only audio blocks are supported.
`options`	`AudioExportOptions`	The options for exporting the audio, including mime type, progress callback, and export settings.

Returns#

Promise<Blob>

A promise that resolves with an audio blob or is rejected with an error. This API is experimental and may change or be removed in future versions.

Example#

const audioBlock = engine.block.create('audio');
// Set up a progress tracking function
const progressTracker = (renderedFrames, encodedFrames, totalFrames) => {
  console.log(`Audio export progress: ${Math.round((encodedFrames / totalFrames) * 100)}%`);
};
const audioOptions = { duration: 10 };
const audioBlob = await engine.block.unstable_exportAudio(audioBlock, MimeType.Wav, progressTracker, audioOptions);

Block Hierarchies#

Manage parent-child relationships and the scene graph structure.

getParent()#

Gets the parent of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

null | number

The parent’s handle or null if the block has no parent.

Signature#

getParent(id: number): null | number

getChildren()#

Gets all direct children of a block.

Children are sorted in their rendering order: Last child is rendered in front of other children.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number[]

A list of block ids.

Signature#

getChildren(id: number): number[]

insertChild()#

Inserts a child block at a specific index.

Parameters#

Parameter	Type	Description
`parent`	`number`	The block whose children should be updated.
`child`	`number`	The child to insert. Can be an existing child of `parent`.
`index`	`number`	The index to insert or move to.

Returns#

void

Signature#

insertChild(parent: number, child: number, index: number): void

appendChild()#

Appends a child block to a parent.

Parameters#

Parameter	Type	Description
`parent`	`number`	The block whose children should be updated.
`child`	`number`	The child to insert. Can be an existing child of `parent`.

Returns#

void

Signature#

appendChild(parent: number, child: number): void

Block Layout#

Structure designs by positioning, sizing, layering, aligning, and distributing blocks.

isTransformLocked()#

Gets the transform-locked state of a block.

If true, the block’s transform can’t be changed.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True if transform locked, false otherwise.

Signature#

isTransformLocked(id: number): boolean

setTransformLocked()#

Sets the transform-locked state of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`locked`	`boolean`	Whether the block’s transform should be locked.

Returns#

void

Signature#

setTransformLocked(id: number, locked: boolean): void

getPositionX()#

Gets the X position of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The value of the x position.

Signature#

getPositionX(id: number): number

getPositionXMode()#

Gets the mode for the block’s X position.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

PositionMode

The current mode for the x position: ‘Absolute’ or ‘Percent’.

Signature#

getPositionXMode(id: number): PositionMode

getPositionY()#

Gets the Y position of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The value of the y position.

Signature#

getPositionY(id: number): number

getPositionYMode()#

Gets the mode for the block’s Y position.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

PositionMode

The current mode for the y position: ‘Absolute’ or ‘Percent’.

Signature#

getPositionYMode(id: number): PositionMode

setPositionX()#

Sets the X position of a block.

The position refers to the block’s local space, relative to its parent with the origin at the top left.

engine.block.setPositionX(block, 0.25);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`value`	`number`	The value of the x position.

Returns#

void

Signature#

setPositionX(id: number, value: number): void

setPositionXMode()#

Sets the mode for the block’s X position.

engine.block.setPositionXMode(block, 'Percent');

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`mode`	`PositionMode`	The x position mode: ‘Absolute’ or ‘Percent’.

Returns#

void

Signature#

setPositionXMode(id: number, mode: PositionMode): void

setPositionY()#

Sets the Y position of a block.

The position refers to the block’s local space, relative to its parent with the origin at the top left.

engine.block.setPositionY(block, 0.25);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`value`	`number`	The value of the y position.

Returns#

void

Signature#

setPositionY(id: number, value: number): void

setPositionYMode()#

Sets the mode for the block’s Y position.

engine.block.setPositionYMode(block, 'Absolute');

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`mode`	`PositionMode`	The y position mode: ‘Absolute’ or ‘Percent’.

Returns#

void

Signature#

setPositionYMode(id: number, mode: PositionMode): void

setAlwaysOnTop()#

Sets a block to always be rendered on top of its siblings.

If true, this block’s sorting order is automatically adjusted to be higher than all other siblings without this property.

Parameters#

Parameter	Type	Description
`id`	`number`	the block to update.
`enabled`	`boolean`	whether the block shall be always-on-top.

Returns#

void

Signature#

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

setAlwaysOnBottom()#

Sets a block to always be rendered below its siblings.

If true, this block’s sorting order is automatically adjusted to be lower than all other siblings without this property.

Parameters#

Parameter	Type	Description
`id`	`number`	the block to update.
`enabled`	`boolean`	whether the block shall always be below its siblings.

Returns#

void

Signature#

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

isAlwaysOnTop()#

Checks if a block is set to always be on top.

Parameters#

Parameter	Type	Description
`id`	`number`	the block to query.

Returns#

boolean

true if the block is set to be always-on-top, false otherwise.

Signature#

isAlwaysOnTop(id: number): boolean

isAlwaysOnBottom()#

Checks if a block is set to always be on the bottom.

Parameters#

Parameter	Type	Description
`id`	`number`	the block to query.

Returns#

boolean

true if the block is set to be always-on-bottom, false otherwise.

Signature#

isAlwaysOnBottom(id: number): boolean

bringToFront()#

Brings a block to the front of its siblings.

Updates the sorting order so that the given block has the highest sorting order.

Parameters#

Parameter	Type	Description
`id`	`number`	The id of the block to bring to the front.

Returns#

void

Signature#

bringToFront(id: number): void

sendToBack()#

Sends a block to the back of its siblings.

Updates the sorting order so that the given block has the lowest sorting order.

Parameters#

Parameter	Type	Description
`id`	`number`	The id of the block to send to the back.

Returns#

void

Signature#

sendToBack(id: number): void

bringForward()#

Brings a block one layer forward.

Updates the sorting order to be higher than its next sibling.

Parameters#

Parameter	Type	Description
`id`	`number`	The id of the block to bring forward.

Returns#

void

Signature#

bringForward(id: number): void

sendBackward()#

Sends a block one layer backward.

Updates the sorting order to be lower than its previous sibling.

Parameters#

Parameter	Type	Description
`id`	`number`	The id of the block to send backward.

Returns#

void

Signature#

sendBackward(id: number): void

getRotation()#

Gets the rotation of a block in radians.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The block’s rotation around its center in radians.

Signature#

getRotation(id: number): number

setRotation()#

Sets the rotation of a block in radians.

Rotation is applied around the block’s center.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`radians`	`number`	The new rotation in radians.

Returns#

void

Signature#

setRotation(id: number, radians: number): void

getWidth()#

Gets the width of a block.

const width = engine.block.getWidth(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The value of the block’s width.

Signature#

getWidth(id: number): number

getWidthMode()#

Gets the mode for the block’s width.

const widthMode = engine.block.getWidthMode(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

SizeMode

The current mode for the width: ‘Absolute’, ‘Percent’ or ‘Auto’.

Signature#

getWidthMode(id: number): SizeMode

getHeight()#

Gets the height of a block.

const height = engine.block.getHeight(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The value of the block’s height.

Signature#

getHeight(id: number): number

getHeightMode()#

Gets the mode for the block’s height.

const heightMode = engine.block.getHeightMode(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

SizeMode

The current mode for the height: ‘Absolute’, ‘Percent’ or ‘Auto’.

Signature#

getHeightMode(id: number): SizeMode

setWidth()#

Update a block’s width and optionally maintain the crop.

If the crop is maintained, the crop values will be automatically adjusted.

engine.block.setWidth(block, 2.5, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`value`	`number`	The new width of the block.
`maintainCrop?`	`boolean`	Whether or not the crop values, if available, should be automatically adjusted.

Returns#

void

Signature#

setWidth(id: number, value: number, maintainCrop?: boolean): void

setWidthMode()#

Sets the mode for the block’s width.

engine.block.setWidthMode(block, 'Percent');

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`mode`	`SizeMode`	The width mode: ‘Absolute’, ‘Percent’ or ‘Auto’.

Returns#

void

Signature#

setWidthMode(id: number, mode: SizeMode): void

setHeight()#

Sets the height of a block.

If the crop is maintained, the crop values will be automatically adjusted.

engine.block.setHeight(block, 0.5);
engine.block.setHeight(block, 2.5, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`value`	`number`	The new height of the block.
`maintainCrop?`	`boolean`	Whether or not the crop values, if available, should be automatically adjusted.

Returns#

void

Signature#

setHeight(id: number, value: number, maintainCrop?: boolean): void

setHeightMode()#

Sets the mode for the block’s height.

engine.block.setHeightMode(block, 'Percent');

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`mode`	`SizeMode`	The height mode: ‘Absolute’, ‘Percent’ or ‘Auto’.

Returns#

void

Signature#

setHeightMode(id: number, mode: SizeMode): void

getFrameX()#

Gets the final calculated X position of a block’s frame.

The position is only available after an internal update loop.

const frameX = engine.block.getFrameX(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The layout position on the x-axis.

Signature#

getFrameX(id: number): number

getFrameY()#

Gets the final calculated Y position of a block’s frame.

The position is only available after an internal update loop.

const frameY = engine.block.getFrameY(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The layout position on the y-axis.

Signature#

getFrameY(id: number): number

getFrameWidth()#

Gets the final calculated width of a block’s frame.

The width is only available after an internal update loop.

const frameWidth = engine.block.getFrameWidth(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The layout width.

Signature#

getFrameWidth(id: number): number

getFrameHeight()#

Gets the final calculated height of a block’s frame.

The height is only available after an internal update loop.

const frameHeight = engine.block.getFrameHeight(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The layout height.

Signature#

getFrameHeight(id: number): number

getGlobalBoundingBoxX()#

Gets the X position of the block’s global bounding box.

The position is in the scene’s global coordinate space, with the origin at the top left.

const globalX = engine.block.getGlobalBoundingBoxX(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose bounding box should be calculated.

Returns#

number

The x coordinate of the axis-aligned bounding box.

Signature#

getGlobalBoundingBoxX(id: number): number

getGlobalBoundingBoxY()#

Gets the Y position of the block’s global bounding box.

The position is in the scene’s global coordinate space, with the origin at the top left.

const globalY = engine.block.getGlobalBoundingBoxY(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose bounding box should be calculated.

Returns#

number

The y coordinate of the axis-aligned bounding box.

Signature#

getGlobalBoundingBoxY(id: number): number

getGlobalBoundingBoxWidth()#

Gets the width of the block’s global bounding box.

The width is in the scene’s global coordinate space.

const globalWidth = engine.block.getGlobalBoundingBoxWidth(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose bounding box should be calculated.

Returns#

number

The width of the axis-aligned bounding box.

Signature#

getGlobalBoundingBoxWidth(id: number): number

getGlobalBoundingBoxHeight()#

Gets the height of the block’s global bounding box.

The height is in the scene’s global coordinate space.

const globalHeight = engine.block.getGlobalBoundingBoxHeight(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose bounding box should be calculated.

Returns#

number

The height of the axis-aligned bounding box.

Signature#

getGlobalBoundingBoxHeight(id: number): number

getScreenSpaceBoundingBoxXYWH()#

Gets the screen-space bounding box for a set of blocks.

const boundingBox = engine.block.getScreenSpaceBoundingBoxXYWH([block]);

Parameters#

Parameter	Type	Description
`ids`	`number`[]	The block to query.

Returns#

XYWH

The position and size of the bounding box.

Signature#

getScreenSpaceBoundingBoxXYWH(ids: number[]): XYWH

alignHorizontally()#

Aligns blocks horizontally.

Aligns multiple blocks within their bounding box or a single block to its parent.

Parameters#

Parameter	Type	Description
`ids`	`number`[]	A non-empty array of block ids.
`horizontalBlockAlignment`	`HorizontalBlockAlignment`	How they should be aligned: ‘Left’, ‘Right’, or ‘Center’.

Returns#

void

Signature#

alignHorizontally(ids: number[], horizontalBlockAlignment: HorizontalBlockAlignment): void

alignVertically()#

Aligns blocks vertically.

Aligns multiple blocks within their bounding box or a single block to its parent.

Parameters#

Parameter	Type	Description
`ids`	`number`[]	A non-empty array of block ids.
`verticalBlockAlignment`	`VerticalBlockAlignment`	How they should be aligned: ‘Top’, ‘Bottom’, or ‘Center’.

Returns#

void

Signature#

alignVertically(ids: number[], verticalBlockAlignment: VerticalBlockAlignment): void

distributeHorizontally()#

Distributes blocks horizontally with even spacing.

Distributes multiple blocks horizontally within their bounding box.

Parameters#

Parameter	Type	Description
`ids`	`number`[]	A non-empty array of block ids.

Returns#

void

Signature#

distributeHorizontally(ids: number[]): void

distributeVertically()#

Distributes blocks vertically with even spacing.

Distributes multiple blocks vertically within their bounding box.

Parameters#

Parameter	Type	Description
`ids`	`number`[]	A non-empty array of block ids.

Returns#

void

Signature#

distributeVertically(ids: number[]): void

fillParent()#

Resizes and positions a block to fill its parent.

The crop values of the block are reset if it can be cropped.

Parameters#

Parameter	Type	Description
`id`	`number`	The block that should fill its parent.

Returns#

void

Signature#

fillParent(id: number): void

resizeContentAware()#

Resizes blocks while adjusting content to fit.

The content of the blocks is automatically adjusted to fit the new dimensions. Full-page blocks are resized to remain as full-page afterwards, while the blocks that are not full-page get resized as a group to the same scale factor and centered.

const pages = engine.scene.getPages();
engine.block.resizeContentAware(pages, width: 100.0, 100.0);

Parameters#

Parameter	Type	Description
`ids`	`number`[]	The blocks to resize.
`width`	`number`	The new width of the blocks.
`height`	`number`	The new height of the blocks.

Returns#

void

Signature#

resizeContentAware(ids: number[], width: number, height: number): void

scale()#

Scales a block and its children proportionally.

This updates the position, size and style properties (e.g. stroke width) of the block and its children around the specified anchor point.

// Scale a block to double its size, anchored at the center.
engine.block.scale(block, 2.0, 0.5, 0.5);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The block that should be scaled.
`scale`	`number`	`undefined`	The scale factor to be applied to the current properties of the block.
`anchorX`	`number`	`0`	The relative position along the width of the block around which the scaling should occur (0=left, 0.5=center, 1=right). Defaults to 0.
`anchorY`	`number`	`0`	The relative position along the height of the block around which the scaling should occur (0=top, 0.5=center, 1=bottom). Defaults to 0.

Returns#

void

Signature#

scale(id: number, scale: number, anchorX?: number, anchorY?: number): void

Block Selection & Visibility#

Manage a block’s selection state and visibility on the canvas.

select()#

Selects a block, deselecting all others.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to be selected.

Returns#

void

Signature#

select(id: number): void

setSelected()#

Sets the selection state of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.
`selected`	`boolean`	Whether or not the block should be selected.

Returns#

void

Signature#

setSelected(id: number, selected: boolean): void

isSelected()#

Gets the selection state of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True if the block is selected, false otherwise.

Signature#

isSelected(id: number): boolean

findAllSelected()#

Finds all currently selected blocks.

Returns#

number[]

An array of block ids.

Signature#

findAllSelected(): number[]

isVisible()#

Gets the visibility state of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True if visible, false otherwise.

Signature#

isVisible(id: number): boolean

setVisible()#

Sets the visibility state of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`visible`	`boolean`	Whether the block shall be visible.

Returns#

void

Signature#

setVisible(id: number, visible: boolean): void

Block Appearance#

Control general appearance, including opacity, blend modes, flipping, and other visual properties.

isClipped()#

Gets the clipped state of a block.

If true, the block should clip its contents to its frame.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True if clipped, false otherwise.

Signature#

isClipped(id: number): boolean

setClipped()#

Sets the clipped state of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`clipped`	`boolean`	Whether the block should clips its contents to its frame.

Returns#

void

Signature#

setClipped(id: number, clipped: boolean): void

getFlipHorizontal()#

Gets the horizontal flip state of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

A boolean indicating whether the block is flipped horizontally.

Signature#

getFlipHorizontal(id: number): boolean

getFlipVertical()#

Gets the vertical flip state of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

A boolean indicating whether the block is flipped vertically.

Signature#

getFlipVertical(id: number): boolean

setFlipHorizontal()#

Sets the horizontal flip state of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`flip`	`boolean`	If the flip should be enabled.

Returns#

void

Signature#

setFlipHorizontal(id: number, flip: boolean): void

setFlipVertical()#

Sets the vertical flip state of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`flip`	`boolean`	If the flip should be enabled.

Returns#

void

Signature#

setFlipVertical(id: number, flip: boolean): void

hasOpacity()#

Checks if a block has an opacity property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has an opacity.

Deprecated#

Use supportsOpacity() instead.

supportsOpacity()#

Checks if a block supports opacity.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block supports opacity.

Signature#

supportsOpacity(id: number): boolean

setOpacity()#

Sets the opacity of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose opacity should be set.
`opacity`	`number`	The opacity to be set. The valid range is 0 to 1.

Returns#

void

Signature#

setOpacity(id: number, opacity: number): void

getOpacity()#

Gets the opacity of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose opacity should be queried.

Returns#

number

The opacity value.

Signature#

getOpacity(id: number): number

hasBlendMode()#

Checks if a block has a blend mode property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has a blend mode.

Deprecated#

Use supportsBlendMode() instead.

supportsBlendMode()#

Checks if a block supports blend modes.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block supports blend modes.

Signature#

supportsBlendMode(id: number): boolean

setBlendMode()#

Sets the blend mode of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose blend mode should be set.
`blendMode`	`BlendMode`	The blend mode to be set.

Returns#

void

Signature#

setBlendMode(id: number, blendMode: BlendMode): void

getBlendMode()#

Gets the blend mode of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose blend mode should be queried.

Returns#

BlendMode

The blend mode.

Signature#

getBlendMode(id: number): BlendMode

hasBackgroundColor()#

Checks if a block has background color properties.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has background color properties.

Deprecated#

Use supportsBackgroundColor() instead.

supportsBackgroundColor()#

Checks if a block supports a background color.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block supports a background color.

Signature#

supportsBackgroundColor(id: number): boolean

setBackgroundColorRGBA()#

Sets the background color of a block using RGBA values.

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The block whose background color should be set.
`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 Use setColor() with the key path 'backgroundColor/color' instead..

getBackgroundColorRGBA()#

Gets the background color of a block as RGBA values.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose background color should be queried.

Returns#

RGBA

The background color.

Deprecated#

Use Use getColor() with the key path 'backgroundColor/color' instead..

setBackgroundColorEnabled()#

Enables or disables the background of a block.

engine.block.setBackgroundColorEnabled(block, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose background should be enabled or disabled.
`enabled`	`boolean`	If true, the background will be enabled.

Returns#

void

Signature#

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

isBackgroundColorEnabled()#

Checks if the background of a block is enabled.

const backgroundColorIsEnabled = engine.block.isBackgroundColorEnabled(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose background state should be queried.

Returns#

boolean

True, if background is enabled.

Signature#

isBackgroundColorEnabled(id: number): boolean

Block Fills#

Create, configure, and manage block fills, including solid colors, gradients, and images.

createFill()#

Creates a new fill block.

const solidColoFill = engine.block.createFill('color');
// Longhand fill types are also supported
const imageFill = engine.block.createFill('//ly.img.ubq/fill/image');

Parameters#

Parameter	Type	Description
`type`	`FillType`	The type of the fill object that shall be created.

Returns#

number

The created fill’s handle.

Signature#

createFill(type: FillType): number

hasContentFillMode()#

Checks if a block supports content fill modes.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has a content fill mode.

Deprecated#

Use supportsContentFillMode instead.

supportsContentFillMode()#

Checks if a block supports content fill modes.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has a content fill mode.

Signature#

supportsContentFillMode(id: number): boolean

setContentFillMode()#

Sets the content fill mode of a block.

engine.block.setContentFillMode(image, 'Cover');

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`mode`	`ContentFillMode`	The content fill mode: ‘Crop’, ‘Cover’ or ‘Contain’.

Returns#

void

Signature#

setContentFillMode(id: number, mode: ContentFillMode): void

getContentFillMode()#

Gets the content fill mode of a block.

engine.block.getContentFillMode(image);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

ContentFillMode

The current mode: ‘Crop’, ‘Cover’ or ‘Contain’.

Signature#

getContentFillMode(id: number): ContentFillMode

setGradientColorStops()#

Sets the color stops for a gradient property.

engine.block.setGradientColorStops(gradientFill, 'fill/gradient/colors', [
  { color: { r: 1.0, g: 0.8, b: 0.2, a: 1.0 }, stop: 0 },
  { color: { r: 0.3, g: 0.4, b: 0.7, a: 1.0 }, stop: 1 }
]);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be set.
`property`	`string`	The name of the property to set, e.g. ‘fill/gradient/colors’.
`colors`	`GradientColorStop`[]	An array of gradient color stops.

Returns#

void

Signature#

setGradientColorStops(id: number, property: string, colors: GradientColorStop[]): void

getGradientColorStops()#

Gets the color stops from a gradient property.

engine.block.getGradientColorStops(gradientFill, 'fill/gradient/colors');

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be queried.
`property`	`string`	The name of the property to query.

Returns#

GradientColorStop[]

The gradient colors.

Signature#

getGradientColorStops(id: number, property: string): GradientColorStop[]

getSourceSet()#

Gets the source set from a block property.

const sourceSet = engine.block.getSourceSet(imageFill, 'fill/image/sourceSet');

Parameters#

Parameter	Type	Description
`id`	`number`	The block that should be queried.
`property`	`string`	The name of the property to query, e.g. ‘fill/image/sourceSet’.

Returns#

Source[]

The block’s source set.

Signature#

getSourceSet(id: number, property: string): Source[]

setSourceSet()#

Sets the source set for a block property.

The crop and content fill mode of the associated block will be reset to default values.

engine.block.setSourceSet(imageFill, 'fill/image/sourceSet', [{
  uri: 'https://example.com/sample.jpg',
  width: 800,
  height: 600
}]);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be set.
`property`	`string`	The name of the property to set.
`sourceSet`	`Source`[]	The block’s new source set.

Returns#

void

Signature#

setSourceSet(id: number, property: string, sourceSet: Source[]): void

addImageFileURIToSourceSet()#

Adds an image file URI to a source set property.

If an image with the same width already exists in the source set, it will be replaced.

await engine.block.addImageFileURIToSourceSet(imageFill, 'fill/image/sourceSet', 'https://example.com/sample.jpg');

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`property`	`string`	The name of the property to modify.
`uri`	`string`	The source to add to the source set.

Returns#

Promise<void>

A promise that resolves when the operation is complete.

Signature#

addImageFileURIToSourceSet(id: number, property: string, uri: string): Promise<void>

addVideoFileURIToSourceSet()#

Adds a video file URI to a source set property.

If a video with the same width already exists in the source set, it will be replaced.

await engine.block.addVideoFileURIToSourceSet(videoFill, 'fill/video/sourceSet', 'https://example.com/sample.mp4');

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`property`	`string`	The name of the property to modify.
`uri`	`string`	The source to add to the source set.

Returns#

Promise<void>

A promise that resolves when the operation is complete.

Signature#

addVideoFileURIToSourceSet(id: number, property: string, uri: string): Promise<void>

hasFillColor()#

Checks if a block has fill color properties.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has fill color properties.

Deprecated#

Query the fill’s type using getFill() and getType() instead.

setFillColorRGBA()#

Sets the fill color of a block using RGBA values.

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The block whose fill color should be set.
`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 setFillSolidColor() instead.

getFillColorRGBA()#

Gets the fill color of a block as RGBA values.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose fill color should be queried.

Returns#

RGBA

The fill color.

Deprecated#

Use getFillSolidColor() instead.

setFillColorEnabled()#

Enables or disables the fill of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose fill should be enabled or disabled.
`enabled`	`boolean`	If true, the fill will be enabled.

Returns#

void

Deprecated#

Use setFillEnabled() instead.

isFillColorEnabled()#

Checks if the fill of a block is enabled.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose fill state should be queried.

Returns#

boolean

True, if fill is enabled.

Deprecated#

Use isFillEnabled() instead.

hasFill()#

Checks if a block has fill properties.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has fill properties.

Deprecated#

Use supportsFill instead.

supportsFill()#

Checks if a block supports a fill.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block supports a fill.

Signature#

supportsFill(id: number): boolean

isFillEnabled()#

Checks if the fill of a block is enabled.

engine.block.isFillEnabled(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose fill state should be queried.

Returns#

boolean

The fill state.

Signature#

isFillEnabled(id: number): boolean

setFillEnabled()#

Enables or disables the fill of a block.

engine.block.setFillEnabled(block, false);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose fill should be enabled or disabled.
`enabled`	`boolean`	If true, the fill will be enabled.

Returns#

void

Signature#

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

getFill()#

Gets the fill block attached to a given block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose fill block should be returned.

Returns#

number

The block that currently defines the given block’s fill.

Signature#

getFill(id: number): number

setFill()#

Sets the fill block for a given block.

The previous fill block is not destroyed automatically.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose fill should be changed.
`fill`	`number`	The new fill block.

Returns#

void

Signature#

setFill(id: number, fill: number): void

setFillSolidColor()#

Sets the solid fill color of a block.

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The block whose fill color should be set.
`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. Defaults to 1.

Returns#

void

Signature#

setFillSolidColor(id: number, r: number, g: number, b: number, a?: number): void

getFillSolidColor()#

Gets the solid fill color of a block as RGBA values.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose fill color should be queried.

Returns#

RGBA

The fill color.

Signature#

getFillSolidColor(id: number): RGBA

Block Shapes#

Create and configure shape blocks and geometric forms.

createShape()#

Creates a new shape block of a given type.

const star = engine.block.createShape('star');
// Longhand shape types are also supported
const rect = engine.block.createShape('//ly.img.ubq/shape/rect');

Parameters#

Parameter	Type	Description
`type`	`ShapeType`	The type of the shape object that shall be created.

Returns#

number

The created shape’s handle.

Signature#

createShape(type: ShapeType): number

hasShape()#

Checks if a block has a shape property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has a shape property, an error otherwise.

Deprecated#

Use supportsShape instead.

supportsShape()#

Checks if a block supports having a shape.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has a shape property, an error otherwise.

Signature#

supportsShape(id: number): boolean

getShape()#

Gets the shape block attached to a given block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose shape block should be returned.

Returns#

number

The block that currently defines the given block’s shape.

Signature#

getShape(id: number): number

setShape()#

Sets the shape block for a given block.

Note that the previous shape block is not destroyed automatically. The new shape is disconnected from its previously attached block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose shape should be changed.
`shape`	`number`	The new shape.

Returns#

void

Signature#

setShape(id: number, shape: number): void

Block Text#

Create, edit, and style text content.

replaceText()#

Replaces a range of text in a text block.

engine.block.replaceText(text, 'Hello World');
engine.block.replaceText(text, 'Alex', 6, 11);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block into which to insert the given text.
`text`	`string`	`undefined`	The text which should replace the selected range in the block.
`from`	`number`	`-1`	The start index of the UTF-16 range to replace. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range to replace. Defaults to the end of the current selection or text.

Returns#

void

Signature#

replaceText(id: number, text: string, from?: number, to?: number): void

removeText()#

Removes a range of text from a text block.

engine.block.removeText(text, 0, 6);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block from which the selected text should be removed.
`from`	`number`	`-1`	The start index of the UTF-16 range to remove. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range to remove. Defaults to the end of the current selection or text.

Returns#

void

Signature#

removeText(id: number, from?: number, to?: number): void

setTextColor()#

Sets the color for a range of text.

engine.block.setTextColor(text, { r: 0.0, g: 0.0, b: 0.0, a: 1.0 }, 1, 4);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose color should be changed.
`color`	`Color`	`undefined`	The new color of the selected text range.
`from`	`number`	`-1`	The start index of the UTF-16 range to change. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range to change. Defaults to the end of the current selection or text.

Returns#

void

Signature#

setTextColor(id: number, color: Color, from?: number, to?: number): void

getTextColors()#

Gets the unique colors within a range of text.

const colorsInRange = engine.block.getTextColors(text, 2, 5);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose colors should be returned.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

Color[]

The ordered unique list of colors.

Signature#

getTextColors(id: number, from?: number, to?: number): Color[]

setTextFontWeight()#

Sets the font weight for a range of text.

engine.block.setTextFontWeight(text, 'bold', 0, 5);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose weight should be changed.
`fontWeight`	`FontWeight`	`undefined`	The new weight of the selected text range.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

void

Signature#

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

getTextFontWeights()#

Gets the unique font weights within a range of text.

const fontWeights = engine.block.getTextFontWeights(text, 0, 6);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose font weights should be returned.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

FontWeight[]

The ordered unique list of font weights.

Signature#

getTextFontWeights(id: number, from?: number, to?: number): FontWeight[]

setTextFontSize()#

Sets the font size for a range of text.

engine.block.setTextFontSize(text, 12, 0, 5);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose font size should be changed.
`fontSize`	`number`	`undefined`	The new font size.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

void

Signature#

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

getTextFontSizes()#

Gets the unique font sizes within a range of text.

const fontSizes = engine.block.getTextFontSizes(text);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose font sizes should be returned.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

number[]

The ordered unique list of font sizes.

Signature#

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

setTextFontStyle()#

Sets the font style for a range of text.

engine.block.setTextFontStyle(text, 'italic', 0, 5);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose style should be changed.
`fontStyle`	`FontStyle`	`undefined`	The new style of the selected text range.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

void

Signature#

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

getTextFontStyles()#

Gets the unique font styles within a range of text.

const fontStyles = engine.block.getTextFontStyles(text);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose font styles should be returned.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

FontStyle[]

The ordered unique list of font styles.

Signature#

getTextFontStyles(id: number, from?: number, to?: number): FontStyle[]

getTextCases()#

Gets the unique text cases within a range of text.

const textCases = engine.block.getTextCases(text);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose text cases should be returned.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

TextCase[]

The ordered list of text cases.

Signature#

getTextCases(id: number, from?: number, to?: number): TextCase[]

setTextCase()#

Sets the text case for a range of text.

engine.block.setTextCase(text, 'Titlecase');

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose text case should be changed.
`textCase`	`TextCase`	`undefined`	The new text case value.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

void

Signature#

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

canToggleBoldFont()#

Checks if the bold font weight can be toggled for a range of text.

Returns true if any part of the range is not bold and the bold font is available.

const canToggleBold = engine.block.canToggleBoldFont(text);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block to check.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

boolean

Whether the font weight can be toggled.

Signature#

canToggleBoldFont(id: number, from?: number, to?: number): boolean

canToggleItalicFont()#

Checks if the italic font style can be toggled for a range of text.

Returns true if any part of the range is not italic and the italic font is available.

const canToggleItalic = engine.block.canToggleItalicFont(text);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block to check.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

boolean

Whether the font style can be toggled.

Signature#

canToggleItalicFont(id: number, from?: number, to?: number): boolean

toggleBoldFont()#

Toggles the font weight of a text range between bold and normal.

If any part of the range is not bold, the entire range becomes bold. If the entire range is already bold, it becomes normal.

engine.block.toggleBoldFont(text);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block to modify.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

void

Signature#

toggleBoldFont(id: number, from?: number, to?: number): void

toggleItalicFont()#

Toggles the font style of a text range between italic and normal.

If any part of the range is not italic, the entire range becomes italic. If the entire range is already italic, it becomes normal.

engine.block.toggleItalicFont(text);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block to modify.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

void

Signature#

toggleItalicFont(id: number, from?: number, to?: number): void

setFont()#

Sets the font and typeface for an entire text block.

Existing formatting is reset.

engine.block.setFont(text, font.uri, typeface);

Parameters#

Parameter	Type	Description
`id`	`number`	The text block whose font should be changed.
`fontFileUri`	`string`	The URI of the new font file.
`typeface`	`Typeface`	The typeface of the new font.

Returns#

void

Signature#

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

setTypeface()#

Sets the typeface for a range of text.

The current formatting is retained as much as possible.

engine.block.setTypeface(text, typeface, 2, 5);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose font should be changed.
`typeface`	`Typeface`	`undefined`	The new typeface.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

void

Signature#

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

getTypeface()#

Gets the base typeface of a text block.

This does not return the typefaces of individual text runs.

const defaultTypeface = engine.block.getTypeface(text);

Parameters#

Parameter	Type	Description
`id`	`number`	The text block whose typeface should be queried.

Returns#

Typeface

the typeface property of the text block.

Signature#

getTypeface(id: number): Typeface

getTypefaces()#

Gets the unique typefaces within a range of text.

const currentTypefaces = engine.block.getTypefaces(text);

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The text block whose typefaces should be queried.
`from`	`number`	`-1`	The start index of the UTF-16 range. Defaults to the start of the current selection or text.
`to`	`number`	`-1`	The end index of the UTF-16 range. Defaults to the end of the current selection or text.

Returns#

Typeface[]

The unique typefaces in the range.

Signature#

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

getTextCursorRange()#

Gets the current text cursor or selection range.

Returns the UTF-16 indices of the selected range of the text block that is currently being edited.

const selectedRange = engine.block.getTextCursorRange();

Returns#

Range

The selected UTF-16 range or { from: -1, to: -1 } if no text block is being edited.

Signature#

getTextCursorRange(): Range

getTextVisibleLineCount()#

Gets the number of visible lines in a text block.

const lineCount = engine.block.getTextVisibleLineCount(text);

Parameters#

Parameter	Type	Description
`id`	`number`	The text block whose line count should be returned.

Returns#

number

The number of lines in the text block.

Signature#

getTextVisibleLineCount(id: number): number

getTextVisibleLineGlobalBoundingBoxXYWH()#

Gets the global bounding box of a visible line of text.

The values are in the scene’s global coordinate space.

const lineBoundingBox = engine.block.getTextVisibleLineGlobalBoundingBoxXYWH(text, 0);

Parameters#

Parameter	Type	Description
`id`	`number`	The text block whose line bounding box should be returned.
`lineIndex`	`number`	The index of the line whose bounding box should be returned.

Returns#

XYWH

The bounding box of the line.

Signature#

getTextVisibleLineGlobalBoundingBoxXYWH(id: number, lineIndex: number): XYWH

getTextVisibleLineContent()#

Gets the text content of a visible line.

Parameters#

Parameter	Type	Description
`id`	`number`	The text block whose line content should be returned.
`lineIndex`	`number`	The index of the line whose content should be returned.

Returns#

string

The text content of the line.

Signature#

getTextVisibleLineContent(id: number, lineIndex: number): string

Block Video#

Manage time-based media like video and audio, including playback, timing, and controls.

createCaptionsFromURI()#

Creates new caption blocks from an SRT or VTT file URI.

Parameters#

Parameter	Type	Description
`uri`	`string`	The URI for the captions file to load. Supported file formats are: SRT and VTT.

Returns#

Promise<number[]>

A promise that resolves with a list of the created caption blocks.

Signature#

createCaptionsFromURI(uri: string): Promise<number[]>

hasDuration()#

Checks if a block has a duration property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true if the block has a duration property.

Deprecated#

Use supportsDuration instead.

supportsDuration()#

Checks if a block supports a duration property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true if the block supports a duration property.

Signature#

supportsDuration(id: number): boolean

setDuration()#

Sets the playback duration of a block.

The duration defines how long the block is active in the scene during playback.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose duration should be changed.
`duration`	`number`	The new duration in seconds.

Returns#

void

Signature#

setDuration(id: number, duration: number): void

getDuration()#

Gets the playback duration of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose duration should be returned.

Returns#

number

The block’s duration in seconds.

Signature#

getDuration(id: number): number

setPageDurationSource()#

Sets a block as the page’s duration source.

This causes the page’s total duration to be automatically determined by this block.

Parameters#

Parameter	Type	Description
`page`	`number`	The page block for which it should be enabled.
`id`	`number`	The block that should become the duration source.

Returns#

void

Signature#

setPageDurationSource(page: number, id: number): void

isPageDurationSource()#

Checks if a block is the duration source for its page.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose duration source property should be queried.

Returns#

boolean

true if the block is a duration source for a page.

Signature#

isPageDurationSource(id: number): boolean

supportsPageDurationSource()#

Checks if a block can be set as the page’s duration source.

Parameters#

Parameter	Type	Description
`page`	`number`	The page to check against.
`id`	`number`	The block to query.

Returns#

boolean

true, if the block can be marked as the page’s duration source.

Signature#

supportsPageDurationSource(page: number, id: number): boolean

removePageDurationSource()#

Removes a block as the page’s duration source.

If a scene or page is given, it is deactivated for all blocks within it.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose duration source property should be removed.

Returns#

void

Signature#

removePageDurationSource(id: number): void

hasTimeOffset()#

Checks if a block has a time offset property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has a time offset property.

Deprecated#

Use supportsTimeOffset instead.

supportsTimeOffset()#

Checks if a block supports a time offset.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block supports a time offset.

Signature#

supportsTimeOffset(id: number): boolean

setTimeOffset()#

Sets the time offset of a block relative to its parent.

The time offset controls when the block first becomes active in the timeline.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose time offset should be changed.
`offset`	`number`	The new time offset in seconds.

Returns#

void

Signature#

setTimeOffset(id: number, offset: number): void

getTimeOffset()#

Gets the time offset of a block relative to its parent.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose time offset should be queried.

Returns#

number

The time offset of the block in seconds.

Signature#

getTimeOffset(id: number): number

hasTrim()#

Checks if a block has trim properties.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has trim properties.

Deprecated#

Use supportsTrim instead.

supportsTrim()#

Checks if a block supports trim properties.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block supports trim properties.

Signature#

supportsTrim(id: number): boolean

setTrimOffset()#

Sets the trim offset of a block’s media content.

This sets the time within the media clip where playback should begin.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose trim should be updated.
`offset`	`number`	The new trim offset in seconds.

Returns#

void

Signature#

setTrimOffset(id: number, offset: number): void

getTrimOffset()#

Gets the trim offset of a block’s media content.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose trim offset should be queried.

Returns#

number

the trim offset in seconds.

Signature#

getTrimOffset(id: number): number

setTrimLength()#

Sets the trim length of a block’s media content.

This is the duration of the media clip that should be used for playback.

Parameters#

Parameter	Type	Description
`id`	`number`	The object whose trim length should be updated.
`length`	`number`	The new trim length in seconds.

Returns#

void

Signature#

setTrimLength(id: number, length: number): void

getTrimLength()#

Gets the trim length of a block’s media content.

Parameters#

Parameter	Type	Description
`id`	`number`	The object whose trim length should be queried.

Returns#

number

The trim length of the object in seconds.

Signature#

getTrimLength(id: number): number

getTotalSceneDuration()#

Gets the total duration of a scene in video mode.

Parameters#

Parameter	Type	Description
`scene`	`number`	The scene whose duration is being queried.

Returns#

number

the total scene duration.

Deprecated#

Use getDuration and pass a page block.

setPlaying()#

Sets whether a block should play its content during active playback.

Parameters#

Parameter	Type	Description
`id`	`number`	The block that should be updated.
`enabled`	`boolean`	Whether the block should be playing its contents.

Returns#

void

Signature#

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

isPlaying()#

Checks if a block is playing its content.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

whether the block is playing during playback.

Signature#

isPlaying(id: number): boolean

hasPlaybackTime()#

Checks if a block has a playback time property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

whether the block has a playback time property.

Deprecated#

Use supportsPlaybackTime instead.

supportsPlaybackTime()#

Checks if a block supports a playback time property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

whether the block supports a playback time property.

Signature#

supportsPlaybackTime(id: number): boolean

setPlaybackTime()#

Sets the current playback time of a block’s content.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose playback time should be updated.
`time`	`number`	The new playback time of the block in seconds.

Returns#

void

Signature#

setPlaybackTime(id: number, time: number): void

getPlaybackTime()#

Gets the current playback time of a block’s content.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The playback time of the block in seconds.

Signature#

getPlaybackTime(id: number): number

setSoloPlaybackEnabled()#

Enables or disables solo playback for a block.

When enabled, only this block’s content will play while the rest of the scene remains paused.

engine.block.setSoloPlaybackEnabled(videoFill, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block or fill to update.
`enabled`	`boolean`	Whether solo playback should be enabled.

Returns#

void

Signature#

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

isSoloPlaybackEnabled()#

Checks if solo playback is enabled for a block.

engine.block.isSoloPlaybackEnabled(videoFill);

Parameters#

Parameter	Type	Description
`id`	`number`	The block or fill to query.

Returns#

boolean

Whether solo playback is enabled for this block.

Signature#

isSoloPlaybackEnabled(id: number): boolean

hasPlaybackControl()#

Checks if a block has playback controls.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

Whether the block has playback control.

Deprecated#

Use supportsPlaybackControl instead

supportsPlaybackControl()#

Checks if a block supports playback controls.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

Whether the block supports playback control.

Signature#

supportsPlaybackControl(id: number): boolean

setLooping()#

Sets whether a block’s media content should loop.

Parameters#

Parameter	Type	Description
`id`	`number`	The block or video fill to update.
`looping`	`boolean`	Whether the block should loop to the beginning or stop.

Returns#

void

Signature#

setLooping(id: number, looping: boolean): void

isLooping()#

Checks if a block’s media content is set to loop.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

Whether the block is looping.

Signature#

isLooping(id: number): boolean

setMuted()#

Sets whether the audio of a block is muted.

Parameters#

Parameter	Type	Description
`id`	`number`	The block or video fill to update.
`muted`	`boolean`	Whether the audio should be muted.

Returns#

void

Signature#

setMuted(id: number, muted: boolean): void

isMuted()#

Checks if a block’s audio is muted.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

Whether the block is muted.

Signature#

isMuted(id: number): boolean

setVolume()#

Sets the audio volume of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block or video fill to update.
`volume`	`number`	The desired volume, ranging from 0.0 to 1.0.

Returns#

void

Signature#

setVolume(id: number, volume: number): void

getVolume()#

Gets the audio volume of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The volume, ranging from 0.0 to 1.0.

Signature#

getVolume(id: number): number

forceLoadAVResource()#

Forces the loading of a block’s audio/video resource.

If the resource failed to load previously, it will be reloaded.

Parameters#

Parameter	Type	Description
`id`	`number`	The video fill or audio block whose resource should be loaded.

Returns#

Promise<void>

A Promise that resolves once the resource has finished loading.

Signature#

forceLoadAVResource(id: number): Promise<void>

unstable_isAVResourceLoaded()#

Checks if a block’s audio/video resource is loaded.

Parameters#

Parameter	Type	Description
`id`	`number`	The video fill or audio block.

Returns#

boolean

The loading state of the resource. This API is experimental and may change or be removed in future versions.

getAVResourceTotalDuration()#

Gets the total duration of a block’s audio/video resource.

Parameters#

Parameter	Type	Description
`id`	`number`	The video fill or audio block.

Returns#

number

The video or audio file duration in seconds.

Signature#

getAVResourceTotalDuration(id: number): number

getVideoWidth()#

Gets the width of a block’s video resource.

Parameters#

Parameter	Type	Description
`id`	`number`	The video fill block.

Returns#

number

The video width in pixels.

Signature#

getVideoWidth(id: number): number

getVideoHeight()#

Gets the height of a block’s video resource.

Parameters#

Parameter	Type	Description
`id`	`number`	The video fill block.

Returns#

number

The video height in pixels.

Signature#

getVideoHeight(id: number): number

generateVideoThumbnailSequence()#

Generate a sequence of thumbnails for the given video fill or design block.

Note: There can only be one thumbnail generation request in progress for a given block. Note: During playback, the thumbnail generation will be paused.

Parameters#

Parameter	Type	Description
`id`	`number`	The video fill or design block.
`thumbnailHeight`	`number`	The height of each thumbnail.
`timeBegin`	`number`	The start time in seconds for the thumbnail sequence.
`timeEnd`	`number`	The end time in seconds for the thumbnail sequence.
`numberOfFrames`	`number`	The number of frames to generate.
`onFrame`	(`frameIndex`, `result`) => `void`	A callback that receives the frame index and image data.

Returns#

A function to cancel the thumbnail generation request.

(): void;

Returns#

void

Signature#

generateVideoThumbnailSequence(id: number, thumbnailHeight: number, timeBegin: number, timeEnd: number, numberOfFrames: number, onFrame: (frameIndex: number, result: ImageData | Error) => void): () => void

generateAudioThumbnailSequence()#

Generate a thumbnail sequence for the given audio block or video fill.

A thumbnail in this case is a chunk of samples in the range of 0 to 1. In case stereo data is requested, the samples are interleaved, starting with the left channel. Note: During playback, the thumbnail generation will be paused.

Parameters#

Parameter	Type	Description
`id`	`number`	The audio block or video fill.
`samplesPerChunk`	`number`	The number of samples per chunk.
`timeBegin`	`number`	The start time in seconds for the thumbnail sequence.
`timeEnd`	`number`	The end time in seconds for the thumbnail sequence.
`numberOfSamples`	`number`	The total number of samples to generate.
`numberOfChannels`	`number`	The number of channels in the output (1 for mono, 2 for stereo).
`onChunk`	(`chunkIndex`, `result`) => `void`	A callback that receives the chunk index and sample data.

Returns#

A function to cancel the thumbnail generation request.

(): void;

Returns#

void

Signature#

generateAudioThumbnailSequence(id: number, samplesPerChunk: number, timeBegin: number, timeEnd: number, numberOfSamples: number, numberOfChannels: number, onChunk: (chunkIndex: number, result: Error | Float32Array) => void): () => void

getVideoFillThumbnail()#

Generates a thumbnail for a video fill.

Parameters#

Parameter	Type	Description
`id`	`number`	The video fill.
`thumbnailHeight`	`number`	The height of a thumbnail. The width will be calculated from the video aspect ratio.

Returns#

Promise<Blob>

A promise that resolves with a thumbnail encoded as a JPEG blob.

Deprecated#

Use generateVideoThumbnailSequence instead.

getVideoFillThumbnailAtlas()#

Generates a thumbnail atlas for a video fill.

Parameters#

Parameter	Type	Description
`id`	`number`	The video fill.
`numberOfColumns`	`number`	The number of columns in the atlas.
`numberOfRows`	`number`	The number of rows in the atlas.
`thumbnailHeight`	`number`	The height of a single thumbnail.

Returns#

Promise<Blob>

A promise that resolves with a thumbnail atlas encoded as a JPEG blob.

Deprecated#

Use generateVideoThumbnailSequence instead.

getPageThumbnailAtlas()#

Generates a thumbnail atlas for a page.

Parameters#

Parameter	Type	Description
`id`	`number`	The page.
`numberOfColumns`	`number`	The number of columns in the atlas.
`numberOfRows`	`number`	The number of rows in the atlas.
`thumbnailHeight`	`number`	The height of a single thumbnail.

Returns#

Promise<Blob>

A promise that resolves with a thumbnail atlas encoded as a JPEG blob.

Deprecated#

Use generateVideoThumbnailSequence instead.

setNativePixelBuffer()#

Updates a pixel stream fill block with a new pixel buffer.

Parameters#

Parameter	Type	Description
`id`	`number`	The pixel stream fill block.
`buffer`	`HTMLCanvasElement`	`HTMLVideoElement`

Returns#

void

Signature#

setNativePixelBuffer(id: number, buffer: HTMLCanvasElement | HTMLVideoElement): void

Block Animations#

Create and manage animations and timeline-based effects.

createAnimation()#

Creates a new animation block.

Parameters#

Parameter	Type	Description
`type`	`AnimationType`	The type of animation to create.

Returns#

number

The handle of the new animation instance.

Signature#

createAnimation(type: AnimationType): number

supportsAnimation()#

Checks if a block supports animation.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

Whether the block supports animation.

Signature#

supportsAnimation(id: number): boolean

setInAnimation()#

Sets the “in” animation of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose “in” animation should be set.
`animation`	`number`	The animation to set.

Returns#

void

Signature#

setInAnimation(id: number, animation: number): void

setLoopAnimation()#

Sets the “loop” animation of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose “loop” animation should be set.
`animation`	`number`	The animation to set.

Returns#

void

Signature#

setLoopAnimation(id: number, animation: number): void

setOutAnimation()#

Sets the “out” animation of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose “out” animation should be set.
`animation`	`number`	The animation to set.

Returns#

void

Signature#

setOutAnimation(id: number, animation: number): void

getInAnimation()#

Gets the “in” animation of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose “in” animation should be queried.

Returns#

number

The “in” animation of the block.

Signature#

getInAnimation(id: number): number

getLoopAnimation()#

Gets the “loop” animation of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose “loop” animation should be queried.

Returns#

number

The “loop” animation of the block.

Signature#

getLoopAnimation(id: number): number

getOutAnimation()#

Gets the “out” animation of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose “out” animation should be queried.

Returns#

number

The “out” animation of the block.

Signature#

getOutAnimation(id: number): number

Block Groups#

Create and manage groups of blocks.

isGroupable()#

Checks if a set of blocks can be grouped.

A scene block or a block that is already part of a group cannot be grouped.

const groupable = engine.block.isGroupable([block1, block2])

Parameters#

Parameter	Type	Description
`ids`	`number`[]	An array of block ids.

Returns#

boolean

Whether the blocks can be grouped together.

Signature#

isGroupable(ids: number[]): boolean

group()#

Groups multiple blocks into a new group block.

if (engine.block.isGroupable([block1, block2])) {
  const group = engine.block.group(block1, block2]);
}

Parameters#

Parameter	Type	Description
`ids`	`number`[]	A non-empty array of block ids.

Returns#

number

The block id of the created group.

Signature#

group(ids: number[]): number

ungroup()#

Ungroups a group block, releasing its children.

engine.block.ungroup(group);

Parameters#

Parameter	Type	Description
`id`	`number`	The group id from a previous call to `group`.

Returns#

void

Signature#

ungroup(id: number): void

enterGroup()#

Changes selection to a block within a selected group.

Nothing happens if the target is not a group.

engine.block.enterGroup(group);

Parameters#

Parameter	Type	Description
`id`	`number`	The group id from a previous call to `group`.

Returns#

void

Signature#

enterGroup(id: number): void

exitGroup()#

Changes selection from a block to its parent group.

Nothing happens if the block is not part of a group.

engine.block.exitGroup(member1);

Parameters#

Parameter	Type	Description
`id`	`number`	A block id.

Returns#

void

Signature#

exitGroup(id: number): void

Block State#

Query the intrinsic state or identity of a block, such as its name, UUID, or lock status.

getType()#

Gets the longhand type of a given block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

ObjectTypeLonghand

The block’s type.

Signature#

getType(id: number): ObjectTypeLonghand

setName()#

Sets the name of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`name`	`string`	The name to set.

Returns#

void

Signature#

setName(id: number, name: string): void

getName()#

Gets the name of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

string

The block’s name.

Signature#

getName(id: number): string

getUUID()#

Gets the unique universal identifier (UUID) of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

string

The block’s UUID.

Signature#

getUUID(id: number): string

isValid()#

Checks if a block handle is valid.

A block becomes invalid once it has been destroyed.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True, if the block is valid.

Signature#

isValid(id: number): boolean

referencesAnyVariables()#

Checks if a block references any variables.

This check does not recurse into children.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to inspect.

Returns#

boolean

true if the block references variables and false otherwise.

Signature#

referencesAnyVariables(id: number): boolean

isIncludedInExport()#

Checks if a block is included in exports.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block is included on the exported result, false otherwise.

Signature#

isIncludedInExport(id: number): boolean

setIncludedInExport()#

Sets whether a block should be included in exports.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose exportable state should be set.
`enabled`	`boolean`	If true, the block will be included on the exported result.

Returns#

void

Signature#

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

isVisibleAtCurrentPlaybackTime()#

Checks if a block is visible at the current scene playback time.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

Whether the block should be visible on the canvas at the current playback time.

Signature#

isVisibleAtCurrentPlaybackTime(id: number): boolean

getState()#

Gets the current state of a block.

A block’s state is determined by its own state and that of its shape, fill, and effects.

const state = engine.block.getState(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

BlockState

The block’s state: ‘Ready’, ‘Pending’, or ‘Error’.

Signature#

getState(id: number): BlockState

setState()#

Sets the state of a block.

engine.block.setState(video, {type: 'Pending', progress: 0.5});
engine.block.setState(page, {type: 'Ready'});
engine.block.setState(image, {type: 'Error', error: 'ImageDecoding'});

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose state should be set.
`state`	`BlockState`	The new state to set.

Returns#

void

Signature#

setState(id: number, state: BlockState): void

Block Crop#

Crop, scale, translate, and transform block content.

hasCrop()#

Checks if a block has crop properties.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block has crop properties.

Deprecated#

Use supportsCrop() instead.

supportsCrop()#

Checks if a block supports cropping.

engine.block.supportsCrop(image);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

true, if the block supports cropping.

Signature#

supportsCrop(id: number): boolean

setCropScaleX()#

Sets the horizontal crop scale of a block.

engine.block.setCropScaleX(image, 2.0);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop should be set.
`scaleX`	`number`	The scale in x direction.

Returns#

void

Signature#

setCropScaleX(id: number, scaleX: number): void

setCropScaleY()#

Sets the vertical crop scale of a block.

engine.block.setCropScaleY(image, 1.5);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop should be set.
`scaleY`	`number`	The scale in y direction.

Returns#

void

Signature#

setCropScaleY(id: number, scaleY: number): void

setCropRotation()#

Sets the crop rotation of a block.

engine.block.setCropRotation(image, Math.PI);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop should be set.
`rotation`	`number`	The rotation in radians.

Returns#

void

Signature#

setCropRotation(id: number, rotation: number): void

setCropScaleRatio()#

Sets the uniform crop scale ratio of a block.

This scales the content up or down from the center of the crop frame.

engine.block.setCropScaleRatio(image, 3.0);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop should be set.
`scaleRatio`	`number`	The crop scale ratio.

Returns#

void

Signature#

setCropScaleRatio(id: number, scaleRatio: number): void

setCropTranslationX()#

Sets the horizontal crop translation of a block.

engine.block.setCropTranslationX(image, -1.0);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop should be set.
`translationX`	`number`	The translation in x direction.

Returns#

void

Signature#

setCropTranslationX(id: number, translationX: number): void

setCropTranslationY()#

Sets the vertical crop translation of a block.

engine.block.setCropTranslationY(image, 1.0);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop should be set.
`translationY`	`number`	The translation in y direction.

Returns#

void

Signature#

setCropTranslationY(id: number, translationY: number): void

resetCrop()#

Resets the crop of a block to its default state.

The block’s content fill mode is set to ‘Cover’.

engine.block.resetCrop(image);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop should be reset.

Returns#

void

Signature#

resetCrop(id: number): void

getCropScaleX()#

Gets the horizontal crop scale of a block.

const scaleX = engine.block.getCropScaleX(image);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose scale should be queried.

Returns#

number

The scale on the x axis.

Signature#

getCropScaleX(id: number): number

getCropScaleY()#

Gets the vertical crop scale of a block.

const scaleY = engine.block.getCropScaleY(image);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose scale should be queried.

Returns#

number

The scale on the y axis.

Signature#

getCropScaleY(id: number): number

getCropRotation()#

Gets the crop rotation of a block.

const cropRotation = engine.block.getCropRotation(image);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop rotation should be queried.

Returns#

number

The crop rotation in radians.

Signature#

getCropRotation(id: number): number

getCropScaleRatio()#

Gets the uniform crop scale ratio of a block.

const cropScaleRatio = engine.block.getCropScaleRatio(image);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop scale ratio should be queried.

Returns#

number

The crop scale ratio.

Signature#

getCropScaleRatio(id: number): number

getCropTranslationX()#

Gets the horizontal crop translation of a block.

const cropTranslationX = engine.block.getCropTranslationX(image);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose translation should be queried.

Returns#

number

The translation on the x axis.

Signature#

getCropTranslationX(id: number): number

getCropTranslationY()#

Gets the vertical crop translation of a block.

const cropTranslationY = engine.block.getCropTranslationY(image);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose translation should be queried.

Returns#

number

The translation on the y axis.

Signature#

getCropTranslationY(id: number): number

adjustCropToFillFrame()#

Adjusts the crop position and scale to fill the crop frame.

const adjustedScaleRatio = engine.block.adjustCropToFillFrame(image, 1.0);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop should be adjusted.
`minScaleRatio`	`number`	The minimal crop scale ratio to use.

Returns#

number

The adjusted scale ratio.

Signature#

adjustCropToFillFrame(id: number, minScaleRatio: number): number

flipCropHorizontal()#

Flips the content horizontally within its crop frame.

engine.block.flipCropHorizontal(image);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop should be updated.

Returns#

void

Signature#

flipCropHorizontal(id: number): void

flipCropVertical()#

Flips the content vertically within its crop frame.

engine.block.flipCropVertical(image);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose crop should be updated.

Returns#

void

Signature#

flipCropVertical(id: number): void

Block Events#

Subscribe to user actions and state changes related to blocks.

onSelectionChanged()#

Subscribes to changes in the selection.

Parameters#

Parameter	Type	Description
`callback`	() => `void`	This function is called at the end of the engine update if the selection has changed.

Returns#

A method to unsubscribe.

(): void;

Returns#

void

Signature#

onSelectionChanged(callback: () => void): () => void

onClicked()#

Subscribes to block click events.

Parameters#

Parameter	Type	Description
`callback`	(`id`) => `void`	This function is called at the end of the engine update if a block has been clicked.

Returns#

A method to unsubscribe.

(): void;

Returns#

void

Signature#

onClicked(callback: (id: number) => void): () => void

onStateChanged()#

Subscribes to state changes for a set of blocks.

The state is determined by the block and its associated shape, fill, and effects.

const unsubscribe = engine.block.onStateChanged([], (blocks) => {
  blocks.forEach(block => console.log(block));
});

Parameters#

Parameter	Type	Description
`ids`	`number`[]	A list of block IDs to monitor. If empty, all blocks are monitored.
`callback`	(`ids`) => `void`	The function to call when a state changes.

Returns#

A function to unsubscribe from the event.

(): void;

Returns#

void

Signature#

onStateChanged(ids: number[], callback: (ids: number[]) => void): () => void

Block Utils#

Check block capabilities like alignability or distributability.

isAlignable()#

Checks if a set of blocks can be aligned.

Parameters#

Parameter	Type	Description
`ids`	`number`[]	An array of block ids.

Returns#

boolean

Whether the blocks can be aligned.

Signature#

isAlignable(ids: number[]): boolean

isDistributable()#

Checks if a set of blocks can be distributed.

Parameters#

Parameter	Type	Description
`ids`	`number`[]	An array of block ids.

Returns#

boolean

Whether the blocks can be distributed.

Signature#

isDistributable(ids: number[]): boolean

Block Kind#

Get and set a block’s ‘kind’ identifier for custom categorization.

getKind()#

Gets the kind of a given block.

const kind = engine.block.getKind(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

string

The block’s kind.

Signature#

getKind(id: number): string

setKind()#

Sets the kind of a given block, a custom string for categorization of blocks.

engine.block.setKind(text, 'title');

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose kind should be changed.
`kind`	`string`	The new kind.

Returns#

void

Signature#

setKind(id: number, kind: string): void

Block Properties#

Get and set any block property by name using low-level, generic accessors.

findAllProperties()#

Gets all available properties of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose properties should be queried.

Returns#

string[]

A list of the property names.

Signature#

findAllProperties(id: number): string[]

isPropertyReadable()#

Checks if a property is readable.

Parameters#

Parameter	Type	Description
`property`	`string`	The name of the property to check.

Returns#

boolean

Whether the property is readable. Returns false for unknown properties.

Signature#

isPropertyReadable(property: string): boolean

isPropertyWritable()#

Checks if a property is writable.

Parameters#

Parameter	Type	Description
`property`	`string`	The name of the property to check.

Returns#

boolean

Whether the property is writable. Returns false for unknown properties.

Signature#

isPropertyWritable(property: string): boolean

getPropertyType()#

Gets the type of a property by its name.

Parameters#

Parameter	Type	Description
`property`	`string`	The name of the property whose type should be queried.

Returns#

PropertyType

The property type.

Signature#

getPropertyType(property: string): PropertyType

getEnumValues()#

Gets all possible values of an enum property.

Type Parameters#

Type Parameter	Default type
`T`	`string`

Parameters#

Parameter	Type	Description
`enumProperty`	`string`	The name of the property whose enum values should be queried.

Returns#

T[]

A list of the enum value names as a string array.

Signature#

getEnumValues(enumProperty: string): T[]

setBool()#

Sets a boolean property on a block.

engine.block.setBool(scene, 'scene/aspectRatioLock', false);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be set.
`property`	`string`	The name of the property to set.
`value`	`boolean`	The value to set.

Returns#

void

Signature#

setBool(id: number, property: string, value: boolean): void

getBool()#

Gets a boolean property from a block.

engine.block.getBool(scene, 'scene/aspectRatioLock');

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be queried.
`property`	`string`	The name of the property to query.

Returns#

boolean

The value of the property.

Signature#

getBool(id: number, property: string): boolean

setInt()#

Sets an integer property on a block.

engine.block.setInt(starShape, 'shape/star/points', points + 2);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be set.
`property`	`string`	The name of the property to set.
`value`	`number`	The value to set.

Returns#

void

Signature#

setInt(id: number, property: string, value: number): void

getInt()#

Gets an integer property from a block.

engine.block.setInt(starShape, 'shape/star/points', points + 2);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be queried.
`property`	`string`	The name of the property to query.

Returns#

number

The value of the property.

Signature#

getInt(id: number, property: string): number

setFloat()#

Sets a float property on a block.

engine.block.setFloat(text, "text/letterSpacing", 0.2);
engine.block.setFloat(text, "text/lineHeight", 1.2);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be set.
`property`	`string`	The name of the property to set.
`value`	`number`	The value to set.

Returns#

void

Signature#

setFloat(id: number, property: string, value: number): void

getFloat()#

Gets a float property from a block.

engine.block.getFloat(starShape, 'shape/star/innerDiameter');

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be queried.
`property`	`string`	The name of the property to query.

Returns#

number

The value of the property.

Signature#

getFloat(id: number, property: string): number

setDouble()#

Sets a double-precision float property on a block.

engine.block.setDouble(audio, 'playback/duration', 1.0);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be set.
`property`	`string`	The name of the property to set.
`value`	`number`	The value to set.

Returns#

void

Signature#

setDouble(id: number, property: string, value: number): void

getDouble()#

Gets a double-precision float property from a block.

engine.block.getDouble(audio, 'playback/duration');

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be queried.
`property`	`string`	The name of the property to query.

Returns#

number

The value of the property.

Signature#

getDouble(id: number, property: string): number

setString()#

Sets a string property on a block.

engine.block.setString(text, 'text/text', 'Hello World');
engine.block.setString(imageFill, 'fill/image/imageFileURI', 'https://example.com/sample.jpg');

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be set.
`property`	`string`	The name of the property to set.
`value`	`string`	The value to set.

Returns#

void

Signature#

setString(id: number, property: string, value: string): void

getString()#

Gets a string property from a block.

engine.block.getString(text, 'text/text');
engine.block.getString(imageFill, 'fill/image/imageFileURI');

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be queried.
`property`	`string`	The name of the property to query.

Returns#

string

The value of the property.

Signature#

getString(id: number, property: string): string

setColor()#

Sets a color property on a block.

// Set the block's fill color to white.
engine.block.setColor(colorFill, 'fill/color/value', { r: 1, g: 1, b: 1, a: 1 });

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be set.
`property`	`string`	The name of the property to set.
`value`	`Color`	The value to set.

Returns#

void

Signature#

setColor(id: number, property: string, value: Color): void

getColor()#

Gets a color property from a block.

engine.block.getColor(colorFill, 'fill/color/value');

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be queried.
`property`	`string`	The name of the property to query.

Returns#

Color

The value of the property.

Signature#

getColor(id: number, property: string): Color

setColorRGBA()#

Sets a color property on a block using RGBA values.

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The block whose property should be set.
`property`	`string`	`undefined`	The name of the property to set.
`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. Defaults to 1.

Returns#

void

Deprecated#

Use setColor() instead.

getColorRGBA()#

Gets a color property from a block as RGBA values.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be queried.
`property`	`string`	The name of the property to query.

Returns#

RGBA

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

Deprecated#

Use getColor() instead.

setColorSpot()#

Sets a spot color property on a block.

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The block whose property should be set.
`property`	`string`	`undefined`	The name of the property to set.
`name`	`string`	`undefined`	The name of the spot color.
`tint`	`number`	`1`	The tint factor in the range of 0 to 1. Defaults to 1.

Returns#

void

Deprecated#

Use setColor() instead.

getColorSpotName()#

Gets the spot color name from a color property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be queried.
`property`	`string`	The name of the property to query.

Returns#

string

The name of the spot color.

Deprecated#

Use getColor() instead.

getColorSpotTint()#

Gets the spot color tint from a color property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be queried.
`property`	`string`	The name of the property to query.

Returns#

number

The tint factor of the spot color.

Deprecated#

Use getColor() instead.

setEnum()#

Sets an enum property on a block.

engine.block.setEnum(text, 'text/horizontalAlignment', 'Center');
engine.block.setEnum(text, 'text/verticalAlignment', 'Center');

Type Parameters#

Type Parameter	Default type
`T` extends `string`	`string`

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be set.
`property`	`string`	The name of the property to set.
`value`	`T`	The enum value as a string.

Returns#

void

Signature#

setEnum(id: number, property: string, value: T): void

getEnum()#

Gets an enum property from a block.

engine.block.getEnum(text, 'text/horizontalAlignment');
engine.block.getEnum(text, 'text/verticalAlignment');

Type Parameters#

Type Parameter	Default type
`T` extends `string`	`string`

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose property should be queried.
`property`	`string`	The name of the property to query.

Returns#

T

The value as a string.

Signature#

getEnum(id: number, property: string): T

Block Strokes#

Control stroke appearance, including color, width, style, and position.

hasStroke()#

Checks if a block has a stroke property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True if the block has a stroke property.

Deprecated#

Use supportsStroke() instead.

supportsStroke()#

Checks if a block supports a stroke.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True if the block supports a stroke.

Signature#

supportsStroke(id: number): boolean

setStrokeEnabled()#

Enables or disables the stroke of a block.

engine.block.setStrokeEnabled(block, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke should be enabled or disabled.
`enabled`	`boolean`	If true, the stroke will be enabled.

Returns#

void

Signature#

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

isStrokeEnabled()#

Checks if the stroke of a block is enabled.

const strokeIsEnabled = engine.block.isStrokeEnabled(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke state should be queried.

Returns#

boolean

True if the block’s stroke is enabled.

Signature#

isStrokeEnabled(id: number): boolean

setStrokeColorRGBA()#

Sets the stroke color of a block using RGBA values.

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The block whose stroke color should be set.
`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 setStrokeColor() instead.

setStrokeColor()#

Sets the stroke color of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke color should be set.
`color`	`Color`	The color to set.

Returns#

void

Signature#

setStrokeColor(id: number, color: Color): void

getStrokeColorRGBA()#

Gets the stroke color of a block as RGBA values.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke color should be queried.

Returns#

RGBA

The stroke color.

Deprecated#

Use getStrokeColor() instead.

getStrokeColor()#

Gets the stroke color of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke color should be queried.

Returns#

Color

The stroke color.

Signature#

getStrokeColor(id: number): Color

setStrokeWidth()#

Sets the stroke width of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke width should be set.
`width`	`number`	The stroke width to be set.

Returns#

void

Signature#

setStrokeWidth(id: number, width: number): void

getStrokeWidth()#

Gets the stroke width of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke width should be queried.

Returns#

number

The stroke’s width.

Signature#

getStrokeWidth(id: number): number

setStrokeStyle()#

Sets the stroke style of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke style should be set.
`style`	`StrokeStyle`	The stroke style to be set.

Returns#

void

Signature#

setStrokeStyle(id: number, style: StrokeStyle): void

getStrokeStyle()#

Gets the stroke style of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke style should be queried.

Returns#

StrokeStyle

The stroke’s style.

Signature#

getStrokeStyle(id: number): StrokeStyle

setStrokePosition()#

Sets the stroke position of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke position should be set.
`position`	`StrokePosition`	The stroke position to be set.

Returns#

void

Signature#

setStrokePosition(id: number, position: StrokePosition): void

getStrokePosition()#

Gets the stroke position of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke position should be queried.

Returns#

StrokePosition

The stroke position.

Signature#

getStrokePosition(id: number): StrokePosition

setStrokeCornerGeometry()#

Sets the stroke corner geometry of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke corner geometry should be set.
`cornerGeometry`	`StrokeCornerGeometry`	The stroke corner geometry to be set.

Returns#

void

Signature#

setStrokeCornerGeometry(id: number, cornerGeometry: StrokeCornerGeometry): void

getStrokeCornerGeometry()#

Gets the stroke corner geometry of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose stroke corner geometry should be queried.

Returns#

StrokeCornerGeometry

The stroke corner geometry.

Signature#

getStrokeCornerGeometry(id: number): StrokeCornerGeometry

Block Drop Shadow#

Configure drop shadow effects, including blur, color, and offset.

hasDropShadow()#

Checks if a block has a drop shadow property.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True if the block has a drop shadow property.

Deprecated#

Use supportsDropShadow() instead.

supportsDropShadow()#

Checks if a block supports a drop shadow.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True if the block supports a drop shadow.

Signature#

supportsDropShadow(id: number): boolean

setDropShadowEnabled()#

Enables or disables the drop shadow of a block.

engine.block.setDropShadowEnabled(block, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow should be enabled or disabled.
`enabled`	`boolean`	If true, the drop shadow will be enabled.

Returns#

void

Signature#

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

isDropShadowEnabled()#

Checks if the drop shadow of a block is enabled.

const dropShadowIsEnabled = engine.block.isDropShadowEnabled(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow state should be queried.

Returns#

boolean

True if the block’s drop shadow is enabled.

Signature#

isDropShadowEnabled(id: number): boolean

setDropShadowColorRGBA()#

Sets the drop shadow color of a block using RGBA values.

Parameters#

Parameter	Type	Default value	Description
`id`	`number`	`undefined`	The block whose drop shadow color should be set.
`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 setDropShadowColor() instead.

setDropShadowColor()#

Sets the drop shadow color of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow color should be set.
`color`	`Color`	The color to set.

Returns#

void

Signature#

setDropShadowColor(id: number, color: Color): void

getDropShadowColorRGBA()#

Gets the drop shadow color of a block as RGBA values.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow color should be queried.

Returns#

RGBA

The drop shadow color.

Deprecated#

Use getDropShadowColor instead.

getDropShadowColor()#

Gets the drop shadow color of a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow color should be queried.

Returns#

Color

The drop shadow color.

Signature#

getDropShadowColor(id: number): Color

setDropShadowOffsetX()#

Sets the drop shadow’s horizontal offset.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow’s X offset should be set.
`offsetX`	`number`	The X offset to be set.

Returns#

void

Signature#

setDropShadowOffsetX(id: number, offsetX: number): void

getDropShadowOffsetX()#

Gets the drop shadow’s horizontal offset.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow’s X offset should be queried.

Returns#

number

The offset.

Signature#

getDropShadowOffsetX(id: number): number

setDropShadowOffsetY()#

Sets the drop shadow’s vertical offset.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow’s Y offset should be set.
`offsetY`	`number`	The Y offset to be set.

Returns#

void

Signature#

setDropShadowOffsetY(id: number, offsetY: number): void

getDropShadowOffsetY()#

Gets the drop shadow’s vertical offset.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow’s Y offset should be queried.

Returns#

number

The offset.

Signature#

getDropShadowOffsetY(id: number): number

setDropShadowBlurRadiusX()#

Sets the drop shadow’s horizontal blur radius.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow’s blur radius should be set.
`blurRadiusX`	`number`	The blur radius to be set.

Returns#

void

Signature#

setDropShadowBlurRadiusX(id: number, blurRadiusX: number): void

getDropShadowBlurRadiusX()#

Gets the drop shadow’s horizontal blur radius.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow’s blur radius should be queried.

Returns#

number

The blur radius.

Signature#

getDropShadowBlurRadiusX(id: number): number

setDropShadowBlurRadiusY()#

Sets the drop shadow’s vertical blur radius.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow’s blur radius should be set.
`blurRadiusY`	`number`	The blur radius to be set.

Returns#

void

Signature#

setDropShadowBlurRadiusY(id: number, blurRadiusY: number): void

getDropShadowBlurRadiusY()#

Gets the drop shadow’s vertical blur radius.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow’s blur radius should be queried.

Returns#

number

The blur radius.

Signature#

getDropShadowBlurRadiusY(id: number): number

setDropShadowClip()#

Sets the drop shadow’s clipping behavior.

This only applies to shapes.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow’s clip should be set.
`clip`	`boolean`	The drop shadow’s clip to be set.

Returns#

void

Signature#

setDropShadowClip(id: number, clip: boolean): void

getDropShadowClip()#

Gets the drop shadow’s clipping behavior.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose drop shadow’s clipping should be queried.

Returns#

boolean

The drop shadow’s clipping state.

Signature#

getDropShadowClip(id: number): boolean

Block Effects#

Create, manage, and apply various visual effects to blocks.

createEffect()#

Creates a new effect block.

Parameters#

Parameter	Type	Description
`type`	`EffectType`	The type of the effect.

Returns#

number

The created effect’s handle.

Signature#

createEffect(type: EffectType): number

hasEffects()#

Checks if a block supports effects.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True, if the block can render effects, false otherwise.

Deprecated#

Use supportsEffects instead.

supportsEffects()#

Checks if a block supports effects.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True, if the block can render effects, false otherwise.

Signature#

supportsEffects(id: number): boolean

getEffects()#

Gets all effects attached to a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number[]

A list of effects or an error, if the block doesn’t support effects.

Signature#

getEffects(id: number): number[]

insertEffect()#

Inserts an effect into a block’s effect list at a given index.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`effectId`	`number`	The effect to insert.
`index`	`number`	The index at which the effect shall be inserted.

Returns#

void

Signature#

insertEffect(id: number, effectId: number, index: number): void

appendEffect()#

Appends an effect to a block’s effect list.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to append the effect to.
`effectId`	`number`	The effect to append.

Returns#

void

Signature#

appendEffect(id: number, effectId: number): void

removeEffect()#

Removes an effect from a block’s effect list at a given index.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to remove the effect from.
`index`	`number`	The index where the effect is stored.

Returns#

void

Signature#

removeEffect(id: number, index: number): void

hasEffectEnabled()#

Checks if an effect block can be enabled or disabled.

Parameters#

Parameter	Type	Description
`effectId`	`number`	The ‘effect’ block to query.

Returns#

boolean

True, if the block supports enabling and disabling, false otherwise.

Deprecated#

Calls to this function can be removed. All effects can be enabled and disabled.

setEffectEnabled()#

Sets the enabled state of an effect block.

engine.block.setEffectEnabled(effects[0], false);

Parameters#

Parameter	Type	Description
`effectId`	`number`	The ‘effect’ block to update.
`enabled`	`boolean`	The new state.

Returns#

void

Signature#

setEffectEnabled(effectId: number, enabled: boolean): void

isEffectEnabled()#

Queries if an effect block is enabled.

engine.block.isEffectEnabled(effects[0]);

Parameters#

Parameter	Type	Description
`effectId`	`number`	The ‘effect’ block to query.

Returns#

boolean

True, if the effect is enabled. False otherwise.

Signature#

isEffectEnabled(effectId: number): boolean

Block Blur#

Apply and configure blur effects on blocks.

createBlur()#

Creates a new blur block.

Parameters#

Parameter	Type	Description
`type`	`BlurType`	The type of blur.

Returns#

number

The handle of the newly created blur.

Signature#

createBlur(type: BlurType): number

hasBlur()#

Checks if a block supports blur.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True, if the block supports blur.

Deprecated#

Use supportsBlur instead.

supportsBlur()#

Checks if a block supports blur.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True, if the block supports blur.

Signature#

supportsBlur(id: number): boolean

setBlur()#

Sets the blur effect for a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`blurId`	`number`	A ‘blur’ block to apply.

Returns#

void

Signature#

setBlur(id: number, blurId: number): void

getBlur()#

Gets the blur block of a given design block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

number

The ‘blur’ block.

Signature#

getBlur(id: number): number

setBlurEnabled()#

Enables or disables the blur effect on a block.

engine.block.setBlurEnabled(block, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`enabled`	`boolean`	The new enabled value.

Returns#

void

Signature#

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

isBlurEnabled()#

Checks if blur is enabled for a block.

const isBlurEnabled = engine.block.isBlurEnabled(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True, if the blur is enabled. False otherwise.

Signature#

isBlurEnabled(id: number): boolean

Block Placeholder#

Manage placeholder functionality, controls, and behavior.

setPlaceholderEnabled()#

Enables or disables the placeholder function for a block.

When set to true, the placeholder capabilities are enabled in Adopter mode.

engine.block.setPlaceholderEnabled(block, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose placeholder function should be enabled or disabled.
`enabled`	`boolean`	Whether the function should be enabled or disabled.

Returns#

void

Signature#

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

isPlaceholderEnabled()#

Checks if the placeholder function for a block is enabled.

const placeholderIsEnabled = engine.block.isPlaceholderEnabled(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose placeholder function state should be queried.

Returns#

boolean

The enabled state of the placeholder function.

Signature#

isPlaceholderEnabled(id: number): boolean

hasPlaceholderBehavior()#

Checks if a block supports placeholder behavior.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True, if the block supports placeholder behavior.

Deprecated#

Use supportsPlaceholderBehavior instead.

supportsPlaceholderBehavior()#

Checks if a block supports placeholder behavior.

const placeholderBehaviorSupported = engine.block.supportsPlaceholderBehavior(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True, if the block supports placeholder behavior.

Signature#

supportsPlaceholderBehavior(id: number): boolean

setPlaceholderBehaviorEnabled()#

Enables or disables the placeholder behavior for a block.

engine.block.setPlaceholderBehaviorEnabled(block, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose placeholder behavior should be enabled or disabled.
`enabled`	`boolean`	Whether the placeholder behavior should be enabled or disabled.

Returns#

void

Signature#

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

isPlaceholderBehaviorEnabled()#

Checks if the placeholder behavior for a block is enabled.

engine.block.setPlaceholderBehaviorEnabled(block, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose placeholder behavior state should be queried.

Returns#

boolean

The enabled state of the placeholder behavior.

Signature#

isPlaceholderBehaviorEnabled(id: number): boolean

hasPlaceholderControls()#

Checks if a block supports placeholder controls.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True, if the block supports placeholder controls.

Deprecated#

Use supportsPlaceholderControls instead.

supportsPlaceholderControls()#

Checks if a block supports placeholder controls.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to query.

Returns#

boolean

True, if the block supports placeholder controls.

Signature#

supportsPlaceholderControls(id: number): boolean

setPlaceholderControlsOverlayEnabled()#

Enables or disables the placeholder overlay pattern.

engine.block.setPlaceholderControlsOverlayEnabled(block, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose placeholder overlay should be enabled or disabled.
`enabled`	`boolean`	Whether the placeholder overlay should be shown or not.

Returns#

void

Signature#

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

isPlaceholderControlsOverlayEnabled()#

Checks if the placeholder overlay pattern is enabled.

const overlayEnabled = engine.block.isPlaceholderControlsOverlayEnabled(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose placeholder overlay visibility state should be queried.

Returns#

boolean

The visibility state of the block’s placeholder overlay pattern.

Signature#

isPlaceholderControlsOverlayEnabled(id: number): boolean

setPlaceholderControlsButtonEnabled()#

Enables or disables the placeholder button.

engine.block.setPlaceholderControlsButtonEnabled(block, true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose placeholder button should be shown or not.
`enabled`	`boolean`	Whether the placeholder button should be shown or not.

Returns#

void

Signature#

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

isPlaceholderControlsButtonEnabled()#

Checks if the placeholder button is enabled.

const buttonEnabled = engine.block.isPlaceholderControlsButtonEnabled(block);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose placeholder button visibility state should be queried.

Returns#

boolean

The visibility state of the block’s placeholder button.

Signature#

isPlaceholderControlsButtonEnabled(id: number): boolean

Block Scopes#

Manage permissions and capabilities per block.

setScopeEnabled()#

Enables or disables a scope for a block.

// Allow the user to move the image block.
engine.block.setScopeEnabled(image, 'layer/move', true);

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose scope should be enabled or disabled.
`key`	`Scope`	The scope to enable or disable.
`enabled`	`boolean`	Whether the scope should be enabled or disabled.

Returns#

void

Signature#

setScopeEnabled(id: number, key: Scope, enabled: boolean): void

isScopeEnabled()#

Checks if a scope is enabled for a block.

engine.block.isScopeEnabled(image, 'layer/move');

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose scope state should be queried.
`key`	`Scope`	The scope to query.

Returns#

boolean

The enabled state of the scope for the given block.

Signature#

isScopeEnabled(id: number, key: Scope): boolean

isAllowedByScope()#

Checks if an operation is allowed by a block’s scopes.

// This will return true when the global scope is set to 'Defer'.
engine.block.isAllowedByScope(image, 'layer/move');

Parameters#

Parameter	Type	Description
`id`	`number`	The block to check.
`key`	`Scope`	The scope to check.

Returns#

boolean

Whether the scope is allowed for the given block.

Signature#

isAllowedByScope(id: number, key: Scope): boolean

Block Boolean Operations#

Combine multiple blocks into a single new block using boolean path operations.

isCombinable()#

Checks if a set of blocks can be combined using a boolean operation.

Only graphics blocks and text blocks can be combined. All blocks must have the “lifecycle/duplicate” scope enabled.

Parameters#

Parameter	Type	Description
`ids`	`number`[]	An array of block ids.

Returns#

boolean

Whether the blocks can be combined.

Signature#

isCombinable(ids: number[]): boolean

combine()#

Performs a boolean operation on a set of blocks.

All blocks must be combinable. See isCombinable. The parent, fill and sort order of the new block is that of the prioritized block.

Parameters#

Parameter	Type	Description
`ids`	`number`[]	The blocks to combine. They will be destroyed if “lifecycle/destroy” scope is enabled.
`op`	`BooleanOperation`	The boolean operation to perform.

Returns#

number

The newly created block or an error.

Signature#

combine(ids: number[], op: BooleanOperation): number

Block Cutout#

Create cutout operations and path-based modifications.

createCutoutFromBlocks()#

Creates a cutout block from the contours of other blocks.

The path is derived from either existing vector paths or by vectorizing the block’s appearance.

Parameters#

Parameter	Type	Default value	Description
`ids`	`number`[]	`undefined`	The blocks whose shape will serve as the basis for the cutout’s path.
`vectorizeDistanceThreshold`	`number`	`2`	Max deviation from the original contour during vectorization.
`simplifyDistanceThreshold`	`number`	`4`	Max deviation for path simplification. 0 disables simplification.
`useExistingShapeInformation`	`boolean`	`true`	If true, use existing vector paths.

Returns#

number

The newly created block or an error.

Signature#

createCutoutFromBlocks(ids: number[], vectorizeDistanceThreshold?: number, simplifyDistanceThreshold?: number, useExistingShapeInformation?: boolean): number

createCutoutFromPath()#

Creates a cutout block from an SVG path string.

Parameters#

Parameter	Type	Description
`path`	`string`	An SVG string describing a path.

Returns#

number

The newly created block or an error.

Signature#

createCutoutFromPath(path: string): number

createCutoutFromOperation()#

Creates a new cutout block by performing a boolean operation on existing cutout blocks.

Parameters#

Parameter	Type	Description
`ids`	`number`[]	The cutout blocks with which to perform to the operation.
`op`	`CutoutOperation`	The boolean operation to perform.

Returns#

number

The newly created block or an error.

Signature#

createCutoutFromOperation(ids: number[], op: CutoutOperation): number

Block Metadata#

setMetadata()#

Sets a metadata value for a given key on a block.

If the key does not exist, it will be added.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose metadata will be accessed.
`key`	`string`	The key used to identify the desired piece of metadata.
`value`	`string`	The value to set.

Returns#

void

Signature#

setMetadata(id: number, key: string, value: string): void

getMetadata()#

Gets a metadata value for a given key from a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose metadata will be accessed.
`key`	`string`	The key used to identify the desired piece of metadata.

Returns#

string

The value associated with the key.

Signature#

getMetadata(id: number, key: string): string

hasMetadata()#

Checks if a block has metadata for a given key.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose metadata will be accessed.
`key`	`string`	The key used to identify the desired piece of metadata.

Returns#

boolean

Whether the key exists.

Signature#

hasMetadata(id: number, key: string): boolean

findAllMetadata()#

Finds all metadata keys on a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose metadata will be accessed.

Returns#

string[]

A list of all metadata keys on this block.

Signature#

findAllMetadata(id: number): string[]

removeMetadata()#

Removes metadata for a given key from a block.

Parameters#

Parameter	Type	Description
`id`	`number`	The block whose metadata will be accessed.
`key`	`string`	The key used to identify the desired piece of metadata.

Returns#

void

Signature#

removeMetadata(id: number, key: string): void

Other#

setSize()#

Update a block’s size.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`width`	`number`	The new width of the block.
`height`	`number`	The new height of the block.
`options?`	{ `maintainCrop?`: `boolean`; `sizeMode?`: `SizeMode`; }	Optional parameters for the size. Properties: - `maintainCrop` - Whether or not the crop values, if available, should be automatically adjusted. - `sizeMode` - The size mode: Absolute, Percent or Auto.
`options.maintainCrop?`	`boolean`	-
`options.sizeMode?`	`SizeMode`	-

Returns#

void

Signature#

setSize(id: number, width: number, height: number, options?: object): void

setPosition()#

Update a block’s position.

Parameters#

Parameter	Type	Description
`id`	`number`	The block to update.
`x`	`number`	The new x position of the block.
`y`	`number`	The new y position of the block.
`options?`	{ `positionMode?`: `PositionMode`; }	Optional parameters for the position. Properties: - `positionMode` - The position mode: absolute, percent or undefined.
`options.positionMode?`	`PositionMode`	-

Returns#

void

Signature#

setPosition(id: number, x: number, y: number, options?: object): void

addImage()#

Adds an image to the current page. The image will be automatically loaded and sized appropriately. In Video mode, timeline and animation options can be applied.

Parameters#

Parameter	Type	Description
`url`	`string`	URL or path to the image file
`options`	`AddImageOptions`	Configuration options for the image

Returns#

Promise<number>

Promise that resolves to the ID of the created image block

Throws#

Error if no current page exists

Signature#

addImage(url: string, options?: AddImageOptions): Promise<number>

addVideo()#

Adds a video block to the current scene page. The video will be positioned and sized according to the provided parameters. Timeline and animation effects can be applied. Only works in Video mode, not in Design mode.

Parameters#

Parameter	Type	Description
`url`	`string`	URL or path to the video file
`width`	`number`	Width of the video in scene design units
`height`	`number`	Height of the video in scene design units
`options`	`AddVideoOptions`	Configuration options for the video

Returns#

Promise<number>

Promise that resolves to the ID of the created video block

Throws#

Error if called in Design mode or if no current page exists

Signature#

addVideo(url: string, width: number, height: number, options?: AddVideoOptions): Promise<number>

applyAnimation()#

Applies an animation to a block.

Parameters#

Parameter	Type	Description
`block`	`number`	The ID of the block to apply the animation to
`animation`	`AnimationOptions`	The animation configuration options

Returns#

void

Signature#

applyAnimation(block: number, animation?: AnimationOptions): void

applyDropShadow()#

Applies a drop shadow effect to any block.

Parameters#

Parameter	Type	Description
`block`	`number`	The ID of the block to apply the shadow to
`options`	`DropShadowOptions`	Shadow configuration options. If not provided, enables shadow with default settings

Returns#

void

Signature#

applyDropShadow(block: number, options?: DropShadowOptions): void

generateThumbnailAtTimeOffset()#

Generates a thumbnail image of the scene at a specific time. Only works in Video mode, not in Design mode.

Parameters#

Parameter	Type	Description
`height`	`number`	Height of the thumbnail in scene design units (maximum 512)
`time`	`number`	Time position in seconds to capture the thumbnail

Returns#

Promise<Blob>

Promise that resolves to a Blob containing the PNG thumbnail image

Throws#

Error if no page exists, if called in Design mode, or if height exceeds 512 pixels

Signature#

generateThumbnailAtTimeOffset(height: number, time: number): Promise<Blob>

getBackgroundTrack()#

Gets the background track of the current scene. The background track is the track that determines the page duration. Only works in Video mode, not in Design mode.

Returns#

null | number

The ID of the background track, or null if none exists

Throws#

Error if called in Design mode

Signature#

getBackgroundTrack(): null | number

moveToBackgroundTrack()#

Moves a block to the background track. This is useful for organizing content in video scenes where you want certain elements to be part of the background layer. The background track is the track that determines the page duration.

Parameters#

Parameter	Type	Description
`block`	`number`	The ID of the block to move to the background track

Returns#

void

Throws#

Error if no background track is found

Signature#

moveToBackgroundTrack(block: number): void