@cesdk/cesdk-js 1.6.0-alpha.1 → 1.6.2

package/cesdk-engine.umd.d.ts

@@ -1,7 +1,7 @@
 /// <reference types="offscreencanvas" />
 
 /**
- * Generic asset informations
+ * Generic asset information
  * @public
  */
 export declare interface Asset {
@@ -280,7 +280,7 @@ export declare interface AssetsQueryResult {
   /** The current, requested page */
   currentPage: number;
   /** The next page to query if it exists */
-  nextPage: number | undefined;
+  nextPage?: number;
   /** How many assets are there in total for the current query regardless of the page */
   total: number;
 }
@@ -295,11 +295,34 @@ declare interface AssetsQueryResult_2 {
   /** The current, requested page */
   currentPage: number;
   /** The next page to query if it exists */
-  nextPage: number | undefined;
+  nextPage?: number;
   /** How many assets are there in total for the current query regardless of the page */
   total: number;
 }
 
+/**
+ * @public
+ */
+export declare type BlendMode =
+  | 'PassThrough'
+  | 'Normal'
+  | 'Darken'
+  | 'Multiply'
+  | 'ColorBurn'
+  | 'Lighten'
+  | 'Screen'
+  | 'ColorDodge'
+  | 'Overlay'
+  | 'SoftLight'
+  | 'HardLight'
+  | 'Difference'
+  | 'Exclusion'
+  | 'Hue'
+  | 'Saturation'
+  | 'Color'
+  | 'Luminosity';
+
+/** @public */
 declare type Block = number;
 
 /**
@@ -337,12 +360,12 @@ export declare class BlockAPI {
    * @returns The created blocks handle.
    */
   create(type: DesignBlockType): DesignBlockId;
-  /**
 
-     * Get the type of the given block, fails if the block is invalid.
-     * @param id - The block to query.
-     * @returns The blocks type.
-     */
+  /**
+   * 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;
   /**
    * Update the selection state of a block.
@@ -526,13 +549,13 @@ export declare class BlockAPI {
   /**
    * Update a block's horizontal flip.
    * @param id - The block to update.
-   * @param horizontal - Whether the block should be flipped along its x-axis.
+   * @param flip - If the flip should be enabled.
    */
   setFlipHorizontal(id: DesignBlockId, flip: boolean): void;
   /**
    * Update a block's vertical flip.
    * @param id - The block to update.
-   * @param vertical - Whether the block should be flipped along its y-axis.
+   * @param flip - If the flip should be enabled.
    */
   setFlipVertical(id: DesignBlockId, flip: boolean): void;
   /**
@@ -687,6 +710,26 @@ export declare class BlockAPI {
    * @returns float The height of the axis-aligned bounding box.
    */
   getGlobalBoundingBoxHeight(id: DesignBlockId): number;
+  /**
+   * Scales the block and all of its children proportionally around the specified
+   * relative anchor point.
+   *
+   * This updates the position, size and style properties (e.g. stroke width) of
+   * the block and its children.
+   *
+   * @param id - The block that should be scaled.
+   * @param scale - The scale factor to be applied to the current properties of the block.
+   * @param anchorX - The relative position along the width of the block around which the
+   * scaling should occur. (0 = left edge, 0.5 = center, 1 = right edge)
+   * @param anchorY - The relative position along the height of the block around which the
+   * scaling should occur. (0 = top edge, 0.5 = center, 1 = bottom edge)
+   */
+  scale(
+    id: DesignBlockId,
+    scale: number,
+    anchorX?: number,
+    anchorY?: number
+  ): void;
   /**
    * Get all available properties of a block.
    * @param id - The block whose properties should be queried.
@@ -874,7 +917,7 @@ export declare class BlockAPI {
   /**
    * Query if the given block has an opacity.
    * @param id - The block to query.
-   * @returns true, if the block has an opcity.
+   * @returns true, if the block has an opacity.
    */
   hasOpacity(id: DesignBlockId): boolean;
   /**
@@ -889,6 +932,19 @@ export declare class BlockAPI {
    * @returns The opacity.
    */
   getOpacity(id: DesignBlockId): number;
+  /**
+   * Set the blend mode of the given design block.
+   * @param id - The block whose blend mode should be set.
+   * @param blendMode - The blend mode to be set.
+   * @returns
+   */
+  setBlendMode(id: DesignBlockId, blendMode: BlendMode): void;
+  /**
+   * Get the blend mode of the given design block.
+   * @param id - The block whose blend mode should be queried.
+   * @returns The blend mode.
+   */
+  getBlendMode(id: DesignBlockId): BlendMode;
   /**
    * Query if the given block has fill color properties.
    * @param id - The block to query.
@@ -1240,8 +1296,8 @@ export declare class BlockAPI {
     y: number
   ): boolean;
   /**
-   * Get the horizontal comopnent of a gradient's control point.
-   * @param id - The block whose gradient control point should be qeried.
+   * Get the horizontal component of a gradient's control point.
+   * @param id - The block whose gradient control point should be queried.
    * @param gradientControlPointType - The type of control point.
    * @returns The horizontal component of the control point, an error otherwise.
    */
@@ -1250,8 +1306,8 @@ export declare class BlockAPI {
     gradientControlPointType: GradientControlPointType
   ): number;
   /**
-   * Get the vertical comopnent of a gradient's control point.
-   * @param id - The block whose gradient control point should be qeried.
+   * Get the vertical component of a gradient's control point.
+   * @param id - The block whose gradient control point should be queried.
    * @param gradientControlPointType - The type of control point.
    * @returns The vertical component of the control point, an error otherwise.
    */
@@ -1284,6 +1340,7 @@ export declare type BlockEvent = {
   type: 'Created' | 'Updated' | 'Destroyed';
 };
 
+/** @public */
 declare interface BlockEvent_2 {
   block: Block;
   type: 'Created' | 'Updated' | 'Destroyed';
@@ -1294,8 +1351,11 @@ declare type Callbacks = {
   log?: Logger;
 };
 
-/** All components between 0 and 1 */
-declare interface CMYKColor {
+/**
+ * All components between 0 and 1
+ * @public
+ */
+export declare interface CMYKColor {
   c: number;
   m: number;
   y: number;
@@ -1319,12 +1379,6 @@ declare type ColorPaletteDefinition = Preset & {
   entries: Color_2[];
 };
 
-declare type Command = {
-  identifier: string;
-  argumentTypes: string[];
-  returnType: string;
-};
-
 declare namespace ConfigTypes {
   export {
     HexColorString,
@@ -1392,10 +1446,6 @@ declare type Core = {
   baseURL: string;
 };
 
-declare interface CreateSceneOptions {
-  layout: SceneLayout;
-}
-
 /**
  * A headless implementation that just initializes & exposes the Document API
  *
@@ -1406,6 +1456,7 @@ declare class CreativeEngine {
   block: BlockAPI;
   scene: SceneAPI;
   variable: VariableAPI;
+  editor: EditorAPI;
 
   event: EventAPI;
 
@@ -1438,6 +1489,7 @@ export declare type DesignBlockId = number;
  */
 export declare enum DesignBlockType {
   Scene = '//ly.img.ubq/scene',
+  Stack = '//ly.img.ubq/stack',
   Camera = '//ly.img.ubq/camera',
   Page = '//ly.img.ubq/page',
   Image = '//ly.img.ubq/image',
@@ -1453,10 +1505,179 @@ export declare enum DesignBlockType {
   Group = '//ly.img.ubq/group'
 }
 
-declare enum DesignUnit {
-  Pixel = 'px',
-  Millimeter = 'mm',
-  Inch = 'in'
+/** @public */
+export declare type DesignUnit = 'mm' | 'px' | 'in';
+
+/**
+ * @public
+ */
+export declare class EditorAPI {
+  #private;
+
+  /**
+   * Subscribe to changes to the editor state.
+   * @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;
+  /**
+   * Set the edit mode of the editor.
+   * An edit mode defines what type of content can currently be edited by the user.
+   * Hint: the initial edit mode is "Transform".
+   * @param mode - "Transform", "Crop", "Text", or a custom value.
+   */
+  setEditMode(mode: 'Transform' | 'Crop' | 'Text' | string): void;
+  /**
+   * Get the current edit mode of the editor.
+   * An edit mode defines what type of content can currently be edited by the user.
+   * @returns "Transform", "Crop", "Text", or a custom value.
+   */
+  getEditMode(): 'Transform' | 'Crop' | 'Text' | string;
+  /**
+   * Get the type of cursor that should be displayed by the application.
+   * @returns The cursor type.
+   */
+  getCursorType():
+    | 'Arrow'
+    | 'Move'
+    | 'MoveNotPermitted'
+    | 'Resize'
+    | 'Rotate'
+    | 'Text';
+  /**
+   * Get the rotation with which to render the mouse cursor.
+   * @returns The angle in radians.
+   */
+  getCursorRotation(): number;
+  /**
+   * Get the current text cursor's x position in screen space.
+   * @returns The text cursor's x position in screen space.
+   */
+  getTextCursorPositionInScreenSpaceX(): number;
+  /**
+   * Get the current text cursor's y position in screen space.
+   * @returns The text cursor's y position in screen space.
+   */
+  getTextCursorPositionInScreenSpaceY(): number;
+  /**
+   * Sets the zoom level of the scene.
+   * @param zoomLevel - The new zoom level.
+   */
+  setZoomLevel(zoomLevel?: number): void;
+  /**
+   * Query a camera zoom level.
+   * @returns The zoom level of the block's (main) camera.
+   */
+  getZoomLevel(): number;
+  /**
+   * Adds a new history state to the stack, if undoable changes were made.
+   */
+  addUndoStep(): void;
+  /**
+   * Undo one step in the history if an undo step is available.
+   */
+  undo(): void;
+  /**
+   * Redo one step in the history if a redo step is available.
+   */
+  redo(): void;
+  /**
+   * If an undo step is available.
+   *
+   * @returns True if an undo step is available.
+   */
+  canUndo(): boolean;
+  /**
+   * If a redo step is available.
+   *
+   * @returns True if a redo step is available.
+   */
+  canRedo(): boolean;
+  /**
+   * Set a boolean setting.
+   * @param keypath - The settings keypath, e.g. `ubq://doubleClickToCropEnabled`
+   * @param value - The value to set.
+   * @throws An error, if the keypath is invalid.
+   */
+  setSettingBool(keypath: string, value: boolean): void;
+  /**
+   * Get a boolean setting.
+   * @param keypath - The settings keypath, e.g. `ubq://doubleClickToCropEnabled`
+   * @throws An error, if the keypath is invalid.
+   */
+  getSettingBool(keypath: string): boolean;
+  /**
+   * Set an integer setting.
+   * @param keypath - The settings keypath.
+   * @param value - The value to set.
+   * @throws An error, if the keypath is invalid.
+   */
+  setSettingInt(keypath: string, value: number): void;
+  /**
+   * Get an integer setting.
+   * @param keypath - The settings keypath.
+   * @throws An error, if the keypath is invalid.
+   */
+  getSettingInt(keypath: string): number;
+  /**
+   * Set a float setting.
+   * @param keypath - The settings keypath, e.g. `ubq://positionSnappingThreshold`
+   * @param value - The value to set.
+   * @throws An error, if the keypath is invalid.
+   */
+  setSettingFloat(keypath: string, value: number): void;
+  /**
+   * Get a float setting.
+   * @param keypath - The settings keypath, e.g. `ubq://positionSnappingThreshold`
+   * @throws An error, if the keypath is invalid.
+   */
+  getSettingFloat(keypath: string): number;
+  /**
+   * Set a string setting.
+   * @param keypath - The settings keypath, e.g. `ubq://license`
+   * @param value - The value to set.
+   * @throws An error, if the keypath is invalid.
+   */
+  setSettingString(keypath: string, value: string): void;
+  /**
+   * Get a string setting.
+   * @param keypath - The settings keypath, e.g. `ubq://license`
+   * @throws An error, if the keypath is invalid.
+   */
+  getSettingString(keypath: string): string;
+  /**
+   * Set a color setting.
+   * @param keypath - The settings keypath, e.g. `ubq://highlightColor`.
+   * @param r - The red color component in the range of 0 to 1.
+   * @param g - The green color component in the range of 0 to 1.
+   * @param b - The blue color component in the range of 0 to 1.
+   * @param a - The alpha color component in the range of 0 to 1.
+   */
+  setSettingColorRGBA(
+    keypath: string,
+    r: number,
+    g: number,
+    b: number,
+    a: number
+  ): void;
+  /**
+   * Get a color setting.
+   * @param keypath - The settings keypath, e.g. `ubq://highlightColor`.
+   * @returns A tuple of channels red, green, blue and alpha in the range of 0 to 1.
+   */
+  getSettingColorRGBA(keypath: string): RGBA;
+  /**
+   * Set an enum setting.
+   * @param keypath - The settings keypath, e.g. `ubq://role`.
+   * @param value - The enum value as string.
+   */
+  setSettingEnum(keypath: string, value: string): void;
+  /**
+   * Get an enum setting.
+   * @param keypath - The settings keypath, e.g. `ubq://role`.
+   * @returns The value as string.
+   */
+  getSettingEnum(keypath: string): string;
 }
 
 /**
@@ -1477,8 +1698,7 @@ export declare class EventAPI {
   ): () => void;
 }
 
-declare type EventSubscription = number;
-
+/** @public */
 declare interface ExportOptions {
   jpegQuality: number;
   pngCompressionLevel: number;
@@ -1487,6 +1707,7 @@ declare interface ExportOptions {
   targetHeight: number;
 }
 
+/** @public */
 declare interface ExportVideoOptions {
   h264Profile: number;
   h264Level: number;
@@ -1507,14 +1728,17 @@ declare type Extensions = {
  */
 export declare type FillType = 'Solid' | 'Gradient';
 
+/** @public */
 declare interface Flip {
   horizontal: boolean;
   vertical: boolean;
 }
 
-declare type FontStyle = 'normal' | 'italic';
+/** @public */
+export declare type FontStyle = 'normal' | 'italic';
 
-declare type FontWeight =
+/** @public */
+export declare type FontWeight =
   | 'thin'
   | 'extraLight'
   | 'Light'
@@ -1553,6 +1777,7 @@ export declare type GradientType = 'Linear' | 'Radial' | 'Conical';
  *
  * Tags in comparison have are more loosely hold meaning used for extended
  * searching/filtering.
+ * @public
  */
 declare type Groups = string[];
 
@@ -1574,12 +1799,17 @@ declare type ImageDefinition = Preset & {
   };
 };
 
-/** e.g. `en`, `de`, etc.  */
+/**
+ * e.g. `en`, `de`, etc.
+ * @public
+ */
 declare type Locale = string;
 
-declare type Logger = (message: string, level: LogLevel) => void;
+/** @public */
+export declare type Logger = (message: string, level: LogLevel) => void;
 
-declare enum LogLevel {
+/** @public */
+export declare enum LogLevel {
   Info = 'Info',
   Warning = 'Warning',
   Error = 'Error'
@@ -1597,17 +1827,6 @@ declare enum MimeType_2 {
 }
 export { MimeType_2 as MimeType };
 
-declare interface NotificationEvent {
-  type: NotificationType;
-  i18n: string;
-}
-
-declare enum NotificationType {
-  Information = 0,
-  Warning = 1,
-  Error = 2
-}
-
 /** @public */
 declare type Page = {
   title: {
@@ -1712,22 +1931,29 @@ declare interface QueryData {
  */
 export declare type RGBA = [r: number, g: number, b: number, a: number];
 
-/** All components between 0 and 1 */
-declare interface RGBAColor {
+/**
+ * All components between 0 and 1
+ * @public
+ */
+export declare interface RGBAColor {
   r: number;
   g: number;
   b: number;
   a: number;
 }
 
-/** All components between 0 and 1 */
-declare interface RGBColor {
+/**
+ * All components between 0 and 1
+ * @public
+ */
+export declare interface RGBColor {
   r: number;
   g: number;
   b: number;
 }
 
-declare type RoleString = 'Creator' | 'Adopter' | 'Viewer' | 'Presenter';
+/** @public */
+export declare type RoleString = 'Creator' | 'Adopter' | 'Viewer' | 'Presenter';
 
 /**
  * Export Settings
@@ -1810,12 +2036,40 @@ export declare class SceneAPI {
    * @returns The scene or null, if none was created yet.
    */
   get(): DesignBlockId | null;
+  /**
+   * Applies the contents of the given template scene to the currently loaded scene.
+   * This loads the template scene while keeping the design unit and page dimensions
+   * of the current scene. Page contents remain centered when the pages are resized
+   * to fit the new dimensions.
+   * @param content - The template scene file contents, a base64 string.
+   * @returns A Promise that resolves once the template was applied or rejects if there was an error.
+   */
+  applyTemplateFromString(content: string): Promise<void>;
+  /**
+   * Applies the contents of the given template scene to the currently loaded scene.
+   * This loads the template scene while keeping the design unit and page dimensions
+   * of the current scene. Page contents remain centered when the pages are resized
+   * to fit the new dimensions.
+   * @param url - The url to the template scene file.
+   * @returns A Promise that resolves once the template was applied or rejects if there was an error.
+   */
+  applyTemplateFromURL(url: string): Promise<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;
 }
 
-declare enum SceneLayout {
-  Free = 0,
-  VerticalStack = 1,
-  HorizontalStack = 2
+/** @public */
+export declare interface Size2 {
+  width: number;
+  height: number;
 }
 
 /**
@@ -1849,40 +2103,26 @@ export declare type StrokeStyle =
   | 'LongDashedRound'
   | 'Solid';
 
+/** @public */
+declare type Subscription = number;
+
 /** @public */
 declare type TemplateDefinition = Preset & {
+  label: string;
   scene: string | URL | (() => Promise<string>);
   thumbnailURL?: string | URL;
 };
 
-declare interface TypeDescription {
-  name: string;
-  members: Array<TypeMemberDescription>;
-}
-
 /** @public */
 declare type TypefaceDefinition = Preset & {
   family: string;
-  fonts: [
-    {
-      fontURL: string;
-      weight: FontWeight;
-      style: FontStyle;
-    }
-  ];
+  fonts: {
+    fontURL: string;
+    weight: FontWeight;
+    style: FontStyle;
+  }[];
 };
 
-declare interface TypeMemberDescription {
-  name: string;
-  type: string;
-  props: Array<TypeProp>;
-}
-
-declare interface TypeProp {
-  key: string;
-  value: number | string;
-}
-
 /**
  * @public
  */
@@ -1923,21 +2163,25 @@ declare type Variables = {
   [id: string]: VariableDefinition;
 };
 
-declare interface Vec2 {
+/** @public */
+export declare interface Vec2 {
   x: number;
   y: number;
 }
 
-declare interface Vec3 {
+/** @public */
+export declare interface Vec3 {
   x: number;
   y: number;
   z: number;
 }
 
-declare interface Vector<T> {
-  size: () => number;
-  get: (index: number) => T;
-  delete: () => void;
+/** @public */
+export declare interface Vec4 {
+  x: number;
+  y: number;
+  z: number;
+  w: number;
 }
 
 export {};