@cesdk/cesdk-js 1.4.0-alpha.2 → 1.4.0

package/BlockAPI.d.ts

@@ -1,29 +1,66 @@
 type Vec2 = { x: number; y: number };
-type DesignElementId = number;
-type DesignElementType = string;
-type MimeType = 'image/png' | 'image/jpeg';
-type Size = number; // | 'auto';
+type DesignBlockId = number;
+type DesignBlockType = string;
+type MimeType =
+  | 'image/png'
+  | 'image/jpeg'
+  | 'image/x-tga'
+  | 'application/octet-stream';
 type Size2 = {
-  width: Size;
-  height: Size;
+  width: number;
+  height: number;
 };
 
+export enum PositionMode {
+  /** Position in absolute design units. */
+  Absolute = 'Absolute',
+  /** Position in relation to the block's parent's size in percent, where 1.0 means 100%. */
+  Percent = 'Percent',
+  /** Position is automatically determined. */
+  Undefined = 'Auto'
+}
+
+export enum SizeMode {
+  /** Size in absolute design units. */
+  Absolute = 'Absolute',
+  /** Size in relation to the block's parent's size in percent, where 1.0 means 100%. */
+  Percent = 'Percent',
+  /** Size is determined by the block's content. */
+  Auto = 'Auto'
+}
+
 export default class BlockAPI {
   /**
    * Exports a design block element as a file of the given mime type.
    * Performs an internal update to resolve the final layout for the blocks.
    * @param handle The design block element to export.
-   * @param mimeType The mime type of the output file.
+   * @param mimeType The mime type of the output file. Defaults to 'image/png'
    * @returns A promise that resolves with the exported image or is rejected with an error.
    */
-  export(handle: DesignElementId, mimeType: MimeType): Promise<Blob>;
+  export(handle: DesignBlockId, mimeType?: MimeType): 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.
+   * @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.
+   */
+  loadFromString(content: string): Promise<DesignBlockId[]>;
+
+  /**
+   * Saves the given blocks into a string. If given the root of a block hierarchy, e.g. a
+   * page with multiple children, the entire hierarchy is saved.
+   * @param blocks
+   * @returns A promise that resolves to a string representing the blocks or an error.
+   */
+  saveToString(blocks: DesignBlockId[]): Promise<string>;
 
   /**
    * Create a new block, fails if type is unknown.
    * @param type The type of the block that shall be created.
    * @returns The created blocks handle.
    */
-  create(type: DesignElementType): DesignElementId;
+  create(type: DesignBlockType): DesignBlockId;
 
   /**
 
@@ -31,7 +68,7 @@ export default class BlockAPI {
    * @param id The block to query.
    * @returns The blocks type.
    */
-  getType(id: DesignElementId): DesignElementType;
+  getType(id: DesignBlockId): DesignBlockType;
 
   /**
    * Update the selection state of a block.
@@ -39,53 +76,60 @@ export default class BlockAPI {
    * @param id The block to query.
    * @param selected Whether or not the block should be selected.
    */
-  setSelected(id: DesignElementId, selected: boolean): void;
+  setSelected(id: DesignBlockId, selected: boolean): void;
 
   /**
    * Get the selected state of a block.
    * @param id The block to query.
    * @returns True if the block is selected, false otherwise.
    */
-  isSelected(id: DesignElementId): boolean;
+  isSelected(id: DesignBlockId): boolean;
 
   /**
    * Get all currently selected blocks.
    * @returns An array of block ids.
    */
-  findAllSelected(): DesignElementId[];
+  findAllSelected(): DesignBlockId[];
+
+  /** Checks whether the given block references any variables. Doesn't check the blocks children.
+   *
+   * @param block The block to inspect.
+   * @return true if the block references variables and false otherwise.
+   */
+  referencesAnyVariables(id: DesignBlockId): boolean;
 
   /**
    * Update a block's name.
    * @param id The block to update.
    * @param name The name to set.
    */
-  setName(id: DesignElementId, name: string): void;
+  setName(id: DesignBlockId, name: string): void;
 
   /**
    * Get a block's name.
    * @param id The block to update.
    */
-  getName(id: DesignElementId): string;
+  getName(id: DesignBlockId): string;
 
   /**
    * Finds all blocks with the given name.
    * @param name The name to search for.
    * @returns A list of block ids.
    */
-  findByName(name: string): DesignElementId[];
+  findByName(name: string): DesignBlockId[];
 
   /**
    * Finds all blocks with the given type.
    * @param type The type to search for.
    * @returns A list of block ids.
    */
-  findByType(type: DesignElementType): DesignElementId[];
+  findByType(type: DesignBlockType): DesignBlockId[];
 
   /**
    * Return all blocks currently known to the engine.
    * @returns A list of block ids.
    */
-  findAll(): /* filterSpec?: unknown */ DesignElementId[];
+  findAll(): /* filterSpec?: unknown */ DesignBlockId[];
 
   // Element
 
@@ -94,113 +138,202 @@ export default class BlockAPI {
    * @param id The block to query.
    * @returns True if visible, false otherwise.
    */
-  isVisible(id: DesignElementId): boolean;
+  isVisible(id: DesignBlockId): boolean;
 
   /**
    * Update a block's visibility.
    * @param id The block to update.
    * @param visible Whether the block shall be visible.
    */
-  setVisible(id: DesignElementId, visible: boolean): void;
+  setVisible(id: DesignBlockId, visible: boolean): void;
+
+  /**
+   * Query a block's x position.
+   * @param id The block to query.
+   * @returns The value of the x position.
+   */
+  getPositionX(id: DesignBlockId): number;
+
+  /**
+   * Query a block's mode for its x position.
+   * @param id The block to query.
+   * @returns The current mode for the x position: absolute, percent or undefined.
+   */
+  getPositionXMode(id: DesignBlockId): PositionMode;
+
+  /**
+   * Query a block's y position.
+   * @param id The block to query.
+   * @returns The value of the y position.
+   */
+  getPositionY(id: DesignBlockId): number;
 
   /**
-   * Query a block's absolute position in design units.
+   * Query a block's mode for its y position.
    * @param id The block to query.
-   * @returns
+   * @returns The current mode for the y position: absolute, percent or undefined.
    */
-  getPosition(id: DesignElementId): Vec2;
+  getPositionYMode(id: DesignBlockId): PositionMode;
 
   /**
-   * Update a block's absolute position.
+   * Update a block's x position.
    * @param id The block to update.
-   * @param { x, y } pos The new position in design units.
+   * @param value The value of the x position.
    */
-  setPosition(id: DesignElementId, { x, y }: Vec2): void;
+  setPositionX(id: DesignBlockId, value: number): void;
+
+  /**
+   * Set a block's mode for its x position.
+   * @param id The block to update.
+   * @param mode The x position mode: absolute, percent or undefined.
+   */
+  setPositionXMode(id: DesignBlockId, mode: PositionMode): void;
+
+  /**
+   * Update a block's y position.
+   * @param id The block to update.
+   * @param value The value of the y position.
+   */
+  setPositionY(id: DesignBlockId, value: number): void;
+
+  /**
+   * Set a block's mode for its y position.
+   * @param id The block to update.
+   * @param mode The y position mode: absolute, percent or undefined.
+   */
+  setPositionYMode(id: DesignBlockId, mode: PositionMode): void;
 
   /**
    * Query a block's rotation in radians.
    * @param id The block to query.
    * @returns The block's rotation around its center in radians.
    */
-  getRotation(id: DesignElementId): number;
+  getRotation(id: DesignBlockId): number;
 
   /**
    * Update a block's rotation.
    * @param id The block to update.
    * @param radians The new rotation in radians. Rotation is applied around the block's center.
    */
-  setRotation(id: DesignElementId, radians: number): void;
+  setRotation(id: DesignBlockId, radians: number): void;
 
   /**
    * Query a block's horizontal flip state.
    * @param id The block to query.
    * @returns A boolean indicating for whether the block is flipped in the queried direction
    */
-  getFlipHorizontal(id: DesignElementId): boolean;
+  getFlipHorizontal(id: DesignBlockId): boolean;
 
   /**
    * Query a block's vertical flip state.
    * @param id The block to query.
    * @returns A boolean indicating for whether the block is flipped in the queried direction
    */
-  getFlipVertical(id: DesignElementId): boolean;
+  getFlipVertical(id: DesignBlockId): boolean;
 
   /**
    * Update a block's horizontal flip.
    * @param id The block to update.
    * @param horizontal Whether the block should be flipped along its x-axis.
-   * @returns
    */
-  setFlipHorizontal(id: DesignElementId, flip: boolean): void;
+  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.
-   * @returns
    */
-  setFlipVertical(id: DesignElementId, flip: boolean): void;
+  setFlipVertical(id: DesignBlockId, flip: boolean): void;
+
+  /**
+   * Query a block's width.
+   * @param id The block to query.
+   * @returns The value of the block's width.
+   */
+  getWidth(id: DesignBlockId): number;
+
+  /**
+   * Query a block's mode for its width.
+   * @param id The block to query.
+   * @returns The current mode for the width: absolute, percent or auto.
+   */
+  getWidthMode(id: DesignBlockId): SizeMode;
+
+  /**
+   * Query a block's height.
+   * @param id The block to query.
+   * @returns The value of the block's height.
+   */
+  getHeight(id: DesignBlockId): number;
 
   /**
-   * Query a block's absolute size in design units.
+   * Query a block's mode for its height.
    * @param id The block to query.
-   * @returns A `Size2` object.
+   * @returns The current mode for the height: absolute, percent or auto.
+   */
+  getHeightMode(id: DesignBlockId): SizeMode;
+
+  /**
+   * Update a block's width.
+   * @param id The block to update.
+   * @param value The new width of the block.
+   */
+  setWidth(id: DesignBlockId, value: number): void;
+
+  /**
+   * Set a block's mode for its width.
+   * @param id The block to update.
+   * @param mode The width mode: absolute, percent or auto.
+   */
+  setWidthMode(id: DesignBlockId, mode: SizeMode): void;
+
+  /**
+   * Update a block's height.
+   * @param id The block to update.
+   * @param value The new height of the block.
    */
-  getSize(id: DesignElementId): Size2;
+  setHeight(id: DesignBlockId, value: number): void;
 
   /**
-   * Update a block's absolute size in design units.
+   * Set a block's mode for its height.
    * @param id The block to update.
-   * @param size A size object defining width and height.
+   * @param mode The height mode: absolute, percent or auto.
+   */
+  setHeightMode(id: DesignBlockId, mode: SizeMode): void;
+
+  /**
+   * Get a block's layouted width. Requires an `engine.render()` beforehand.
+   * @param id The block to query.
+   * @returns The layouted width.
    */
-  setSize(id: DesignElementId, size: Size2): void;
+  getFrameWidth(id: DesignBlockId): number;
 
   /**
-   * Get a block's layouted size. Requires an `engine.render()` beforehand.
+   * Get a block's layouted height. Requires an `engine.render()` beforehand.
    * @param id The block to query.
-   * @returns A `Size2` object holding the size.
+   * @returns The layouted height.
    */
-  getFrameSize(id: DesignElementId): Size2;
+  getFrameHeight(id: DesignBlockId): number;
 
   /**
    * Duplicates a block including its children.
    * @param id The block to duplicate.
    * @returns The handle of the duplicate.
    */
-  duplicate(id: DesignElementId): DesignElementId;
+  duplicate(id: DesignBlockId): DesignBlockId;
 
   /**
    * Destroys a block.
    * @param id The block to destroy.
    */
-  destroy(id: DesignElementId): void;
+  destroy(id: DesignBlockId): void;
 
   /**
    * Query a block's parent.
    * @param id The block to query.
    * @returns The parent's handle.
    */
-  getParent(id: DesignElementId): DesignElementId;
+  getParent(id: DesignBlockId): DesignBlockId;
 
   /**
    * Get all children of the given block. Children
@@ -209,7 +342,7 @@ export default class BlockAPI {
    * @param id The block to query.
    * @returns A list of block ids.
    */
-  getChildren(id: DesignElementId): DesignElementId[];
+  getChildren(id: DesignBlockId): DesignBlockId[];
 
   /**
    * Insert a new or existing child at a certain position in the parent's children.
@@ -217,16 +350,44 @@ export default class BlockAPI {
    * @param child The child to insert. Can be an existing child of `parent`.
    * @param index The index to insert or move to.
    */
-  insertChild(
-    parent: DesignElementId,
-    child: DesignElementId,
-    index: number
-  ): void;
+  insertChild(parent: DesignBlockId, child: DesignBlockId, index: number): void;
 
   /**
    * Appends a new or existing child to a block's children.
    * @param parent The block whose children should be updated.
    * @param child The child to insert. Can be an existing child of `parent`.
    */
-  appendChild(parent: DesignElementId, child: DesignElementId): void;
+  appendChild(parent: DesignBlockId, child: DesignBlockId): void;
+
+  /**
+   * Get the x position of the block's axis-aligned bounding box in the scene's global coordinate space.
+   * The scene's global coordinate space has its position at the top left.
+   * @param id The block whose bounding box should be calculated.
+   * @return UBQResult<float> The x coordinate of the position of the axis-aligned bounding box.
+   */
+  getGlobalBoundingBoxX(id: DesignBlockId): number;
+
+  /**
+   * Get the y position of the block's axis-aligned bounding box in the scene's global coordinate space.
+   * The scene's global coordinate space has its position at the top left.
+   * @param id The block whose bounding box should be calculated.
+   * @return UBQResult<float> The y coordinate of the position of the axis-aligned bounding box.
+   */
+  getGlobalBoundingBoxY(id: DesignBlockId): number;
+
+  /**
+   * Get the width of the block's axis-aligned bounding box in the scene's global coordinate space.
+   * The scene's global coordinate space has its position at the top left.
+   * @param id The block whose bounding box should be calculated.
+   * @return UBQResult<float> The width of the axis-aligned bounding box.
+   */
+  getGlobalBoundingBoxWidth(id: DesignBlockId): number;
+
+  /**
+   * Get the height of the block's axis-aligned bounding box in the scene's global coordinate space.
+   * The scene's global coordinate space has its position at the top left.
+   * @param id The block whose bounding box should be calculated.
+   * @return UBQResult<float> The height of the axis-aligned bounding box.
+   */
+  getGlobalBoundingBoxHeight(id: DesignBlockId): number;
 }