How do I programmatically change how many times an item in my Test Composition or Test Clip plays?
Every item in a Test Composition can be set to repeat a specified number of times. If an item is not set to repeat, it will play once. If an item is set to repeat zero times, it will not play at all.
For most types of items, a Script can set the number of times that the item will repeat. A Script can prevent an item from playing by setting its repeat count to zero.
You can insert Scripts into your Test Composition that dynamically change the repeat counts of one or more items when the Script plays.
It is important to keep in mind that an item's repeat count cannot be changed once it has started playing.
Since all Tracks start playing immediately when the Test Composition begins, a Script cannot modify the repeat count for a Track. However, the repeat count for lower-level items, such as Test Clips, Chains, and Messages can be changed.
Certain types of items are only allowed to have a repeat count of either zero or one. These items are Checkpoints and Delays. For these items, the repeat count is used only to "enable" or "disable" the play of the item.
For items that have a specific scheduled time to play, during play the Maestro server may begin initializing them up to 5 seconds before their scheduled time, for performance reasons. Once this initialization process has started, the repeat count cannot be changed. Items with a scheduled time are all Test Clips and all items inside a time-based Test Clip except those items inside Chains. A time-based Test Clip is any type of Test Clip other than Sequenced.
Insert one or more Scripts into your Test Clips at the points at which you wish to adjust the repeat counts of one or more following items, keeping in mind the restrictions listed above.
Your Scripts can traverse the object hierarchy of the Test Composition to find the other items in the Test Composition. For example, the following statement retrieves the item in the current Test Clip that immediately follows the current Script:
Refer to the Scripting documentation for more information about how to traverse the object hierarchy.
Once your Script has found an item to change, the following examples show how to adjust the item's repeat count. In these examples, it is assumed that "anItem" is a variable containing an item's object whose repeat count is to be changed.
You must ensure that you change the repeat count before the item starts playing. This can be assured in any of the following ways.