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.

Variables

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.

Variables

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.

Variables

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:

Variables

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

Tip: You can change the value of most variables without opening the editing popover.

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.

Connecting a variable to an attribute 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).

Making variable connection directly to the shape on canvas

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.

Connection Button

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

Connection Popover

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:

Connection Disconnected

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.

Using boolean variable for visibilityUsing boolean variable for visibility

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

Visibility OptionsVisibility Options

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.

Variables displayed in canvas

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 displayed in canvas

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.

Code generation settings for variable

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.

Expressions

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.

Expressions

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

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!

Important: It is legal for library items such as colors to have spaces in their names.

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.