@cesdk/engine 1.10.1 → 1.11.0-preview.1

package/index.d.ts

@@ -438,17 +438,13 @@ export declare class BlockAPI {
     /**
      * Exports a design block as a video file of the given mime type.
      * Note: The export will run across multiple iterations of the update loop. In each iteration a frame is scheduled for encoding.
-     * @param block - The design block to export.
-     * @param timeOffset - The time offset in seconds of the scene's timeline from which the video will start.
-     * @param duration - The duration in seconds of the final video.
+     * @param handle - The design block element to export. Currently, only the scene block is supported.
      * @param mimeType - The mime type of the output video file.
-     * @param resolutionWidth - The target video width in pixel.
-     * @param resolutionHeight - The target video height in pixel.
-     * @param framerate - The target framerate in Hz.
      * @param progressCallback - A callback which reports on the progress of the export. It informs the receiver of the current frame index, which currently gets exported and the total frame count.
+     * @param options - The options for exporting the video
      * @returns A promise that resolves with video blob or is rejected with an error.
      */
-    exportVideo(handle: DesignBlockId, timeOffset: number, duration: number, mimeType: MimeType_2 | undefined, resolutionWidth: number, resolutionHeight: number, framerate: number, progressCallback: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void): Promise<Blob>;
+    exportVideo(handle: DesignBlockId, mimeType: MimeType_2 | undefined, progressCallback: (numberOfRenderedFrames: number, numberOfEncodedFrames: number, totalNumberOfFrames: number) => void, options: VideoExportOptions): Promise<Blob>;
     /**
      * 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.
@@ -768,7 +764,7 @@ export declare class BlockAPI {
     /**
      * Set a block's mode for its width.
      * @param id - The block to update.
-     * @param mode - The width mode: absolute, percent or auto.
+     * @param mode - The width mode: Absolute, Percent or Auto.
      */
     setWidthMode(id: DesignBlockId, mode: SizeMode): void;
     /**
@@ -780,7 +776,7 @@ export declare class BlockAPI {
     /**
      * Set a block's mode for its height.
      * @param id - The block to update.
-     * @param mode - The height mode: absolute, percent or auto.
+     * @param mode - The height mode: Absolute, Percent or Auto.
      */
     setHeightMode(id: DesignBlockId, mode: SizeMode): void;
     /**
@@ -907,6 +903,24 @@ export declare class BlockAPI {
      * @returns The position and size of the bounding box.
      */
     getScreenSpaceBoundingBoxXYWH(ids: DesignBlockId[]): XYWH;
+    /**
+     * Align multiple blocks horizontally within their bounding box (or group) or a single block to its parent.
+     * @param ids - A non-empty array of block ids.
+     * @param alignment - How they should be aligned: left, right, or center
+     */
+    alignHorizontally(ids: DesignBlockId[], horizontalBlockAlignment: HorizontalBlockAlignment): void;
+    /**
+     * Align multiple blocks vertically within their bounding box (or group) or a single block to its parent.
+     * @param ids - A non-empty array of block ids.
+     * @param alignment - How they should be aligned: top, bottom, or center
+     */
+    alignVertically(ids: DesignBlockId[], verticalBlockAlignment: VerticalBlockAlignment): void;
+    /**
+     * Confirms that a given set of blocks can be aligned.
+     * @param ids - A non-empty array of block ids.
+     * @returns Whether the blocks can be aligned.
+     */
+    isAlignable(ids: DesignBlockId[]): boolean;
     /**
      * Scales the block and all of its children proportionally around the specified
      * relative anchor point.
@@ -1068,14 +1082,14 @@ export declare class BlockAPI {
      * @param property - The name of the property to set.
      * @param value - The enum value as string.
      */
-    setEnum(id: DesignBlockId, property: string, value: string): void;
+    setEnum<T extends string = string>(id: DesignBlockId, property: string, value: T): void;
     /**
      * Get the value of an enum property of the given design block.
      * @param id - The block whose property should be queried.
      * @param property - The name of the property to query.
      * @returns The value as string.
      */
-    getEnum(id: DesignBlockId, property: string): string;
+    getEnum<T extends string = string>(id: DesignBlockId, property: string): T;
     /**
      * Query if the given block has crop properties.
      * @param id - The block to query.
@@ -1607,6 +1621,69 @@ export declare class BlockAPI {
      * @returns The drop shadow's clipping.
      */
     getDropShadowClip(id: DesignBlockId): boolean;
+    /**
+     * Inserts the given text into the selected range of the text block.
+     * @param block - The text block into which to insert the given text.
+     * @param text - The text which should replace the selected range in the block.
+     * @param from - The start index of the UTF-16 range that should be replaced.
+     * If the value is negative, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme that should be replaced by the inserted text.
+     *   If `from` and `to` are negative, a this will fall back to the end of the entire text range, so the entire text will be replaced.
+     *   If `to` is negative but `from` is greater than or equal to 0, the text will be inserted at the index defined by `from`.
+     */
+    replaceText(id: DesignBlockId, text: string, from?: number, to?: number): void;
+    /**
+     * Removes selected range of text of the given text block.
+     * @param block - The text block from which the selected text should be removed.
+     * @param from - The start index of the UTF-16 range that should be removed.
+     * If the value is negative, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme that should be removed.
+     * If the value is negative, this will fall back to the end of the entire text range.
+     */
+    removeText(id: DesignBlockId, from?: number, to?: number): void;
+    /**
+     * Changes the color of the text in the selected range to the given color.
+     * @param block - The text block whose color should be changed.
+     * @param color - The new color of the selected text range.
+     * @param from - The start index of the UTF-16 range whose color should be changed.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose color should be changed.
+     *   If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
+     */
+    setTextColor(id: DesignBlockId, color: RGBAColor | SpotColor, from?: number, to?: number): void;
+    /**
+     * Returns the ordered unique list of colors of the text in the selected range.
+     * @param block - The text block whose colors should be returned.
+     * @param from - The start index of the UTF-16 range whose colors should be returned.
+     * If the value is negative, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose colors should be returned.
+     * If the value is negative, this will fall back to the end of the entire text range.
+     */
+    getTextColors(id: DesignBlockId, from?: number, to?: number): Array<RGBAColor | SpotColor>;
+    /**
+     * Returns the ordered unique list of font weights of the text in the selected range.
+     * @param block - The text block whose font weights should be returned.
+     * @param from - The start index of the UTF-16 range whose font weights should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose font weights should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
+     */
+    getTextFontWeights(id: DesignBlockId, from?: number, to?: number): FontWeight[];
+    /**
+     * Returns the ordered unique list of font styles of the text in the selected range.
+     * @param block - The text block whose font styles should be returned.
+     * @param from - The start index of the UTF-16 range whose font weights should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the start of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the start of the entire text range.
+     * @param to - The UTF-16 index after the last grapheme whose font styles should be returned.
+     *   If the value is negative and the block is currently being edited, this will fall back to the end of the current cursor index / selected grapheme range.
+     *   If the value is negative and the block is not being edited, this will fall back to the end of the entire text range.
+     */
+    getTextFontStyles(id: DesignBlockId, from?: number, to?: number): FontStyle[];
     /**
      * Query if the given block has fill color properties.
      * @param id - The block to query.
@@ -2199,15 +2276,14 @@ export { ConfigTypes }
 export declare interface Configuration {
     baseURL: string;
     license?: string;
-    role: RoleString;
-    featureFlags?: Record<string, string | boolean>;
+    featureFlags?: {
+        [flag: string]: boolean | string;
+    };
     /**
      * @deprecated Extensions have been superseded by AssetSources and should no longer be used.
      */
     extensions: ConfigTypes.Extensions;
     core: ConfigTypes.Core;
-    scene: ConfigTypes.Scene;
-    page: ConfigTypes.Page;
     assetSources: ConfigTypes.AssetSources;
     presets: ConfigTypes.Presets;
     variables: ConfigTypes.Variables;
@@ -2276,7 +2352,7 @@ declare class CreativeEngine {
      * @param config - An optional configuration object.
      * @returns An engine instance.
      */
-    static init<C extends Partial<Configuration>>(config?: C): Promise<CreativeEngine & (C extends {
+    static init<C extends Partial<Configuration> & OldConfiguration>(config?: C): Promise<CreativeEngine & (C extends {
         readonly canvas: any;
     } ? {
         readonly element: undefined;
@@ -2314,7 +2390,7 @@ declare class CreativeEngine {
      * - `'ly.img.image.upload'` - Demo source to upload image assets
      * - `'ly.img.audio'` - Sample audios
      * - `'ly.img.audio.upload'` - Demo source to upload audio assets
-     * - `'ly.img.video'` - Sample audios
+     * - `'ly.img.video'` - Sample videos
      * - `'ly.img.video.upload'` - Demo source to upload video assets
      *
      * @param excludeAssetSourceIds - A list of IDs, that will be ignored during load.
@@ -2383,8 +2459,11 @@ export declare enum DesignBlockType {
     Group = "//ly.img.ubq/group"
 }
 
-/** @public */
-export declare type DesignUnit = 'mm' | 'px' | 'in';
+/**
+ * The scene layout determines how the layout stack should layout its pages.
+ * @public
+ */
+export declare type DesignUnit = 'Pixel' | 'Millimeter' | 'Inch';
 
 /**
  * @public
@@ -2397,7 +2476,7 @@ export declare class EditorAPI {
      * @param callback - This function is called at the end of the engine update, if the editor state has changed.
      * @returns A method to unsubscribe.
      */
-    onStateChanged(callback: () => void): () => void;
+    onStateChanged: (callback: () => void) => (() => void);
     /**
      * Set the edit mode of the editor.
      * An edit mode defines what type of content can currently be edited by the user.
@@ -2483,13 +2562,13 @@ export declare class EditorAPI {
      * @param callback - This function is called at the end of the engine update, if the undo/redo history has been changed.
      * @returns A method to unsubscribe
      */
-    onHistoryUpdated(callback: () => void): () => void;
+    onHistoryUpdated: (callback: () => void) => (() => void);
     /**
      * Subscribe to changes to the editor settings.
      * @param callback - This function is called at the end of the engine update, if the editor settings have changed.
      * @returns A method to unsubscribe.
      */
-    onSettingsChanged(callback: () => void): () => void;
+    onSettingsChanged: (callback: () => void) => (() => void);
     /**
      * Set a boolean setting.
      * @param keypath - The settings keypath, e.g. `doubleClickToCropEnabled`
@@ -2657,7 +2736,7 @@ export declare class EventAPI {
      * @param callback - The event callback. Events are bundled and sent at the end of each engine update.
      * @returns A method to unsubscribe.
      */
-    subscribe(blocks: DesignBlockId[], callback: (events: BlockEvent[]) => void): () => void;
+    subscribe: (blocks: DesignBlockId[], callback: (events: BlockEvent[]) => void) => (() => void);
 }
 
 /**
@@ -2731,7 +2810,7 @@ declare type Extensions = {
 /**
  * @public
  */
-export declare type FillType = 'Solid' | 'Gradient' | 'Video';
+export declare type FillType = 'Solid' | 'Gradient' | 'Video' | 'Image';
 
 /** @public */
 declare interface FindAssetsQuery {
@@ -2807,6 +2886,18 @@ declare type HexColorString = string;
  */
 export declare type HistoryId = number;
 
+/**
+ * - Left: The blocks get left aligned.
+ * - Right: The blocks get right aligned.
+ * - Center: The blocks get center aligned.
+ *
+ * @public
+ */
+export declare type HorizontalBlockAlignment = 'Left' | 'Right' | 'Center';
+
+/** @public */
+export declare type HorizontalTextAlignment = 'Left' | 'Right' | 'Center';
+
 /**
  * A wrapper around a plain canvas
  *
@@ -2862,7 +2953,45 @@ declare enum MimeType_2 {
 }
 export { MimeType_2 as MimeType }
 
-/** @public */
+/**
+ * Contains configuration keys that have been removed from the actual
+ * configuration, but are still supported publicly
+ * @public
+ */
+export declare interface OldConfiguration {
+    /**
+     * @deprecated This config key has been removed.
+     * You can configure a role via `setSettingEnum('role', role)` in the
+     * EditorAPI.
+     */
+    role?: RoleString;
+    /**
+     * @deprecated This config key has been removed completely.
+     * The settings that were configured here can be set via the
+     * following EditorAPI settings:
+     * - `setSettingBool('page/title/show', show)`
+     * - `setSettingString('page/title/fontFileUri', uri)`
+     * - `setSettingBool('page/title/dimOutOfPageAreas', dim)`
+     */
+    page?: Page;
+    /**
+     * @deprecated This type definition has been removed
+     * The settings that were configured here can be set via the
+     * BlockApi on the scene block
+     * @public
+     */
+    scene?: Scene;
+}
+
+/**
+ * @deprecated This type definition has been removed
+ * The settings that were configured here can be set via the
+ * following EditorAPI settings:
+ * - `setSettingBool('page/title/show', show)`
+ * - `setSettingString('page/title/fontFileUri', uri)`
+ * - `setSettingBool('page/title/dimOutOfPageAreas', dim)`
+ * @public
+ */
 declare type Page = {
     title: {
         /**
@@ -2893,7 +3022,7 @@ export declare interface PageDuration {
 declare type PageFormatDefinition = Preset & {
     width: number;
     height: number;
-    unit: DesignUnit;
+    unit: 'px' | 'mm' | 'in';
     fixedOrientation?: boolean;
 };
 
@@ -3033,23 +3162,26 @@ export declare interface RGBColor {
 export declare type RoleString = 'Creator' | 'Adopter' | 'Viewer' | 'Presenter';
 
 /**
- * Export Settings
+ * @deprecated This type definition is not used anymore and will be removed
+ * in the future. The settings that were configured here can be set via the
+ * BlockApi on the scene block:
+ *
+ * ```ts
+ * engine.block.setInt(sceneId, 'scene/dpi', dpi);
+ * engine.block.setInt(sceneId, 'scene/pixelScaleFactor', factor);
+ * ```
+ *
  * @public
  */
 declare type Scene = {
     /**
-     * The DPI value to use when exporting and when converting between pixels and inches or millimeter units.
-     * (In the CESDK, this value is synonymous with PPI).
-     *
-     * This is only relevant for new scenes that are created in the editor. Loaded scenes will use the
-     * value stored in their serialization file.
+     * @deprecated Setting this value has no effect. You can change the dpi of the
+     * current scene via `engine.block.setInt(sceneId, 'scene/dpi', dpi)`
      */
     dpi: number;
     /**
-     * A scale factor that is applied to the final export resolution.
-     *
-     * This is only relevant for new scenes that are created in the editor. Loaded scenes will use the
-     * value stored in their serialization file.
+     * @deprecated Setting this value has no effect. You can change the dpi of the
+     * current scene via `engine.block.setInt(sceneId, 'scene/pixelScaleFactor', * factor)`
      */
     pixelScaleFactor: number;
 };
@@ -3103,11 +3235,19 @@ export declare class SceneAPI {
      * Fetching the image may take an arbitrary amount of time, so the scene isn't immediately
      * available.
      * @param url - The image URL.
-     * @param dpi - The scenes DPI.
-     * @param pixelScaleFactor - The displays pixel scale factor.
+     * @param dpi - The scene's DPI.
+     * @param pixelScaleFactor - The display's pixel scale factor.
      * @returns A promise that resolves with the scene ID on success or rejected with an error otherwise.
      */
     createFromImage(url: string, dpi?: number, pixelScaleFactor?: number, sceneLayout?: SceneLayout, spacing?: number, spacingInScreenSpace?: boolean): Promise<DesignBlockId>;
+    /**
+     * Loads the given video and creates a scene with a single page showing the video.
+     * Fetching the video may take an arbitrary amount of time, so the scene isn't immediately
+     * available.
+     * @param url - The video URL.
+     * @returns A promise that resolves with the scene ID on success or rejected with an error otherwise.
+     */
+    createFromVideo(url: string): Promise<DesignBlockId>;
     /**
      * Return the currently active scene.
      * @returns The scene or null, if none was created yet.
@@ -3136,6 +3276,16 @@ export declare class SceneAPI {
      * @returns The current mode of the scene.
      */
     getMode(): SceneMode;
+    /**
+     * Converts all values of the current scene into the given design unit.
+     * @param designUnit - The new design unit of the scene
+     */
+    setDesignUnit(designUnit: DesignUnit): void;
+    /**
+     * Returns the design unit of the current scene.
+     * @returns The current design unit.
+     */
+    getDesignUnit(): DesignUnit;
     /**
      * Get the sorted list of pages in the scene.
      * @returns The sorted list of pages in the scene.
@@ -3213,23 +3363,13 @@ export declare class SceneAPI {
      * @returns A method to unsubscribe.
      * @privateRemarks This will currently fire on _all_ changes to camera properties
      */
-    onZoomLevelChanged(callback: () => void): () => void;
+    onZoomLevelChanged: (callback: () => void) => (() => void);
     /**
      * Subscribe to changes to the active scene rendered by the engine.
      * @param callback - This function is called at the end of the engine update, if the active scene has changed.
      * @returns A method to unsubscribe.
      */
-    onActiveChanged(callback: () => void): () => void;
-    /**
-     * Converts all values of the current scene into the given design unit.
-     * @param designUnit - The new design unit of the scene
-     */
-    unstable_setDesignUnit(designUnit: DesignUnit): void;
-    /**
-     * Returns the design unit of the current scene.
-     * @returns The current design unit.
-     */
-    unstable_getDesignUnit(): DesignUnit;
+    onActiveChanged: (callback: () => void) => (() => void);
 }
 
 /**
@@ -3292,8 +3432,6 @@ declare type Source<T> = (handler: Handler<T>) => UnsubscribeFn;
 /** @public */
 export declare interface SpotColor {
     name: string;
-    rgbApproximation: RGBAColor;
-    cmykApproximation: CMYKColor;
 }
 
 declare interface SpotColorLookup {
@@ -3414,6 +3552,68 @@ export declare interface Vec4 {
     w: number;
 }
 
+/**
+ * - Top: The blocks get top aligned.
+ * - Bottom: The blocks get bottom aligned.
+ * - Center: The blocks get center aligned.
+ *
+ * @public
+ */
+export declare type VerticalBlockAlignment = 'Top' | 'Bottom' | 'Center';
+
+/** @public */
+export declare type VerticalTextAlignment = 'Top' | 'Bottom' | 'Center';
+
+/**
+ * @public
+ */
+export declare type VideoExportOptions = {
+    /**
+     * Determines the encoder feature set and in turn the quality, size and speed of the encoding process.
+     *
+     * @defaultValue 77 (Main)
+     */
+    h264Profile?: number;
+    /**
+     * Controls the H.264 encoding level. This relates to parameters used by the encoder such as bit rate,
+     * timings and motion vectors. Defined by the spec are levels 1.0 up to 6.2. To arrive at an integer value,
+     * the level is multiplied by ten. E.g. to get level 5.2, pass a value of 52.
+     *
+     * @defaultValue 52
+     */
+    h264Level?: number;
+    /**
+     * The time offset in seconds of the scene's timeline from which the video will start.
+     *
+     * @defaultValue 0
+     */
+    timeOffset?: number;
+    /**
+     * The duration in seconds of the final video.
+     *
+     * @defaultValue The duration of the scene.
+     */
+    duration?: number;
+    /**
+     * The target framerate of the exported video in Hz.
+     *
+     * @defaultValue 30
+     */
+    framerate?: number;
+    /**
+     * An optional target width used in conjunction with target height.
+     * If used, the block will be rendered large enough, that it fills the target
+     * size entirely while maintaining its aspect ratio.
+     */
+    targetWidth?: number;
+    /**
+     * An optional target height used in conjunction with target width.
+     * If used, the block will be rendered large enough, that it fills the target
+     * size entirely while maintaining its aspect ratio.
+     */
+    targetHeight?: number;
+};
+
 /**
  * Describes a rectangle on the screen
  * - `x` and `y` indicate the position