How to Use Shapes

The graphic design block in CE.SDK allows you to modify and replace its shape. CreativeEditor SDK supports many different types of shapes, such as rectangles, lines, ellipses, polygons and custom vector paths.

Similarly to blocks, each shape object has a numeric id which can be used to query and modify its properties.

Explore a full code sample on Stackblitz or view the code on Github.

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.

Accessing Shapes#

In order to query whether a block supports shapes, you should call the supportsShape(id: number): boolean API. Currently, only the graphic design block supports shape objects.

Creating Shapes#

graphic blocks don't have any shape after you create them, which leaves them invisible by default. In order to make them visible, we need to assign both a shape and a fill to the graphic block. You can find more information on fills here. In this example we have created and attached an image fill.

In order to create a new shape, we must call the createShape(type: string): number API.

We currently support the following shape types:

'//ly.img.ubq/shape/rect'
'//ly.img.ubq/shape/line'
'//ly.img.ubq/shape/ellipse'
'//ly.img.ubq/shape/polygon'
'//ly.img.ubq/shape/star'
'//ly.img.ubq/shape/vector_path'

Note: short types are also accepted, e.g. 'rect' instead of '//ly.img.ubq/shape/rect'.

In order to assign this shape to the graphic block, call the setShape(id: number, shape: number): void API.

To query the shape id of a design block, call the getShape(id: number): number API. You can now pass this id into other APIs in order to query more information about the shape, e.g. its type via the getType(id: number): string API.

When replacing the shape of a design block, remember to destroy the previous shape object if you don't intend to use it any further. Shape objects that are not attached to a design block will never be automatically destroyed.

Destroying a design block will also destroy its attached shape block.

Shape Properties#

Just like design blocks, shapes with different types have different properties that you can query and modify via the API. Use findAllProperties(id: number): string[] in order to get a list of all properties of a given shape.

For the star shape in this example, the call would return ['name', 'shape/star/innerDiameter', 'shape/star/points', 'type', 'uuid'].

Please refer to the API docs for a complete list of all available properties for each type of shape.

Once we know the property keys of a shape, we can use the same APIs as for design blocks in order to modify those properties. For example, we can use setInt(id: number, property: string, value: number): void in order to change the number of points of the star to six.


import CreativeEngine from 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.41.1/index.js';

const config = {
  license: 'mtLT-_GJwMhE7LDnO8KKEma7qSuzWuDxiKuQcxHKmz3fjaXWY2lT3o3Z2VdL5twm',
  userId: 'guides-user',
  baseURL: 'https://cdn.img.ly/packages/imgly/cesdk-engine/1.41.1/assets'
};

CreativeEngine.init(config).then(async (engine) => {
  document.getElementById('cesdk_container').append(engine.element);

  const scene = engine.scene.create();
  engine.editor.setSettingBool('page/dimOutOfPageAreas', false);

  const graphic = engine.block.create('graphic');
  const imageFill = engine.block.createFill('image');
  engine.block.setString(
    imageFill,
    'fill/image/imageFileURI',
    'https://img.ly/static/ubq_samples/sample_1.jpg'
  );
  engine.block.setFill(graphic, imageFill);
  engine.block.setWidth(graphic, 100);
  engine.block.setHeight(graphic, 100);
  engine.block.appendChild(scene, graphic);

  engine.scene.zoomToBlock(graphic, 40, 40, 40, 40);


  engine.block.supportsShape(graphic); // Returns true
  const text = engine.block.create('text');
  engine.block.supportsShape(text); // Returns false

  const rectShape = engine.block.createShape('rect');
  engine.block.setShape(graphic, rectShape);
  const shape = engine.block.getShape(graphic);
  const shapeType = engine.block.getType(shape);

  const starShape = engine.block.createShape('star');
  engine.block.destroy(engine.block.getShape(graphic));
  engine.block.setShape(graphic, starShape);
  /* The following line would also destroy the currently attached starShape */
  // engine.block.destroy(graphic);

  const allShapeProperties = engine.block.findAllProperties(starShape);
  engine.block.setInt(starShape, 'shape/star/points', 6);
});