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. SeegetEnumValues(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.
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 Propertiesengine.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); // Whiteengine.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');