How to Use Fills

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 Fills#

Not all types of design blocks support fills, so you should always first call the hasFill(id: number): boolean API before accessing any of the following APIs.

In order to receive the fill id of a design block, call the getFill(id: number): number API. You can now pass this id into other APIs in order to query more information about the fill, e.g. its type via the getType(id: number): ObjectType API.

Fill Properties#

Just like design blocks, fills 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 fill.

For the solid color fill in this example, the call would return ["fill/color/value", "type"].

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

Once we know the property keys of a fill, we can use the same APIs as for design blocks in order to modify those properties. For example, we can use setColor(id: number, property: string, value: Color): void in order to change the color of the fill to red.

Once we do this, our graphic block with rect shape will be filled with solid red.

Disabling Fills#

You can disable and enable a fill using the setFillEnabled(id: number, enabled: boolean): void API, for example in cases where the design block should only have a stroke but no fill. Notice that you have to pass the id of the design block and not of the fill to the API.

Changing Fill Types#

All design blocks that support fills allow you to also exchange their current fill for any other type of fill. In order to do this, you need to first create a new fill object using createFill(type: FillType): number.

We currently support the following fill types:

• '//ly.img.ubq/fill/color'
• '//ly.img.ubq/fill/gradient/linear'
• '//ly.img.ubq/fill/gradient/radial'
• '//ly.img.ubq/fill/gradient/conical'
• '//ly.img.ubq/fill/image'
• '//ly.img.ubq/fill/video'
• '//ly.img.ubq/fill/pixelStream'

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

In order to assign a fill to a design block, simply call setFill(id: number, fill: number): void. Make sure to delete the previous fill of the design block first if you don't need it any more, otherwise we will have leaked it into the scene and won't be able to access it any more, because we don't know its id.

Notice that we don't use the appendChild API here, which only works with design blocks and not fills.

When a fill is attached to one design block, it will be automatically destroyed when the block itself gets destroyed.

Duplicating Fills#

If we duplicate a design block with a fill that is only attached to this block, the fill will automatically be duplicated as well. In order to modify the properties of the duplicate fill, we have to query its id from the duplicate block.

Sharing Fills#

It is also possible to share a single fill instance between multiple design blocks. In that case, changing the properties of the fill will apply to all of the blocks that it's attached to at once.

Destroying a block with a shared fill will not destroy the fill until there are no other design blocks left that still use that fill.