@cesdk/node 1.9.2 → 1.10.0-preview.1

package/index.d.ts

@@ -4,21 +4,24 @@
  */
 export declare interface Asset {
     /**
-     *  Is a combination of source id, extension pack id (optional), type and asset id
-     *  e.g. "extension://ly.img.cesdk.images.samples/ly.img.image/sample.1"
+     * The unique id of this asset.
      */
     id: string;
-    /**   E.g. `ly.img.image` */
     /**  Groups of the asset.  */
     groups?: Groups;
-    /** URI to a thumbnail of the asset used e.g. in the content library UI */
-    thumbUri: string;
-
     /** Asset-specific and custom meta information */
     meta?: {
+        /** The mime type of this asset or the data behind the asset's uri. */
+        mimeType?: string;
+        /** The type id of the design block that should be created from this asset. */
+        blockType?: string;
         uri?: string;
+        thumbUri?: string;
+        previewUri?: string;
         filename?: string;
         vectorPath?: string;
+        width?: number;
+        height?: number;
         duration?: string;
     } & Record<string, unknown>;
 }
@@ -34,6 +37,16 @@ export declare class AssetAPI {
      * @param source - The asset source.
      */
     addSource(source: AssetSource): void;
+    /**
+     * Adds a local asset source. Its ID has to be unique.
+     * @param source - The asset source.
+     * @param supportedMimeTypes - The mime types of assets that are allowed to be added to this local source.
+     * @param applyAsset - An optional callback that can be used to override the default behavior of applying a given
+     * asset result to the active scene.
+     * @param applyAssetToBlock - An optional callback that can be used to override the default behavior of applying
+     * an asset result to a given block.
+     */
+    addLocalSource(id: string, supportedMimeTypes?: string[], applyAsset?: (asset: AssetResult) => Promise<DesignBlockId | undefined>, applyAssetToBlock?: (asset: AssetResult, block: DesignBlockId) => Promise<void>): void;
     /**
      * Removes an asset source with the given ID.
      * @param id - The ID to refer to the asset source.
@@ -57,6 +70,7 @@ export declare class AssetAPI {
      * @returns The asset groups.
      */
     getGroups(id: string): Promise<string[]>;
+    getSupportedMimeTypes(sourceId: string): string[];
     /**
      * Queries the asset source's credits info.
      * @param sourceId - The ID of the asset source.
@@ -76,9 +90,18 @@ export declare class AssetAPI {
         url: string | undefined;
     } | undefined;
     canManageAssets(sourceId: string): boolean;
-
-
-
+    /**
+     * Adds the given asset to a local asset source.
+     * @param sourceId - The local asset source ID that the asset should be added to.
+     * @param asset - The asset to be added to the asset source.
+     */
+    addAssetToSource(sourceId: string, asset: AssetDefinition): void;
+    /**
+     * Removes the specified asset from its local asset source.
+     * @param sourceId - The id of the local asset source that currently contains the asset.
+     * @param assetId - The id of the asset to be removed.
+     */
+    removeAssetFromSource(sourceId: string, assetId: string): void;
 
     /**
      * Apply an asset result to the active scene.
@@ -87,7 +110,7 @@ export declare class AssetAPI {
      * @param sourceId - The ID of the asset source.
      * @param assetResult - A single assetResult of a `findAssets` query.
      */
-    apply(sourceId: string, assetResult: AssetResult): Promise<void>;
+    apply(sourceId: string, assetResult: AssetResult): Promise<DesignBlockId | undefined>;
     /**
      * Apply an asset result to the given block.
      * @param sourceId - The ID of the asset source.
@@ -100,7 +123,7 @@ export declare class AssetAPI {
      * This implementation is used when no `applyAsset` function is provided to `addSource`.
      * @param assetResult - A single assetResult of a `findAssets` query.
      */
-    defaultApplyAsset(assetResult: AssetResult): Promise<void>;
+    defaultApplyAsset(assetResult: AssetResult): Promise<DesignBlockId | undefined>;
     /**
      * The default implementation for applying an asset to an existing block.
      * @param assetResult - A single assetResult of a `findAssets` query.
@@ -111,7 +134,7 @@ export declare class AssetAPI {
 }
 
 /**
- * Definition of an assets used if an asset is added to an asset source.
+ * Definition of an asset used if an asset is added to an asset source.
  * @public
  */
 export declare interface AssetDefinition extends Asset {
@@ -195,13 +218,6 @@ export declare interface AssetResult extends Asset {
 declare interface AssetResult_2 {
     /** A unique id of this asset */
     id: string;
-    /** URI to a thumbnail of the asset used e.g. in the content library UI */
-    thumbUri: string;
-    /** Original size of the asset. */
-    size: {
-        width: number;
-        height: number;
-    };
     /** Asset-specific and custom meta information */
     meta?: {
         uri?: string;
@@ -269,16 +285,17 @@ export declare interface AssetSource {
      */
     getAsset?(id: string): Promise<AssetResult | undefined>;
     /**
-     * Can the source add, update and remove assets dynamically? If `false`
-     * methods like `addAsset` `updateAsset` and `removeAsset` will throw an
+     * Can the source add and remove assets dynamically? If `false`
+     * methods like `addAsset` and `removeAsset` will throw an
      * error.
      */
     canManageAssets?: boolean;
     /**
      * Apply the given asset result to the active scene.
      * You can override this with custom behavior.
+     * @returns the id of a new block if one was created from the asset.
      */
-    applyAsset?: (asset: AssetResult) => Promise<void>;
+    applyAsset?: (asset: AssetResult) => Promise<DesignBlockId | undefined>;
     /**
      * Apply the given asset result to the given block.
      * You can override this with custom behavior.
@@ -288,22 +305,12 @@ export declare interface AssetSource {
      * Adds the given asset to this source. Throws an error if `canManageAssets`
      * is `false`.
      *
-     * @returns the id of the added asset
-     */
-    addAsset?(asset: AssetDefinition): Promise<string>;
-    /**
-     * Updates the asset of this source. Throws an error if `canManageAssets`
-     * is `false` or no asset with the given id could not be found.
-     *
-     * @returns the id of the added asset
      */
-    updateAsset?(assetId: string, asset: AssetDefinition): Promise<void>;
+    addAsset?(asset: AssetDefinition): void;
     /**
      * Removes the given asset from this source.
-     *
-     * @returns true if asset was found and removed, and false otherwise
      */
-    removeAsset?(assetId: string): Promise<boolean>;
+    removeAsset?(assetId: string): void;
     /**
      * Generates a list of supported mime types for this source.
      *
@@ -323,7 +330,7 @@ declare interface AssetSource_2 {
      * Apply the given asset result to the active scene.
      * You can override this with custom behavior.
      */
-    applyAsset?: (asset: AssetResult_2) => Promise<void>;
+    applyAsset?: (asset: AssetResult_2) => Promise<DesignBlockId | undefined>;
     /**
      * Apply the given asset result to the given block.
      * You can override this with custom behavior.
@@ -443,6 +450,7 @@ export declare class BlockAPI {
     /**
      * Loads existing blocks from the given 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.
      * @param content - A string representing the given blocks.
      * @returns A promise that resolves with a list of handles representing the found blocks or an error.
      */
@@ -466,13 +474,17 @@ export declare class BlockAPI {
      * @returns The created fill's handle.
      */
     createFill(type: string): DesignBlockId;
-
     /**
      * Get the type of the given block, fails if the block is invalid.
      * @param id - The block to query.
      * @returns The blocks type.
      */
     getType(id: DesignBlockId): DesignBlockType;
+    /**
+     * Selects the given block and deselects all other blocks.
+     * @param id - The block to be selected.
+     */
+    select(id: DesignBlockId): void;
     /**
      * Update the selection state of a block.
      * Fails for invalid blocks.
@@ -634,6 +646,46 @@ export declare class BlockAPI {
      * @param mode - The y position mode: absolute, percent or undefined.
      */
     setPositionYMode(id: DesignBlockId, mode: PositionMode): void;
+    /**
+     * Update the block's always-on-top property. If true, this blocks's global sorting order is automatically
+     * adjusted to be higher than all other siblings
+     * without this property. If more than one block is set to be always-on-top, the child order decides which is on top.
+     *
+     * @param id - the block to update.
+     * @param enabled - whether the block shall be always-on-top.
+     */
+    setAlwaysOnTop(id: DesignBlockId, enabled: boolean): void;
+    /**
+     * Query a block's always-on-top property.
+     *
+     * @param id - the block to query.
+     * @returns true if the block is set to be always-on-top, false otherwise.
+     */
+    isAlwaysOnTop(id: DesignBlockId): boolean;
+    /**
+     * Updates the sorting order of this block and all of its manually created siblings
+     * so that the given block has the highest sorting order.
+     * @param id - The id of the block to be given the highest sorting order among its siblings.
+     */
+    bringToFront(id: DesignBlockId): void;
+    /**
+     * Updates the sorting order of this block and all of its manually created siblings
+     * so that the given block has the lowest sorting order.
+     * @param id - The id of the block to be given the lowest sorting order among its siblings.
+     */
+    sendToBack(id: DesignBlockId): void;
+    /**
+     * Updates the sorting order of this block and all of its superjacent siblings
+     * so that the given block has a higher sorting order than the next superjacent sibling.
+     * @param id - The id of the block to be given a higher sorting than the next superjacent sibling.
+     */
+    bringForward(id: DesignBlockId): void;
+    /**
+     * Updates the sorting order of this block and all of its manually created and subjacent siblings
+     * so that the given block will have a lower sorting order than the next subjacent sibling.
+     * @param id - The id of the block to be given a lower sorting order than the next subjacent sibling.
+     */
+    sendBackward(id: DesignBlockId): void;
     /**
      * Query a block's rotation in radians.
      * @param id - The block to query.
@@ -700,12 +752,6 @@ export declare class BlockAPI {
      * @returns The current mode for the height: absolute, percent or auto.
      */
     getHeightMode(id: DesignBlockId): SizeMode;
-    /**
-     * Query a block's content fill mode.
-     * @param id - The block to query.
-     * @returns The current mode: crop, cover or contain.
-     */
-    getContentFillMode(id: DesignBlockId): ContentFillMode;
     /**
      * Update a block's width.
      * @param id - The block to update.
@@ -731,25 +777,45 @@ export declare class BlockAPI {
      */
     setHeightMode(id: DesignBlockId, mode: SizeMode): void;
     /**
-     * Set a block's content fill mode.
-     * @param id - The block to update.
-     * @param mode - The content fill mode mode: crop, cover or contain.
+     * Get a block's layout position on the x-axis. The position is only available after an
+     * internal update loop which only occurs if the `features/implicitUpdatesEnabled` setting is set.
+     * @param id - The block to query.
+     * @returns The layout position on the x-axis.
      */
-    setContentFillMode(id: DesignBlockId, mode: ContentFillMode): void;
+    getFrameX(id: DesignBlockId): number;
     /**
-     * Get a block's layout width. The layout width is only available after an
-     * internal update loop, which may not happen immediately.
+     * Get a block's layout position on the y-axis. The position is only available after an
+     * internal update loop which only occurs if the `features/implicitUpdatesEnabled` setting is set.
+     * @param id - The block to query.
+     * @returns The layout position on the y-axis.
+     */
+    getFrameY(id: DesignBlockId): number;
+    /**
+     * Get a block's layout width. The width is only available after an
+     * internal update loop which only occurs if the `features/implicitUpdatesEnabled` setting is set.
      * @param id - The block to query.
      * @returns The layout width.
      */
     getFrameWidth(id: DesignBlockId): number;
     /**
-     * Get a block's layout height. The layout height is only available after an
-     * internal update loop, which may not happen immediately.
+     * Get a block's layout height. The height is only available after an
+     * internal update loop which only occurs if the `features/implicitUpdatesEnabled` setting is set.
      * @param id - The block to query.
      * @returns The layout height.
      */
     getFrameHeight(id: DesignBlockId): number;
+    /**
+     * Set a block's content fill mode.
+     * @param id - The block to update.
+     * @param mode - The content fill mode mode: crop, cover or contain.
+     */
+    setContentFillMode(id: DesignBlockId, mode: ContentFillMode): void;
+    /**
+     * Query a block's content fill mode.
+     * @param id - The block to query.
+     * @returns The current mode: crop, cover or contain.
+     */
+    getContentFillMode(id: DesignBlockId): ContentFillMode;
     /**
      * Duplicates a block including its children.
      * @param id - The block to duplicate.
@@ -828,6 +894,12 @@ export declare class BlockAPI {
      * @returns float The height of the axis-aligned bounding box.
      */
     getGlobalBoundingBoxHeight(id: DesignBlockId): number;
+    /**
+     * Get the position and size of the axis-aligned bounding box for the given blocks in screen space.
+     * @param ids - The block to query.
+     * @returns The position and size of the bounding box.
+     */
+    getScreenSpaceBoundingBoxXYWH(ids: DesignBlockId[]): XYWH;
     /**
      * Scales the block and all of its children proportionally around the specified
      * relative anchor point.
@@ -1872,6 +1944,48 @@ export declare class BlockAPI {
      * @returns Whether solo playback is enabled for this block.
      */
     isSoloPlaybackEnabled(id: DesignBlockId): boolean;
+    /**
+     * Returns whether the block supports a playback control.
+     * @param block - The block to query.
+     * @returns Whether the block has playback control.
+     */
+    hasPlaybackControl(id: DesignBlockId): boolean;
+    /**
+     * Set whether the block should start from the beginning again or stop.
+     * @param block - The block or video fill to update.
+     * @param looping - Whether the block should loop to the beginning or stop.
+     */
+    setLooping(id: DesignBlockId, looping: boolean): void;
+    /**
+     * Query whether the block is looping.
+     * @param block - The block to query.
+     * @returns Whether the block is looping.
+     */
+    isLooping(id: DesignBlockId): boolean;
+    /**
+     * Set whether the audio of the block is muted.
+     * @param block - The block or video fill to update.
+     * @param muted - Whether the audio should be muted.
+     */
+    setMuted(id: DesignBlockId, muted: boolean): void;
+    /**
+     * Query whether the block is muted.
+     * @param block - The block to query.
+     * @returns Whether the block is muted.
+     */
+    isMuted(id: DesignBlockId): boolean;
+    /**
+     * Set the audio volume of the given block.
+     * @param block - The block or video fill to update.
+     * @param volume - The desired volume with a range of [0, 1].
+     */
+    setVolume(id: DesignBlockId, volume: number): void;
+    /**
+     * Get the audio volume of the given block.
+     * @param block - The block to query.
+     * @returns The volume with a range of [0, 1].
+     */
+    getVolume(id: DesignBlockId): number;
     /**
      * Begins loading the required audio and video resource for the given video fill or audio block.
      * @param id - The video fill or audio block whose resource should be loaded.
@@ -2278,6 +2392,16 @@ export declare class EditorAPI {
      * @returns The value as string.
      */
     getSettingEnum(keypath: string): string;
+    /**
+     * Get the currently available memory in bytes.
+     * @returns The currently available memory in bytes.
+     */
+    getAvailableMemory(): number;
+    /**
+     * Get the current memory usage of the engine in bytes.
+     * @returns The current memory usage in bytes.
+     */
+    getUsedMemory(): number;
     /**
      * Sets a custom URI resolver.
      * This function can be called more than once. Subsequent calls will overwrite previous calls.
@@ -2558,6 +2682,14 @@ declare type Page = {
     dimOutOfPageAreas?: boolean;
 };
 
+/** @public */
+export declare interface PageDuration {
+    pageId: DesignBlockId;
+    duration: number;
+    start: number;
+    end: number;
+}
+
 /** @public */
 declare type PageFormatDefinition = Preset & {
     width: number;
@@ -2759,6 +2891,11 @@ export declare class SceneAPI {
      * @returns The current mode of the scene.
      */
     getMode(): SceneMode;
+    /**
+     * Get the sorted list of pages in the scene.
+     * @returns The sorted list of pages in the scene.
+     */
+    getPages(): DesignBlockId[];
     /**
      * Sets the zoom level of the active scene.
      * Only has an effect if the zoom level is not handled by the UI.
@@ -2784,6 +2921,47 @@ export declare class SceneAPI {
      * @returns A promise that resolves once the zoom was set or rejects with an error otherwise.
      */
     zoomToBlock(id: DesignBlockId, paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): Promise<void>;
+    /**
+     * Continually adjusts the zoom level to fit the width or height of a block's axis-aligned bounding box.
+     * Only has an effect if the zoom level is not handled by the UI.
+     * Without padding, this results in a tight view on the block.
+     * No more than one block per scene can have zoom auto-fit enabled.
+     * Calling `setZoomLevel` or `zoomToBlock` disables the continuous adjustment.
+     *
+     * @param id - The block for which the zoom is adjusted.
+     * @param axis - The block axis for which the zoom is adjusted.
+     * @param paddingBefore - Optional padding in screen pixels before the block.
+     * @param paddingAfter - Optional padding in screen pixels after the block.
+     */
+    enableZoomAutoFit(id: DesignBlockId, axis: 'Horizontal' | 'Vertical', paddingBefore?: number, paddingAfter?: number): void;
+    /**
+     * Continually adjusts the zoom level to fit the width or height of a block's axis-aligned bounding box.
+     * Only has an effect if the zoom level is not handled by the UI.
+     * Without padding, this results in a tight view on the block.
+     * Calling `setZoomLevel` or `zoomToBlock` disables the continuous adjustment.
+     *
+     * @param id - The block for which the zoom is adjusted.
+     * @param axis - The block axis for which the zoom is adjusted.
+     * @param paddingLeft - Optional padding in screen pixels to the left of the block.
+     * @param paddingTop - Optional padding in screen pixels to the top of the block.
+     * @param paddingRight - Optional padding in screen pixels to the right of the block.
+     * @param paddingBottom - Optional padding in screen pixels to the bottom of the block.
+     */
+    enableZoomAutoFit(id: DesignBlockId, axis: 'Both', paddingLeft?: number, paddingTop?: number, paddingRight?: number, paddingBottom?: number): void;
+    /**
+     *  Disables any previously set zoom auto-fit.
+     *
+     * @param blockOrScene - The scene or a block in the scene for which to disable a zoom auto-fit.
+     */
+    disableZoomAutoFit(blockOrScene: DesignBlockId): void;
+    /**
+     *  Queries whether zoom auto-fit is enabled.
+     *
+     * @param blockOrScene - The scene or a block in the scene for which to disable a zoom auto-fit.
+     * @returns True if the given block has auto-fit set or the scene contains a block for which auto-fit is set, false
+     * otherwise.
+     */
+    isZoomAutoFitEnabled(blockOrScene: DesignBlockId): boolean;
     /**
      * Subscribe to changes to the zoom level.
      * @param callback - This function is called at the end of the engine update, if the zoom level has changed.
@@ -2937,4 +3115,15 @@ export declare interface Vec4 {
     w: number;
 }
 
+/**
+ * Describes a rectangle on the screen
+ * - `x` and `y` indicate the position
+ * - `w` and `h` indicate the width and height
+ * @public
+ */
+export declare type XYWH = [x: number, y: number, w: number, h: number];
+
+/**  @public */
+export declare type ZoomAutoFitAxis = 'Horizontal' | 'Vertical' | 'Both';
+
 export { }