<< Click to Display Table of Contents >> Navigation:  Advanced Features > Scripting > Advanced Scripting > Loops

•In coding context “loops” are blocks of code that are executed several times, often in conjunction with a local variable whose value changes for each iteration.

•There are three different types of loops which will be described below. Further, additional features common to all three types will be explained.

•Each loop definition begins with one of the loop methods (see below), followed by one or several lines of code, followed by an `EndLoop` statement. Loops can also be nested.

Loop From To

The “Loop From To” construct allows defining a loop for iterating over a range of integer numbers.

 

Example1:

 

Loop X From 1 To 3

    Log X
Endloop

 

            Output:

     1

     2

     3

 

In this example a loop is defined with a code-block (in this case only one line) that will be executed three times; for each iteration a local variable named “X” will be provided with the values 1,2 and 3, respectively.

The “Loop From To“ construct has three obligatory parts: the custom name of local variable, the designated integer value for the first and last. The local variable will start with the first value.

 

Each iteration will be incremented (or decremented, if the first value is larger than the last) by 1.

 

Example2:

               

                Assumptions: Project contains Sequence1 with several Clip Containers.

 

Set.Array containers = Sequence1.ClipContainers
 
Loop i From 0 To containers.MaxIndex
    Eval pos = i * 100
   
    Set cc = containers.ByIndex i
   
    cc.DynamicValue.Transform.Position.X = pos
    cc.DynamicValue.Transform.Position.Y = pos

    Log i

    Log cc

    Log pos

EndLoop

 

 Output:

0

Blue.png

0

1

Red.png

100

2

Green.png

200

 

A walk-through of the code:

-An Array named `containers` is defined that contains all Clip Containers of Sequence1.

-A loop is started which iterates from 0 to the maximum index (= count – 1, because Arrays have a 0-based index), assigning the value to the local variable `i`.

-Then, for each iteration:

oA new position is calculated and assigned to the local variable `pos`using the `eval` keyword for evaluating the mathematical expression.

oA reference to a Clip Container is assigned to the local variable `cc` using the Array method `ByIndex`.

oUsing the `DynamicValue` member of the local variable `cc`, the X and Y position of the Clip Container are modified.

oThe values for `i`, `cc` and `pos` are logged.

 

 

LoopEach In

The “LoopEach In” construct allows defining a loop for iterating over enumerable values.

Consider the following example that repositions Clip Containers depending on their sizes:

 

 Assumptions: Project contains Sequence1 with several Clip Containers.

 

Set.Array containers = Sequence1.ClipContainers
 
Set x = 0
Set y = 0

LoopEach cc In containers
    cc.DynamicValue.Transform.Position.X = x
    cc.DynamicValue.Transform.Position.Y = y
   
    x += cc.DynamicValue.MainContent.Size.Width
    y += cc.DynamicValue.MainContent.Size.Height   

EndLoop

 

 

A walk-through of the code:

-An Array named `containers` is defined that contains all Clip Containers of Sequence1.

-Two local variables, `x` and `y` are defined for storing and calculating a position offset.

-A loop is started that iterates over all items in `containers` and assigns each item to the local variable `cc` for each iteration.

-Then, for each iteration, using the `DynamicValue` member of the local variable `cc`:

oThe X and Y position of the Clip Container are modified.

oThe offsets are updated by adding the Clip Container’s width and height respectively.

 

The “LoopEach In” construct consists of two parts: the custom name of local variable and a reference to the enumerable values.

 

LoopWhile

•The “LoopWhile” construct does not offer a local variable that is redefined for each iteration, in contrast to the other loop types.

•Instead, it simply repeats a code block as long as the specified condition is true.

 

Consider the following example that runs an endless loop as long as a Clip Container is visible:

                Assumptions: Project contains a Sequence1 with a ClipContainer1

 

Set i = 0
LoopWhile Sequence1.ClipContainer1.Opacity > 0
    i += 1
    Log i
Endloop

 

The “LoopWhile” construct only has one parameter which is evaluated as a boolean condition.

 

Be cautious of unintendedly created endless loops running undetected in the background, as they can consume considerate resources!
 

Common Loop Features

As shown in the examples above, every loop definition ends with an `EndLoop` statement. It will often be a requirement not to process all lines within the loop block for every iteration, depending on custom business logic.

 

There are two methods to address these requirements:

-ExitLoop: skips execution of any code following within the loop block and then exits the loop, aborting execution of any further iterations

-ContinueLoop: skips execution of any code following within the loop block and continues loop execution with the next iteration.

 

In addition to influencing the loop block, in which these methods are used, they can also impact potential outer loops. This is done by specifying how many levels are to be exited/continued; the default value is 1.

 

The following examples should help demonstrate the behavior of these methods. First, consider this nested loop construct that logs the values while iterating, including an additional action, if `Col = 2`:

 

Loop Row From 1 to 3
    Log.Values Row, StartRow
 
    Loop Col From -1 to -3
        Log.Values Col, StartCol
 
        If Col = 2 ? Log XXXXX
       
        Log.Values Col, EndCol
    Endloop
   
    Log.Values Row, EndRow
Endloop

 

The negative range for the inner loop was chosen only because it makes comparing the outputs in the table below easier.
Now, imagine replacing the highlighted additional action with the following variants of ExitLoop and ContinueLoop.
The following table displays the output for the different substitutions. Empty lines have been inserted to help illustrate which lines were executed.

 

 

 

 
Apart from terminating loop executions as described above, it is, of course, also possible to use the `return` statement to finish/abort the execution of the entire script.