Layout

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine to modify scenes layout through the block API.

Setup#

This example uses the headless CreativeEngine. See the Setup article for a detailed guide. To get started right away, you can also access the block API within a running CE.SDK instance via cesdk.engine.block. Check out the APIs Overview to see that illustrated in more detail.

Layout of Blocks#

Note on layout and frame size#

The frame size is determined during the layout phase of the render process inside the engine. This means that calling getFrameSize() immediately after modifying the scene might return an inaccurate result.

The CreativeEngine supports three different modes for positioning blocks. These can be set for each block and both coordinates independently:

'Absolute': the position value is interpreted in the scene's current design unit.
'Percent': the position value is interpreted as percentage of the block's parent's size, where 1.0 means 100%.
'Auto' : the position is automatically determined.

Likewise there are also three different modes for controlling a block's size. Again both dimensions can be set independently:

'Absolute': the size value is interpreted in the scene's current design unit.
'Percent': the size value is interpreted as percentage of the block's parent's size, where 1.0 means 100%.
'Auto' : the block's size is automatically determined by the size of the block's content.

Positioning#

JavaScript


getPositionX(id: DesignBlockId): number

Query a block's x position.

id: The block to query.
Returns The value of the x position.

JavaScript


getPositionY(id: DesignBlockId): number

Query a block's y position.

id: The block to query.
Returns The value of the y position.

JavaScript


getPositionXMode(id: DesignBlockId): PositionMode

Query a block's mode for its x position.

id: The block to query.
Returns The current mode for the x position: absolute, percent or undefined.

JavaScript


getPositionYMode(id: DesignBlockId): PositionMode

Query a block's mode for its y position.

id: The block to query.
Returns The current mode for the y position: absolute, percent or undefined.

JavaScript


setPositionX(id: DesignBlockId, value: number): void

Update a block's x position. The position refers to the block's local space, relative to its parent with the origin at the top left. Required scope: 'layer/move'

id: The block to update.
value: The value of the x position.

JavaScript


setPositionY(id: DesignBlockId, value: number): void

Update a block's y position. The position refers to the block's local space, relative to its parent with the origin at the top left. Required scope: 'layer/move'

id: The block to update.
value: The value of the y position.

JavaScript


setPositionXMode(id: DesignBlockId, mode: PositionMode): void

Set a block's mode for its x position. Required scope: 'layer/move'

id: The block to update.
mode: The x position mode: absolute, percent or undefined.

JavaScript


setPositionYMode(id: DesignBlockId, mode: PositionMode): void

Set a block's mode for its y position. Required scope: 'layer/move'

id: The block to update.
mode: The y position mode: absolute, percent or undefined.

TypeScript


type PositionMode = 'Absolute' | 'Percent' | 'Auto'

Absolute: Position in absolute design units. - Percent: Position in relation to the block's parent's size in percent, where 1.0 means 100%. - Auto: Position is automatically determined

Size#

JavaScript


getWidth(id: DesignBlockId): number

Query a block's width.

id: The block to query.
Returns The value of the block's width.

JavaScript


getWidthMode(id: DesignBlockId): SizeMode

Query a block's mode for its width.

id: The block to query.
Returns The current mode for the width: absolute, percent or auto.

JavaScript


getHeight(id: DesignBlockId): number

Query a block's height.

id: The block to query.
Returns The value of the block's height.

JavaScript


getHeightMode(id: DesignBlockId): SizeMode

Query a block's mode for its height.

id: The block to query.
Returns The current mode for the height: absolute, percent or auto.

JavaScript


setWidth(id: DesignBlockId, value: number, maintainCrop?: boolean): void

Update a block's width and optionally maintain the crop. Required scope: 'layer/resize'

id: The block to update.
value: The new width of the block.
maintainCrop: Whether or not the crop values, if available, should be automatically adjusted.

JavaScript


setWidthMode(id: DesignBlockId, mode: SizeMode): void

Set a block's mode for its width. Required scope: 'layer/resize'

id: The block to update.
mode: The width mode: Absolute, Percent or Auto.

JavaScript


setHeight(id: DesignBlockId, value: number, maintainCrop?: boolean): void

Update a block's height and optionally maintain the crop. Required scope: 'layer/resize'

id: The block to update.
value: The new height of the block.
maintainCrop: Whether or not the crop values, if available, should be automatically adjusted.

JavaScript


setHeightMode(id: DesignBlockId, mode: SizeMode): void

Set a block's mode for its height. Required scope: 'layer/resize'

id: The block to update.
mode: The height mode: Absolute, Percent or Auto.

TypeScript


type SizeMode = 'Absolute' | 'Percent' | 'Auto'

Absolute: Size in absolute design units. - Percent: Size in relation to the block's parent's size in percent, where 1.0 means 100%. - Auto: Size is automatically determined

Layers#

JavaScript


setAlwaysOnTop(id: DesignBlockId, enabled: boolean): void

Update the block's always-on-top property. If true, this blocks's global sorting order is automatically adjusted to be higher than all other siblings without this property. If more than one block is set to be always-on-top, the child order decides which is on top.

id: the block to update.
enabled: whether the block shall be always-on-top.

JavaScript


isAlwaysOnTop(id: DesignBlockId): boolean

Query a block's always-on-top property.

id: the block to query.
Returns true if the block is set to be always-on-top, false otherwise.

JavaScript


setAlwaysOnBottom(id: DesignBlockId, enabled: boolean): void

Update the block's always-on-bottom property. If true, this blocks's global sorting order is automatically adjusted to be lower than all other siblings without this property. If more than one block is set to be always-on-bottom, the child order decides which is on bottom.

id: the block to update.
enabled: whether the block shall always be below its siblings.

JavaScript


isAlwaysOnBottom(id: DesignBlockId): boolean

Query a block's always-on-bottom property.

id: the block to query.
Returns true if the block is set to be always-on-bottom, false otherwise.

JavaScript


bringToFront(id: DesignBlockId): void

Updates the sorting order of this block and all of its manually created siblings so that the given block has the highest sorting order.

id: The id of the block to be given the highest sorting order among its siblings.

JavaScript


sendToBack(id: DesignBlockId): void

Updates the sorting order of this block and all of its manually created siblings so that the given block has the lowest sorting order.

id: The id of the block to be given the lowest sorting order among its siblings.

JavaScript


bringForward(id: DesignBlockId): void

Updates the sorting order of this block and all of its superjacent siblings so that the given block has a higher sorting order than the next superjacent sibling.

id: The id of the block to be given a higher sorting than the next superjacent sibling.

JavaScript


sendBackward(id: DesignBlockId): void

Updates the sorting order of this block and all of its manually created and subjacent siblings so that the given block will have a lower sorting order than the next subjacent sibling.

id: The id of the block to be given a lower sorting order than the next subjacent sibling.

Rotation#

JavaScript


getRotation(id: DesignBlockId): number

Query a block's rotation in radians.

id: The block to query.
Returns The block's rotation around its center in radians.

JavaScript


setRotation(id: DesignBlockId, radians: number): void

Update a block's rotation. Required scope: 'layer/rotate'

id: The block to update.
radians: The new rotation in radians. Rotation is applied around the block's center.

Flipping#

JavaScript


getFlipHorizontal(id: DesignBlockId): boolean

Query a block's horizontal flip state.

id: The block to query.
Returns A boolean indicating for whether the block is flipped in the queried direction

JavaScript


getFlipVertical(id: DesignBlockId): boolean

Query a block's vertical flip state.

id: The block to query.
Returns A boolean indicating for whether the block is flipped in the queried direction

JavaScript


setFlipHorizontal(id: DesignBlockId, flip: boolean): void

Update a block's horizontal flip. Required scope: 'layer/flip'

id: The block to update.
flip: If the flip should be enabled.

JavaScript


setFlipVertical(id: DesignBlockId, flip: boolean): void

Update a block's vertical flip. Required scope: 'layer/flip'

id: The block to update.
flip: If the flip should be enabled.

Scaling#

JavaScript


scale(id: DesignBlockId, scale: number, anchorX?: number, anchorY?: number): void

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. Required scope: 'layer/resize'

id: The block that should be scaled.
scale: The scale factor to be applied to the current properties of the block.
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)
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)

Fill a Block's Parent#

JavaScript


fillParent(id: DesignBlockId): void

Resize and position a block to entirely fill its parent block. Required scope: 'layer/move' - 'layer/resize'

id: The block that should fill its parent.

Resize Blocks Content-aware#

JavaScript


resizeContentAware(ids: DesignBlockId[], width: number, height: number): void

Resize all blocks to the given size. The content of the blocks is automatically adjusted to fit the new dimensions. Required scope: 'layer/resize'

ids: The blocks to resize.
width: The new width of the blocks.
height: The new height of the blocks.

Even Distribution#

Multiple blocks can be distributed horizontally or vertically within their bounding box. The blocks are moved to have the remaining space divided evenly between the blocks. Blocks without a position and blocks that are not allowed to be moved will not be distributed.

JavaScript


isDistributable(ids: DesignBlockId[]): boolean

Confirms that a given set of blocks can be distributed.

ids: An array of block ids.
Returns Whether the blocks can be distributed.

JavaScript


distributeHorizontally(ids: DesignBlockId[]): void

Distribute multiple blocks horizontally within their bounding box so that the space between them is even. Required scope: 'layer/move'

ids: A non-empty array of block ids.

JavaScript


distributeVertically(ids: DesignBlockId[]): void

Distribute multiple blocks vertically within their bounding box so that the space between them is even. Required scope: 'layer/move'

ids: A non-empty array of block ids.

Alignment#

Multiple blocks can be aligned horizontally or vertically within their bounding box. When a group is given, the elements within the group are aligned. If a single block is given, it gets aligned within its parent. Blocks without a position and blocks that are not allowed to be moved will not be aligned.

JavaScript


isAlignable(ids: DesignBlockId[]): boolean

Confirms that a given set of blocks can be aligned.

ids: An array of block ids.
Returns Whether the blocks can be aligned.

JavaScript


alignHorizontally(ids: DesignBlockId[], horizontalBlockAlignment: HorizontalBlockAlignment): void

Align multiple blocks horizontally within their bounding box or a single block to its parent. Required scope: 'layer/move'

ids: A non-empty array of block ids.
alignment: How they should be aligned: left, right, or center

JavaScript


alignVertically(ids: DesignBlockId[], verticalBlockAlignment: VerticalBlockAlignment): void

Align multiple blocks vertically within their bounding box or a single block to its parent. Required scope: 'layer/move'

ids: A non-empty array of block ids.
alignment: How they should be aligned: top, bottom, or center

Computed Dimensions#

JavaScript


getFrameX(id: DesignBlockId): number

Get a block's layout position on the x-axis. The position is only available after an internal update loop which only occurs if the features/implicitUpdatesEnabled setting is set.

id: The block to query.
Returns The layout position on the x-axis.

JavaScript


getFrameY(id: DesignBlockId): number

Get a block's layout position on the y-axis. The position is only available after an internal update loop which only occurs if the features/implicitUpdatesEnabled setting is set.

id: The block to query.
Returns The layout position on the y-axis.

JavaScript


getFrameWidth(id: DesignBlockId): number

Get a block's layout width. The width is only available after an internal update loop which only occurs if the features/implicitUpdatesEnabled setting is set.

id: The block to query.
Returns The layout width.

JavaScript


getFrameHeight(id: DesignBlockId): number

Get a block's layout height. The height is only available after an internal update loop which only occurs if the features/implicitUpdatesEnabled setting is set.

id: The block to query.
Returns The layout height.

JavaScript


getGlobalBoundingBoxX(id: DesignBlockId): number

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 origin at the top left.

id: The block whose bounding box should be calculated.
Returns float The x coordinate of the position of the axis-aligned bounding box.

JavaScript


getGlobalBoundingBoxY(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 origin at the top left.

id: The block whose bounding box should be calculated.
Returns float The y coordinate of the position of the axis-aligned bounding box.

JavaScript


getGlobalBoundingBoxWidth(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 origin at the top left.

id: The block whose bounding box should be calculated.
Returns float The width of the axis-aligned bounding box.

JavaScript


getGlobalBoundingBoxHeight(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 origin at the top left.

id: The block whose bounding box should be calculated.
Returns float The height of the axis-aligned bounding box.

JavaScript


getScreenSpaceBoundingBoxXYWH(ids: DesignBlockId[]): XYWH

Get the position and size of the axis-aligned bounding box for the given blocks in screen space.

ids: The block to query.
Returns The position and size of the bounding box.

Transform Locking#

You can lock the transform of a block to prevent changes to any of its transformations. That is the block's position, rotation, scale, and sizing.

JavaScript


isTransformLocked(id: DesignBlockId): boolean

Query a block's transform locked state. If true, the block's transform can't be changed.

id: The block to query.
Returns True if transform locked, false otherwise.

JavaScript


setTransformLocked(id: DesignBlockId, locked: boolean): void

Update a block's transform locked state.

id: The block to update.
locked: Whether the block's transform should be locked.


const x = engine.block.getPositionX(block);
const xMode = engine.block.getPositionXMode(block);
const y = engine.block.getPositionY(block);
const yMode = engine.block.getPositionYMode(block);
engine.block.setPositionX(block, 0.25);
engine.block.setPositionXMode(block, 'Percent');
engine.block.setPositionY(block, 0.25);
engine.block.setPositionYMode(block, 'Percent');

const rad = engine.block.getRotation(block);
engine.block.setRotation(block, Math.PI / 2);

const flipHorizontal = engine.block.getFlipHorizontal(block);
const flipVertical = engine.block.getFlipVertical(block);
engine.block.setFlipHorizontal(block, true);
engine.block.setFlipVertical(block, false);

const width = engine.block.getWidth(block);
const widthMode = engine.block.getWidthMode(block);
const height = engine.block.getHeight(block);
const heightMode = engine.block.getHeightMode(block);
engine.block.setWidth(block, 0.5);
engine.block.setWidth(block, 2.5, true);
engine.block.setWidthMode(block, 'Percent');
engine.block.setHeight(block, 0.5);
engine.block.setHeight(block, 2.5, true);
engine.block.setHeightMode(block, 'Percent');
const frameX = engine.block.getFrameX(block);
const frameY = engine.block.getFrameY(block);
const frameWidth = engine.block.getFrameWidth(block);
const frameHeight = engine.block.getFrameHeight(block);

engine.block.setAlwaysOnTop(block, false)
val isAlwaysOnTop = engine.block.isAlwaysOnTop(block)
engine.block.setAlwaysOnBottom(block, false)
val isAlwaysOnBottom = engine.block.isAlwaysOnBottom(block)
engine.block.bringToFront(block)
engine.block.sendToBack(block)
engine.block.bringForward(block)
engine.block.sendBackward(block)

const globalX = engine.block.getGlobalBoundingBoxX(block);
const globalY = engine.block.getGlobalBoundingBoxY(block);
const globalWidth = engine.block.getGlobalBoundingBoxWidth(block);
const globalHeight = engine.block.getGlobalBoundingBoxHeight(block);
const screenSpaceRect = engine.block.getScreenSpaceBoundingBoxXYWH([block]);

engine.block.scale(block, 2.0, 0.5, 0.5);

engine.block.fillParent(block);

const pages = engine.scene.getPages();
engine.block.resizeContentAware(pages, width: 100.0, 100.0);

// Create blocks and append to page
const member1 = engine.block.create('graphic');
const member2 = engine.block.create('graphic');
engine.block.appendChild(page, member1);
engine.block.appendChild(page, member2);
const distributable = engine.block.isDistributable([member1, member2]);
if (distributable) {
  engine.block.distributeHorizontally([member1, member2], "Left");
  engine.block.distributeVertically([member1, member2], "Top");
}
const alignable = engine.block.isAlignable([member1, member2]);
if (alignable) {
  engine.block.alignHorizontally([member1, member2], "Left");
  engine.block.alignVertically([member1, member2], "Top");
}

const isTransformLocked = engine.block.isTransformLocked(block);
if (!isTransformLocked) {
  engine.block.setTransformLocked(block, true);
}