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

Modify Properties

In this example, we will show you how to use the CreativeEditor SDK's CreativeEngine to modify block properties 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.

Reflection#

For every block, you can get a list of all its properties by calling findAllProperties(id: number): string[]. Properties specific to a block are prefixed with the block's type followed by a forward slash. There are also common properties shared between blocks which are prefixed by their respective type. A list of all properties can be found in the Blocks Overview.

Given a property you can query its type as an enum using getPropertyType(property: string): 'Bool' | 'Int' | 'Float' | 'String' | 'Color' | 'Enum' | 'Struct'.

The property type 'Enum' is a special type. Properties of this type only accept a set of certain strings. To get a list of possible values for an enum property call getEnumValues(enumProperty: string): string[].

Some properties can only be written to or only be read. To find out what is possible with a property, you can use the isPropertyReadable and isPropertyWritable methods.

Generic Properties#

There are dedicated setter and getter functions for each property type. You have to provide a block and the property path. Use findAllProperties to get a list of all the available properties a block has.

Please make sure you call the setter and getter function matching the type of the property you want to set or query or else you will get an error. Use getPropertyType to figure out the pair of functions you need to use.

  • setBool(id: number, property: string, value: boolean): void sets the value of a boolean property.
  • getBool(id: number, property: string): boolean gets the value of a boolean property.
  • setInt(id: number, property: string, value: number): void sets the value of an integer property.
  • getInt(id: number, property: string): number gets the value of an integer property.
  • setFloat(id: number, property: string, value: number): void sets the value of a float property.
  • getFloat(id: number, property: string): number gets the value of a float property.
  • setString(id: number, property: string, value: string): void sets the value of a string property.
  • getString(id: number, property: string): string gets the value of a float property.
  • setColorRGBA(id: number, property: string, r: number, g: number, b: number, a: number): void sets the red, green, blue, and alpha components of a color property. The range for each channel is 0 to 1.
  • getColorRGBA(id: number, property: string): RGBA gets the value of a color property.

RGBA is a tuple of four numbers representing the color channels red, green, and blue and an alpha channel for transparency. The range for these numbers is 0 to 1.

  • setEnum(id: number, property: string, value: string): void sets the value of an enum property. See getEnumValues(property: string): string[] to get a list of accepted values for an enum property.
  • getEnum(id: number, property: string): string gets the value of an enum property.
File:
const propertyNamesStar = engine.block.findAllProperties(star); // Array [ "shapes/star/innerDiameter", "shapes/star/points", "opacity/value", ... ]
const propertyNamesImage = engine.block.findAllProperties(image); // Array [ "image/imageFileURI", "image/previewFileURI", "image/externalReference", ... ]
const propertyNamesText = engine.block.findAllProperties(text); // Array [ "text/text", "text/fontFileUri", "text/externalReference", "text/fontSize", "text/horizontalAlignment", ... ]


const pointsType = engine.block.getPropertyType('shapes/star/points'); // "Int"
const alignmentType = engine.block.getPropertyType('text/horizontalAlignment'); // "Enum"
engine.block.getEnumValues('text/horizontalAlignment');
const readable = engine.block.isPropertyReadable('shapes/star/points');
const writable = engine.block.isPropertyWritable('shapes/star/points');




// Generic Properties
engine.block.setBool(scene, 'scene/aspectRatioLock', false);
engine.block.getBool(scene, 'scene/aspectRatioLock');
const points = engine.block.getInt(star, 'shapes/star/points');
engine.block.setInt(star, 'shapes/star/points', points + 2);
engine.block.setFloat(star, 'shapes/star/innerDiameter', 0.75);
engine.block.getFloat(star, 'shapes/star/innerDiameter');
engine.block.setString(text, 'text/text', '*o*');
engine.block.setString(image, 'image/imageFileURI', 'https://img.ly/static/ubq_samples/sample_4.jpg');
engine.block.getString(text, 'text/text');
engine.block.getString(image, 'image/imageFileURI');
engine.block.setColorRGBA(colorFill, 'fill/color/value', 1, 1, 1, 1); // White
engine.block.getColorRGBA(colorFill, 'fill/color/value');
engine.block.setEnum(text, 'text/horizontalAlignment', 'Center');
engine.block.setEnum(text, 'text/verticalAlignment', 'Center');
engine.block.getEnum(text, 'text/horizontalAlignment');
engine.block.getEnum(text, 'text/verticalAlignment');