Variable Bindings - Mac Catalyst

import Foundation
import IMGLYEngine

struct VariableBindingsResult {
  let accentType: VariableType
  let cornerRadius: Float
  let colorVariables: [String]
  let textVariables: [String]
  let updatedCardColor: Color
  let cardFillBinding: String?
  let opacityBinding: String?
  let shapeBindings: [String]
  let boundWriteErrorCode: EngineErrorCode?
  let detachedCornerRadius: Float
  let boundCornerRadius: Float
  let renamedBinding: String?
  let renamedText: String
  let renameErrorCodes: [EngineErrorCode?]
  let typeMismatchErrorCode: EngineErrorCode?
  let bindingTypeErrorCode: EngineErrorCode?
}

@MainActor
func variableBindings(engine: Engine) async throws -> VariableBindingsResult {
  // Resolve sample assets (font, images) against the engine's configured base URL.
  let baseURL = try engine.guidesBaseURL

  let scene = try engine.scene.create()
  let page = try engine.block.create(.page)
  try engine.block.setWidth(page, value: 800)
  try engine.block.setHeight(page, value: 600)
  try engine.block.appendChild(to: scene, child: page)

  // One variable per type. A setter creates the variable when the key is new.
  let roboto = Typeface(
    name: "Roboto",
    fonts: [
      Font(
        uri: baseURL.appendingPathComponent("ly.img.typeface/fonts/Roboto/Roboto-Regular.ttf"),
        subFamily: "Regular",
        weight: .normal,
        style: .normal,
      ),
    ],
  )
  try engine.variable.set(key: "accent", color: .rgba(r: 0.48, g: 0.23, b: 0.93, a: 1))
  try engine.variable.set(key: "cornerRadius", number: 40)
  try engine.variable.set(
    key: "heroImage",
    imageURL: baseURL.appendingPathComponent("ly.img.image/images/sample_1.jpg"),
  )
  try engine.variable.set(key: "headline", typeface: roboto)
  try engine.variable.set(key: "title", value: "Summer Sale")

  let accentType = try engine.variable.getType(key: "accent") // .color
  let cornerRadius = try engine.variable.getNumber(key: "cornerRadius") // 40
  let colorVariables = engine.variable.findAll(type: .color) // ["accent"]
  // findAll() lists text variables only
  let textVariables = engine.variable.findAll() // ["title"]
  print(accentType, cornerRadius, colorVariables, textVariables)

  // A card with a color fill and a rect shape
  let card = try engine.block.create(.graphic)
  try engine.block.setShape(card, shape: engine.block.createShape(.rect))
  try engine.block.setFill(card, fill: engine.block.createFill(.color))
  try engine.block.setWidth(card, value: 720)
  try engine.block.setHeight(card, value: 520)
  try engine.block.setPositionX(card, value: 40)
  try engine.block.setPositionY(card, value: 40)
  try engine.block.appendChild(to: page, child: card)
  let cardFill = try engine.block.getFill(card)
  let cardShape = try engine.block.getShape(card)

  // An image with an image fill
  let image = try engine.block.create(.graphic)
  try engine.block.setShape(image, shape: engine.block.createShape(.rect))
  let imageFill = try engine.block.createFill(.image)
  try engine.block.setFill(image, fill: imageFill)
  try engine.block.setWidth(image, value: 640)
  try engine.block.setHeight(image, value: 300)
  try engine.block.setPositionX(image, value: 80)
  try engine.block.setPositionY(image, value: 80)
  try engine.block.appendChild(to: page, child: image)

  // A headline that shows the text variable
  let text = try engine.block.create(.text)
  try engine.block.replaceText(text, text: "{{title}}")
  try engine.block.setWidth(text, value: 640)
  try engine.block.setHeightMode(text, mode: .auto)
  try engine.block.setPositionX(text, value: 80)
  try engine.block.setPositionY(text, value: 420)
  try engine.block.appendChild(to: page, child: text)

  // Each binding applies the current value of the variable at once
  try engine.block.setVariableBinding(cardFill, property: "fill/color/value", key: "accent")
  for corner in ["TL", "TR", "BL", "BR"] {
    try engine.block.setVariableBinding(cardShape, property: "shape/rect/cornerRadius\(corner)", key: "cornerRadius")
  }
  try engine.block.setVariableBinding(imageFill, property: "fill/image/imageFileURI", key: "heroImage")
  try engine.block.setVariableBinding(text, property: "text/typeface", key: "headline")

  // Every bound property follows the new values
  try engine.variable.set(key: "accent", color: .rgba(r: 0.05, g: 0.55, b: 0.55, a: 1))
  try engine.variable.set(key: "cornerRadius", number: 24)
  try engine.variable.set(
    key: "heroImage",
    imageURL: baseURL.appendingPathComponent("ly.img.image/images/sample_2.jpg"),
  )
  let updatedCardColor: Color = try engine.block.getColor(cardFill, property: "fill/color/value")

  let cardFillBinding = try engine.block.getVariableBinding(cardFill, property: "fill/color/value") // "accent"
  let opacityBinding = try engine.block.getVariableBinding(card, property: "opacity") // nil
  // The four corner radius properties of the shape
  let shapeBindings = try engine.block.findAllVariableBindings(cardShape)

  // A bound property changes only through its variable
  var boundWriteErrorCode: EngineErrorCode?
  do {
    try engine.block.setColor(cardFill, property: "fill/color/value", color: .rgba(r: 1, g: 0, b: 0, a: 1))
  } catch let error as EngineError {
    boundWriteErrorCode = error.catalogCode // .blockPropertyBound
  }

  // The bottom corners keep their current radius and stop following
  try engine.block.removeVariableBinding(cardShape, property: "shape/rect/cornerRadiusBL")
  try engine.block.removeVariableBinding(cardShape, property: "shape/rect/cornerRadiusBR")
  try engine.variable.set(key: "cornerRadius", number: 60)
  let detachedCornerRadius = try engine.block.getFloat(cardShape, property: "shape/rect/cornerRadiusBL") // 24
  let boundCornerRadius = try engine.block.getFloat(cardShape, property: "shape/rect/cornerRadiusTL") // 60

  // Bindings and {{tokens}} in text follow the new name
  try engine.variable.rename(key: "accent", to: "brand/accent")
  try engine.variable.rename(key: "title", to: "campaign/title")
  let renamedBinding = try engine.block.getVariableBinding(cardFill, property: "fill/color/value") // "brand/accent"
  let renamedText = try engine.block.getString(text, property: "text/text") // "{{campaign/title}}"

  // .blockVariableNameInvalid for the first three names,
  // .blockVariableNameTaken for the name of another variable
  var renameErrorCodes: [EngineErrorCode?] = []
  for name in ["", " padded", "a{{b", "campaign/title"] {
    do {
      try engine.variable.rename(key: "brand/accent", to: name)
    } catch let error as EngineError {
      renameErrorCodes.append(error.catalogCode)
    }
  }

  var typeMismatchErrorCode: EngineErrorCode?
  do {
    // A color variable has no number value
    _ = try engine.variable.getNumber(key: "brand/accent")
  } catch let error as EngineError {
    typeMismatchErrorCode = error.catalogCode // .blockVariableTypeMismatch
  }
  var bindingTypeErrorCode: EngineErrorCode?
  do {
    // Opacity is a number property, so it cannot bind to a color variable
    try engine.block.setVariableBinding(card, property: "opacity", key: "brand/accent")
  } catch let error as EngineError {
    bindingTypeErrorCode = error.catalogCode // .blockVariableBindingUnsupported
  }

  let png = try await engine.block.export(page, mimeType: .png)
  print("Exported \(png.count) bytes")

  return VariableBindingsResult(
    accentType: accentType,
    cornerRadius: cornerRadius,
    colorVariables: colorVariables,
    textVariables: textVariables,
    updatedCardColor: updatedCardColor,
    cardFillBinding: cardFillBinding,
    opacityBinding: opacityBinding,
    shapeBindings: shapeBindings,
    boundWriteErrorCode: boundWriteErrorCode,
    detachedCornerRadius: detachedCornerRadius,
    boundCornerRadius: boundCornerRadius,
    renamedBinding: renamedBinding,
    renamedText: renamedText,
    renameErrorCodes: renameErrorCodes,
    typeMismatchErrorCode: typeMismatchErrorCode,
    bindingTypeErrorCode: bindingTypeErrorCode,
  )
}

Drive block colors, sizes, images and typefaces from typed variables, so one change updates every bound property.

10 mins

estimated time

GitHub

Text variables fill {{key}} tokens in text, as the Text Variables guide shows. Color, number, image and typeface variables hold one typed value each. When you bind a block property to such a variable, the property takes the variable’s value and follows every change of it. One brand color can then drive every fill, border and text that uses it.

This guide covers the typed variables, binding and unbinding properties, the lock on bound properties, renaming variables, and the errors to expect.

Creating Typed Variables#

Each type has its own setter. set(key:color:), set(key:number:), set(key:imageURL:) and set(key:typeface:) create the variable when the key is new, and update it otherwise. set(key:value:) stays the setter for text variables.

// One variable per type. A setter creates the variable when the key is new.
let roboto = Typeface(
  name: "Roboto",
  fonts: [
    Font(
      uri: baseURL.appendingPathComponent("ly.img.typeface/fonts/Roboto/Roboto-Regular.ttf"),
      subFamily: "Regular",
      weight: .normal,
      style: .normal,
    ),
  ],
)
try engine.variable.set(key: "accent", color: .rgba(r: 0.48, g: 0.23, b: 0.93, a: 1))
try engine.variable.set(key: "cornerRadius", number: 40)
try engine.variable.set(
  key: "heroImage",
  imageURL: baseURL.appendingPathComponent("ly.img.image/images/sample_1.jpg"),
)
try engine.variable.set(key: "headline", typeface: roboto)
try engine.variable.set(key: "title", value: "Summer Sale")

A number must be finite. A typeface needs a name and at least one font. One key holds one type, so set(key: "accent", number: 1) throws while accent is a color variable.

Reading Variables#

getColor(key:), getNumber(key:), getImageURL(key:) and getTypeface(key:) return the values. getType(key:) returns a VariableType: .string, .color, .number, .image or .typeface. findAll(type:) lists the keys of one type.

let accentType = try engine.variable.getType(key: "accent") // .color
let cornerRadius = try engine.variable.getNumber(key: "cornerRadius") // 40
let colorVariables = engine.variable.findAll(type: .color) // ["accent"]
// findAll() lists text variables only
let textVariables = engine.variable.findAll() // ["title"]
print(accentType, cornerRadius, colorVariables, textVariables)

findAll() lists text variables only, as before. Use findAll(type:) for the other types.

Binding Properties#

We create a card with a color fill and a rect shape, an image with an image fill, and a text that shows the title variable. A binding targets the block that owns the property: the fill owns fill/color/value, and the shape owns the corner radii.

// A card with a color fill and a rect shape
let card = try engine.block.create(.graphic)
try engine.block.setShape(card, shape: engine.block.createShape(.rect))
try engine.block.setFill(card, fill: engine.block.createFill(.color))
try engine.block.setWidth(card, value: 720)
try engine.block.setHeight(card, value: 520)
try engine.block.setPositionX(card, value: 40)
try engine.block.setPositionY(card, value: 40)
try engine.block.appendChild(to: page, child: card)
let cardFill = try engine.block.getFill(card)
let cardShape = try engine.block.getShape(card)

// An image with an image fill
let image = try engine.block.create(.graphic)
try engine.block.setShape(image, shape: engine.block.createShape(.rect))
let imageFill = try engine.block.createFill(.image)
try engine.block.setFill(image, fill: imageFill)
try engine.block.setWidth(image, value: 640)
try engine.block.setHeight(image, value: 300)
try engine.block.setPositionX(image, value: 80)
try engine.block.setPositionY(image, value: 80)
try engine.block.appendChild(to: page, child: image)

// A headline that shows the text variable
let text = try engine.block.create(.text)
try engine.block.replaceText(text, text: "{{title}}")
try engine.block.setWidth(text, value: 640)
try engine.block.setHeightMode(text, mode: .auto)
try engine.block.setPositionX(text, value: 80)
try engine.block.setPositionY(text, value: 420)
try engine.block.appendChild(to: page, child: text)

setVariableBinding(_:property:key:) binds a property to a variable. The property takes the variable’s current value at once.

// Each binding applies the current value of the variable at once
try engine.block.setVariableBinding(cardFill, property: "fill/color/value", key: "accent")
for corner in ["TL", "TR", "BL", "BR"] {
  try engine.block.setVariableBinding(cardShape, property: "shape/rect/cornerRadius\(corner)", key: "cornerRadius")
}
try engine.block.setVariableBinding(imageFill, property: "fill/image/imageFileURI", key: "heroImage")
try engine.block.setVariableBinding(text, property: "text/typeface", key: "headline")

Each variable type binds to a fixed set of properties:

Variable type	Properties it binds to
Color	Color properties, for example `fill/color/value` and `fill/solid/color`
Number	Float properties, for example `opacity`, `width` and `shape/rect/cornerRadiusTL`. Int properties, such as `shape/star/points`, do not bind
Image	`fill/image/imageFileURI`, `fill/image/previewFileURI` and `fill/video/fileURI`
Typeface	`text/typeface` and `caption/typeface`

Text variables and gradient color stops cannot bind. On a text block, a bound typeface, text color or font size applies to the whole text.

Changing Variables#

Set a variable again to update every property that is bound to it.

// Every bound property follows the new values
try engine.variable.set(key: "accent", color: .rgba(r: 0.05, g: 0.55, b: 0.55, a: 1))
try engine.variable.set(key: "cornerRadius", number: 24)
try engine.variable.set(
  key: "heroImage",
  imageURL: baseURL.appendingPathComponent("ly.img.image/images/sample_2.jpg"),
)
let updatedCardColor: Color = try engine.block.getColor(cardFill, property: "fill/color/value")

An image variable also empties the source set of the fill, so the fill shows the URL of the variable. When one bound property rejects a value, for example an opacity above 1, the setter throws the first error. The variable and the other bound properties change anyway.

Reading Bindings#

getVariableBinding(_:property:) returns the key of the variable that a property is bound to, or nil. findAllVariableBindings(_:) lists the bound properties of a block.

let cardFillBinding = try engine.block.getVariableBinding(cardFill, property: "fill/color/value") // "accent"
let opacityBinding = try engine.block.getVariableBinding(card, property: "opacity") // nil
// The four corner radius properties of the shape
let shapeBindings = try engine.block.findAllVariableBindings(cardShape)

Bound Properties Are Locked#

A bound property changes only through its variable. A direct write throws an EngineError whose catalogCode is .blockPropertyBound, and the value stays as it is.

// A bound property changes only through its variable
var boundWriteErrorCode: EngineErrorCode?
do {
  try engine.block.setColor(cardFill, property: "fill/color/value", color: .rgba(r: 1, g: 0, b: 0, a: 1))
} catch let error as EngineError {
  boundWriteErrorCode = error.catalogCode // .blockPropertyBound
}

Moving, resizing, rotating, cropping, aligning and scaling also leave a bound property unchanged. A bound typeface also locks setTypeface and setFont. Keyframes, undo and loading a scene still change a bound property. Changing the design unit also converts a bound length, such as a width or a corner radius. A number variable whose bound properties all hold its value converts with them. Otherwise the variable keeps its value, and the next write to the variable sets the lengths in the new unit.

Removing Bindings#

removeVariableBinding(_:property:) removes the binding. The property keeps its current value and no longer follows the variable.

// The bottom corners keep their current radius and stop following
try engine.block.removeVariableBinding(cardShape, property: "shape/rect/cornerRadiusBL")
try engine.block.removeVariableBinding(cardShape, property: "shape/rect/cornerRadiusBR")
try engine.variable.set(key: "cornerRadius", number: 60)
let detachedCornerRadius = try engine.block.getFloat(cardShape, property: "shape/rect/cornerRadiusBL") // 24
let boundCornerRadius = try engine.block.getFloat(cardShape, property: "shape/rect/cornerRadiusTL") // 60

remove(key:) removes a variable of any type. Its bound properties keep the last value and the binding. When you set a variable with the same key and type again, they follow it again.

Renaming Variables#

rename(key:to:) moves the value and the type of a variable to a new key. Every binding follows the new key. For a text variable, every {{key}} token in text changes to the new key.

// Bindings and {{tokens}} in text follow the new name
try engine.variable.rename(key: "accent", to: "brand/accent")
try engine.variable.rename(key: "title", to: "campaign/title")
let renamedBinding = try engine.block.getVariableBinding(cardFill, property: "fill/color/value") // "brand/accent"
let renamedText = try engine.block.getString(text, property: "text/text") // "{{campaign/title}}"

A new name must follow these rules:

It is not empty.
It does not start or end with whitespace. Spaces inside the name are allowed.
It does not contain {{ or }}, because text tokens use them.
No other variable uses it. A rename to the current name does nothing.

// .blockVariableNameInvalid for the first three names,
// .blockVariableNameTaken for the name of another variable
var renameErrorCodes: [EngineErrorCode?] = []
for name in ["", " padded", "a{{b", "campaign/title"] {
  do {
    try engine.variable.rename(key: "brand/accent", to: name)
  } catch let error as EngineError {
    renameErrorCodes.append(error.catalogCode)
  }
}

Handling Type Errors#

A getter of another type and a binding to a property of another type throw errors. The variable and the property stay unchanged.

var typeMismatchErrorCode: EngineErrorCode?
do {
  // A color variable has no number value
  _ = try engine.variable.getNumber(key: "brand/accent")
} catch let error as EngineError {
  typeMismatchErrorCode = error.catalogCode // .blockVariableTypeMismatch
}
var bindingTypeErrorCode: EngineErrorCode?
do {
  // Opacity is a number property, so it cannot bind to a color variable
  try engine.block.setVariableBinding(card, property: "opacity", key: "brand/accent")
} catch let error as EngineError {
  bindingTypeErrorCode = error.catalogCode // .blockVariableBindingUnsupported
}

Saving and Undo#

A scene or an archive saves the typed variables and the bindings. Undo and redo restore variable values, bindings and renames.

Exporting the Result#

We export the page as a PNG. The card shows the last values of its variables.

let png = try await engine.block.export(page, mimeType: .png)
print("Exported \(png.count) bytes")

Troubleshooting#

The variable does not exist (.blockVariableNotFound): set the variable before you read or bind it.
The key holds another type (.blockVariableTypeMismatch): use the getter and setter of the stored type, or remove the variable first.
The typeface is not accepted (.blockVariableTypefaceInvalid): pass a typeface with a name and at least one font.
The property cannot bind to this variable (.blockVariableBindingUnsupported): check the table in Binding Properties, and pass the block that owns the property.
Gradient stops do not bind (.blockVariableBindingGradientStopsUnsupported): bind a color variable to a solid color fill instead.
A write to a property fails (.blockPropertyBound): set the variable instead, or remove the binding first.
A rename fails with an invalid name (.blockVariableNameInvalid): follow the name rules in Renaming Variables.
A rename fails with a taken name (.blockVariableNameTaken): pick a name that no variable uses.

The Error Catalog lists every error code.

API Reference#

Methods#

Method	Description
`engine.variable.set(key:color:)` / `getColor(key:)`	Set or read a color variable
`engine.variable.set(key:number:)` / `getNumber(key:)`	Set or read a number variable
`engine.variable.set(key:imageURL:)` / `getImageURL(key:)`	Set or read an image variable
`engine.variable.set(key:typeface:)` / `getTypeface(key:)`	Set or read a typeface variable
`engine.variable.set(key:value:)`	Set a text variable
`engine.variable.getType(key:)`	Get the type of a variable
`engine.variable.findAll(type:)`	List the keys of the variables of one type
`engine.variable.findAll()`	List the keys of the text variables
`engine.variable.rename(key:to:)`	Rename a variable of any type
`engine.variable.remove(key:)`	Remove a variable of any type
`engine.block.setVariableBinding(_:property:key:)`	Bind a property to a variable
`engine.block.getVariableBinding(_:property:)`	Get the key of the bound variable, or `nil`
`engine.block.findAllVariableBindings(_:)`	List the bound properties of a block
`engine.block.removeVariableBinding(_:property:)`	Remove a binding and keep the current value

Next Steps#

Text Variables: fill {{key}} tokens in text with values.
Placeholders: mark the blocks that template users can replace.
Undo and History: work with undo steps.