Search
Loading...
Skip to content

Class: BlockAPI

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#

ParameterTypeDescription
contentstringA 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#

ParameterTypeDescription
urlstringThe 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#

ParameterTypeDescription
blocksnumber[]The blocks to save.
allowedResourceSchemesstring[]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#

ParameterTypeDescription
blocksnumber[]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#

ParameterTypeDescription
typeDesignBlockTypeThe 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe block to duplicate.
attachToParentbooleantrueWhether 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idsnumber[]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#

ParameterTypeDescription
namestringThe 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#

ParameterTypeDescription
typeObjectTypeThe 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#

ParameterTypeDescription
kindstringThe 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#
ParameterTypeDescription
handlenumberThe design block element to export.
options?EngineExportOptionsThe 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#
ParameterTypeDescription
handlenumberThe 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#
ParameterTypeDescription
handlenumberThe design block element to export.
maskColorRnumberThe red component of the special color mask color.
maskColorGnumberThe green component of the special color mask color.
maskColorBnumberThe blue component of the special color mask color.
options?EngineExportOptionsThe 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#
ParameterTypeDescription
handlenumberThe design block element to export.
mimeTypeundefined
maskColorRnumberThe red component of the special color mask color.
maskColorGnumberThe green component of the special color mask color.
maskColorBnumberThe 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#
ParameterTypeDescription
handlenumberThe design block element to export. Currently, only page blocks are supported.
options?VideoExportOptionsThe 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#
ParameterTypeDescription
handlenumberThe design block element to export. Currently, only page blocks are supported.
mimeType?VideoMimeTypeThe MIME type of the output video file.
progressCallback?(numberOfRenderedFrames, numberOfEncodedFrames, totalNumberOfFrames) => voidA 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#

ParameterTypeDescription
handlenumberThe design block element to export. Currently, only audio blocks are supported.
optionsAudioExportOptionsThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
parentnumberThe block whose children should be updated.
childnumberThe child to insert. Can be an existing child of parent.
indexnumberThe 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#

ParameterTypeDescription
parentnumberThe block whose children should be updated.
childnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
lockedbooleanWhether 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
valuenumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
modePositionModeThe 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#

ParameterTypeDescription
idnumberThe block to update.
valuenumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
modePositionModeThe 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#

ParameterTypeDescription
idnumberthe block to update.
enabledbooleanwhether 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#

ParameterTypeDescription
idnumberthe block to update.
enabledbooleanwhether 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#

ParameterTypeDescription
idnumberthe 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#

ParameterTypeDescription
idnumberthe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe id of the block to send backward.

Returns#

void

Signature#

sendBackward(id: number): void

getRotation()#


Gets the rotation of a block in radians.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
radiansnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
valuenumberThe new width of the block.
maintainCrop?booleanWhether 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#

ParameterTypeDescription
idnumberThe block to update.
modeSizeModeThe 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#

ParameterTypeDescription
idnumberThe block to update.
valuenumberThe new height of the block.
maintainCrop?booleanWhether 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#

ParameterTypeDescription
idnumberThe block to update.
modeSizeModeThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idsnumber[]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#

ParameterTypeDescription
idsnumber[]A non-empty array of block ids.
horizontalBlockAlignmentHorizontalBlockAlignmentHow 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#

ParameterTypeDescription
idsnumber[]A non-empty array of block ids.
verticalBlockAlignmentVerticalBlockAlignmentHow 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#

ParameterTypeDescription
idsnumber[]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#

ParameterTypeDescription
idsnumber[]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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idsnumber[]The blocks to resize.
widthnumberThe new width of the blocks.
heightnumberThe 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe block that should be scaled.
scalenumberundefinedThe scale factor to be applied to the current properties of the block.
anchorXnumber0The relative position along the width of the block around which the scaling should occur (0=left, 0.5=center, 1=right). Defaults to 0.
anchorYnumber0The 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#

ParameterTypeDescription
idnumberThe block to be selected.

Returns#

void

Signature#

select(id: number): void

setSelected()#


Sets the selection state of a block.

Parameters#

ParameterTypeDescription
idnumberThe block to query.
selectedbooleanWhether 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block to query.

Returns#

boolean

True if visible, false otherwise.

Signature#

isVisible(id: number): boolean

setVisible()#


Sets the visibility state of a block.

Parameters#

ParameterTypeDescription
idnumberThe block to update.
visiblebooleanWhether 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#

ParameterTypeDescription
idnumberThe block to query.

Returns#

boolean

True if clipped, false otherwise.

Signature#

isClipped(id: number): boolean

setClipped()#


Sets the clipped state of a block.

Parameters#

ParameterTypeDescription
idnumberThe block to update.
clippedbooleanWhether 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
flipbooleanIf the flip should be enabled.

Returns#

void

Signature#

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

setFlipVertical()#


Sets the vertical flip state of a block.

Parameters#

ParameterTypeDescription
idnumberThe block to update.
flipbooleanIf the flip should be enabled.

Returns#

void

Signature#

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

hasOpacity()#


Checks if a block has an opacity property.

Parameters#

ParameterTypeDescription
idnumberThe block to query.

Returns#

boolean

true, if the block has an opacity.

Deprecated#

Use supportsOpacity() instead.


supportsOpacity()#


Checks if a block supports opacity.

Parameters#

ParameterTypeDescription
idnumberThe block to query.

Returns#

boolean

true, if the block supports opacity.

Signature#

supportsOpacity(id: number): boolean

setOpacity()#


Sets the opacity of a block.

Parameters#

ParameterTypeDescription
idnumberThe block whose opacity should be set.
opacitynumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose blend mode should be set.
blendModeBlendModeThe blend mode to be set.

Returns#

void

Signature#

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

getBlendMode()#


Gets the blend mode of a block.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe block whose background color should be set.
rnumberundefinedThe red color component in the range of 0 to 1.
gnumberundefinedThe green color component in the range of 0 to 1.
bnumberundefinedThe blue color component in the range of 0 to 1.
anumber1The 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose background should be enabled or disabled.
enabledbooleanIf 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
typeFillTypeThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
modeContentFillModeThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose property should be set.
propertystringThe name of the property to set, e.g. ‘fill/gradient/colors’.
colorsGradientColorStop[]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#

ParameterTypeDescription
idnumberThe block whose property should be queried.
propertystringThe 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#

ParameterTypeDescription
idnumberThe block that should be queried.
propertystringThe 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#

ParameterTypeDescription
idnumberThe block whose property should be set.
propertystringThe name of the property to set.
sourceSetSource[]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#

ParameterTypeDescription
idnumberThe block to update.
propertystringThe name of the property to modify.
uristringThe 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#

ParameterTypeDescription
idnumberThe block to update.
propertystringThe name of the property to modify.
uristringThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe block whose fill color should be set.
rnumberundefinedThe red color component in the range of 0 to 1.
gnumberundefinedThe green color component in the range of 0 to 1.
bnumberundefinedThe blue color component in the range of 0 to 1.
anumber1The 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose fill should be enabled or disabled.
enabledbooleanIf true, the fill will be enabled.

Returns#

void

Deprecated#

Use setFillEnabled() instead.


isFillColorEnabled()#


Checks if the fill of a block is enabled.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose fill should be enabled or disabled.
enabledbooleanIf 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose fill should be changed.
fillnumberThe new fill block.

Returns#

void

Signature#

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

setFillSolidColor()#


Sets the solid fill color of a block.

Parameters#

ParameterTypeDefault valueDescription
idnumberundefinedThe block whose fill color should be set.
rnumberundefinedThe red color component in the range of 0 to 1.
gnumberundefinedThe green color component in the range of 0 to 1.
bnumberundefinedThe blue color component in the range of 0 to 1.
anumber1The 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
typeShapeTypeThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose shape should be changed.
shapenumberThe 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block into which to insert the given text.
textstringundefinedThe text which should replace the selected range in the block.
fromnumber-1The start index of the UTF-16 range to replace. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block from which the selected text should be removed.
fromnumber-1The start index of the UTF-16 range to remove. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose color should be changed.
colorColorundefinedThe new color of the selected text range.
fromnumber-1The start index of the UTF-16 range to change. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose colors should be returned.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose weight should be changed.
fontWeightFontWeightundefinedThe new weight of the selected text range.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose font weights should be returned.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose font size should be changed.
fontSizenumberundefinedThe new font size.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose font sizes should be returned.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose style should be changed.
fontStyleFontStyleundefinedThe new style of the selected text range.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose font styles should be returned.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose text cases should be returned.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose text case should be changed.
textCaseTextCaseundefinedThe new text case value.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block to check.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block to check.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block to modify.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block to modify.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDescription
idnumberThe text block whose font should be changed.
fontFileUristringThe URI of the new font file.
typefaceTypefaceThe 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose font should be changed.
typefaceTypefaceundefinedThe new typeface.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe text block whose typefaces should be queried.
fromnumber-1The start index of the UTF-16 range. Defaults to the start of the current selection or text.
tonumber-1The 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe text block whose line bounding box should be returned.
lineIndexnumberThe 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#

ParameterTypeDescription
idnumberThe text block whose line content should be returned.
lineIndexnumberThe 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#

ParameterTypeDescription
uristringThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose duration should be changed.
durationnumberThe new duration in seconds.

Returns#

void

Signature#

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

getDuration()#


Gets the playback duration of a block.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
pagenumberThe page block for which it should be enabled.
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
pagenumberThe page to check against.
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose time offset should be changed.
offsetnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose trim should be updated.
offsetnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe object whose trim length should be updated.
lengthnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
scenenumberThe 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#

ParameterTypeDescription
idnumberThe block that should be updated.
enabledbooleanWhether 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose playback time should be updated.
timenumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block or fill to update.
enabledbooleanWhether 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block to query.

Returns#

boolean

Whether the block has playback control.

Deprecated#

Use supportsPlaybackControl instead


supportsPlaybackControl()#


Checks if a block supports playback controls.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block or video fill to update.
loopingbooleanWhether 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block or video fill to update.
mutedbooleanWhether the audio should be muted.

Returns#

void

Signature#

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

isMuted()#


Checks if a block’s audio is muted.

Parameters#

ParameterTypeDescription
idnumberThe block to query.

Returns#

boolean

Whether the block is muted.

Signature#

isMuted(id: number): boolean

setVolume()#


Sets the audio volume of a block.

Parameters#

ParameterTypeDescription
idnumberThe block or video fill to update.
volumenumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe video fill or design block.
thumbnailHeightnumberThe height of each thumbnail.
timeBeginnumberThe start time in seconds for the thumbnail sequence.
timeEndnumberThe end time in seconds for the thumbnail sequence.
numberOfFramesnumberThe number of frames to generate.
onFrame(frameIndex, result) => voidA 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#

ParameterTypeDescription
idnumberThe audio block or video fill.
samplesPerChunknumberThe number of samples per chunk.
timeBeginnumberThe start time in seconds for the thumbnail sequence.
timeEndnumberThe end time in seconds for the thumbnail sequence.
numberOfSamplesnumberThe total number of samples to generate.
numberOfChannelsnumberThe number of channels in the output (1 for mono, 2 for stereo).
onChunk(chunkIndex, result) => voidA 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#

ParameterTypeDescription
idnumberThe video fill.
thumbnailHeightnumberThe 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#

ParameterTypeDescription
idnumberThe video fill.
numberOfColumnsnumberThe number of columns in the atlas.
numberOfRowsnumberThe number of rows in the atlas.
thumbnailHeightnumberThe 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#

ParameterTypeDescription
idnumberThe page.
numberOfColumnsnumberThe number of columns in the atlas.
numberOfRowsnumberThe number of rows in the atlas.
thumbnailHeightnumberThe 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#

ParameterTypeDescription
idnumberThe pixel stream fill block.
bufferHTMLCanvasElementHTMLVideoElement

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#

ParameterTypeDescription
typeAnimationTypeThe 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#

ParameterTypeDescription
idnumberThe block to query.

Returns#

boolean

Whether the block supports animation.

Signature#

supportsAnimation(id: number): boolean

setInAnimation()#


Sets the “in” animation of a block.

Parameters#

ParameterTypeDescription
idnumberThe block whose “in” animation should be set.
animationnumberThe animation to set.

Returns#

void

Signature#

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

setLoopAnimation()#


Sets the “loop” animation of a block.

Parameters#

ParameterTypeDescription
idnumberThe block whose “loop” animation should be set.
animationnumberThe animation to set.

Returns#

void

Signature#

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

setOutAnimation()#


Sets the “out” animation of a block.

Parameters#

ParameterTypeDescription
idnumberThe block whose “out” animation should be set.
animationnumberThe animation to set.

Returns#

void

Signature#

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

getInAnimation()#


Gets the “in” animation of a block.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idsnumber[]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#

ParameterTypeDescription
idsnumber[]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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberA 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#

ParameterTypeDescription
idnumberThe block to query.

Returns#

ObjectTypeLonghand

The block’s type.

Signature#

getType(id: number): ObjectTypeLonghand

setName()#


Sets the name of a block.

Parameters#

ParameterTypeDescription
idnumberThe block to update.
namestringThe name to set.

Returns#

void

Signature#

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

getName()#


Gets the name of a block.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose exportable state should be set.
enabledbooleanIf 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose state should be set.
stateBlockStateThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose crop should be set.
scaleXnumberThe 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#

ParameterTypeDescription
idnumberThe block whose crop should be set.
scaleYnumberThe 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#

ParameterTypeDescription
idnumberThe block whose crop should be set.
rotationnumberThe 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#

ParameterTypeDescription
idnumberThe block whose crop should be set.
scaleRationumberThe 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#

ParameterTypeDescription
idnumberThe block whose crop should be set.
translationXnumberThe 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#

ParameterTypeDescription
idnumberThe block whose crop should be set.
translationYnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose crop should be adjusted.
minScaleRationumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
callback() => voidThis 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#

ParameterTypeDescription
callback(id) => voidThis 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#

ParameterTypeDescription
idsnumber[]A list of block IDs to monitor. If empty, all blocks are monitored.
callback(ids) => voidThe 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#

ParameterTypeDescription
idsnumber[]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#

ParameterTypeDescription
idsnumber[]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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose kind should be changed.
kindstringThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
propertystringThe 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#

ParameterTypeDescription
propertystringThe 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#

ParameterTypeDescription
propertystringThe 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 ParameterDefault type
Tstring

Parameters#

ParameterTypeDescription
enumPropertystringThe 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#

ParameterTypeDescription
idnumberThe block whose property should be set.
propertystringThe name of the property to set.
valuebooleanThe 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#

ParameterTypeDescription
idnumberThe block whose property should be queried.
propertystringThe 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#

ParameterTypeDescription
idnumberThe block whose property should be set.
propertystringThe name of the property to set.
valuenumberThe 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#

ParameterTypeDescription
idnumberThe block whose property should be queried.
propertystringThe 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#

ParameterTypeDescription
idnumberThe block whose property should be set.
propertystringThe name of the property to set.
valuenumberThe 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#

ParameterTypeDescription
idnumberThe block whose property should be queried.
propertystringThe 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#

ParameterTypeDescription
idnumberThe block whose property should be set.
propertystringThe name of the property to set.
valuenumberThe 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#

ParameterTypeDescription
idnumberThe block whose property should be queried.
propertystringThe 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#

ParameterTypeDescription
idnumberThe block whose property should be set.
propertystringThe name of the property to set.
valuestringThe 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#

ParameterTypeDescription
idnumberThe block whose property should be queried.
propertystringThe 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#

ParameterTypeDescription
idnumberThe block whose property should be set.
propertystringThe name of the property to set.
valueColorThe 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#

ParameterTypeDescription
idnumberThe block whose property should be queried.
propertystringThe 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe block whose property should be set.
propertystringundefinedThe name of the property to set.
rnumberundefinedThe red color component in the range of 0 to 1.
gnumberundefinedThe green color component in the range of 0 to 1.
bnumberundefinedThe blue color component in the range of 0 to 1.
anumber1The 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#

ParameterTypeDescription
idnumberThe block whose property should be queried.
propertystringThe 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe block whose property should be set.
propertystringundefinedThe name of the property to set.
namestringundefinedThe name of the spot color.
tintnumber1The 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#

ParameterTypeDescription
idnumberThe block whose property should be queried.
propertystringThe 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#

ParameterTypeDescription
idnumberThe block whose property should be queried.
propertystringThe 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 ParameterDefault type
T extends stringstring

Parameters#

ParameterTypeDescription
idnumberThe block whose property should be set.
propertystringThe name of the property to set.
valueTThe 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 ParameterDefault type
T extends stringstring

Parameters#

ParameterTypeDescription
idnumberThe block whose property should be queried.
propertystringThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose stroke should be enabled or disabled.
enabledbooleanIf 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe block whose stroke color should be set.
rnumberundefinedThe red color component in the range of 0 to 1.
gnumberundefinedThe green color component in the range of 0 to 1.
bnumberundefinedThe blue color component in the range of 0 to 1.
anumber1The 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#

ParameterTypeDescription
idnumberThe block whose stroke color should be set.
colorColorThe color to set.

Returns#

void

Signature#

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

getStrokeColorRGBA()#


Gets the stroke color of a block as RGBA values.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose stroke width should be set.
widthnumberThe stroke width to be set.

Returns#

void

Signature#

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

getStrokeWidth()#


Gets the stroke width of a block.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose stroke style should be set.
styleStrokeStyleThe stroke style to be set.

Returns#

void

Signature#

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

getStrokeStyle()#


Gets the stroke style of a block.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose stroke position should be set.
positionStrokePositionThe stroke position to be set.

Returns#

void

Signature#

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

getStrokePosition()#


Gets the stroke position of a block.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose stroke corner geometry should be set.
cornerGeometryStrokeCornerGeometryThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose drop shadow should be enabled or disabled.
enabledbooleanIf 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDefault valueDescription
idnumberundefinedThe block whose drop shadow color should be set.
rnumberundefinedThe red color component in the range of 0 to 1.
gnumberundefinedThe green color component in the range of 0 to 1.
bnumberundefinedThe blue color component in the range of 0 to 1.
anumber1The 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#

ParameterTypeDescription
idnumberThe block whose drop shadow color should be set.
colorColorThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose drop shadow’s X offset should be set.
offsetXnumberThe X offset to be set.

Returns#

void

Signature#

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

getDropShadowOffsetX()#


Gets the drop shadow’s horizontal offset.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose drop shadow’s Y offset should be set.
offsetYnumberThe Y offset to be set.

Returns#

void

Signature#

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

getDropShadowOffsetY()#


Gets the drop shadow’s vertical offset.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose drop shadow’s blur radius should be set.
blurRadiusXnumberThe blur radius to be set.

Returns#

void

Signature#

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

getDropShadowBlurRadiusX()#


Gets the drop shadow’s horizontal blur radius.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose drop shadow’s blur radius should be set.
blurRadiusYnumberThe blur radius to be set.

Returns#

void

Signature#

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

getDropShadowBlurRadiusY()#


Gets the drop shadow’s vertical blur radius.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose drop shadow’s clip should be set.
clipbooleanThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
typeEffectTypeThe type of the effect.

Returns#

number

The created effect’s handle.

Signature#

createEffect(type: EffectType): number

hasEffects()#


Checks if a block supports effects.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
effectIdnumberThe effect to insert.
indexnumberThe 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#

ParameterTypeDescription
idnumberThe block to append the effect to.
effectIdnumberThe 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#

ParameterTypeDescription
idnumberThe block to remove the effect from.
indexnumberThe 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#

ParameterTypeDescription
effectIdnumberThe ‘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#

ParameterTypeDescription
effectIdnumberThe ‘effect’ block to update.
enabledbooleanThe 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#

ParameterTypeDescription
effectIdnumberThe ‘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#

ParameterTypeDescription
typeBlurTypeThe 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#

ParameterTypeDescription
idnumberThe block to query.

Returns#

boolean

True, if the block supports blur.

Deprecated#

Use supportsBlur instead.


supportsBlur()#


Checks if a block supports blur.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
blurIdnumberA ‘blur’ block to apply.

Returns#

void

Signature#

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

getBlur()#


Gets the blur block of a given design block.

Parameters#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
enabledbooleanThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose placeholder function should be enabled or disabled.
enabledbooleanWhether 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose placeholder behavior should be enabled or disabled.
enabledbooleanWhether 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose placeholder overlay should be enabled or disabled.
enabledbooleanWhether 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose placeholder button should be shown or not.
enabledbooleanWhether 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose scope should be enabled or disabled.
keyScopeThe scope to enable or disable.
enabledbooleanWhether 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#

ParameterTypeDescription
idnumberThe block whose scope state should be queried.
keyScopeThe 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#

ParameterTypeDescription
idnumberThe block to check.
keyScopeThe 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#

ParameterTypeDescription
idsnumber[]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#

ParameterTypeDescription
idsnumber[]The blocks to combine. They will be destroyed if “lifecycle/destroy” scope is enabled.
opBooleanOperationThe 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#

ParameterTypeDefault valueDescription
idsnumber[]undefinedThe blocks whose shape will serve as the basis for the cutout’s path.
vectorizeDistanceThresholdnumber2Max deviation from the original contour during vectorization.
simplifyDistanceThresholdnumber4Max deviation for path simplification. 0 disables simplification.
useExistingShapeInformationbooleantrueIf 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#

ParameterTypeDescription
pathstringAn 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#

ParameterTypeDescription
idsnumber[]The cutout blocks with which to perform to the operation.
opCutoutOperationThe 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#

ParameterTypeDescription
idnumberThe block whose metadata will be accessed.
keystringThe key used to identify the desired piece of metadata.
valuestringThe 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#

ParameterTypeDescription
idnumberThe block whose metadata will be accessed.
keystringThe 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#

ParameterTypeDescription
idnumberThe block whose metadata will be accessed.
keystringThe 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#

ParameterTypeDescription
idnumberThe 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#

ParameterTypeDescription
idnumberThe block whose metadata will be accessed.
keystringThe 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#

ParameterTypeDescription
idnumberThe block to update.
widthnumberThe new width of the block.
heightnumberThe 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#

ParameterTypeDescription
idnumberThe block to update.
xnumberThe new x position of the block.
ynumberThe 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#

ParameterTypeDescription
urlstringURL or path to the image file
optionsAddImageOptionsConfiguration 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#

ParameterTypeDescription
urlstringURL or path to the video file
widthnumberWidth of the video in scene design units
heightnumberHeight of the video in scene design units
optionsAddVideoOptionsConfiguration 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#

ParameterTypeDescription
blocknumberThe ID of the block to apply the animation to
animationAnimationOptionsThe animation configuration options

Returns#

void

Signature#

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

applyDropShadow()#


Applies a drop shadow effect to any block.

Parameters#

ParameterTypeDescription
blocknumberThe ID of the block to apply the shadow to
optionsDropShadowOptionsShadow 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#

ParameterTypeDescription
heightnumberHeight of the thumbnail in scene design units (maximum 512)
timenumberTime 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#

ParameterTypeDescription
blocknumberThe 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