Iterated objects

Introduction

Iterating objects allows you to go from this...

to this...

...without adding more (blue) rectangle objects.

In general, templates in Bluepic are designed so that users cannot add new objects. However, as long as there is an explicit pattern, you can use object iteration to automatically add (or rather duplicate) objects.

Iteration properties

There are three properties that are needed for iterations. Any object can be iterated. The iteration properties can be found in the last property tab.

Iteration

Click the checkbox to enable the iteration.

Count

The iteration count is a number (integer) that defines how many copies of the object are displayed. This can be a static value, but in most cases a subproperty or variable is used. In the example above, the count is...

Count =    text1.lines.length

This expression using a subproperty returns the number of lines in a particular text object. Therefore, a copy of the blue rectangle is displayed for each line of text in the example.

Keep in mind that when you create an iteration and set a specific number of iterations, it is probably not immediately visible because each copy is initially displayed in the same position (on top of each other).

Key

The iteration key is a local variable that starts at 0 and is incremented by 1 for each copy of the object. You can think of the key as a subproperty that is unique for each copy and therefore acts as an identifier for the copy.

Working with iterations

The iteration key is key to working with iterations 🔑 😉

To understand how the iteration key is used to position each copy according to a specific pattern, let's take another look at the example from above:

The expressions used for the X-, Y-, Width- and Height- properties are:

X =         text1.lines[i].x - 10
Y =         text1.lines[i].y
Width =     text1.lines[i].width + 20
Height =    text1.lines[i].height

When inserting _.lines[i]_ into the subproperties of the text object, the subproperties are returned one level deeper - i.e. the subproperties of a single text line. Which text line? The i-th text line - where "i" is the iteration key.

You can also find the text1.lines[i]-subproperties in the Smart Expression Editor:

By using expressions with the iteration key "i" as an argument, you can give each copy of the iterated object different properties, like position, size or even color.