Using Variables

Like colors and gradients, variables are also a kind of library item you can use in your document.

Variables can be numbers, texts, booleans (logical values), points, rectangles, sizes, even colors, shadows and gradients. You can connect variables to attributes of your shapes on the canvas.

For example, you can create a numeric variable called "radius" and connect it to the corner radius attribute of several rounded rectangles. When you then change the value of the "radius" variable, corner radiuses of all connected shapes will be updated immediately.

In the drawing method generated by a canvas, variables turn into method parameters.

Creating variables

To create a new variable, simply click on the "+" button which is located on the left side of the Variables header in the Library. Next, choose the kind of the variable you want to create.

Editing variables

When you create a new variable, an editing popover automatically appears. You can access this popover at any time by double-clicking on the variable in the Library.

The editing popover allows you to change several attributes of the variable, perhaps most importantly its value and name.

Different kinds of variables have different editing popovers. Here's how the editing popover looks for rectangle variables:

The "Usage" attribute affects the generated code. We'll return back to that later.

Simply click & drag the value field of the variable up or down in the Variables list.

Connecting variable to shapes

There are several ways how to connect a variable to an attribute of some shape. The first one is to select the shape (or multiple shapes) on the canvas, the click & drag the variable's connection dot onto an attribute of the shape in the Inspector.

Alternatively, you can click & drag the connection dot directly onto a shape on the canvas, then choose the desired attribute from the contextual menu that appears. This approach is often more convenient that the first one. However, you can only use it to connect the variable to one shape at a time (in contrast, it is possible to connect a variable to multiple shapes at once when you create the connection via Inspector).

Also note that some attributes, such as positions of bezier control points and some group attributes can only be connected via Inspector.

Connection indicator button

After you connect a variable to some attribute, a connection indicator button usually appears in the inspector (the button replaces the original text field of the attribute). In the example below, we've connected a variable to the corner radius attribute of a rounded rectangle.

When you click on the connection indicator button, a connection popover appears.

This popover allows you to specify an offset - a value that should be added to the value of the variable when it is being used by that attribute. These custom variable offsets can greatly reduce the number of variables you need to create in your document. Additionally, the connection indicator button also allows you to switch the attribute to use a different variable, if available.

Disconnecting a variable from an attribute

Variable can be easily disconnected from an attribute by clicking on the small purple circle with a white X (this circle is displayed in the connection indicator button).

After you disconnect the variable, the connection indicator button disappears and the original text field returns:

Controlling the visibility of shapes using variables

You can use a boolean variable to control the visibility of any shape. In the shape's Inspector, just below the name text field is a popup button that controls the visibility of the shape.

Popup menu is populated with all boolean variables that you have in your PaintCode document.

In the example above, our document contains an boolean variable called "isPressed". By choosing the "Visible if isPressed" option, we'll make sure that the shape is only visible when the isPressed variable is true.

Variables displayed in canvas

When you create point or rectangle variable and connect it with some shape on your canvas, the variable itself will also appear on the canvas, drawn in purple.

In case of the point, it is a small target symbol you can drag around - the value of the point variable will change accordingly. The rectangular variable works in a similar way.

This feature is very useful when you, for example, create a point variable that represents a mouse cursor. You can then create many variables that depend on this variable (using expressions), and simply by moving the point variable around, you can easily test the resulting behavior.

Use the Canvas ▸ Show Variables menu to turn this feature on and off.

Variables and code generation

In the drawing method generated by a canvas, variables turn into parameters:

- (void)drawRateButtonWithRadius: (CGFloat)radius title: (NSString*)title pressed: (BOOL)pressed;

Unless, of course, you choose that the variable should behave as a local variable in its editing popover. Note that expression variables are always local.

Expressions

PaintCode allows you to create a special kind of variable - an expression. These variables can use mathematical and programming expressions to define their value. They can depend on other variables and even other library items, such as colors.

We've essentially added a tiny programming language to PaintCode. It is a subset of both C and JavaScript, and it is very easy to use. With expression variables, you can create really complex, dynamic drawings, even animated characters for games.

When an orange background appears behind a part of your expression, it means that there is some kind of error. Click on the orange part of your expression or the warning triangle in the bottom left corner of the editing popover to display the error message.

Expressions are not limited to numbers - you can use logical operators, the ?: ternary operator made popular by C, and even reference colors from your Library and create new ones!

However, when you want to refer to a library item by name in your expression, you have to omit the spaces, capitalize each word and make the first letter lowercase. For example, if you have a color called "My Red Color" in your Library, you can use it in your expressions using the "myRedColor" identiifer.

To learn everything you need to know about PaintCode Expression Language, read the next section of this documentation.