@cesdk/cesdk-js 1.4.0-alpha.1 → 1.4.0-alpha.6

package/BlockAPI.d.ts

@@ -1,22 +1,59 @@
 type Vec2 = { x: number; y: number };
 type DesignElementId = number;
 type DesignElementType = string;
-type MimeType = 'image/png' | 'image/jpeg';
-type Size = number; // | 'auto';
+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 not defined. */
+  Undefined = 'Undefined'
+}
+
+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: DesignElementId, 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<DesignElementId[]>;
+
+  /**
+   * 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: DesignElementId[]): Promise<string>;
 
   /**
    * Create a new block, fails if type is unknown.
@@ -104,18 +141,60 @@ export default class BlockAPI {
   setVisible(id: DesignElementId, visible: boolean): void;
 
   /**
-   * Query a block's absolute position in design units.
+   * Query a block's x position.
    * @param id The block to query.
-   * @returns
+   * @returns The value of the x position.
+   */
+  getPositionX(id: DesignElementId): 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: DesignElementId): PositionMode;
+
+  /**
+   * Query a block's y position.
+   * @param id The block to query.
+   * @returns The value of the y position.
+   */
+  getPositionY(id: DesignElementId): number;
+
+  /**
+   * Query a block's mode for its y position.
+   * @param id The block to query.
+   * @returns The current mode for the y position: absolute, percent or undefined.
+   */
+  getPositionYMode(id: DesignElementId): PositionMode;
+
+  /**
+   * Update a block's x position.
+   * @param id The block to update.
+   * @param value The value of the x position.
+   */
+  setPositionX(id: DesignElementId, 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: DesignElementId, mode: PositionMode): void;
+
+  /**
+   * Update a block's y position.
+   * @param id The block to update.
+   * @param value The value of the y position.
    */
-  getPosition(id: DesignElementId): Vec2;
+  setPositionY(id: DesignElementId, value: number): void;
 
   /**
-   * Update a block's absolute position.
+   * Set a block's mode for its y position.
    * @param id The block to update.
-   * @param { x, y } pos The new position in design units.
+   * @param mode The y position mode: absolute, percent or undefined.
    */
-  setPosition(id: DesignElementId, { x, y }: Vec2): void;
+  setPositionYMode(id: DesignElementId, mode: PositionMode): void;
 
   /**
    * Query a block's rotation in radians.
@@ -149,7 +228,6 @@ export default 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.
-   * @returns
    */
   setFlipHorizontal(id: DesignElementId, flip: boolean): void;
 
@@ -157,23 +235,64 @@ export default class BlockAPI {
    * 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;
 
   /**
-   * Query a block's absolute size in design units.
+   * Query a block's width.
    * @param id The block to query.
-   * @returns A `Size2` object.
+   * @returns The value of the block's width.
+   */
+  getWidth(id: DesignElementId): 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: DesignElementId): SizeMode;
+
+  /**
+   * Query a block's height.
+   * @param id The block to query.
+   * @returns The value of the block's height.
+   */
+  getHeight(id: DesignElementId): number;
+
+  /**
+   * Query a block's mode for its height.
+   * @param id The block to query.
+   * @returns The current mode for the height: absolute, percent or auto.
+   */
+  getHeightMode(id: DesignElementId): SizeMode;
+
+  /**
+   * Update a block's width.
+   * @param id The block to update.
+   * @param value The new width of the block.
+   */
+  setWidth(id: DesignElementId, 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: DesignElementId, 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: DesignElementId, 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.
    */
-  setSize(id: DesignElementId, size: Size2): void;
+  setHeightMode(id: DesignElementId, mode: SizeMode): void;
 
   /**
    * Get a block's layouted size. Requires an `engine.render()` beforehand.

package/PropertyAPI.d.ts

@@ -0,0 +1,388 @@
+type DesignBlockId = number;
+type RGBA = [r: number, g: number, b: number, a: number];
+
+export enum PropertyType {
+  Bool = 'Bool',
+  Int = 'Int',
+  Float = 'Float',
+  String = 'String',
+  Color = 'Color',
+  Enum = 'Enum',
+  Struct = 'Struct'
+}
+
+export default class PropertyAPI {
+  /**
+   * Get all available properties of a block.
+   * @param id The block whose properties should be queried.
+   * @returns A list of the property names.
+   */
+  findAll(id: DesignBlockId): string[];
+
+  /**
+   * Get the type of a property given its name.
+   * @param property The name of the property whose type should be queried.
+   * @returns The property type.
+   */
+  getType(property: string): PropertyType;
+
+  /**
+   * Get all the possible values of an enum given an enum property.
+   * @param enumProperty The name of the property whose enum values should be queried.
+   * @returns A list of the enum value names as string.
+   */
+  getEnumValues<T = string>(enumProperty: string): T[];
+
+  /**
+   * Set a bool property of the given design block to the given value.
+   * @param id The block whose property should be set.
+   * @param property The name of the property to set.
+   * @param value The value to set.
+   */
+  setBool(id: DesignBlockId, property: string, value: boolean): void;
+
+  /**
+   * Get the value of a bool 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 of the property.
+   */
+  getBool(id: DesignBlockId, property: string): boolean;
+
+  /**
+   * Set an int property of the given design block to the given value.
+   * @param id The block whose property should be set.
+   * @param property The name of the property to set.
+   * @param value The value to set.
+   */
+  setInt(id: DesignBlockId, property: string, value: number): void;
+
+  /**
+   * Get the value of an int 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 of the property.
+   */
+  getInt(id: DesignBlockId, property: string): number;
+
+  /**
+   * Set a float property of the given design block to the given value.
+   * @param id The block whose property should be set.
+   * @param property The name of the property to set.
+   * @param value The value to set.
+   */
+  setFloat(id: DesignBlockId, property: string, value: number): void;
+
+  /**
+   * Get the value of a float 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 of the property.
+   */
+  getFloat(id: DesignBlockId, property: string): number;
+
+  /**
+   * Set a string property of the given design block to the given value.
+   * @param id The block whose property should be set.
+   * @param property The name of the property to set.
+   * @param value The value to set.
+   */
+  setString(id: DesignBlockId, property: string, value: string): void;
+
+  /**
+   * Get the value of a string 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 of the property.
+   */
+  getString(id: DesignBlockId, property: string): string;
+
+  /**
+   * Set a color property of the given design block to the given value.
+   * @param id The block whose property should be set.
+   * @param property The name of the property to set.
+   * @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.
+   */
+  setColorRGBA(
+    id: DesignBlockId,
+    property: string,
+    r: number,
+    g: number,
+    b: number,
+    a: number
+  ): void;
+
+  /**
+   * Get the value of a string 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 A tuple of channels red, green, blue and alpha in the range of 0 to 1.
+   */
+  getColorRGBA(id: DesignBlockId, property: string): RGBA;
+
+  /**
+   * Set an enum property of the given design block to the given value.
+   * @param block The block whose property should be set.
+   * @param property The name of the property to set.
+   * @param value The enum value as string.
+   */
+  setEnum(id: DesignBlockId, property: string, value: string): void;
+
+  /**
+   * Get the value of an enum property of the given design block.
+   * @param block 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;
+
+  /**
+   * Query if the given block has crop properties.
+   * @param id The block to query.
+   * @returns true, if the block has crop properties.
+   */
+  hasCrop(id: DesignBlockId): boolean;
+
+  /**
+   * Set the crop scale in x direction of the given design block.
+   * @param id The block whose crop should be set.
+   * @param scaleX The scale in x direction.
+   */
+  setCropScaleX(id: DesignBlockId, scaleX: number): void;
+
+  /**
+   * Set the crop scale in y direction of the given design block.
+   * @param id The block whose crop should be set.
+   * @param scaleY The scale in y direction.
+   */
+  setCropScaleY(id: DesignBlockId, scaleY: number): void;
+
+  /**
+   * Set the crop rotation of the given design block.
+   * @param id The block whose crop should be set.
+   * @param rotation The rotation in radians.
+   */
+  setCropRotation(id: DesignBlockId, rotation: number): void;
+
+  /**
+   * Set the crop translation in x direction of the given design block.
+   * @param id The block whose crop should be set.
+   * @param translationY The translation in x direction.
+   */
+  setCropTranslationX(id: DesignBlockId, translationX: number): void;
+
+  /**
+   * Set the crop translation in y direction of the given design block.
+   * @param id The block whose crop should be set.
+   * @param translationY The translation in y direction.
+   */
+  setCropTranslationY(id: DesignBlockId, translationY: number): void;
+
+  /**
+   * Get the crop scale on the x axis of the given design block.
+   * @param id The block whose scale should be queried.
+   * @returns The scale on the x axis.
+   */
+  getCropScaleX(id: DesignBlockId): number;
+
+  /**
+   * Get the crop scale on the y axis of the given design block.
+   * @param id The block whose scale should be queried.
+   * @returns The scale on the y axis.
+   */
+  getCropScaleY(id: DesignBlockId): number;
+
+  /**
+   * Get the crop rotation of the given design block.
+   * @param id The block whose crop rotation should be queried.
+   * @returns The crop rotation.
+   */
+  getCropRotation(id: DesignBlockId): number;
+
+  /**
+   * Get the crop translation on the x axis of the given design block.
+   * @param id The block whose translation should be queried.
+   * @returns The translation on the x axis.
+   */
+  getCropTranslationX(id: DesignBlockId): number;
+
+  /**
+   * Get the crop translation on the y axis of the given design block.
+   * @param id The block whose translation should be queried.
+   * @returns The translation on the y axis.
+   */
+  getCropTranslationY(id: DesignBlockId): number;
+
+  /**
+   * Query if the given block has an opacity.
+   * @param id The block to query.
+   * @returns true, if the block has an opcity.
+   */
+  hasOpacity(id: DesignBlockId): boolean;
+
+  /**
+   * Set the opacity of the given design block.
+   * @param id The block whose opacity should be set.
+   * @param opacity The opacity to be set. The valid range is 0 to 1.
+   */
+  setOpacity(id: DesignBlockId, opacity: number): void;
+
+  /**
+   * Get the opacity of the given design block.
+   * @param id The block whose opacity should be queried.
+   * @returns The opacity in a range of 0 to 1.
+   */
+  getOpacity(id: DesignBlockId): number;
+
+  /**
+   * Query if the given block has fill color properties.
+   * @param id The block to query.
+   * @returns true, if the block has fill color properties.
+   */
+  hasFillColor(id: DesignBlockId): boolean;
+
+  /**
+   * Set the fill color of the given design block.
+   * @param id The block whose fill color should be set.
+   * @param color The fill color to be set, a tuple of
+   * @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.
+   */
+  setFillColorRGBA(
+    id: DesignBlockId,
+    r: number,
+    g: number,
+    b: number,
+    a: number
+  ): void;
+
+  /**
+   * Get the fill color of the given design block.
+   * @param id The block whose fill color should be queried.
+   * @returns The fill color.
+   */
+  getFillColorRGBA(id: DesignBlockId): RGBA;
+
+  /**
+   * Enable or disable the fill of the given design block.
+   * @param id The block whose fill should be enabled or disabled.
+   * @param enabled If true, the fill will be enabled.
+   */
+  setFillColorEnabled(id: DesignBlockId, enabled: boolean): void;
+
+  /**
+   * Query if the fill of the given design block is enabled.
+   * @param id The block whose fill state should be queried.
+   * @returns True, if fill is enabled.
+   */
+  isFillColorEnabled(id: DesignBlockId): boolean;
+
+  /**
+   * Query if the given block has background color properties.
+   * @param id The block to query.
+   * @returns true, if the block has background color properties.
+   */
+  hasBackgroundColor(id: DesignBlockId): boolean;
+
+  /**
+   * Set the background color of the given design block.
+   * @param id The block whose background color should be set.
+   * @param color The background color to be set, a tuple of
+   * @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.
+   */
+  setBackgroundColorRGBA(
+    id: DesignBlockId,
+    r: number,
+    g: number,
+    b: number,
+    a: number
+  ): void;
+
+  /**
+   * Get the background color of the given design block.
+   * @param id The block whose background color should be queried.
+   * @returns The background color.
+   */
+  getBackgroundColorRGBA(id: DesignBlockId): RGBA;
+
+  /**
+   * Enable or disable the background of the given design block.
+   * @param id The block whose background should be enabled or disabled.
+   * @param enabled If true, the background will be enabled.
+   */
+  setBackgroundColorEnabled(id: DesignBlockId, enabled: boolean): void;
+
+  /**
+   * Query if the background of the given design block is enabled.
+   * @param id The block whose background state should be queried.
+   * @returns True, if background is enabled.
+   */
+  isBackgroundColorEnabled(id: DesignBlockId): boolean;
+
+  /**
+   * Query if the given block has outline properties.
+   * @param id The block to query.
+   * @returns true, if the block has outline properties.
+   */
+  hasOutline(id: DesignBlockId): boolean;
+
+  /**
+   * Set the outline color of the given design block.
+   * @param id The block whose outline color should be set.
+   * @param color The outline color to be set, a tuple of
+   * @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.
+   */
+  setOutlineColorRGBA(
+    id: DesignBlockId,
+    r: number,
+    g: number,
+    b: number,
+    a: number
+  ): void;
+
+  /**
+   * Get the outline color of the given design block.
+   * @param id The block whose outline color should be queried.
+   * @returns The outline color.
+   */
+  getOutlineColorRGBA(id: DesignBlockId): RGBA;
+
+  /**
+   * Enable or disable the outline of the given design block.
+   * @param id The block whose outline should be enabled or disabled.
+   * @param enabled If true, the outline will be enabled.
+   */
+  setOutlineEnabled(id: DesignBlockId, enabled: boolean): void;
+
+  /**
+   * Query if the outline of the given design block is enabled.
+   * @param id The block whose outline state should be queried.
+   * @returns True, if outline is enabled.
+   */
+  isOutlineEnabled(id: DesignBlockId): boolean;
+
+  /**
+   * Set the outline width of the given design block.
+   * @param id The block whose outline width should be set.
+   * @param width The outline width to be set.
+   */
+  setOutlineWidth(id: DesignBlockId, width: number): void;
+
+  /**
+   * Get the outline width of the given design block.
+   * @param id The block whose outline width should be queried.
+   * @returns The outline width.
+   */
+  getOutlineWidth(id: DesignBlockId): number;
+}

package/SceneAPI.d.ts

@@ -6,7 +6,7 @@ export default class SceneAPI {
    * @param sceneContent The scene file contents, a base64 string.
    * @returns A handle to the loaded scene.
    */
-  loadFromString(sceneContent: string): DesignBlockId;
+  loadFromString(sceneContent: string): Promise<DesignBlockId>;
 
   /**
    * Load a scene from the URL to the scene file.

package/VariableAPI.d.ts

@@ -6,16 +6,22 @@ export default class VariableAPI {
   findAll(): string[];
 
   /**
-   * Set a text variable.
+   * Set a text variable to a string value.
    * @param key The variable's key.
    * @param value The text to replace the variable with.
    */
-  set(key: string, value: string): void;
+  setString(key: string, value: string): void;
 
   /**
-   * Set a text variable.
+   * Set a text variable to a string value.
    * @param key The variable's key.
    * @returns  The text value of the variable.
    */
-  get(key: string): string;
+  getString(key: string): string;
+
+  /**
+   * Remove a text variable.
+   * @param key The variable's key.
+   */
+  remove(key: string): void;
 }

package/api.d.ts

@@ -1,5 +1,6 @@
 import BlockAPI from './BlockAPI';
 import SceneAPI from './SceneAPI';
+import PropertyAPI from './PropertyAPI';
 import VariableAPI from './VariableAPI';
 
 export default class API {
@@ -7,5 +8,7 @@ export default class API {
 
   scene: SceneAPI;
 
+  property: PropertyAPI;
+
   variable: VariableAPI;
 }