@cesdk/engine 1.7.0-alpha.5 → 1.8.0-alpha.0

package/index.d.ts

@@ -77,6 +77,8 @@ export declare class AssetAPI {
         url: string | undefined;
     } | undefined;
     canManageAssets(sourceId: string): boolean;
+
+
     /**
      * Apply an asset result to the active scene.
      * The default behavior will instantiate a block and configure it according to the asset's properties.
@@ -85,6 +87,12 @@ export declare class AssetAPI {
      * @param assetResult - A single assetResult of a `findAssets` query.
      */
     apply(sourceId: string, assetResult: AssetResult): Promise<void>;
+    /**
+     * The default implementation for applying an asset to the scene.
+     * 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>;
 }
 
 /**
@@ -221,7 +229,7 @@ export declare interface AssetSource {
     /** Find all asset for the given type and the provided query data.  */
     findAssets(queryData: AssetQueryData): Promise<AssetsQueryResult>;
     /** Return every available group */
-    getGroups: () => Promise<string[]>;
+    getGroups?: () => Promise<string[]>;
     /** Credits for the source/api */
     credits?: {
         name: string;
@@ -243,7 +251,7 @@ export declare interface AssetSource {
     /**
      * @returns the asset or undefined if no asset with the given id could be found
      */
-    getAsset(id: string): Promise<AssetResult | undefined>;
+    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
@@ -261,20 +269,20 @@ export declare interface AssetSource {
      *
      * @returns the id of the added asset
      */
-    addAsset(asset: AssetDefinition): Promise<string>;
+    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>;
+    updateAsset?(assetId: string, asset: AssetDefinition): Promise<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): Promise<boolean>;
 }
 
 /**
@@ -289,6 +297,8 @@ declare interface AssetSource_2 {
      * You can override this with custom behavior.
      */
     applyAsset?: (asset: AssetResult_2) => Promise<void>;
+    /** Return every available group */
+    getGroups?: () => Promise<string[]>;
     /**
      * Indicates if the asset shall be downloaded to handle the raw data instead
      * of an URL reference. Do this if you do not want to depend on
@@ -349,9 +359,6 @@ declare interface AssetsQueryResult_2 {
  */
 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;
-
 /**
  * @public
  */
@@ -388,6 +395,12 @@ export declare class BlockAPI {
      * @returns The created blocks handle.
      */
     create(type: DesignBlockType): DesignBlockId;
+    /**
+     * Create a new fill, fails if type is unknown.
+     * @param type - The type of the fill object that shall be created.
+     * @returns The created fill's handle.
+     */
+    createFill(type: string): DesignBlockId;
 
     /**
      * Get the type of the given block, fails if the block is invalid.
@@ -592,12 +605,6 @@ export declare class BlockAPI {
      * @returns true, if the block has a content fill mode.
      */
     hasContentFillMode(id: DesignBlockId): boolean;
-    /**
-     * Query if the given block shows placeholder content.
-     * @param id - The block to query.
-     * @returns true, if the block shows placeholder content.
-     */
-    hasPlaceholderContent(id: DesignBlockId): boolean;
     /**
      * Query a block's width.
      * @param id - The block to query.
@@ -894,6 +901,12 @@ export declare class BlockAPI {
      * @param rotation - The rotation in radians.
      */
     setCropRotation(id: DesignBlockId, rotation: number): void;
+    /**
+     * Set the crop scale ratio of the given design block.
+     * @param id - The block whose crop should be set.
+     * @param scaleRatio - The crop scale ratio.
+     */
+    setCropScaleRatio(id: DesignBlockId, scaleRatio: number): void;
     /**
      * Set the crop translation in x direction of the given design block.
      * @param id - The block whose crop should be set.
@@ -930,6 +943,12 @@ export declare class BlockAPI {
      * @returns The crop rotation.
      */
     getCropRotation(id: DesignBlockId): number;
+    /**
+     * Get the crop scale ratio of the given design block.
+     * @param id - The block whose crop scale ratio should be queried.
+     * @returns The crop scale ratio.
+     */
+    getCropScaleRatio(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.
@@ -942,6 +961,12 @@ export declare class BlockAPI {
      * @returns The translation on the y axis.
      */
     getCropTranslationY(id: DesignBlockId): number;
+    /**
+     * Adjust the crop position/scale to at least fill the crop frame.
+     * @param id - The block whose crop scale ratio should be queried.
+     * @param minScaleRatio - The minimal crop scale ratio to go down to.
+     */
+    adjustCropToFillFrame(id: DesignBlockId, minScaleRatio: number): number;
     /**
      * Query if the given block has an opacity.
      * @param id - The block to query.
@@ -1013,6 +1038,99 @@ export declare class BlockAPI {
      * @returns True, if fill is enabled.
      */
     isFillColorEnabled(id: DesignBlockId): boolean;
+    /**
+     * Create a new effect block, fails if type is unknown or not a valid effect block type.
+     * @param type - The type id of the effect.
+     * @returns The created effects handle.
+     */
+    createEffect(type: string): DesignBlockId;
+    /**
+     * Queries whether the block supports effects.
+     * @param id - The block to query.
+     * @returns True, if the block can render effects, false otherwise.
+     */
+    hasEffects(id: DesignBlockId): boolean;
+    /**
+     * Get a list of all effects attached to this block
+     * @param id - The block to query.
+     * @returns A list of effects or an error, if the block doesn't support effects.
+     */
+    getEffects(id: DesignBlockId): DesignBlockId[];
+    /**
+     * Inserts an effect at the given index into the list of effects of the given block.
+     * The same effect can appear multiple times in the list and won't be removed if appended again.
+     * @param id - The block to update.
+     * @param effectId - The effect to insert
+     * @param index - The index at which the effect shall be inserted.
+     */
+    insertEffect(id: DesignBlockId, effectId: DesignBlockId, index: number): void;
+    /**
+     * Inserts an effect at the end of the list of effects
+     * The same effect can appear multiple times in the list and won't be removed if appended again.
+     * @param id - The block to append the effect to.
+     * @param effectId - The effect to append.
+     */
+    appendEffect(id: DesignBlockId, effectId: DesignBlockId): void;
+    /**
+     * Removes the effect at the given index.
+     * @param id - The block to remove the effect from.
+     * @param index - The index where the effect is stored.
+     */
+    removeEffect(id: DesignBlockId, index: number): void;
+    /**
+     * Checks whether an 'effect' block may be enabled and disabled.
+     * @param effectId - The 'effect' block to query.
+     * @returns True, if the block supports enabling and disabling, false otherwise.
+     */
+    hasEffectEnabled(effectId: DesignBlockId): boolean;
+    /**
+     * Sets the enabled state of an 'effect' block.
+     * @param effectId - The 'effect' block to update.
+     * @param enabled - The new state.
+     */
+    setEffectEnabled(effectId: DesignBlockId, enabled: boolean): void;
+    /**
+     * Queries whether an 'effect' block is enabled and therefore applies its effect.
+     * @param effectId - The 'effect' block to query.
+     * @returns True, if the effect is enabled. False otherwise.
+     */
+    isEffectEnabled(effectId: DesignBlockId): boolean;
+    /**
+     * Create a new blur, fails if type is unknown or not a valid blur type.
+     * @param type - The type id of the block.
+     * @returns The handle of the newly created blur.
+     */
+    createBlur(type: string): DesignBlockId;
+    /**
+     * Checks whether the block supports blur.
+     * @param id - The block to query.
+     * @returns True, if the block supports blur.
+     */
+    hasBlur(id: DesignBlockId): boolean;
+    /**
+     * Connects `block`'s blur to the given `blur` block.
+     * @param id - The block to update.
+     * @param blurId - A 'blur' block.
+     */
+    setBlur(id: DesignBlockId, blurId: DesignBlockId): void;
+    /**
+     * Get the 'blur' block of the given design block.
+     * @param id - The block to query.
+     * @returns The 'blur' block.
+     */
+    getBlur(id: DesignBlockId): DesignBlockId;
+    /**
+     * Enable or disable the blur of the given design block.
+     * @param id - The block to update.
+     * @param enabled - The new enabled value.
+     */
+    setBlurEnabled(id: DesignBlockId, enabled: boolean): void;
+    /**
+     * Query if blur is enabled for the given block.
+     * @param id - The block to query.
+     * @returns True, if the blur is enabled. False otherwise.
+     */
+    isBlurEnabled(id: DesignBlockId): boolean;
     /**
      * Query if the given block has background color properties.
      * @param id - The block to query.
@@ -1218,51 +1336,51 @@ export declare class BlockAPI {
     /**
      * Set the drop shadow's X offset of the given design block.
      * @param id - The block whose drop shadow's X offset should be set.
-     * @param xOffset - The X offset to be set.
+     * @param offsetX - The X offset to be set.
      */
-    setDropShadowXOffset(id: DesignBlockId, xOffset: number): void;
+    setDropShadowOffsetX(id: DesignBlockId, offsetX: number): void;
     /**
      * Get the drop shadow's X offset of the given design block.
      * @param id - The block whose drop shadow's X offset should be queried.
      * @returns The offset.
      */
-    getDropShadowXOffset(id: DesignBlockId): number;
+    getDropShadowOffsetX(id: DesignBlockId): number;
     /**
      * Set the drop shadow's Y offset of the given design block.
      * @param id - The block whose drop shadow's Y offset should be set.
-     * @param yOffset - The X offset to be set.
+     * @param offsetY - The X offset to be set.
      */
-    setDropShadowYOffset(id: DesignBlockId, yOffset: number): void;
+    setDropShadowOffsetY(id: DesignBlockId, offsetY: number): void;
     /**
      * Get the drop shadow's Y offset of the given design block.
      * @param id - The block whose drop shadow's Y offset should be queried.
      * @returns The offset.
      */
-    getDropShadowYOffset(id: DesignBlockId): number;
+    getDropShadowOffsetY(id: DesignBlockId): number;
     /**
      * Set the drop shadow's blur radius on the X axis of the given design block.
      * @param id - The block whose drop shadow's blur radius should be set.
-     * @param xBlurRadius - The blur radius to be set.
+     * @param blurRadiusX - The blur radius to be set.
      */
-    setDropShadowXBlurRadius(id: DesignBlockId, xBlurRadius: number): void;
+    setDropShadowBlurRadiusX(id: DesignBlockId, blurRadiusX: number): void;
     /**
      * Get the drop shadow's blur radius on the X axis of the given design block.
      * @param id - The block whose drop shadow's blur radius should be queried.
      * @returns The blur radius.
      */
-    getDropShadowXBlurRadius(id: DesignBlockId): number;
+    getDropShadowBlurRadiusX(id: DesignBlockId): number;
     /**
      * Set the drop shadow's blur radius on the Y axis of the given design block.
      * @param id - The block whose drop shadow's blur radius should be set.
-     * @param yBlurRadius - The blur radius to be set.
+     * @param blurRadiusY - The blur radius to be set.
      */
-    setDropShadowYBlurRadius(id: DesignBlockId, yBlurRadius: number): void;
+    setDropShadowBlurRadiusY(id: DesignBlockId, blurRadiusY: number): void;
     /**
      * Get the drop shadow's blur radius on the Y axis of the given design block.
      * @param id - The block whose drop shadow's blur radius should be queried.
      * @returns The blur radius.
      */
-    getDropShadowYBlurRadius(id: DesignBlockId): number;
+    getDropShadowBlurRadiusY(id: DesignBlockId): number;
     /**
      * Set the drop shadow's clipping of the given design block. (Only applies to shapes.)
      * @param id - The block whose drop shadow's clip should be set.
@@ -1300,6 +1418,13 @@ export declare class BlockAPI {
      * @returns The block that currently defines the given block's fill.
      */
     getFill(id: DesignBlockId): DesignBlockId;
+    /**
+     * Sets the block containing the fill properties of the given block.
+     * Note that the previous fill block is not destroyed automatically.
+     * @param id - The block whose fill should be changed.
+     * @param fill - The new fill.
+     */
+    setFill(id: DesignBlockId, fill: DesignBlockId): void;
     /**
      * Set the fill type of the given design block.
      * @param id - The block whose fill type should be set.
@@ -1412,10 +1537,28 @@ export declare class BlockAPI {
      * @returns the gradient's radius, an error otherwise.
      */
     getFillGradientRadius(id: DesignBlockId): number;
+    /**
+     * Enable or disable the placeholder function for a block.
+     * @param id - The block whose placeholder function should be enabled or disabled.
+     * @param enabled - Whether the function should be enabled or disabled.
+     */
+    setPlaceholderEnabled(id: DesignBlockId, enabled: boolean): void;
+    /**
+     * Query whether the placeholder function for a block is enabled.
+     * @param id - The block whose placeholder function state should be queried.
+     * @returns the enabled state of the placeholder function.
+     */
+    isPlaceholderEnabled(id: DesignBlockId): boolean;
+    /**
+     * Query if the given block shows placeholder content.
+     * @param id - The block to query.
+     * @returns true, if the block shows placeholder content.
+     */
+    showsPlaceholderContent(id: DesignBlockId): boolean;
     /**
      * Set a metadata value of a block identified by a key.
      * If the key does not exist, yet, it will be added.
-     * @param block - The block whose metadata will be accessed.
+     * @param id - The block whose metadata will be accessed.
      * @param key - The key used to identify the desired piece of metadata.
      * @param value - The value to set.
      */
@@ -1423,14 +1566,14 @@ export declare class BlockAPI {
     /**
      * Get a metadata value of a block identified by a key.
      * If the key does not exist, yet, this method will fail.
-     * @param block - The block whose metadata will be accessed.
+     * @param id - The block whose metadata will be accessed.
      * @param key - The key used to identify the desired piece of metadata.
      * @returns the value associated with the key.
      */
     getMetadata(id: DesignBlockId, key: string): string;
     /**
      * Check if the block has metadata associated with the key.
-     * @param block - The block whose metadata will be accessed.
+     * @param id - The block whose metadata will be accessed.
      * @param key - The key used to identify the desired piece of metadata.
      * @returns whether the key exists.
      */
@@ -1438,23 +1581,36 @@ export declare class BlockAPI {
     /**
      * Remove metadata associated with the key from the given block.
      * If the key does not exist, this method will fail.
-     * @param block - The block whose metadata will be accessed.
+     * @param id - The block whose metadata will be accessed.
      * @param key - The key used to identify the desired piece of metadata.
      */
     removeMetadata(id: DesignBlockId, key: string): void;
+    /**
+     * Enable or disable a scope for a given block.
+     * @param id - The block whose scope should be enabled or disabled.
+     * @param key - The scope to enable or disable.
+     * @param enabled - Whether the scope should be enabled or disabled.
+     */
+    setScopeEnabled(id: DesignBlockId, key: string, enabled: boolean): void;
+    /**
+     * Query whether a scope is enabled for a given block.
+     * @param id - The block whose scope state should be queried.
+     * @param key - The scope to query.
+     * @returns the enabled state of the scope for the given block.
+     */
+    isScopeEnabled(id: DesignBlockId, key: string): boolean;
+    /**
+     * Check if a scope is allowed for a given block.
+     * @param id - The block to check.
+     * @param key - The scope to check.
+     * @returns whether the scope is allowed for the given block.
+     */
+    isAllowedByScope(id: DesignBlockId, key: string): boolean;
 }
 
-/**
- * @public
- */
-export declare type BlockEvent = {
-    block: DesignBlockId;
-    type: 'Created' | 'Updated' | 'Destroyed';
-};
-
 /** @public */
-declare interface BlockEvent_2 {
-    block: Block;
+export declare interface BlockEvent {
+    block: DesignBlockId;
     type: 'Created' | 'Updated' | 'Destroyed';
 }
 
@@ -1600,6 +1756,19 @@ declare class CreativeEngine {
 }
 export default CreativeEngine;
 
+/**
+ * Dispatched on the engine canvas when the text input has been blurred.
+ * Call `preventDefault()` to disallow this and refocus the engine text input.
+ * @public
+ */
+export declare interface CursorEvent extends CustomEvent<string> {
+    readonly type: 'cesdk-cursor';
+    /** Contains the cursor style */
+    readonly detail: string;
+    /** If default is prevented, the Creative Engine won't apply the cursor style to itself. */
+    preventDefault(): void;
+}
+
 /**
  * A numerical identifier for a design block
  * @public
@@ -1792,6 +1961,13 @@ export declare class EditorAPI {
      * @param resolver - Custom resolution function.
      */
     setURIResolver(resolver: (URI: string) => string): void;
+    /**
+     * This is the default implementation for the URI resolver.
+     * It resolves the given path relative to the `ubq://basePath` setting.
+     * @param relativePath - The relative path that should be resolved.
+     * @returns The resolved absolute URI.
+     */
+    defaultURIResolver(relativePath: string): string;
     /**
      * Resolves the given path.
      * If a custom resolver has been set with `setURIResolver`, it invokes it with the given path.
@@ -1801,6 +1977,18 @@ export declare class EditorAPI {
      * @returns The resolved absolute uri or an error if an invalid path was given.
      */
     getAbsoluteURI(relativePath: string): string;
+    /**
+     * Set a scope to be globally allowed, denied, or deferred to the block-level.
+     * @param key - The scope to set.
+     * @param value - `Allow` will always allow the scope, `Deny` will always deny the scope, and `Defer` will defer to the block-level.
+     */
+    setGlobalScope(key: string, value: 'Allow' | 'Deny' | 'Defer'): void;
+    /**
+     * Query the state of a global scope.
+     * @param key - The scope to query.
+     * @returns `Allow` if the scope is allowed, `Deny` if it is disallowed, and `Defer` if it is deferred to the block-level.
+     */
+    getGlobalScope(key: string): 'Allow' | 'Deny' | 'Defer';
 }
 
 /**
@@ -1852,6 +2040,12 @@ export declare type ExportOptions = {
      * size entirely while maintaining its aspect ratio.
      */
     targetHeight?: number;
+    /**
+     * Export the PDF document with a higher compatibility to different PDF viewers.
+     * Bitmap images and some effects like gradients will be rasterized with the DPI
+     * setting instead of embedding them directly.
+     */
+    exportPdfWithHighCompatibility?: boolean;
 };
 
 /** @public */
@@ -1861,6 +2055,7 @@ declare interface ExportOptions_2 {
     useTargetSize: boolean;
     targetWidth: number;
     targetHeight: number;
+    exportPdfWithHighCompatibility: boolean;
 }
 
 /** @public */
@@ -2011,6 +2206,7 @@ declare type PageFormatDefinition = Preset & {
     unit: DesignUnit;
     dpi?: number;
     bleedMargin?: number;
+    fixedOrientation?: boolean;
 };
 
 /**