Create, manipulate, and query the building blocks of your design.
This is the primary interface for all block-level operations. Use it to manage the entire lifecycle of blocks from creation and serialization to destruction. You can precisely control a block’s appearance by modifying its fills, strokes, and effects, or transform its position, size, and rotation. The API also includes powerful features for managing complex content like text and video, organizing blocks into groups and hierarchies, and exporting final designs to various formats.
Block Lifecycle#
Manage the complete lifecycle: create, find, duplicate, destroy, and serialize blocks.
loadFromString()#
Loads blocks from a serialized string.
The blocks are not attached by default and won’t be visible until attached to a page or the scene. The UUID of the loaded blocks is replaced with a new one.
Parameters#
Parameter | Type | Description |
---|---|---|
content | string | A string representing the given blocks. |
Returns#
Promise
<number
[]>
A promise that resolves with a list of handles representing the found blocks or an error.
Example#
const serializedBlocks = await engine.block.saveToString([pageBlockId]);// Later, load those blocksconst loadedBlocks = await engine.block.loadFromString(serializedBlocks);// Attach the first loaded block to the sceneengine.block.appendChild(sceneBlockId, loadedBlocks[0]);
Signature#
loadFromString(content: string): Promise<number[]>
loadFromArchiveURL()#
Loads blocks from a remote archive URL.
The blocks are not attached by default and won’t be visible until attached to a page or the scene. The UUID of the loaded blocks is replaced with a new one.
Parameters#
Parameter | Type | Description |
---|---|---|
url | string | The URL to load the blocks from. |
Returns#
Promise
<number
[]>
A promise that resolves with a list of handles representing the found blocks or an error.
Example#
// Load blocks from a remote archiveconst loadedBlocks = await engine.block.loadFromArchiveURL('https://example.com/blocks.zip');// Attach the first loaded block to the sceneengine.block.appendChild(sceneBlockId, loadedBlocks[0]);
Signature#
loadFromArchiveURL(url: string): Promise<number[]>
saveToString()#
Saves the given blocks to a serialized string.
If a page with multiple children is given, the entire hierarchy is saved.
Parameters#
Parameter | Type | Description |
---|---|---|
blocks | number [] | The blocks to save. |
allowedResourceSchemes | string [] | The resource schemes to allow in the saved string. Defaults to [‘buffer’, ‘http’, ‘https’]. |
Returns#
Promise
<string
>
A promise that resolves to a string representing the blocks or an error.
Example#
// Create a page with a text elementconst page = engine.block.create('page');const text = engine.block.create('text');engine.block.appendChild(page, text);
// Save the whole page hierarchy to a stringconst serialized = await engine.block.saveToString([page]);
Signature#
saveToString(blocks: number[], allowedResourceSchemes?: string[]): Promise<string>
saveToArchive()#
Saves the given blocks and their assets to a zip archive.
The archive contains all assets that were accessible when this function was called. Blocks in the archived scene reference assets relative to the location of the scene file.
Parameters#
Parameter | Type | Description |
---|---|---|
blocks | number [] | The blocks to save. |
Returns#
Promise
<Blob
>
A promise that resolves with a Blob on success or an error on failure.
Signature#
saveToArchive(blocks: number[]): Promise<Blob>
create()#
Creates a new block of a given type.
// Create a new text blockconst text = engine.block.create('text');const page = engine.scene.getCurrentPage();engine.block.appendChild(page, text);
// Create a new image blockconst 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 blockconst video = engine.block.create('graphic');engine.block.setShape(video, engine.block.createShape('rect'));const videoFill = engine.block.createFill('video');engine.block.setString(videoFill, 'fill/video/fileURI', 'https://cdn.img.ly/assets/demo/v2/ly.img.video/videos/pexels-drone-footage-of-a-surfer-barrelling-a-wave-12715991.mp4');engine.block.setFill(video, videoFill);engine.block.appendChild(page, video);
Parameters#
Parameter | Type | Description |
---|---|---|
type | DesignBlockType | The type of the block that shall be created. |
Returns#
number
The created block’s handle.
Signature#
create(type: DesignBlockType): number
duplicate()#
Duplicates a block and its children.
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The block to duplicate. |
attachToParent | boolean | true | Whether the duplicated block should be attached to the original’s parent. Defaults to true. |
Returns#
number
The handle of the duplicate.
Signature#
duplicate(id: number, attachToParent?: boolean): number
destroy()#
Destroys a block and its children.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to destroy. |
Returns#
void
Signature#
destroy(id: number): void
forceLoadResources()#
Forces the loading of resources for a set of blocks and their children.
This is useful for preloading resources. If a resource failed to load previously, it will be reloaded.
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | The blocks whose resources should be loaded. |
Returns#
Promise
<void
>
A Promise that resolves once all resources have finished loading.
Signature#
forceLoadResources(ids: number[]): Promise<void>
Block Exploration#
Find blocks by properties like name, type, or kind.
findByName()#
Finds all blocks with a given name.
Parameters#
Parameter | Type | Description |
---|---|---|
name | string | The name to search for. |
Returns#
number
[]
A list of block ids.
Signature#
findByName(name: string): number[]
findByType()#
Finds all blocks with a given type.
Parameters#
Parameter | Type | Description |
---|---|---|
type | ObjectType | The type to search for. |
Returns#
number
[]
A list of block ids.
Signature#
findByType(type: ObjectType): number[]
findByKind()#
Finds all blocks with a given kind.
const allTitles = engine.block.findByKind('title');
Parameters#
Parameter | Type | Description |
---|---|---|
kind | string | The kind to search for. |
Returns#
number
[]
A list of block ids.
Signature#
findByKind(kind: string): number[]
findAll()#
Finds all blocks known to the engine.
Returns#
number
[]
A list of block ids.
Signature#
findAll(): number[]
findAllPlaceholders()#
Finds all placeholder blocks in the current scene.
Returns#
number
[]
A list of block ids.
Signature#
findAllPlaceholders(): number[]
Block Export#
Export blocks to various formats like images, videos, and audio.
export()#
Exports a design block to a Blob.
Performs an internal update to resolve the final layout for the blocks.
Parameters#
Parameter | Type | Description |
---|---|---|
handle | number | The design block element to export. |
options? | EngineExportOptions | The options for exporting the block type, including mime type and export settings. |
Returns#
Promise
<Blob
>
A promise that resolves with the exported image or is rejected with an error.
Call Signature#
export( handle, mimeType?,options?): Promise<Blob>;
Exports a design block to a Blob.
Performs an internal update to resolve the final layout for the blocks.
Parameters#
Parameter | Type | Description |
---|---|---|
handle | number | The design block element to export. |
mimeType? | "application/octet-stream" | |
options? | Omit <EngineExportOptions , "mimeType" > | The options for exporting the block type |
Returns#
Promise
<Blob
>
A promise that resolves with the exported image or is rejected with an error.
Deprecated#
Use the new export
signature instead
Example#
// Before migrationconst blob = await cesdk.block.export(blockId, MimeType.Png, { pngCompressionLevel: 5 })// After migrationconst blob = await cesdk.block.export(blockId, { mimeType: 'image/png', pngCompressionLevel: 5 })
Signatures#
export(handle: number, options?: ExportOptions): Promise<Blob>
export(handle: number, mimeType?: "application/octet-stream" | "application/pdf" | ImageMimeType, options?: Omit<ExportOptions, "mimeType">): Promise<Blob>
exportWithColorMask()#
Exports a design block and a color mask to two separate Blobs.
Performs an internal update to resolve the final layout for the blocks.
Parameters#
Parameter | Type | Description |
---|---|---|
handle | number | The design block element to export. |
maskColorR | number | The red component of the special color mask color. |
maskColorG | number | The green component of the special color mask color. |
maskColorB | number | The blue component of the special color mask color. |
options? | EngineExportOptions | The options for exporting the block type |
Returns#
Promise
<Blob
[]>
A promise that resolves with an array of the exported image and mask or is rejected with an error.
Call Signature#
exportWithColorMask( handle, mimeType, maskColorR, maskColorG, maskColorB,options?): Promise<Blob[]>;
Exports a design block and a color mask to two separate Blobs.
Performs an internal update to resolve the final layout for the blocks. Removes all pixels that exactly match the given RGB color and replaces them with transparency. The output includes two files: the masked image and the mask itself.
Parameters#
Parameter | Type | Description |
---|---|---|
handle | number | The design block element to export. |
mimeType | undefined | |
maskColorR | number | The red component of the special color mask color. |
maskColorG | number | The green component of the special color mask color. |
maskColorB | number | The blue component of the special color mask color. |
options? | Omit <EngineExportOptions , "mimeType" > | The options for exporting the block type |
Returns#
Promise
<Blob
[]>
A promise that resolves with an array of the exported image and mask or is rejected with an error.
Deprecated#
Use the new exportWithColorMask
signature instead
Example#
// Before migrationconst blob = await cesdk.block.exportWithColorMask( blockId, MimeType.Png, 0.5, 0, 0, { pngCompressionLevel: 5 });// After migrationconst blob = await cesdk.block.exportWithColorMask( blockId, 0.5, 0, 0, { mimeType: 'image/png', pngCompressionLevel: 5 });
Signatures#
exportWithColorMask(handle: number, maskColorR: number, maskColorG: number, maskColorB: number, options?: ExportOptions): Promise<Blob[]>
exportWithColorMask(handle: number, mimeType: undefined | "application/octet-stream" | "application/pdf" | ImageMimeType, maskColorR: number, maskColorG: number, maskColorB: number, options?: Omit<ExportOptions, "mimeType">): Promise<Blob[]>
exportVideo()#
Exports a design block as a video file.
Note: The export will run across multiple iterations of the update loop. In each iteration a frame is scheduled for encoding.
Parameters#
Parameter | Type | Description |
---|---|---|
handle | number | The design block element to export. Currently, only page blocks are supported. |
options? | VideoExportOptions | The options for exporting the video, including mime type, h264 profile, level, bitrate, time offset, duration, framerate, target width and height. |
Returns#
Promise
<Blob
>
A promise that resolves with a video blob or is rejected with an error.
Example#
const page = engine.block.create('page');// Set up a progress tracking functionconst progressTracker = (renderedFrames, encodedFrames, totalFrames) => { console.log(`Progress: ${Math.round((encodedFrames / totalFrames) * 100)}%`);};const videoOptions = { framerate: 30, duration: 5 };const videoBlob = await engine.block.exportVideo(page, MimeType.Mp4, progressTracker, videoOptions);
Call Signature#
exportVideo( handle, mimeType?, progressCallback?,options?): Promise<Blob>;
Exports a design block as a video file.
Note: The export will run across multiple iterations of the update loop. In each iteration a frame is scheduled for encoding.
Parameters#
Parameter | Type | Description |
---|---|---|
handle | number | The design block element to export. Currently, only page blocks are supported. |
mimeType? | VideoMimeType | The MIME type of the output video file. |
progressCallback? | (numberOfRenderedFrames , numberOfEncodedFrames , totalNumberOfFrames ) => void | A callback which reports on the progress of the export. |
options? | Omit <VideoExportOptions , "mimeType" | "onProgress" > |
Returns#
Promise
<Blob
>
A promise that resolves with a video blob or is rejected with an error.
Deprecated#
Use the new exportVideo
signature instead
Example#
// Before migrationconst blob = await cesdk.block.exportVideo(blockId, 'video/mp4', handleProgress, { targetWidth: 1920, targetHeight: 1080,})// After migrationconst blob = await cesdk.block.exportVideo(blockId, { mimeType: 'video/mp4', progressCallback: handleProgress, targetWidth: 1920, targetHeight: 1080,})
Signatures#
exportVideo(handle: number, options?: VideoExportOptions): Promise<Blob>
exportVideo(handle: number, mimeType?: VideoMimeType, progressCallback?: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void, options?: Omit<VideoExportOptions, "mimeType" | "onProgress">): Promise<Blob>
unstable_exportAudio()#
Exports a design block as an audio file.
Parameters#
Parameter | Type | Description |
---|---|---|
handle | number | The design block element to export. Currently, only audio blocks are supported. |
options | AudioExportOptions | The options for exporting the audio, including mime type, progress callback, and export settings. |
Returns#
Promise
<Blob
>
A promise that resolves with an audio blob or is rejected with an error. This API is experimental and may change or be removed in future versions.
Example#
const audioBlock = engine.block.create('audio');// Set up a progress tracking functionconst progressTracker = (renderedFrames, encodedFrames, totalFrames) => { console.log(`Audio export progress: ${Math.round((encodedFrames / totalFrames) * 100)}%`);};const audioOptions = { duration: 10 };const audioBlob = await engine.block.unstable_exportAudio(audioBlock, MimeType.Wav, progressTracker, audioOptions);
Block Hierarchies#
Manage parent-child relationships and the scene graph structure.
getParent()#
Gets the parent of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
null
| number
The parent’s handle or null if the block has no parent.
Signature#
getParent(id: number): null | number
getChildren()#
Gets all direct children of a block.
Children are sorted in their rendering order: Last child is rendered in front of other children.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
[]
A list of block ids.
Signature#
getChildren(id: number): number[]
insertChild()#
Inserts a child block at a specific index.
Parameters#
Parameter | Type | Description |
---|---|---|
parent | number | The block whose children should be updated. |
child | number | The child to insert. Can be an existing child of parent . |
index | number | The index to insert or move to. |
Returns#
void
Signature#
insertChild(parent: number, child: number, index: number): void
appendChild()#
Appends a child block to a parent.
Parameters#
Parameter | Type | Description |
---|---|---|
parent | number | The block whose children should be updated. |
child | number | The child to insert. Can be an existing child of parent . |
Returns#
void
Signature#
appendChild(parent: number, child: number): void
Block Layout#
Structure designs by positioning, sizing, layering, aligning, and distributing blocks.
isTransformLocked()#
Gets the transform-locked state of a block.
If true, the block’s transform can’t be changed.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True if transform locked, false otherwise.
Signature#
isTransformLocked(id: number): boolean
setTransformLocked()#
Sets the transform-locked state of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
locked | boolean | Whether the block’s transform should be locked. |
Returns#
void
Signature#
setTransformLocked(id: number, locked: boolean): void
getPositionX()#
Gets the X position of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The value of the x position.
Signature#
getPositionX(id: number): number
getPositionXMode()#
Gets the mode for the block’s X position.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
PositionMode
The current mode for the x position: ‘Absolute’ or ‘Percent’.
Signature#
getPositionXMode(id: number): PositionMode
getPositionY()#
Gets the Y position of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The value of the y position.
Signature#
getPositionY(id: number): number
getPositionYMode()#
Gets the mode for the block’s Y position.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
PositionMode
The current mode for the y position: ‘Absolute’ or ‘Percent’.
Signature#
getPositionYMode(id: number): PositionMode
setPositionX()#
Sets the X position of a block.
The position refers to the block’s local space, relative to its parent with the origin at the top left.
engine.block.setPositionX(block, 0.25);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
value | number | The value of the x position. |
Returns#
void
Signature#
setPositionX(id: number, value: number): void
setPositionXMode()#
Sets the mode for the block’s X position.
engine.block.setPositionXMode(block, 'Percent');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
mode | PositionMode | The x position mode: ‘Absolute’ or ‘Percent’. |
Returns#
void
Signature#
setPositionXMode(id: number, mode: PositionMode): void
setPositionY()#
Sets the Y position of a block.
The position refers to the block’s local space, relative to its parent with the origin at the top left.
engine.block.setPositionY(block, 0.25);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
value | number | The value of the y position. |
Returns#
void
Signature#
setPositionY(id: number, value: number): void
setPositionYMode()#
Sets the mode for the block’s Y position.
engine.block.setPositionYMode(block, 'Absolute');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
mode | PositionMode | The y position mode: ‘Absolute’ or ‘Percent’. |
Returns#
void
Signature#
setPositionYMode(id: number, mode: PositionMode): void
setAlwaysOnTop()#
Sets a block to always be rendered on top of its siblings.
If true, this block’s sorting order is automatically adjusted to be higher than all other siblings without this property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | the block to update. |
enabled | boolean | whether the block shall be always-on-top. |
Returns#
void
Signature#
setAlwaysOnTop(id: number, enabled: boolean): void
setAlwaysOnBottom()#
Sets a block to always be rendered below its siblings.
If true, this block’s sorting order is automatically adjusted to be lower than all other siblings without this property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | the block to update. |
enabled | boolean | whether the block shall always be below its siblings. |
Returns#
void
Signature#
setAlwaysOnBottom(id: number, enabled: boolean): void
isAlwaysOnTop()#
Checks if a block is set to always be on top.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | the block to query. |
Returns#
boolean
true if the block is set to be always-on-top, false otherwise.
Signature#
isAlwaysOnTop(id: number): boolean
isAlwaysOnBottom()#
Checks if a block is set to always be on the bottom.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | the block to query. |
Returns#
boolean
true if the block is set to be always-on-bottom, false otherwise.
Signature#
isAlwaysOnBottom(id: number): boolean
bringToFront()#
Brings a block to the front of its siblings.
Updates the sorting order so that the given block has the highest sorting order.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The id of the block to bring to the front. |
Returns#
void
Signature#
bringToFront(id: number): void
sendToBack()#
Sends a block to the back of its siblings.
Updates the sorting order so that the given block has the lowest sorting order.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The id of the block to send to the back. |
Returns#
void
Signature#
sendToBack(id: number): void
bringForward()#
Brings a block one layer forward.
Updates the sorting order to be higher than its next sibling.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The id of the block to bring forward. |
Returns#
void
Signature#
bringForward(id: number): void
sendBackward()#
Sends a block one layer backward.
Updates the sorting order to be lower than its previous sibling.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The id of the block to send backward. |
Returns#
void
Signature#
sendBackward(id: number): void
getRotation()#
Gets the rotation of a block in radians.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The block’s rotation around its center in radians.
Signature#
getRotation(id: number): number
setRotation()#
Sets the rotation of a block in radians.
Rotation is applied around the block’s center.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
radians | number | The new rotation in radians. |
Returns#
void
Signature#
setRotation(id: number, radians: number): void
getWidth()#
Gets the width of a block.
const width = engine.block.getWidth(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The value of the block’s width.
Signature#
getWidth(id: number): number
getWidthMode()#
Gets the mode for the block’s width.
const widthMode = engine.block.getWidthMode(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
SizeMode
The current mode for the width: ‘Absolute’, ‘Percent’ or ‘Auto’.
Signature#
getWidthMode(id: number): SizeMode
getHeight()#
Gets the height of a block.
const height = engine.block.getHeight(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The value of the block’s height.
Signature#
getHeight(id: number): number
getHeightMode()#
Gets the mode for the block’s height.
const heightMode = engine.block.getHeightMode(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
SizeMode
The current mode for the height: ‘Absolute’, ‘Percent’ or ‘Auto’.
Signature#
getHeightMode(id: number): SizeMode
setWidth()#
Update a block’s width and optionally maintain the crop.
If the crop is maintained, the crop values will be automatically adjusted.
engine.block.setWidth(block, 2.5, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
value | number | The new width of the block. |
maintainCrop? | boolean | Whether or not the crop values, if available, should be automatically adjusted. |
Returns#
void
Signature#
setWidth(id: number, value: number, maintainCrop?: boolean): void
setWidthMode()#
Sets the mode for the block’s width.
engine.block.setWidthMode(block, 'Percent');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
mode | SizeMode | The width mode: ‘Absolute’, ‘Percent’ or ‘Auto’. |
Returns#
void
Signature#
setWidthMode(id: number, mode: SizeMode): void
setHeight()#
Sets the height of a block.
If the crop is maintained, the crop values will be automatically adjusted.
engine.block.setHeight(block, 0.5);engine.block.setHeight(block, 2.5, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
value | number | The new height of the block. |
maintainCrop? | boolean | Whether or not the crop values, if available, should be automatically adjusted. |
Returns#
void
Signature#
setHeight(id: number, value: number, maintainCrop?: boolean): void
setHeightMode()#
Sets the mode for the block’s height.
engine.block.setHeightMode(block, 'Percent');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
mode | SizeMode | The height mode: ‘Absolute’, ‘Percent’ or ‘Auto’. |
Returns#
void
Signature#
setHeightMode(id: number, mode: SizeMode): void
getFrameX()#
Gets the final calculated X position of a block’s frame.
The position is only available after an internal update loop.
const frameX = engine.block.getFrameX(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The layout position on the x-axis.
Signature#
getFrameX(id: number): number
getFrameY()#
Gets the final calculated Y position of a block’s frame.
The position is only available after an internal update loop.
const frameY = engine.block.getFrameY(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The layout position on the y-axis.
Signature#
getFrameY(id: number): number
getFrameWidth()#
Gets the final calculated width of a block’s frame.
The width is only available after an internal update loop.
const frameWidth = engine.block.getFrameWidth(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The layout width.
Signature#
getFrameWidth(id: number): number
getFrameHeight()#
Gets the final calculated height of a block’s frame.
The height is only available after an internal update loop.
const frameHeight = engine.block.getFrameHeight(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The layout height.
Signature#
getFrameHeight(id: number): number
getGlobalBoundingBoxX()#
Gets the X position of the block’s global bounding box.
The position is in the scene’s global coordinate space, with the origin at the top left.
const globalX = engine.block.getGlobalBoundingBoxX(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose bounding box should be calculated. |
Returns#
number
The x coordinate of the axis-aligned bounding box.
Signature#
getGlobalBoundingBoxX(id: number): number
getGlobalBoundingBoxY()#
Gets the Y position of the block’s global bounding box.
The position is in the scene’s global coordinate space, with the origin at the top left.
const globalY = engine.block.getGlobalBoundingBoxY(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose bounding box should be calculated. |
Returns#
number
The y coordinate of the axis-aligned bounding box.
Signature#
getGlobalBoundingBoxY(id: number): number
getGlobalBoundingBoxWidth()#
Gets the width of the block’s global bounding box.
The width is in the scene’s global coordinate space.
const globalWidth = engine.block.getGlobalBoundingBoxWidth(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose bounding box should be calculated. |
Returns#
number
The width of the axis-aligned bounding box.
Signature#
getGlobalBoundingBoxWidth(id: number): number
getGlobalBoundingBoxHeight()#
Gets the height of the block’s global bounding box.
The height is in the scene’s global coordinate space.
const globalHeight = engine.block.getGlobalBoundingBoxHeight(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose bounding box should be calculated. |
Returns#
number
The height of the axis-aligned bounding box.
Signature#
getGlobalBoundingBoxHeight(id: number): number
getScreenSpaceBoundingBoxXYWH()#
Gets the screen-space bounding box for a set of blocks.
const boundingBox = engine.block.getScreenSpaceBoundingBoxXYWH([block]);
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | The block to query. |
Returns#
XYWH
The position and size of the bounding box.
Signature#
getScreenSpaceBoundingBoxXYWH(ids: number[]): XYWH
alignHorizontally()#
Aligns blocks horizontally.
Aligns multiple blocks within their bounding box or a single block to its parent.
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | A non-empty array of block ids. |
horizontalBlockAlignment | HorizontalBlockAlignment | How they should be aligned: ‘Left’, ‘Right’, or ‘Center’. |
Returns#
void
Signature#
alignHorizontally(ids: number[], horizontalBlockAlignment: HorizontalBlockAlignment): void
alignVertically()#
Aligns blocks vertically.
Aligns multiple blocks within their bounding box or a single block to its parent.
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | A non-empty array of block ids. |
verticalBlockAlignment | VerticalBlockAlignment | How they should be aligned: ‘Top’, ‘Bottom’, or ‘Center’. |
Returns#
void
Signature#
alignVertically(ids: number[], verticalBlockAlignment: VerticalBlockAlignment): void
distributeHorizontally()#
Distributes blocks horizontally with even spacing.
Distributes multiple blocks horizontally within their bounding box.
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | A non-empty array of block ids. |
Returns#
void
Signature#
distributeHorizontally(ids: number[]): void
distributeVertically()#
Distributes blocks vertically with even spacing.
Distributes multiple blocks vertically within their bounding box.
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | A non-empty array of block ids. |
Returns#
void
Signature#
distributeVertically(ids: number[]): void
fillParent()#
Resizes and positions a block to fill its parent.
The crop values of the block are reset if it can be cropped.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block that should fill its parent. |
Returns#
void
Signature#
fillParent(id: number): void
resizeContentAware()#
Resizes blocks while adjusting content to fit.
The content of the blocks is automatically adjusted to fit the new dimensions. Full-page blocks are resized to remain as full-page afterwards, while the blocks that are not full-page get resized as a group to the same scale factor and centered.
const pages = engine.scene.getPages();engine.block.resizeContentAware(pages, width: 100.0, 100.0);
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | The blocks to resize. |
width | number | The new width of the blocks. |
height | number | The new height of the blocks. |
Returns#
void
Signature#
resizeContentAware(ids: number[], width: number, height: number): void
scale()#
Scales a block and its children proportionally.
This updates the position, size and style properties (e.g. stroke width) of the block and its children around the specified anchor point.
// Scale a block to double its size, anchored at the center.engine.block.scale(block, 2.0, 0.5, 0.5);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The block that should be scaled. |
scale | number | undefined | The scale factor to be applied to the current properties of the block. |
anchorX | number | 0 | The relative position along the width of the block around which the scaling should occur (0=left, 0.5=center, 1=right). Defaults to 0. |
anchorY | number | 0 | The relative position along the height of the block around which the scaling should occur (0=top, 0.5=center, 1=bottom). Defaults to 0. |
Returns#
void
Signature#
scale(id: number, scale: number, anchorX?: number, anchorY?: number): void
Block Selection & Visibility#
Manage a block’s selection state and visibility on the canvas.
select()#
Selects a block, deselecting all others.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to be selected. |
Returns#
void
Signature#
select(id: number): void
setSelected()#
Sets the selection state of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
selected | boolean | Whether or not the block should be selected. |
Returns#
void
Signature#
setSelected(id: number, selected: boolean): void
isSelected()#
Gets the selection state of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True if the block is selected, false otherwise.
Signature#
isSelected(id: number): boolean
findAllSelected()#
Finds all currently selected blocks.
Returns#
number
[]
An array of block ids.
Signature#
findAllSelected(): number[]
isVisible()#
Gets the visibility state of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True if visible, false otherwise.
Signature#
isVisible(id: number): boolean
setVisible()#
Sets the visibility state of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
visible | boolean | Whether the block shall be visible. |
Returns#
void
Signature#
setVisible(id: number, visible: boolean): void
Block Appearance#
Control general appearance, including opacity, blend modes, flipping, and other visual properties.
isClipped()#
Gets the clipped state of a block.
If true, the block should clip its contents to its frame.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True if clipped, false otherwise.
Signature#
isClipped(id: number): boolean
setClipped()#
Sets the clipped state of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
clipped | boolean | Whether the block should clips its contents to its frame. |
Returns#
void
Signature#
setClipped(id: number, clipped: boolean): void
getFlipHorizontal()#
Gets the horizontal flip state of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
A boolean indicating whether the block is flipped horizontally.
Signature#
getFlipHorizontal(id: number): boolean
getFlipVertical()#
Gets the vertical flip state of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
A boolean indicating whether the block is flipped vertically.
Signature#
getFlipVertical(id: number): boolean
setFlipHorizontal()#
Sets the horizontal flip state of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
flip | boolean | If the flip should be enabled. |
Returns#
void
Signature#
setFlipHorizontal(id: number, flip: boolean): void
setFlipVertical()#
Sets the vertical flip state of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
flip | boolean | If the flip should be enabled. |
Returns#
void
Signature#
setFlipVertical(id: number, flip: boolean): void
hasOpacity()#
Checks if a block has an opacity property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has an opacity.
Deprecated#
Use supportsOpacity() instead.
supportsOpacity()#
Checks if a block supports opacity.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block supports opacity.
Signature#
supportsOpacity(id: number): boolean
setOpacity()#
Sets the opacity of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose opacity should be set. |
opacity | number | The opacity to be set. The valid range is 0 to 1. |
Returns#
void
Signature#
setOpacity(id: number, opacity: number): void
getOpacity()#
Gets the opacity of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose opacity should be queried. |
Returns#
number
The opacity value.
Signature#
getOpacity(id: number): number
hasBlendMode()#
Checks if a block has a blend mode property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has a blend mode.
Deprecated#
Use supportsBlendMode() instead.
supportsBlendMode()#
Checks if a block supports blend modes.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block supports blend modes.
Signature#
supportsBlendMode(id: number): boolean
setBlendMode()#
Sets the blend mode of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose blend mode should be set. |
blendMode | BlendMode | The blend mode to be set. |
Returns#
void
Signature#
setBlendMode(id: number, blendMode: BlendMode): void
getBlendMode()#
Gets the blend mode of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose blend mode should be queried. |
Returns#
BlendMode
The blend mode.
Signature#
getBlendMode(id: number): BlendMode
hasBackgroundColor()#
Checks if a block has background color properties.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has background color properties.
Deprecated#
Use supportsBackgroundColor() instead.
supportsBackgroundColor()#
Checks if a block supports a background color.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block supports a background color.
Signature#
supportsBackgroundColor(id: number): boolean
setBackgroundColorRGBA()#
Sets the background color of a block using RGBA values.
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The block whose background color should be set. |
r | number | undefined | The red color component in the range of 0 to 1. |
g | number | undefined | The green color component in the range of 0 to 1. |
b | number | undefined | The blue color component in the range of 0 to 1. |
a | number | 1 | The alpha color component in the range of 0 to 1. |
Returns#
void
Deprecated#
Use Use setColor() with the key path 'backgroundColor/color' instead.
.
getBackgroundColorRGBA()#
Gets the background color of a block as RGBA values.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose background color should be queried. |
Returns#
RGBA
The background color.
Deprecated#
Use Use getColor() with the key path 'backgroundColor/color' instead.
.
setBackgroundColorEnabled()#
Enables or disables the background of a block.
engine.block.setBackgroundColorEnabled(block, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose background should be enabled or disabled. |
enabled | boolean | If true, the background will be enabled. |
Returns#
void
Signature#
setBackgroundColorEnabled(id: number, enabled: boolean): void
isBackgroundColorEnabled()#
Checks if the background of a block is enabled.
const backgroundColorIsEnabled = engine.block.isBackgroundColorEnabled(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose background state should be queried. |
Returns#
boolean
True, if background is enabled.
Signature#
isBackgroundColorEnabled(id: number): boolean
Block Fills#
Create, configure, and manage block fills, including solid colors, gradients, and images.
createFill()#
Creates a new fill block.
const solidColoFill = engine.block.createFill('color');// Longhand fill types are also supportedconst imageFill = engine.block.createFill('//ly.img.ubq/fill/image');
Parameters#
Parameter | Type | Description |
---|---|---|
type | FillType | The type of the fill object that shall be created. |
Returns#
number
The created fill’s handle.
Signature#
createFill(type: FillType): number
hasContentFillMode()#
Checks if a block supports content fill modes.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has a content fill mode.
Deprecated#
Use supportsContentFillMode instead.
supportsContentFillMode()#
Checks if a block supports content fill modes.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has a content fill mode.
Signature#
supportsContentFillMode(id: number): boolean
setContentFillMode()#
Sets the content fill mode of a block.
engine.block.setContentFillMode(image, 'Cover');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
mode | ContentFillMode | The content fill mode: ‘Crop’, ‘Cover’ or ‘Contain’. |
Returns#
void
Signature#
setContentFillMode(id: number, mode: ContentFillMode): void
getContentFillMode()#
Gets the content fill mode of a block.
engine.block.getContentFillMode(image);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
ContentFillMode
The current mode: ‘Crop’, ‘Cover’ or ‘Contain’.
Signature#
getContentFillMode(id: number): ContentFillMode
setGradientColorStops()#
Sets the color stops for a gradient property.
engine.block.setGradientColorStops(gradientFill, 'fill/gradient/colors', [ { color: { r: 1.0, g: 0.8, b: 0.2, a: 1.0 }, stop: 0 }, { color: { r: 0.3, g: 0.4, b: 0.7, a: 1.0 }, stop: 1 }]);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be set. |
property | string | The name of the property to set, e.g. ‘fill/gradient/colors’. |
colors | GradientColorStop [] | An array of gradient color stops. |
Returns#
void
Signature#
setGradientColorStops(id: number, property: string, colors: GradientColorStop[]): void
getGradientColorStops()#
Gets the color stops from a gradient property.
engine.block.getGradientColorStops(gradientFill, 'fill/gradient/colors');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be queried. |
property | string | The name of the property to query. |
Returns#
The gradient colors.
Signature#
getGradientColorStops(id: number, property: string): GradientColorStop[]
getSourceSet()#
Gets the source set from a block property.
const sourceSet = engine.block.getSourceSet(imageFill, 'fill/image/sourceSet');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block that should be queried. |
property | string | The name of the property to query, e.g. ‘fill/image/sourceSet’. |
Returns#
Source
[]
The block’s source set.
Signature#
getSourceSet(id: number, property: string): Source[]
setSourceSet()#
Sets the source set for a block property.
The crop and content fill mode of the associated block will be reset to default values.
engine.block.setSourceSet(imageFill, 'fill/image/sourceSet', [{ uri: 'https://example.com/sample.jpg', width: 800, height: 600}]);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be set. |
property | string | The name of the property to set. |
sourceSet | Source [] | The block’s new source set. |
Returns#
void
Signature#
setSourceSet(id: number, property: string, sourceSet: Source[]): void
addImageFileURIToSourceSet()#
Adds an image file URI to a source set property.
If an image with the same width already exists in the source set, it will be replaced.
await engine.block.addImageFileURIToSourceSet(imageFill, 'fill/image/sourceSet', 'https://example.com/sample.jpg');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
property | string | The name of the property to modify. |
uri | string | The source to add to the source set. |
Returns#
Promise
<void
>
A promise that resolves when the operation is complete.
Signature#
addImageFileURIToSourceSet(id: number, property: string, uri: string): Promise<void>
addVideoFileURIToSourceSet()#
Adds a video file URI to a source set property.
If a video with the same width already exists in the source set, it will be replaced.
await engine.block.addVideoFileURIToSourceSet(videoFill, 'fill/video/sourceSet', 'https://example.com/sample.mp4');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
property | string | The name of the property to modify. |
uri | string | The source to add to the source set. |
Returns#
Promise
<void
>
A promise that resolves when the operation is complete.
Signature#
addVideoFileURIToSourceSet(id: number, property: string, uri: string): Promise<void>
hasFillColor()#
Checks if a block has fill color properties.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has fill color properties.
Deprecated#
Query the fill’s type using getFill() and getType() instead.
setFillColorRGBA()#
Sets the fill color of a block using RGBA values.
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The block whose fill color should be set. |
r | number | undefined | The red color component in the range of 0 to 1. |
g | number | undefined | The green color component in the range of 0 to 1. |
b | number | undefined | The blue color component in the range of 0 to 1. |
a | number | 1 | The alpha color component in the range of 0 to 1. |
Returns#
void
Deprecated#
Use setFillSolidColor() instead.
getFillColorRGBA()#
Gets the fill color of a block as RGBA values.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose fill color should be queried. |
Returns#
RGBA
The fill color.
Deprecated#
Use getFillSolidColor() instead.
setFillColorEnabled()#
Enables or disables the fill of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose fill should be enabled or disabled. |
enabled | boolean | If true, the fill will be enabled. |
Returns#
void
Deprecated#
Use setFillEnabled() instead.
isFillColorEnabled()#
Checks if the fill of a block is enabled.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose fill state should be queried. |
Returns#
boolean
True, if fill is enabled.
Deprecated#
Use isFillEnabled() instead.
hasFill()#
Checks if a block has fill properties.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has fill properties.
Deprecated#
Use supportsFill instead.
supportsFill()#
Checks if a block supports a fill.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block supports a fill.
Signature#
supportsFill(id: number): boolean
isFillEnabled()#
Checks if the fill of a block is enabled.
engine.block.isFillEnabled(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose fill state should be queried. |
Returns#
boolean
The fill state.
Signature#
isFillEnabled(id: number): boolean
setFillEnabled()#
Enables or disables the fill of a block.
engine.block.setFillEnabled(block, false);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose fill should be enabled or disabled. |
enabled | boolean | If true, the fill will be enabled. |
Returns#
void
Signature#
setFillEnabled(id: number, enabled: boolean): void
getFill()#
Gets the fill block attached to a given block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose fill block should be returned. |
Returns#
number
The block that currently defines the given block’s fill.
Signature#
getFill(id: number): number
setFill()#
Sets the fill block for a given block.
The previous fill block is not destroyed automatically.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose fill should be changed. |
fill | number | The new fill block. |
Returns#
void
Signature#
setFill(id: number, fill: number): void
setFillSolidColor()#
Sets the solid fill color of a block.
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The block whose fill color should be set. |
r | number | undefined | The red color component in the range of 0 to 1. |
g | number | undefined | The green color component in the range of 0 to 1. |
b | number | undefined | The blue color component in the range of 0 to 1. |
a | number | 1 | The alpha color component in the range of 0 to 1. Defaults to 1. |
Returns#
void
Signature#
setFillSolidColor(id: number, r: number, g: number, b: number, a?: number): void
getFillSolidColor()#
Gets the solid fill color of a block as RGBA values.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose fill color should be queried. |
Returns#
RGBA
The fill color.
Signature#
getFillSolidColor(id: number): RGBA
Block Shapes#
Create and configure shape blocks and geometric forms.
createShape()#
Creates a new shape block of a given type.
const star = engine.block.createShape('star');// Longhand shape types are also supportedconst rect = engine.block.createShape('//ly.img.ubq/shape/rect');
Parameters#
Parameter | Type | Description |
---|---|---|
type | ShapeType | The type of the shape object that shall be created. |
Returns#
number
The created shape’s handle.
Signature#
createShape(type: ShapeType): number
hasShape()#
Checks if a block has a shape property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has a shape property, an error otherwise.
Deprecated#
Use supportsShape instead.
supportsShape()#
Checks if a block supports having a shape.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has a shape property, an error otherwise.
Signature#
supportsShape(id: number): boolean
getShape()#
Gets the shape block attached to a given block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose shape block should be returned. |
Returns#
number
The block that currently defines the given block’s shape.
Signature#
getShape(id: number): number
setShape()#
Sets the shape block for a given block.
Note that the previous shape block is not destroyed automatically. The new shape is disconnected from its previously attached block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose shape should be changed. |
shape | number | The new shape. |
Returns#
void
Signature#
setShape(id: number, shape: number): void
Block Text#
Create, edit, and style text content.
replaceText()#
Replaces a range of text in a text block.
engine.block.replaceText(text, 'Hello World');engine.block.replaceText(text, 'Alex', 6, 11);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block into which to insert the given text. |
text | string | undefined | The text which should replace the selected range in the block. |
from | number | -1 | The start index of the UTF-16 range to replace. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range to replace. Defaults to the end of the current selection or text. |
Returns#
void
Signature#
replaceText(id: number, text: string, from?: number, to?: number): void
removeText()#
Removes a range of text from a text block.
engine.block.removeText(text, 0, 6);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block from which the selected text should be removed. |
from | number | -1 | The start index of the UTF-16 range to remove. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range to remove. Defaults to the end of the current selection or text. |
Returns#
void
Signature#
removeText(id: number, from?: number, to?: number): void
setTextColor()#
Sets the color for a range of text.
engine.block.setTextColor(text, { r: 0.0, g: 0.0, b: 0.0, a: 1.0 }, 1, 4);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose color should be changed. |
color | Color | undefined | The new color of the selected text range. |
from | number | -1 | The start index of the UTF-16 range to change. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range to change. Defaults to the end of the current selection or text. |
Returns#
void
Signature#
setTextColor(id: number, color: Color, from?: number, to?: number): void
getTextColors()#
Gets the unique colors within a range of text.
const colorsInRange = engine.block.getTextColors(text, 2, 5);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose colors should be returned. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
Color
[]
The ordered unique list of colors.
Signature#
getTextColors(id: number, from?: number, to?: number): Color[]
setTextFontWeight()#
Sets the font weight for a range of text.
engine.block.setTextFontWeight(text, 'bold', 0, 5);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose weight should be changed. |
fontWeight | FontWeight | undefined | The new weight of the selected text range. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
void
Signature#
setTextFontWeight(id: number, fontWeight: FontWeight, from?: number, to?: number): void
getTextFontWeights()#
Gets the unique font weights within a range of text.
const fontWeights = engine.block.getTextFontWeights(text, 0, 6);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose font weights should be returned. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
The ordered unique list of font weights.
Signature#
getTextFontWeights(id: number, from?: number, to?: number): FontWeight[]
setTextFontSize()#
Sets the font size for a range of text.
engine.block.setTextFontSize(text, 12, 0, 5);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose font size should be changed. |
fontSize | number | undefined | The new font size. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
void
Signature#
setTextFontSize(id: number, fontSize: number, from?: number, to?: number): void
getTextFontSizes()#
Gets the unique font sizes within a range of text.
const fontSizes = engine.block.getTextFontSizes(text);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose font sizes should be returned. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
number
[]
The ordered unique list of font sizes.
Signature#
getTextFontSizes(id: number, from?: number, to?: number): number[]
setTextFontStyle()#
Sets the font style for a range of text.
engine.block.setTextFontStyle(text, 'italic', 0, 5);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose style should be changed. |
fontStyle | FontStyle | undefined | The new style of the selected text range. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
void
Signature#
setTextFontStyle(id: number, fontStyle: FontStyle, from?: number, to?: number): void
getTextFontStyles()#
Gets the unique font styles within a range of text.
const fontStyles = engine.block.getTextFontStyles(text);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose font styles should be returned. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
The ordered unique list of font styles.
Signature#
getTextFontStyles(id: number, from?: number, to?: number): FontStyle[]
getTextCases()#
Gets the unique text cases within a range of text.
const textCases = engine.block.getTextCases(text);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose text cases should be returned. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
TextCase
[]
The ordered list of text cases.
Signature#
getTextCases(id: number, from?: number, to?: number): TextCase[]
setTextCase()#
Sets the text case for a range of text.
engine.block.setTextCase(text, 'Titlecase');
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose text case should be changed. |
textCase | TextCase | undefined | The new text case value. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
void
Signature#
setTextCase(id: number, textCase: TextCase, from?: number, to?: number): void
canToggleBoldFont()#
Checks if the bold font weight can be toggled for a range of text.
Returns true if any part of the range is not bold and the bold font is available.
const canToggleBold = engine.block.canToggleBoldFont(text);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block to check. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
boolean
Whether the font weight can be toggled.
Signature#
canToggleBoldFont(id: number, from?: number, to?: number): boolean
canToggleItalicFont()#
Checks if the italic font style can be toggled for a range of text.
Returns true if any part of the range is not italic and the italic font is available.
const canToggleItalic = engine.block.canToggleItalicFont(text);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block to check. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
boolean
Whether the font style can be toggled.
Signature#
canToggleItalicFont(id: number, from?: number, to?: number): boolean
toggleBoldFont()#
Toggles the font weight of a text range between bold and normal.
If any part of the range is not bold, the entire range becomes bold. If the entire range is already bold, it becomes normal.
engine.block.toggleBoldFont(text);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block to modify. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
void
Signature#
toggleBoldFont(id: number, from?: number, to?: number): void
toggleItalicFont()#
Toggles the font style of a text range between italic and normal.
If any part of the range is not italic, the entire range becomes italic. If the entire range is already italic, it becomes normal.
engine.block.toggleItalicFont(text);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block to modify. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
void
Signature#
toggleItalicFont(id: number, from?: number, to?: number): void
setFont()#
Sets the font and typeface for an entire text block.
Existing formatting is reset.
engine.block.setFont(text, font.uri, typeface);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The text block whose font should be changed. |
fontFileUri | string | The URI of the new font file. |
typeface | Typeface | The typeface of the new font. |
Returns#
void
Signature#
setFont(id: number, fontFileUri: string, typeface: Typeface): void
setTypeface()#
Sets the typeface for a range of text.
The current formatting is retained as much as possible.
engine.block.setTypeface(text, typeface, 2, 5);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose font should be changed. |
typeface | Typeface | undefined | The new typeface. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
void
Signature#
setTypeface(id: number, typeface: Typeface, from?: number, to?: number): void
getTypeface()#
Gets the base typeface of a text block.
This does not return the typefaces of individual text runs.
const defaultTypeface = engine.block.getTypeface(text);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The text block whose typeface should be queried. |
Returns#
Typeface
the typeface property of the text block.
Signature#
getTypeface(id: number): Typeface
getTypefaces()#
Gets the unique typefaces within a range of text.
const currentTypefaces = engine.block.getTypefaces(text);
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The text block whose typefaces should be queried. |
from | number | -1 | The start index of the UTF-16 range. Defaults to the start of the current selection or text. |
to | number | -1 | The end index of the UTF-16 range. Defaults to the end of the current selection or text. |
Returns#
Typeface
[]
The unique typefaces in the range.
Signature#
getTypefaces(id: number, from?: number, to?: number): Typeface[]
getTextCursorRange()#
Gets the current text cursor or selection range.
Returns the UTF-16 indices of the selected range of the text block that is currently being edited.
const selectedRange = engine.block.getTextCursorRange();
Returns#
Range
The selected UTF-16 range or { from: -1, to: -1 }
if no text block is being edited.
Signature#
getTextCursorRange(): Range
getTextVisibleLineCount()#
Gets the number of visible lines in a text block.
const lineCount = engine.block.getTextVisibleLineCount(text);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The text block whose line count should be returned. |
Returns#
number
The number of lines in the text block.
Signature#
getTextVisibleLineCount(id: number): number
getTextVisibleLineGlobalBoundingBoxXYWH()#
Gets the global bounding box of a visible line of text.
The values are in the scene’s global coordinate space.
const lineBoundingBox = engine.block.getTextVisibleLineGlobalBoundingBoxXYWH(text, 0);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The text block whose line bounding box should be returned. |
lineIndex | number | The index of the line whose bounding box should be returned. |
Returns#
XYWH
The bounding box of the line.
Signature#
getTextVisibleLineGlobalBoundingBoxXYWH(id: number, lineIndex: number): XYWH
getTextVisibleLineContent()#
Gets the text content of a visible line.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The text block whose line content should be returned. |
lineIndex | number | The index of the line whose content should be returned. |
Returns#
string
The text content of the line.
Signature#
getTextVisibleLineContent(id: number, lineIndex: number): string
Block Video#
Manage time-based media like video and audio, including playback, timing, and controls.
createCaptionsFromURI()#
Creates new caption blocks from an SRT or VTT file URI.
Parameters#
Parameter | Type | Description |
---|---|---|
uri | string | The URI for the captions file to load. Supported file formats are: SRT and VTT. |
Returns#
Promise
<number
[]>
A promise that resolves with a list of the created caption blocks.
Signature#
createCaptionsFromURI(uri: string): Promise<number[]>
hasDuration()#
Checks if a block has a duration property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true if the block has a duration property.
Deprecated#
Use supportsDuration instead.
supportsDuration()#
Checks if a block supports a duration property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true if the block supports a duration property.
Signature#
supportsDuration(id: number): boolean
setDuration()#
Sets the playback duration of a block.
The duration defines how long the block is active in the scene during playback.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose duration should be changed. |
duration | number | The new duration in seconds. |
Returns#
void
Signature#
setDuration(id: number, duration: number): void
getDuration()#
Gets the playback duration of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose duration should be returned. |
Returns#
number
The block’s duration in seconds.
Signature#
getDuration(id: number): number
setPageDurationSource()#
Sets a block as the page’s duration source.
This causes the page’s total duration to be automatically determined by this block.
Parameters#
Parameter | Type | Description |
---|---|---|
page | number | The page block for which it should be enabled. |
id | number | The block that should become the duration source. |
Returns#
void
Signature#
setPageDurationSource(page: number, id: number): void
isPageDurationSource()#
Checks if a block is the duration source for its page.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose duration source property should be queried. |
Returns#
boolean
true if the block is a duration source for a page.
Signature#
isPageDurationSource(id: number): boolean
supportsPageDurationSource()#
Checks if a block can be set as the page’s duration source.
Parameters#
Parameter | Type | Description |
---|---|---|
page | number | The page to check against. |
id | number | The block to query. |
Returns#
boolean
true, if the block can be marked as the page’s duration source.
Signature#
supportsPageDurationSource(page: number, id: number): boolean
removePageDurationSource()#
Removes a block as the page’s duration source.
If a scene or page is given, it is deactivated for all blocks within it.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose duration source property should be removed. |
Returns#
void
Signature#
removePageDurationSource(id: number): void
hasTimeOffset()#
Checks if a block has a time offset property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has a time offset property.
Deprecated#
Use supportsTimeOffset instead.
supportsTimeOffset()#
Checks if a block supports a time offset.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block supports a time offset.
Signature#
supportsTimeOffset(id: number): boolean
setTimeOffset()#
Sets the time offset of a block relative to its parent.
The time offset controls when the block first becomes active in the timeline.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose time offset should be changed. |
offset | number | The new time offset in seconds. |
Returns#
void
Signature#
setTimeOffset(id: number, offset: number): void
getTimeOffset()#
Gets the time offset of a block relative to its parent.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose time offset should be queried. |
Returns#
number
The time offset of the block in seconds.
Signature#
getTimeOffset(id: number): number
hasTrim()#
Checks if a block has trim properties.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has trim properties.
Deprecated#
Use supportsTrim instead.
supportsTrim()#
Checks if a block supports trim properties.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block supports trim properties.
Signature#
supportsTrim(id: number): boolean
setTrimOffset()#
Sets the trim offset of a block’s media content.
This sets the time within the media clip where playback should begin.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose trim should be updated. |
offset | number | The new trim offset in seconds. |
Returns#
void
Signature#
setTrimOffset(id: number, offset: number): void
getTrimOffset()#
Gets the trim offset of a block’s media content.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose trim offset should be queried. |
Returns#
number
the trim offset in seconds.
Signature#
getTrimOffset(id: number): number
setTrimLength()#
Sets the trim length of a block’s media content.
This is the duration of the media clip that should be used for playback.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The object whose trim length should be updated. |
length | number | The new trim length in seconds. |
Returns#
void
Signature#
setTrimLength(id: number, length: number): void
getTrimLength()#
Gets the trim length of a block’s media content.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The object whose trim length should be queried. |
Returns#
number
The trim length of the object in seconds.
Signature#
getTrimLength(id: number): number
getTotalSceneDuration()#
Gets the total duration of a scene in video mode.
Parameters#
Parameter | Type | Description |
---|---|---|
scene | number | The scene whose duration is being queried. |
Returns#
number
the total scene duration.
Deprecated#
Use getDuration
and pass a page block.
setPlaying()#
Sets whether a block should play its content during active playback.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block that should be updated. |
enabled | boolean | Whether the block should be playing its contents. |
Returns#
void
Signature#
setPlaying(id: number, enabled: boolean): void
isPlaying()#
Checks if a block is playing its content.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
whether the block is playing during playback.
Signature#
isPlaying(id: number): boolean
hasPlaybackTime()#
Checks if a block has a playback time property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
whether the block has a playback time property.
Deprecated#
Use supportsPlaybackTime instead.
supportsPlaybackTime()#
Checks if a block supports a playback time property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
whether the block supports a playback time property.
Signature#
supportsPlaybackTime(id: number): boolean
setPlaybackTime()#
Sets the current playback time of a block’s content.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose playback time should be updated. |
time | number | The new playback time of the block in seconds. |
Returns#
void
Signature#
setPlaybackTime(id: number, time: number): void
getPlaybackTime()#
Gets the current playback time of a block’s content.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The playback time of the block in seconds.
Signature#
getPlaybackTime(id: number): number
setSoloPlaybackEnabled()#
Enables or disables solo playback for a block.
When enabled, only this block’s content will play while the rest of the scene remains paused.
engine.block.setSoloPlaybackEnabled(videoFill, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block or fill to update. |
enabled | boolean | Whether solo playback should be enabled. |
Returns#
void
Signature#
setSoloPlaybackEnabled(id: number, enabled: boolean): void
isSoloPlaybackEnabled()#
Checks if solo playback is enabled for a block.
engine.block.isSoloPlaybackEnabled(videoFill);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block or fill to query. |
Returns#
boolean
Whether solo playback is enabled for this block.
Signature#
isSoloPlaybackEnabled(id: number): boolean
hasPlaybackControl()#
Checks if a block has playback controls.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
Whether the block has playback control.
Deprecated#
Use supportsPlaybackControl instead
supportsPlaybackControl()#
Checks if a block supports playback controls.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
Whether the block supports playback control.
Signature#
supportsPlaybackControl(id: number): boolean
setLooping()#
Sets whether a block’s media content should loop.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block or video fill to update. |
looping | boolean | Whether the block should loop to the beginning or stop. |
Returns#
void
Signature#
setLooping(id: number, looping: boolean): void
isLooping()#
Checks if a block’s media content is set to loop.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
Whether the block is looping.
Signature#
isLooping(id: number): boolean
setMuted()#
Sets whether the audio of a block is muted.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block or video fill to update. |
muted | boolean | Whether the audio should be muted. |
Returns#
void
Signature#
setMuted(id: number, muted: boolean): void
isMuted()#
Checks if a block’s audio is muted.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
Whether the block is muted.
Signature#
isMuted(id: number): boolean
setVolume()#
Sets the audio volume of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block or video fill to update. |
volume | number | The desired volume, ranging from 0.0 to 1.0. |
Returns#
void
Signature#
setVolume(id: number, volume: number): void
getVolume()#
Gets the audio volume of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The volume, ranging from 0.0 to 1.0.
Signature#
getVolume(id: number): number
forceLoadAVResource()#
Forces the loading of a block’s audio/video resource.
If the resource failed to load previously, it will be reloaded.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The video fill or audio block whose resource should be loaded. |
Returns#
Promise
<void
>
A Promise that resolves once the resource has finished loading.
Signature#
forceLoadAVResource(id: number): Promise<void>
unstable_isAVResourceLoaded()#
Checks if a block’s audio/video resource is loaded.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The video fill or audio block. |
Returns#
boolean
The loading state of the resource. This API is experimental and may change or be removed in future versions.
getAVResourceTotalDuration()#
Gets the total duration of a block’s audio/video resource.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The video fill or audio block. |
Returns#
number
The video or audio file duration in seconds.
Signature#
getAVResourceTotalDuration(id: number): number
getVideoWidth()#
Gets the width of a block’s video resource.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The video fill block. |
Returns#
number
The video width in pixels.
Signature#
getVideoWidth(id: number): number
getVideoHeight()#
Gets the height of a block’s video resource.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The video fill block. |
Returns#
number
The video height in pixels.
Signature#
getVideoHeight(id: number): number
generateVideoThumbnailSequence()#
Generate a sequence of thumbnails for the given video fill or design block.
Note: There can only be one thumbnail generation request in progress for a given block. Note: During playback, the thumbnail generation will be paused.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The video fill or design block. |
thumbnailHeight | number | The height of each thumbnail. |
timeBegin | number | The start time in seconds for the thumbnail sequence. |
timeEnd | number | The end time in seconds for the thumbnail sequence. |
numberOfFrames | number | The number of frames to generate. |
onFrame | (frameIndex , result ) => void | A callback that receives the frame index and image data. |
Returns#
A function to cancel the thumbnail generation request.
(): void;
Returns#
void
Signature#
generateVideoThumbnailSequence(id: number, thumbnailHeight: number, timeBegin: number, timeEnd: number, numberOfFrames: number, onFrame: (frameIndex: number, result: ImageData | Error) => void): () => void
generateAudioThumbnailSequence()#
Generate a thumbnail sequence for the given audio block or video fill.
A thumbnail in this case is a chunk of samples in the range of 0 to 1. In case stereo data is requested, the samples are interleaved, starting with the left channel. Note: During playback, the thumbnail generation will be paused.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The audio block or video fill. |
samplesPerChunk | number | The number of samples per chunk. |
timeBegin | number | The start time in seconds for the thumbnail sequence. |
timeEnd | number | The end time in seconds for the thumbnail sequence. |
numberOfSamples | number | The total number of samples to generate. |
numberOfChannels | number | The number of channels in the output (1 for mono, 2 for stereo). |
onChunk | (chunkIndex , result ) => void | A callback that receives the chunk index and sample data. |
Returns#
A function to cancel the thumbnail generation request.
(): void;
Returns#
void
Signature#
generateAudioThumbnailSequence(id: number, samplesPerChunk: number, timeBegin: number, timeEnd: number, numberOfSamples: number, numberOfChannels: number, onChunk: (chunkIndex: number, result: Error | Float32Array) => void): () => void
getVideoFillThumbnail()#
Generates a thumbnail for a video fill.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The video fill. |
thumbnailHeight | number | The height of a thumbnail. The width will be calculated from the video aspect ratio. |
Returns#
Promise
<Blob
>
A promise that resolves with a thumbnail encoded as a JPEG blob.
Deprecated#
Use generateVideoThumbnailSequence
instead.
getVideoFillThumbnailAtlas()#
Generates a thumbnail atlas for a video fill.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The video fill. |
numberOfColumns | number | The number of columns in the atlas. |
numberOfRows | number | The number of rows in the atlas. |
thumbnailHeight | number | The height of a single thumbnail. |
Returns#
Promise
<Blob
>
A promise that resolves with a thumbnail atlas encoded as a JPEG blob.
Deprecated#
Use generateVideoThumbnailSequence
instead.
getPageThumbnailAtlas()#
Generates a thumbnail atlas for a page.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The page. |
numberOfColumns | number | The number of columns in the atlas. |
numberOfRows | number | The number of rows in the atlas. |
thumbnailHeight | number | The height of a single thumbnail. |
Returns#
Promise
<Blob
>
A promise that resolves with a thumbnail atlas encoded as a JPEG blob.
Deprecated#
Use generateVideoThumbnailSequence
instead.
setNativePixelBuffer()#
Updates a pixel stream fill block with a new pixel buffer.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The pixel stream fill block. |
buffer | HTMLCanvasElement | HTMLVideoElement |
Returns#
void
Signature#
setNativePixelBuffer(id: number, buffer: HTMLCanvasElement | HTMLVideoElement): void
Block Animations#
Create and manage animations and timeline-based effects.
createAnimation()#
Creates a new animation block.
Parameters#
Parameter | Type | Description |
---|---|---|
type | AnimationType | The type of animation to create. |
Returns#
number
The handle of the new animation instance.
Signature#
createAnimation(type: AnimationType): number
supportsAnimation()#
Checks if a block supports animation.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
Whether the block supports animation.
Signature#
supportsAnimation(id: number): boolean
setInAnimation()#
Sets the “in” animation of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose “in” animation should be set. |
animation | number | The animation to set. |
Returns#
void
Signature#
setInAnimation(id: number, animation: number): void
setLoopAnimation()#
Sets the “loop” animation of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose “loop” animation should be set. |
animation | number | The animation to set. |
Returns#
void
Signature#
setLoopAnimation(id: number, animation: number): void
setOutAnimation()#
Sets the “out” animation of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose “out” animation should be set. |
animation | number | The animation to set. |
Returns#
void
Signature#
setOutAnimation(id: number, animation: number): void
getInAnimation()#
Gets the “in” animation of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose “in” animation should be queried. |
Returns#
number
The “in” animation of the block.
Signature#
getInAnimation(id: number): number
getLoopAnimation()#
Gets the “loop” animation of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose “loop” animation should be queried. |
Returns#
number
The “loop” animation of the block.
Signature#
getLoopAnimation(id: number): number
getOutAnimation()#
Gets the “out” animation of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose “out” animation should be queried. |
Returns#
number
The “out” animation of the block.
Signature#
getOutAnimation(id: number): number
Block Groups#
Create and manage groups of blocks.
isGroupable()#
Checks if a set of blocks can be grouped.
A scene block or a block that is already part of a group cannot be grouped.
const groupable = engine.block.isGroupable([block1, block2])
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | An array of block ids. |
Returns#
boolean
Whether the blocks can be grouped together.
Signature#
isGroupable(ids: number[]): boolean
group()#
Groups multiple blocks into a new group block.
if (engine.block.isGroupable([block1, block2])) { const group = engine.block.group(block1, block2]);}
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | A non-empty array of block ids. |
Returns#
number
The block id of the created group.
Signature#
group(ids: number[]): number
ungroup()#
Ungroups a group block, releasing its children.
engine.block.ungroup(group);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The group id from a previous call to group . |
Returns#
void
Signature#
ungroup(id: number): void
enterGroup()#
Changes selection to a block within a selected group.
Nothing happens if the target is not a group.
engine.block.enterGroup(group);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The group id from a previous call to group . |
Returns#
void
Signature#
enterGroup(id: number): void
exitGroup()#
Changes selection from a block to its parent group.
Nothing happens if the block is not part of a group.
engine.block.exitGroup(member1);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | A block id. |
Returns#
void
Signature#
exitGroup(id: number): void
Block State#
Query the intrinsic state or identity of a block, such as its name, UUID, or lock status.
getType()#
Gets the longhand type of a given block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
ObjectTypeLonghand
The block’s type.
Signature#
getType(id: number): ObjectTypeLonghand
setName()#
Sets the name of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
name | string | The name to set. |
Returns#
void
Signature#
setName(id: number, name: string): void
getName()#
Gets the name of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
string
The block’s name.
Signature#
getName(id: number): string
getUUID()#
Gets the unique universal identifier (UUID) of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
string
The block’s UUID.
Signature#
getUUID(id: number): string
isValid()#
Checks if a block handle is valid.
A block becomes invalid once it has been destroyed.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True, if the block is valid.
Signature#
isValid(id: number): boolean
referencesAnyVariables()#
Checks if a block references any variables.
This check does not recurse into children.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to inspect. |
Returns#
boolean
true if the block references variables and false otherwise.
Signature#
referencesAnyVariables(id: number): boolean
isIncludedInExport()#
Checks if a block is included in exports.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block is included on the exported result, false otherwise.
Signature#
isIncludedInExport(id: number): boolean
setIncludedInExport()#
Sets whether a block should be included in exports.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose exportable state should be set. |
enabled | boolean | If true, the block will be included on the exported result. |
Returns#
void
Signature#
setIncludedInExport(id: number, enabled: boolean): void
isVisibleAtCurrentPlaybackTime()#
Checks if a block is visible at the current scene playback time.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
Whether the block should be visible on the canvas at the current playback time.
Signature#
isVisibleAtCurrentPlaybackTime(id: number): boolean
getState()#
Gets the current state of a block.
A block’s state is determined by its own state and that of its shape, fill, and effects.
const state = engine.block.getState(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
BlockState
The block’s state: ‘Ready’, ‘Pending’, or ‘Error’.
Signature#
getState(id: number): BlockState
setState()#
Sets the state of a block.
engine.block.setState(video, {type: 'Pending', progress: 0.5});engine.block.setState(page, {type: 'Ready'});engine.block.setState(image, {type: 'Error', error: 'ImageDecoding'});
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose state should be set. |
state | BlockState | The new state to set. |
Returns#
void
Signature#
setState(id: number, state: BlockState): void
Block Crop#
Crop, scale, translate, and transform block content.
hasCrop()#
Checks if a block has crop properties.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block has crop properties.
Deprecated#
Use supportsCrop() instead.
supportsCrop()#
Checks if a block supports cropping.
engine.block.supportsCrop(image);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
true, if the block supports cropping.
Signature#
supportsCrop(id: number): boolean
setCropScaleX()#
Sets the horizontal crop scale of a block.
engine.block.setCropScaleX(image, 2.0);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop should be set. |
scaleX | number | The scale in x direction. |
Returns#
void
Signature#
setCropScaleX(id: number, scaleX: number): void
setCropScaleY()#
Sets the vertical crop scale of a block.
engine.block.setCropScaleY(image, 1.5);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop should be set. |
scaleY | number | The scale in y direction. |
Returns#
void
Signature#
setCropScaleY(id: number, scaleY: number): void
setCropRotation()#
Sets the crop rotation of a block.
engine.block.setCropRotation(image, Math.PI);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop should be set. |
rotation | number | The rotation in radians. |
Returns#
void
Signature#
setCropRotation(id: number, rotation: number): void
setCropScaleRatio()#
Sets the uniform crop scale ratio of a block.
This scales the content up or down from the center of the crop frame.
engine.block.setCropScaleRatio(image, 3.0);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop should be set. |
scaleRatio | number | The crop scale ratio. |
Returns#
void
Signature#
setCropScaleRatio(id: number, scaleRatio: number): void
setCropTranslationX()#
Sets the horizontal crop translation of a block.
engine.block.setCropTranslationX(image, -1.0);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop should be set. |
translationX | number | The translation in x direction. |
Returns#
void
Signature#
setCropTranslationX(id: number, translationX: number): void
setCropTranslationY()#
Sets the vertical crop translation of a block.
engine.block.setCropTranslationY(image, 1.0);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop should be set. |
translationY | number | The translation in y direction. |
Returns#
void
Signature#
setCropTranslationY(id: number, translationY: number): void
resetCrop()#
Resets the crop of a block to its default state.
The block’s content fill mode is set to ‘Cover’.
engine.block.resetCrop(image);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop should be reset. |
Returns#
void
Signature#
resetCrop(id: number): void
getCropScaleX()#
Gets the horizontal crop scale of a block.
const scaleX = engine.block.getCropScaleX(image);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose scale should be queried. |
Returns#
number
The scale on the x axis.
Signature#
getCropScaleX(id: number): number
getCropScaleY()#
Gets the vertical crop scale of a block.
const scaleY = engine.block.getCropScaleY(image);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose scale should be queried. |
Returns#
number
The scale on the y axis.
Signature#
getCropScaleY(id: number): number
getCropRotation()#
Gets the crop rotation of a block.
const cropRotation = engine.block.getCropRotation(image);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop rotation should be queried. |
Returns#
number
The crop rotation in radians.
Signature#
getCropRotation(id: number): number
getCropScaleRatio()#
Gets the uniform crop scale ratio of a block.
const cropScaleRatio = engine.block.getCropScaleRatio(image);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop scale ratio should be queried. |
Returns#
number
The crop scale ratio.
Signature#
getCropScaleRatio(id: number): number
getCropTranslationX()#
Gets the horizontal crop translation of a block.
const cropTranslationX = engine.block.getCropTranslationX(image);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose translation should be queried. |
Returns#
number
The translation on the x axis.
Signature#
getCropTranslationX(id: number): number
getCropTranslationY()#
Gets the vertical crop translation of a block.
const cropTranslationY = engine.block.getCropTranslationY(image);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose translation should be queried. |
Returns#
number
The translation on the y axis.
Signature#
getCropTranslationY(id: number): number
adjustCropToFillFrame()#
Adjusts the crop position and scale to fill the crop frame.
const adjustedScaleRatio = engine.block.adjustCropToFillFrame(image, 1.0);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop should be adjusted. |
minScaleRatio | number | The minimal crop scale ratio to use. |
Returns#
number
The adjusted scale ratio.
Signature#
adjustCropToFillFrame(id: number, minScaleRatio: number): number
flipCropHorizontal()#
Flips the content horizontally within its crop frame.
engine.block.flipCropHorizontal(image);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop should be updated. |
Returns#
void
Signature#
flipCropHorizontal(id: number): void
flipCropVertical()#
Flips the content vertically within its crop frame.
engine.block.flipCropVertical(image);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose crop should be updated. |
Returns#
void
Signature#
flipCropVertical(id: number): void
Block Events#
Subscribe to user actions and state changes related to blocks.
onSelectionChanged()#
Subscribes to changes in the selection.
Parameters#
Parameter | Type | Description |
---|---|---|
callback | () => void | This function is called at the end of the engine update if the selection has changed. |
Returns#
A method to unsubscribe.
(): void;
Returns#
void
Signature#
onSelectionChanged(callback: () => void): () => void
onClicked()#
Subscribes to block click events.
Parameters#
Parameter | Type | Description |
---|---|---|
callback | (id ) => void | This function is called at the end of the engine update if a block has been clicked. |
Returns#
A method to unsubscribe.
(): void;
Returns#
void
Signature#
onClicked(callback: (id: number) => void): () => void
onStateChanged()#
Subscribes to state changes for a set of blocks.
The state is determined by the block and its associated shape, fill, and effects.
const unsubscribe = engine.block.onStateChanged([], (blocks) => { blocks.forEach(block => console.log(block));});
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | A list of block IDs to monitor. If empty, all blocks are monitored. |
callback | (ids ) => void | The function to call when a state changes. |
Returns#
A function to unsubscribe from the event.
(): void;
Returns#
void
Signature#
onStateChanged(ids: number[], callback: (ids: number[]) => void): () => void
Block Utils#
Check block capabilities like alignability or distributability.
isAlignable()#
Checks if a set of blocks can be aligned.
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | An array of block ids. |
Returns#
boolean
Whether the blocks can be aligned.
Signature#
isAlignable(ids: number[]): boolean
isDistributable()#
Checks if a set of blocks can be distributed.
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | An array of block ids. |
Returns#
boolean
Whether the blocks can be distributed.
Signature#
isDistributable(ids: number[]): boolean
Block Kind#
Get and set a block’s ‘kind’ identifier for custom categorization.
getKind()#
Gets the kind of a given block.
const kind = engine.block.getKind(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
string
The block’s kind.
Signature#
getKind(id: number): string
setKind()#
Sets the kind of a given block, a custom string for categorization of blocks.
engine.block.setKind(text, 'title');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose kind should be changed. |
kind | string | The new kind. |
Returns#
void
Signature#
setKind(id: number, kind: string): void
Block Properties#
Get and set any block property by name using low-level, generic accessors.
findAllProperties()#
Gets all available properties of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose properties should be queried. |
Returns#
string
[]
A list of the property names.
Signature#
findAllProperties(id: number): string[]
isPropertyReadable()#
Checks if a property is readable.
Parameters#
Parameter | Type | Description |
---|---|---|
property | string | The name of the property to check. |
Returns#
boolean
Whether the property is readable. Returns false for unknown properties.
Signature#
isPropertyReadable(property: string): boolean
isPropertyWritable()#
Checks if a property is writable.
Parameters#
Parameter | Type | Description |
---|---|---|
property | string | The name of the property to check. |
Returns#
boolean
Whether the property is writable. Returns false for unknown properties.
Signature#
isPropertyWritable(property: string): boolean
getPropertyType()#
Gets the type of a property by its name.
Parameters#
Parameter | Type | Description |
---|---|---|
property | string | The name of the property whose type should be queried. |
Returns#
PropertyType
The property type.
Signature#
getPropertyType(property: string): PropertyType
getEnumValues()#
Gets all possible values of an enum property.
Type Parameters#
Type Parameter | Default type |
---|---|
T | string |
Parameters#
Parameter | Type | Description |
---|---|---|
enumProperty | string | The name of the property whose enum values should be queried. |
Returns#
T
[]
A list of the enum value names as a string array.
Signature#
getEnumValues(enumProperty: string): T[]
setBool()#
Sets a boolean property on a block.
engine.block.setBool(scene, 'scene/aspectRatioLock', false);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be set. |
property | string | The name of the property to set. |
value | boolean | The value to set. |
Returns#
void
Signature#
setBool(id: number, property: string, value: boolean): void
getBool()#
Gets a boolean property from a block.
engine.block.getBool(scene, 'scene/aspectRatioLock');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be queried. |
property | string | The name of the property to query. |
Returns#
boolean
The value of the property.
Signature#
getBool(id: number, property: string): boolean
setInt()#
Sets an integer property on a block.
engine.block.setInt(starShape, 'shape/star/points', points + 2);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be set. |
property | string | The name of the property to set. |
value | number | The value to set. |
Returns#
void
Signature#
setInt(id: number, property: string, value: number): void
getInt()#
Gets an integer property from a block.
engine.block.setInt(starShape, 'shape/star/points', points + 2);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be queried. |
property | string | The name of the property to query. |
Returns#
number
The value of the property.
Signature#
getInt(id: number, property: string): number
setFloat()#
Sets a float property on a block.
engine.block.setFloat(text, "text/letterSpacing", 0.2);engine.block.setFloat(text, "text/lineHeight", 1.2);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be set. |
property | string | The name of the property to set. |
value | number | The value to set. |
Returns#
void
Signature#
setFloat(id: number, property: string, value: number): void
getFloat()#
Gets a float property from a block.
engine.block.getFloat(starShape, 'shape/star/innerDiameter');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be queried. |
property | string | The name of the property to query. |
Returns#
number
The value of the property.
Signature#
getFloat(id: number, property: string): number
setDouble()#
Sets a double-precision float property on a block.
engine.block.setDouble(audio, 'playback/duration', 1.0);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be set. |
property | string | The name of the property to set. |
value | number | The value to set. |
Returns#
void
Signature#
setDouble(id: number, property: string, value: number): void
getDouble()#
Gets a double-precision float property from a block.
engine.block.getDouble(audio, 'playback/duration');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be queried. |
property | string | The name of the property to query. |
Returns#
number
The value of the property.
Signature#
getDouble(id: number, property: string): number
setString()#
Sets a string property on a block.
engine.block.setString(text, 'text/text', 'Hello World');engine.block.setString(imageFill, 'fill/image/imageFileURI', 'https://example.com/sample.jpg');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be set. |
property | string | The name of the property to set. |
value | string | The value to set. |
Returns#
void
Signature#
setString(id: number, property: string, value: string): void
getString()#
Gets a string property from a block.
engine.block.getString(text, 'text/text');engine.block.getString(imageFill, 'fill/image/imageFileURI');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be queried. |
property | string | The name of the property to query. |
Returns#
string
The value of the property.
Signature#
getString(id: number, property: string): string
setColor()#
Sets a color property on a block.
// Set the block's fill color to white.engine.block.setColor(colorFill, 'fill/color/value', { r: 1, g: 1, b: 1, a: 1 });
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be set. |
property | string | The name of the property to set. |
value | Color | The value to set. |
Returns#
void
Signature#
setColor(id: number, property: string, value: Color): void
getColor()#
Gets a color property from a block.
engine.block.getColor(colorFill, 'fill/color/value');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be queried. |
property | string | The name of the property to query. |
Returns#
Color
The value of the property.
Signature#
getColor(id: number, property: string): Color
setColorRGBA()#
Sets a color property on a block using RGBA values.
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The block whose property should be set. |
property | string | undefined | The name of the property to set. |
r | number | undefined | The red color component in the range of 0 to 1. |
g | number | undefined | The green color component in the range of 0 to 1. |
b | number | undefined | The blue color component in the range of 0 to 1. |
a | number | 1 | The alpha color component in the range of 0 to 1. Defaults to 1. |
Returns#
void
Deprecated#
Use setColor() instead.
getColorRGBA()#
Gets a color property from a block as RGBA values.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be queried. |
property | string | The name of the property to query. |
Returns#
RGBA
A tuple of channels red, green, blue and alpha in the range of 0 to 1.
Deprecated#
Use getColor() instead.
setColorSpot()#
Sets a spot color property on a block.
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The block whose property should be set. |
property | string | undefined | The name of the property to set. |
name | string | undefined | The name of the spot color. |
tint | number | 1 | The tint factor in the range of 0 to 1. Defaults to 1. |
Returns#
void
Deprecated#
Use setColor() instead.
getColorSpotName()#
Gets the spot color name from a color property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be queried. |
property | string | The name of the property to query. |
Returns#
string
The name of the spot color.
Deprecated#
Use getColor() instead.
getColorSpotTint()#
Gets the spot color tint from a color property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be queried. |
property | string | The name of the property to query. |
Returns#
number
The tint factor of the spot color.
Deprecated#
Use getColor() instead.
setEnum()#
Sets an enum property on a block.
engine.block.setEnum(text, 'text/horizontalAlignment', 'Center');engine.block.setEnum(text, 'text/verticalAlignment', 'Center');
Type Parameters#
Type Parameter | Default type |
---|---|
T extends string | string |
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be set. |
property | string | The name of the property to set. |
value | T | The enum value as a string. |
Returns#
void
Signature#
setEnum(id: number, property: string, value: T): void
getEnum()#
Gets an enum property from a block.
engine.block.getEnum(text, 'text/horizontalAlignment');engine.block.getEnum(text, 'text/verticalAlignment');
Type Parameters#
Type Parameter | Default type |
---|---|
T extends string | string |
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose property should be queried. |
property | string | The name of the property to query. |
Returns#
T
The value as a string.
Signature#
getEnum(id: number, property: string): T
Block Strokes#
Control stroke appearance, including color, width, style, and position.
hasStroke()#
Checks if a block has a stroke property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True if the block has a stroke property.
Deprecated#
Use supportsStroke() instead.
supportsStroke()#
Checks if a block supports a stroke.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True if the block supports a stroke.
Signature#
supportsStroke(id: number): boolean
setStrokeEnabled()#
Enables or disables the stroke of a block.
engine.block.setStrokeEnabled(block, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke should be enabled or disabled. |
enabled | boolean | If true, the stroke will be enabled. |
Returns#
void
Signature#
setStrokeEnabled(id: number, enabled: boolean): void
isStrokeEnabled()#
Checks if the stroke of a block is enabled.
const strokeIsEnabled = engine.block.isStrokeEnabled(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke state should be queried. |
Returns#
boolean
True if the block’s stroke is enabled.
Signature#
isStrokeEnabled(id: number): boolean
setStrokeColorRGBA()#
Sets the stroke color of a block using RGBA values.
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The block whose stroke color should be set. |
r | number | undefined | The red color component in the range of 0 to 1. |
g | number | undefined | The green color component in the range of 0 to 1. |
b | number | undefined | The blue color component in the range of 0 to 1. |
a | number | 1 | The alpha color component in the range of 0 to 1. |
Returns#
void
Deprecated#
Use setStrokeColor() instead.
setStrokeColor()#
Sets the stroke color of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke color should be set. |
color | Color | The color to set. |
Returns#
void
Signature#
setStrokeColor(id: number, color: Color): void
getStrokeColorRGBA()#
Gets the stroke color of a block as RGBA values.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke color should be queried. |
Returns#
RGBA
The stroke color.
Deprecated#
Use getStrokeColor() instead.
getStrokeColor()#
Gets the stroke color of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke color should be queried. |
Returns#
Color
The stroke color.
Signature#
getStrokeColor(id: number): Color
setStrokeWidth()#
Sets the stroke width of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke width should be set. |
width | number | The stroke width to be set. |
Returns#
void
Signature#
setStrokeWidth(id: number, width: number): void
getStrokeWidth()#
Gets the stroke width of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke width should be queried. |
Returns#
number
The stroke’s width.
Signature#
getStrokeWidth(id: number): number
setStrokeStyle()#
Sets the stroke style of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke style should be set. |
style | StrokeStyle | The stroke style to be set. |
Returns#
void
Signature#
setStrokeStyle(id: number, style: StrokeStyle): void
getStrokeStyle()#
Gets the stroke style of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke style should be queried. |
Returns#
StrokeStyle
The stroke’s style.
Signature#
getStrokeStyle(id: number): StrokeStyle
setStrokePosition()#
Sets the stroke position of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke position should be set. |
position | StrokePosition | The stroke position to be set. |
Returns#
void
Signature#
setStrokePosition(id: number, position: StrokePosition): void
getStrokePosition()#
Gets the stroke position of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke position should be queried. |
Returns#
StrokePosition
The stroke position.
Signature#
getStrokePosition(id: number): StrokePosition
setStrokeCornerGeometry()#
Sets the stroke corner geometry of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke corner geometry should be set. |
cornerGeometry | StrokeCornerGeometry | The stroke corner geometry to be set. |
Returns#
void
Signature#
setStrokeCornerGeometry(id: number, cornerGeometry: StrokeCornerGeometry): void
getStrokeCornerGeometry()#
Gets the stroke corner geometry of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose stroke corner geometry should be queried. |
Returns#
StrokeCornerGeometry
The stroke corner geometry.
Signature#
getStrokeCornerGeometry(id: number): StrokeCornerGeometry
Block Drop Shadow#
Configure drop shadow effects, including blur, color, and offset.
hasDropShadow()#
Checks if a block has a drop shadow property.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True if the block has a drop shadow property.
Deprecated#
Use supportsDropShadow() instead.
supportsDropShadow()#
Checks if a block supports a drop shadow.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True if the block supports a drop shadow.
Signature#
supportsDropShadow(id: number): boolean
setDropShadowEnabled()#
Enables or disables the drop shadow of a block.
engine.block.setDropShadowEnabled(block, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow should be enabled or disabled. |
enabled | boolean | If true, the drop shadow will be enabled. |
Returns#
void
Signature#
setDropShadowEnabled(id: number, enabled: boolean): void
isDropShadowEnabled()#
Checks if the drop shadow of a block is enabled.
const dropShadowIsEnabled = engine.block.isDropShadowEnabled(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow state should be queried. |
Returns#
boolean
True if the block’s drop shadow is enabled.
Signature#
isDropShadowEnabled(id: number): boolean
setDropShadowColorRGBA()#
Sets the drop shadow color of a block using RGBA values.
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
id | number | undefined | The block whose drop shadow color should be set. |
r | number | undefined | The red color component in the range of 0 to 1. |
g | number | undefined | The green color component in the range of 0 to 1. |
b | number | undefined | The blue color component in the range of 0 to 1. |
a | number | 1 | The alpha color component in the range of 0 to 1. |
Returns#
void
Deprecated#
Use setDropShadowColor() instead.
setDropShadowColor()#
Sets the drop shadow color of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow color should be set. |
color | Color | The color to set. |
Returns#
void
Signature#
setDropShadowColor(id: number, color: Color): void
getDropShadowColorRGBA()#
Gets the drop shadow color of a block as RGBA values.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow color should be queried. |
Returns#
RGBA
The drop shadow color.
Deprecated#
Use getDropShadowColor instead.
getDropShadowColor()#
Gets the drop shadow color of a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow color should be queried. |
Returns#
Color
The drop shadow color.
Signature#
getDropShadowColor(id: number): Color
setDropShadowOffsetX()#
Sets the drop shadow’s horizontal offset.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow’s X offset should be set. |
offsetX | number | The X offset to be set. |
Returns#
void
Signature#
setDropShadowOffsetX(id: number, offsetX: number): void
getDropShadowOffsetX()#
Gets the drop shadow’s horizontal offset.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow’s X offset should be queried. |
Returns#
number
The offset.
Signature#
getDropShadowOffsetX(id: number): number
setDropShadowOffsetY()#
Sets the drop shadow’s vertical offset.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow’s Y offset should be set. |
offsetY | number | The Y offset to be set. |
Returns#
void
Signature#
setDropShadowOffsetY(id: number, offsetY: number): void
getDropShadowOffsetY()#
Gets the drop shadow’s vertical offset.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow’s Y offset should be queried. |
Returns#
number
The offset.
Signature#
getDropShadowOffsetY(id: number): number
setDropShadowBlurRadiusX()#
Sets the drop shadow’s horizontal blur radius.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow’s blur radius should be set. |
blurRadiusX | number | The blur radius to be set. |
Returns#
void
Signature#
setDropShadowBlurRadiusX(id: number, blurRadiusX: number): void
getDropShadowBlurRadiusX()#
Gets the drop shadow’s horizontal blur radius.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow’s blur radius should be queried. |
Returns#
number
The blur radius.
Signature#
getDropShadowBlurRadiusX(id: number): number
setDropShadowBlurRadiusY()#
Sets the drop shadow’s vertical blur radius.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow’s blur radius should be set. |
blurRadiusY | number | The blur radius to be set. |
Returns#
void
Signature#
setDropShadowBlurRadiusY(id: number, blurRadiusY: number): void
getDropShadowBlurRadiusY()#
Gets the drop shadow’s vertical blur radius.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow’s blur radius should be queried. |
Returns#
number
The blur radius.
Signature#
getDropShadowBlurRadiusY(id: number): number
setDropShadowClip()#
Sets the drop shadow’s clipping behavior.
This only applies to shapes.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow’s clip should be set. |
clip | boolean | The drop shadow’s clip to be set. |
Returns#
void
Signature#
setDropShadowClip(id: number, clip: boolean): void
getDropShadowClip()#
Gets the drop shadow’s clipping behavior.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose drop shadow’s clipping should be queried. |
Returns#
boolean
The drop shadow’s clipping state.
Signature#
getDropShadowClip(id: number): boolean
Block Effects#
Create, manage, and apply various visual effects to blocks.
createEffect()#
Creates a new effect block.
Parameters#
Parameter | Type | Description |
---|---|---|
type | EffectType | The type of the effect. |
Returns#
number
The created effect’s handle.
Signature#
createEffect(type: EffectType): number
hasEffects()#
Checks if a block supports effects.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True, if the block can render effects, false otherwise.
Deprecated#
Use supportsEffects instead.
supportsEffects()#
Checks if a block supports effects.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True, if the block can render effects, false otherwise.
Signature#
supportsEffects(id: number): boolean
getEffects()#
Gets all effects attached to a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
[]
A list of effects or an error, if the block doesn’t support effects.
Signature#
getEffects(id: number): number[]
insertEffect()#
Inserts an effect into a block’s effect list at a given index.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
effectId | number | The effect to insert. |
index | number | The index at which the effect shall be inserted. |
Returns#
void
Signature#
insertEffect(id: number, effectId: number, index: number): void
appendEffect()#
Appends an effect to a block’s effect list.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to append the effect to. |
effectId | number | The effect to append. |
Returns#
void
Signature#
appendEffect(id: number, effectId: number): void
removeEffect()#
Removes an effect from a block’s effect list at a given index.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to remove the effect from. |
index | number | The index where the effect is stored. |
Returns#
void
Signature#
removeEffect(id: number, index: number): void
hasEffectEnabled()#
Checks if an effect block can be enabled or disabled.
Parameters#
Parameter | Type | Description |
---|---|---|
effectId | number | The ‘effect’ block to query. |
Returns#
boolean
True, if the block supports enabling and disabling, false otherwise.
Deprecated#
Calls to this function can be removed. All effects can be enabled and disabled.
setEffectEnabled()#
Sets the enabled state of an effect block.
engine.block.setEffectEnabled(effects[0], false);
Parameters#
Parameter | Type | Description |
---|---|---|
effectId | number | The ‘effect’ block to update. |
enabled | boolean | The new state. |
Returns#
void
Signature#
setEffectEnabled(effectId: number, enabled: boolean): void
isEffectEnabled()#
Queries if an effect block is enabled.
engine.block.isEffectEnabled(effects[0]);
Parameters#
Parameter | Type | Description |
---|---|---|
effectId | number | The ‘effect’ block to query. |
Returns#
boolean
True, if the effect is enabled. False otherwise.
Signature#
isEffectEnabled(effectId: number): boolean
Block Blur#
Apply and configure blur effects on blocks.
createBlur()#
Creates a new blur block.
Parameters#
Parameter | Type | Description |
---|---|---|
type | BlurType | The type of blur. |
Returns#
number
The handle of the newly created blur.
Signature#
createBlur(type: BlurType): number
hasBlur()#
Checks if a block supports blur.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True, if the block supports blur.
Deprecated#
Use supportsBlur instead.
supportsBlur()#
Checks if a block supports blur.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True, if the block supports blur.
Signature#
supportsBlur(id: number): boolean
setBlur()#
Sets the blur effect for a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
blurId | number | A ‘blur’ block to apply. |
Returns#
void
Signature#
setBlur(id: number, blurId: number): void
getBlur()#
Gets the blur block of a given design block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
number
The ‘blur’ block.
Signature#
getBlur(id: number): number
setBlurEnabled()#
Enables or disables the blur effect on a block.
engine.block.setBlurEnabled(block, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
enabled | boolean | The new enabled value. |
Returns#
void
Signature#
setBlurEnabled(id: number, enabled: boolean): void
isBlurEnabled()#
Checks if blur is enabled for a block.
const isBlurEnabled = engine.block.isBlurEnabled(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True, if the blur is enabled. False otherwise.
Signature#
isBlurEnabled(id: number): boolean
Block Placeholder#
Manage placeholder functionality, controls, and behavior.
setPlaceholderEnabled()#
Enables or disables the placeholder function for a block.
When set to true
, the placeholder capabilities are enabled in Adopter mode.
engine.block.setPlaceholderEnabled(block, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose placeholder function should be enabled or disabled. |
enabled | boolean | Whether the function should be enabled or disabled. |
Returns#
void
Signature#
setPlaceholderEnabled(id: number, enabled: boolean): void
isPlaceholderEnabled()#
Checks if the placeholder function for a block is enabled.
const placeholderIsEnabled = engine.block.isPlaceholderEnabled(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose placeholder function state should be queried. |
Returns#
boolean
The enabled state of the placeholder function.
Signature#
isPlaceholderEnabled(id: number): boolean
hasPlaceholderBehavior()#
Checks if a block supports placeholder behavior.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True, if the block supports placeholder behavior.
Deprecated#
Use supportsPlaceholderBehavior instead.
supportsPlaceholderBehavior()#
Checks if a block supports placeholder behavior.
const placeholderBehaviorSupported = engine.block.supportsPlaceholderBehavior(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True, if the block supports placeholder behavior.
Signature#
supportsPlaceholderBehavior(id: number): boolean
setPlaceholderBehaviorEnabled()#
Enables or disables the placeholder behavior for a block.
engine.block.setPlaceholderBehaviorEnabled(block, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose placeholder behavior should be enabled or disabled. |
enabled | boolean | Whether the placeholder behavior should be enabled or disabled. |
Returns#
void
Signature#
setPlaceholderBehaviorEnabled(id: number, enabled: boolean): void
isPlaceholderBehaviorEnabled()#
Checks if the placeholder behavior for a block is enabled.
engine.block.setPlaceholderBehaviorEnabled(block, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose placeholder behavior state should be queried. |
Returns#
boolean
The enabled state of the placeholder behavior.
Signature#
isPlaceholderBehaviorEnabled(id: number): boolean
hasPlaceholderControls()#
Checks if a block supports placeholder controls.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True, if the block supports placeholder controls.
Deprecated#
Use supportsPlaceholderControls instead.
supportsPlaceholderControls()#
Checks if a block supports placeholder controls.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to query. |
Returns#
boolean
True, if the block supports placeholder controls.
Signature#
supportsPlaceholderControls(id: number): boolean
setPlaceholderControlsOverlayEnabled()#
Enables or disables the placeholder overlay pattern.
engine.block.setPlaceholderControlsOverlayEnabled(block, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose placeholder overlay should be enabled or disabled. |
enabled | boolean | Whether the placeholder overlay should be shown or not. |
Returns#
void
Signature#
setPlaceholderControlsOverlayEnabled(id: number, enabled: boolean): void
isPlaceholderControlsOverlayEnabled()#
Checks if the placeholder overlay pattern is enabled.
const overlayEnabled = engine.block.isPlaceholderControlsOverlayEnabled(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose placeholder overlay visibility state should be queried. |
Returns#
boolean
The visibility state of the block’s placeholder overlay pattern.
Signature#
isPlaceholderControlsOverlayEnabled(id: number): boolean
setPlaceholderControlsButtonEnabled()#
Enables or disables the placeholder button.
engine.block.setPlaceholderControlsButtonEnabled(block, true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose placeholder button should be shown or not. |
enabled | boolean | Whether the placeholder button should be shown or not. |
Returns#
void
Signature#
setPlaceholderControlsButtonEnabled(id: number, enabled: boolean): void
isPlaceholderControlsButtonEnabled()#
Checks if the placeholder button is enabled.
const buttonEnabled = engine.block.isPlaceholderControlsButtonEnabled(block);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose placeholder button visibility state should be queried. |
Returns#
boolean
The visibility state of the block’s placeholder button.
Signature#
isPlaceholderControlsButtonEnabled(id: number): boolean
Block Scopes#
Manage permissions and capabilities per block.
setScopeEnabled()#
Enables or disables a scope for a block.
// Allow the user to move the image block.engine.block.setScopeEnabled(image, 'layer/move', true);
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose scope should be enabled or disabled. |
key | Scope | The scope to enable or disable. |
enabled | boolean | Whether the scope should be enabled or disabled. |
Returns#
void
Signature#
setScopeEnabled(id: number, key: Scope, enabled: boolean): void
isScopeEnabled()#
Checks if a scope is enabled for a block.
engine.block.isScopeEnabled(image, 'layer/move');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose scope state should be queried. |
key | Scope | The scope to query. |
Returns#
boolean
The enabled state of the scope for the given block.
Signature#
isScopeEnabled(id: number, key: Scope): boolean
isAllowedByScope()#
Checks if an operation is allowed by a block’s scopes.
// This will return true when the global scope is set to 'Defer'.engine.block.isAllowedByScope(image, 'layer/move');
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to check. |
key | Scope | The scope to check. |
Returns#
boolean
Whether the scope is allowed for the given block.
Signature#
isAllowedByScope(id: number, key: Scope): boolean
Block Boolean Operations#
Combine multiple blocks into a single new block using boolean path operations.
isCombinable()#
Checks if a set of blocks can be combined using a boolean operation.
Only graphics blocks and text blocks can be combined. All blocks must have the “lifecycle/duplicate” scope enabled.
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | An array of block ids. |
Returns#
boolean
Whether the blocks can be combined.
Signature#
isCombinable(ids: number[]): boolean
combine()#
Performs a boolean operation on a set of blocks.
All blocks must be combinable. See isCombinable
.
The parent, fill and sort order of the new block is that of the prioritized block.
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | The blocks to combine. They will be destroyed if “lifecycle/destroy” scope is enabled. |
op | BooleanOperation | The boolean operation to perform. |
Returns#
number
The newly created block or an error.
Signature#
combine(ids: number[], op: BooleanOperation): number
Block Cutout#
Create cutout operations and path-based modifications.
createCutoutFromBlocks()#
Creates a cutout block from the contours of other blocks.
The path is derived from either existing vector paths or by vectorizing the block’s appearance.
Parameters#
Parameter | Type | Default value | Description |
---|---|---|---|
ids | number [] | undefined | The blocks whose shape will serve as the basis for the cutout’s path. |
vectorizeDistanceThreshold | number | 2 | Max deviation from the original contour during vectorization. |
simplifyDistanceThreshold | number | 4 | Max deviation for path simplification. 0 disables simplification. |
useExistingShapeInformation | boolean | true | If true, use existing vector paths. |
Returns#
number
The newly created block or an error.
Signature#
createCutoutFromBlocks(ids: number[], vectorizeDistanceThreshold?: number, simplifyDistanceThreshold?: number, useExistingShapeInformation?: boolean): number
createCutoutFromPath()#
Creates a cutout block from an SVG path string.
Parameters#
Parameter | Type | Description |
---|---|---|
path | string | An SVG string describing a path. |
Returns#
number
The newly created block or an error.
Signature#
createCutoutFromPath(path: string): number
createCutoutFromOperation()#
Creates a new cutout block by performing a boolean operation on existing cutout blocks.
Parameters#
Parameter | Type | Description |
---|---|---|
ids | number [] | The cutout blocks with which to perform to the operation. |
op | CutoutOperation | The boolean operation to perform. |
Returns#
number
The newly created block or an error.
Signature#
createCutoutFromOperation(ids: number[], op: CutoutOperation): number
Block Metadata#
setMetadata()#
Sets a metadata value for a given key on a block.
If the key does not exist, it will be added.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose metadata will be accessed. |
key | string | The key used to identify the desired piece of metadata. |
value | string | The value to set. |
Returns#
void
Signature#
setMetadata(id: number, key: string, value: string): void
getMetadata()#
Gets a metadata value for a given key from a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose metadata will be accessed. |
key | string | The key used to identify the desired piece of metadata. |
Returns#
string
The value associated with the key.
Signature#
getMetadata(id: number, key: string): string
hasMetadata()#
Checks if a block has metadata for a given key.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose metadata will be accessed. |
key | string | The key used to identify the desired piece of metadata. |
Returns#
boolean
Whether the key exists.
Signature#
hasMetadata(id: number, key: string): boolean
findAllMetadata()#
Finds all metadata keys on a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose metadata will be accessed. |
Returns#
string
[]
A list of all metadata keys on this block.
Signature#
findAllMetadata(id: number): string[]
removeMetadata()#
Removes metadata for a given key from a block.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block whose metadata will be accessed. |
key | string | The key used to identify the desired piece of metadata. |
Returns#
void
Signature#
removeMetadata(id: number, key: string): void
Other#
setSize()#
Update a block’s size.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
width | number | The new width of the block. |
height | number | The new height of the block. |
options? | { maintainCrop? : boolean ; sizeMode? : SizeMode ; } | Optional parameters for the size. Properties: - maintainCrop - Whether or not the crop values, if available, should be automatically adjusted. - sizeMode - The size mode: Absolute, Percent or Auto. |
options.maintainCrop? | boolean | - |
options.sizeMode? | SizeMode | - |
Returns#
void
Signature#
setSize(id: number, width: number, height: number, options?: object): void
setPosition()#
Update a block’s position.
Parameters#
Parameter | Type | Description |
---|---|---|
id | number | The block to update. |
x | number | The new x position of the block. |
y | number | The new y position of the block. |
options? | { positionMode? : PositionMode ; } | Optional parameters for the position. Properties: - positionMode - The position mode: absolute, percent or undefined. |
options.positionMode? | PositionMode | - |
Returns#
void
Signature#
setPosition(id: number, x: number, y: number, options?: object): void
addImage()#
Adds an image to the current page. The image will be automatically loaded
and sized appropriately. In Video mode, timeline and animation options can be applied.
Parameters#
Parameter | Type | Description |
---|---|---|
url | string | URL or path to the image file |
options | AddImageOptions | Configuration options for the image |
Returns#
Promise
<number
>
Promise that resolves to the ID of the created image block
Throws#
Error if no current page exists
Signature#
addImage(url: string, options?: AddImageOptions): Promise<number>
addVideo()#
Adds a video block to the current scene page. The video will be positioned and sized
according to the provided parameters. Timeline and animation effects can be applied.
Only works in Video mode, not in Design mode.
Parameters#
Parameter | Type | Description |
---|---|---|
url | string | URL or path to the video file |
width | number | Width of the video in scene design units |
height | number | Height of the video in scene design units |
options | AddVideoOptions | Configuration options for the video |
Returns#
Promise
<number
>
Promise that resolves to the ID of the created video block
Throws#
Error if called in Design mode or if no current page exists
Signature#
addVideo(url: string, width: number, height: number, options?: AddVideoOptions): Promise<number>
applyAnimation()#
Applies an animation to a block.
Parameters#
Parameter | Type | Description |
---|---|---|
block | number | The ID of the block to apply the animation to |
animation | AnimationOptions | The animation configuration options |
Returns#
void
Signature#
applyAnimation(block: number, animation?: AnimationOptions): void
applyDropShadow()#
Applies a drop shadow effect to any block.
Parameters#
Parameter | Type | Description |
---|---|---|
block | number | The ID of the block to apply the shadow to |
options | DropShadowOptions | Shadow configuration options. If not provided, enables shadow with default settings |
Returns#
void
Signature#
applyDropShadow(block: number, options?: DropShadowOptions): void
generateThumbnailAtTimeOffset()#
Generates a thumbnail image of the scene at a specific time.
Only works in Video mode, not in Design mode.
Parameters#
Parameter | Type | Description |
---|---|---|
height | number | Height of the thumbnail in scene design units (maximum 512) |
time | number | Time position in seconds to capture the thumbnail |
Returns#
Promise
<Blob
>
Promise that resolves to a Blob containing the PNG thumbnail image
Throws#
Error if no page exists, if called in Design mode, or if height exceeds 512 pixels
Signature#
generateThumbnailAtTimeOffset(height: number, time: number): Promise<Blob>
getBackgroundTrack()#
Gets the background track of the current scene.
The background track is the track that determines the page duration.
Only works in Video mode, not in Design mode.
Returns#
null
| number
The ID of the background track, or null if none exists
Throws#
Error if called in Design mode
Signature#
getBackgroundTrack(): null | number
moveToBackgroundTrack()#
Moves a block to the background track.
This is useful for organizing content in video scenes where you want
certain elements to be part of the background layer.
The background track is the track that determines the page duration.
Parameters#
Parameter | Type | Description |
---|---|---|
block | number | The ID of the block to move to the background track |
Returns#
void
Throws#
Error if no background track is found
Signature#
moveToBackgroundTrack(block: number): void