Skip to main content
Contact SalesFree Trial
Contact SalesFree Trial
Platform:
Language:

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#

  • getPositionX(id: number): number returns the x position of a block.
  • getPositionXMode(id: number): 'Absolute' | 'Percent' | 'Auto' returns the current mode for the x position.
  • getPositionY(id: number): number returns the y position of a block.
  • getPositionYMode(id: number): 'Absolute' | 'Percent' | 'Auto' returns the current mode for the y position.
  • setPositionX(id: number, value: number): void sets the x position value of a block. The position refers to the block's local space, relative to its parent with the origin at the top left.
  • setPositionXMode(id: number, mode: 'Absolute' | 'Percent' | 'Auto'): void sets the x position mode of a block.
  • setPositionY(id: number, value: number): void sets the y position value of a block. The position refers to the block's local space, relative to its parent with the origin at the top left.
  • setPositionYMode(id: number, mode: 'Absolute' | 'Percent' | 'Auto'): void sets the y position mode of a block.

Size#

  • getWidth(id:number): number returns the block's width value.
  • getWidthMode(id:number): 'Absolute' | 'Percent' | 'Auto' returns the block's width mode.
  • getHeight(id:number): number returns the block's height value.
  • getHeightMode(id:number): 'Absolute' | 'Percent' | 'Auto' returns the block's height mode.
  • setWidth(id: number, value: number): void sets a block's width value.
  • setWidthMode(id: number, mode: 'Absolute' | 'Percent' | 'Auto') sets a block's width mode.
  • setHeight(id: number, value: number): void sets a block's height value.
  • setHeightMode(id: number, mode: 'Absolute' | 'Percent' | 'Auto'): void sets a block's height mode.

Layers#

  • setAlwaysOnTop(id:number, enabled:bool) 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.
  • isAlwaysOnTop(block: DesignBlock): Bool If a block is set to be always-on-top.
  • bringToFront(block: DesignBlock) Updates the sorting order of this block and all of its manually created siblings so that the given block has the highest sorting order.

sendToBack(block: DesignBlock) Updates the sorting order of this block and all of its manually created siblings so that the given block has the lowest sorting order.

bringForward(block: DesignBlock) 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.

sendBackward(block: DesignBlock) 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.

Rotation#

  • getRotation(id: number): number returns the rotation of the block around its center in radians.
  • setRotation(id: number, rotation: number): void sets the rotation of a block in radians.

Flipping#

  • getFlipHorizontal(id:number): boolean, setFlipHorizontal(id: number, flipped: boolean): void and the corresponding vertical methods returns whether a block has been flipped along a particular axis. The setter methods allow setting the respective property.

Scaling#

  • scale(id: number, scale: number, anchorX: number, anchorY: number): void scales the block and all of its children proportionally around the specified relative anchor point. By default, the top-left is used as the anchor-point.

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.

  • isAlignable(ids: number[]): boolean confirms that a given set of blocks can be aligned.
  • alignHorizontally(ids: number[], alignment) Align multiple blocks horizontally within their bounding box (or group) or a single block to its parent. The alignment can be set to Left, Right, or Center.
  • alignVertically(ids: number[], alignment: String) Align multiple blocks vertically within their bounding box (or group) or a single block to its parent. The alignment can be set to Top, Bottom, or Center.

Computed Dimensions#

  • getFrameWidth(id: number): number returns a block's frame width. The frame width is the effective width of a block after the layout phase. This is mostly relevant for text blocks that might not have a defined height, but adjust their height automatically depending on their content, but can also be an important distinction in other contexts.
  • getFrameHeight(id: number): number returns a block's frame height. The frame height is the effective height of a block after the layout phase.
  • getGlobalBoundingBoxX(id: number): number returns the block's x position in the scene's global coordinate space, which has its origin at the top left.
  • getGlobalBoundingBoxY(id: number): number returns the block's y position in the scene's global coordinate space, which has its origin at the top left.
  • getGlobalBoundingBoxWidth(id: number): number returns the block's width in the scene's global coordinate space, which has its origin at the top left.
  • getGlobalBoundingBoxHeight(id: number): number returns the block's height in the scene's global coordinate space, which has its origin at the top left.
File:
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.setWidthMode(block, 'Percent');
engine.block.setHeight(block, 0.5);
engine.block.setHeightMode(block, 'Percent');
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.bringToFront(block)
engine.block.sendToBack(block)
// highlight_bringForward
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);


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


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