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 toLeft
,Right
, orCenter
.
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 toTop
,Bottom
, orCenter
.
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.
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_bringForwardengine.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 pageconst 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");}