Class CompositionItem

Class Summary
Constructor Attributes	Constructor Name and Description
	CompositionItem() The base class for all objects that represent an item within the Composition hierarchy.

Field Summary
Field Attributes	Field Name and Description
{object[]}	children An array of objects representing the children, if any, of this item.
{String}	completionType The "completion type" of this item.
{String}	failureText The failure text for this item, if any, otherwise null.
{anything}	forEachValue If this item is repeating due to a "for-each" repeat, this property contains the for-each value associated with this instance of the object.
{boolean}	hasErrorEvents True if this item has any error events.
{integer}	index The position (zero-based index) of this item within it's parent's array of children.
{String}	name The name of this item.
{object}	nextItem Returns the next item after this one in this item's parent's array of children, or null of this is the last item.
{object}	parent The parent item of this item.
{String}	path Returns the full property path for this item as specified for "In Situ Substitution Specifications" (see the separate documentation on ISSEs).
{integer}	playNumber An integer value that represents the "play ordinal number" of this item.
{integer}	playNumberBeforeRenewal If this item repeats in parallel with the "Renew parallel repeats" option enabled, this is an integer value that is the "playNumber" value of the original parallel repeat for this item if it has been renewed because a prior parallel repeat ended.
{integer}	playNumberWithinRenewal If this item repeats in parallel with the "Renew parallel repeats" option enabled, this is an integer value that is the ordinal of the current repeat within the sequence of repeat renewals.
{object}	previousItem Returns the previous item before this one in this item's parent's array of children, or null of this is the first item.
{PropertyList}	propertyList A PropertyList object that allows read and write access to all of the Custom Properties contained in this item.
<constant> {integer}	REPEAT_DISTRIBUTION_CONSTANT A constant that can be passed in calls to the "setRepeat" method.
<constant> {integer}	REPEAT_TIMING_PARALLEL A constant that can be passed in calls to the "setRepeat" method.
<constant> {integer}	REPEAT_TIMING_SERIAL A constant that can be passed in calls to the "setRepeat" method.
<constant> {integer}	REPEAT_TYPE_COUNT_CONSTANT A constant that can be passed in calls to the "setRepeat" method.
{integer}	repeatIndex An integer value that represents the "repeat index" of this item if it repeats, according to the context in which the current script is executing.
{SystemPropertyList}	systemPropertyList A SystemPropertyList object that allows read and write access to all of the Custom Properties contained in this item.
{String}	type A String that represents the type of this item.

Method Summary
Method Attributes	Method Name and Description
	clearRepeat() Removes any current repeating specification from this item (so that it will play exactly once).
	end(optionalErrorText) Requests that play of this item be terminated.
	endRepeat() Requests that repeating for this item be ended.
{object}	getChild(childName) Returns a specific child object by name.
{object}	getItemViaPath(pathType, propertyPath) Given a path to an item in the Composition object hierarchy, returns the object in the hierarchy that represents that item.
	setRepeat(timingType, repeatType, control, distributionType, distribution) Sets a new repeating specification for this item.

Class Detail

CompositionItem()

The base class for all objects that represent an item within the Composition hierarchy.

All of the objects that represent various types of items in the Composition derive from this base class.

Field Detail

{object[]} children

An array of objects representing the children, if any, of this item. Null if this item has no children

Read only.

When items repeat, a copy is made of the item and all of it's children for each repeat, so that repeats are isolated and changes made during play of the repeat do not affect other repeats.

If this method is called for an item that has children that are repeating, the returned list will contain only the original children and not the copies that were made for the repeats.

If this method is called for an item that is itself repeating, the list returned will be the copies of the children that were made for that repeat of the parent.

Care must be taken when traversing the Composition object hierarchy when items repeat. In order to refer to the copies within the current repeat hierarchy in which the calling Script resides, it is generally best to start at the current item and use positional properties such as the parent property and/or the $context.currentXXX properties to traverse the structure.

{String} completionType

The "completion type" of this item.

Will be one of the following values:

"Success"
"Stopped"
"Failed"
"Error" (Contained non-fatal errors, but still completed successfully.)

Until the item actually plays, "Success" will be returned. If the item never actually plays, it will remain as "Success".

Read only.

Since:: Build 5618

{String} failureText

The failure text for this item, if any, otherwise null.

Null until the item plays. If the item never plays, remains null.

Read only.

Since:: Build 5618

{anything} forEachValue

If this item is repeating due to a "for-each" repeat, this property contains the for-each value associated with this instance of the object. This will be a value in the array used for the for-each.

If this item is not repeating due to a "for-each" repeat, this property will be null.

Read only.

{boolean} hasErrorEvents

True if this item has any error events.

Note that an item may have error events even if it didn't "fail", and can have error events even if it doesn't actually play.

Read only.

Since:: Build 5618

{integer} index

The position (zero-based index) of this item within it's parent's array of children.

Read only.

{String} name

The name of this item.

An item's name can be changed by setting this property, with the following restrictions:

The name can only be changed before any activity has occurred for this item. It cannot have been started playing yet, cannot have started repeating yet, no other actions for it can have occurred yet (no other properties of it can have been set).
The name must be a legal item name (255 chars max, no square brackets or slashes), and must not be the same name as another item in the same container.

{object} nextItem

Returns the next item after this one in this item's parent's array of children, or null of this is the last item. In other words, returns the next sibling in the object hierarchy.

Equivalent to:

item.parent.children(item.index + 1)

where "item" is the current item.

Read only.

{object} parent

The parent item of this item.

Read only.

{String} path

Returns the full property path for this item as specified for "In Situ Substitution Specifications" (see the separate documentation on ISSEs). This is the full path from the Composition level.

Some example paths:

Band 1/Track 5
Band 1/Track 3/Clip A/Transaction 5/Browser Action 7
Band 1/Track 1[3]/Clip 5[2]/Message 1

Read only.

Since:: Build 5789

{integer} playNumber

An integer value that represents the "play ordinal number" of this item.

Starting with the number 0, each play is assigned a unique number. The numbers are contiguous (no gaps).

Play number sequences are maintained within the item's parent only. For example, if a parent item repeats, then the child items inside each repeat of the parent will have their own play number sequence starting at 0.

An item will only have a non-zero play number if it repeats. The play number is equivalent to the repeat index, except that the play number is 0 for items that don't repeat or have a repeat count of one, whereas the repeat index would be -1 in those cases.

Read only.

{integer} playNumberBeforeRenewal

If this item repeats in parallel with the "Renew parallel repeats" option enabled, this is an integer value that is the "playNumber" value of the original parallel repeat for this item if it has been renewed because a prior parallel repeat ended. If this is the original parallel repeat, the value of "playNumberNumberBeforeRenewal" will be equal to the value of "playNumber". If this item does not repeat in parallel, the value will be zero.

See also "playNumber", above.

For example, if parallel repeat number 5 of the item ends, but the "Renew parallel repeats" option is enabled, the ending repeat will be replaced with a new, replacement repeat. The new repeat will have new "repeatIndex" and "playNumber" values (according to how many other repeats have already occurred). However, the "playNumberBeforeRenewal" value will still be 5 in this example.

Read only.

{integer} playNumberWithinRenewal

If this item repeats in parallel with the "Renew parallel repeats" option enabled, this is an integer value that is the ordinal of the current repeat within the sequence of repeat renewals. For example, if this is the original repeat, this value will be zero, but if this is the third renewal of the original repeat this value will be 3.

If "Renew parallel repeats" is not enabled for this item, or it doesn't repeat in parallel, this value will always be zero.

Read only.

Since:: Build 5030

{object} previousItem

Returns the previous item before this one in this item's parent's array of children, or null of this is the first item. In other words, returns the next sibling in the object hierarchy.

Equivalent to:

item.parent.children(item.index - 1)

where "item" is the current item.

Read only.

{PropertyList} propertyList

A PropertyList object that allows read and write access to all of the Custom Properties contained in this item.

This property itself is read only.

<constant> {integer} REPEAT_DISTRIBUTION_CONSTANT

A constant that can be passed in calls to the "setRepeat" method. (See the description of the "setRepeat" method.)

Read only.

<constant> {integer} REPEAT_TIMING_PARALLEL

A constant that can be passed in calls to the "setRepeat" method. (See the description of the "setRepeat" method.)

Read only.

<constant> {integer} REPEAT_TIMING_SERIAL

A constant that can be passed in calls to the "setRepeat" method. (See the description of the "setRepeat" method.)

Read only.

<constant> {integer} REPEAT_TYPE_COUNT_CONSTANT

A constant that can be passed in calls to the "setRepeat" method. (See the description of the "setRepeat" method.)

Read only.

{integer} repeatIndex

An integer value that represents the "repeat index" of this item if it repeats, according to the context in which the current script is executing.

The first repeat starts at index zero.

The value is -1 if the current item does not repeat or has a repeat count of one (in other words, it is -1 if it doesn't actually repeat).

Read only.

{SystemPropertyList} systemPropertyList

A SystemPropertyList object that allows read and write access to all of the Custom Properties contained in this item.

This property itself is read only.

{String} type

A String that represents the type of this item.

Read only.

Method Detail

clearRepeat()

Removes any current repeating specification from this item (so that it will play exactly once).

end(optionalErrorText)

Requests that play of this item be terminated. If an optional error text string is provided, the item will be considered to have ended in error. If the item is not currently playing, no action is taken.

Note that this is not an "abort" -- play will be ended after any currently playing items(s) complete.

This call is supported only for Tracks, Clips, and containers within Clips.

Parameters:
{String} optionalErrorText Optional, Default: null: If an optional error text string is provided, the item will be considered to have ended in error.

endRepeat()

Requests that repeating for this item be ended. If this item is not currently playing, no action is taken.

Note that this is not an "abort" -- repeating will be ended after any currently playing individual repeat of the item completes.

This method is permitted only for serial repeating and for parallel repeating with the "renewal" option. It is not supported for parallel repeating without repeat renewal and an error will be generated if it is attempted to call this method for such a repeat.

For items that repeat serially, this call ends the serial repeating.

For items that repeat in parallel with "parallel repeat renewal", this call ends the renewals for the current sequence of parallel renewals, but does not affect other parallel renewal sequences. For example, consider the case of an item that repeats 3 times with parallel repeat renewal enabled. This item thus has 3 parallel renewal "lines" that are proceeding in parallel (there will always be 3 instances active at any given time). If this method is called from a Script that is playing from some repeat renewal that originated from the second repeat, then there will be no further renewals for the renewal line that started from the second repeat. However, renewals in the renewal lines that started from the first and third repeats will be unaffected.

This call is supported only for Bands, Tracks, Clips, and containers within Clips.

{object} getChild(childName)

Returns a specific child object by name.

When items repeat, a copy is made of the item and all of it's children for each repeat, so that repeats are isolated and changes made during play of the repeat do not affect other repeats.

If this method is called for an item that has children that are repeating, any child returned will be one of the original children and not the copy that was made for the repeats.

If this method is called for an item that is itself repeating, the child returned will be the copy of the child that was made for that repeat of the parent.

Parameters:
{String} childName: The name of the child to return.

Returns:: {object}
The object that represents the child, or null if there is no child with the given name.

{object} getItemViaPath(pathType, propertyPath)

Given a path to an item in the Composition object hierarchy, returns the object in the hierarchy that represents that item.

When items repeat, a copy is made of the item and all of it's children for each repeat, so that repeats are isolated and changes made during play of the repeat do not affect other repeats.

If the path refers to an item that has children that are repeating, or to an item that is itself repeating, any child returned may be one of the original children and not the copy that was made for the repeats, or may be a copy, depending upon the starting point of the given path.

Parameters:

{String} pathType

Specifies the "starting point" of the path, relative to this item. It can be any of the following values (case is not significant):

"Composition"
The path is relative to the Composition as a whole. (Therefore, the path must start with the name of a Band.)
"Band"
The path is relative to the current Band.
"Track"
The path is relative to the current Track.
"MessageClip" or "Clip" (either one is accepted)
The path is relative to the current Clip. If the item is nested within multiple Clips, the path is relative to the lowest-level containing Clip (the Clip "nearest to" the item in terms of the parentage hierarchy).
"Chain"
The path is relative to the current Chain. If the item is nested within multiple Chains, the path is relative to the lowest-level containing Chain (the Chain "nearest to" the item in terms of the parentage hierarchy).
"Group"
The path is relative to the current Group. If the item is nested within multiple Groups, the path is relative to the lowest-level containing Group (the Group "nearest to" the item in terms of the parentage hierarchy).
"Transaction"
The path is relative to the current Transaction. If the item is nested within multiple Transactions, the path is relative to the lowest-level containing Transaction (the Transaction "nearest to" the item in terms of the parentage hierarchy).
"If"
The path is relative to the current If. If the item is nested within multiple Ifs, the path is relative to the lowest-level containing If (the If "nearest to" the item in terms of the parentage hierarchy).
"Switch"
The path is relative to the current Switch. If the item is nested within multiple Switch, the path is relative to the lowest-level containing Switch (the Switch "nearest to" the item in terms of the parentage hierarchy).
"Page"
The path is relative to the current Page.

{String} propertyPath

Contains a property path as specified for "In Situ Substitution Specifications" (see the separate documentation on ISSEs).

Returns:: {object}
The object in the hierarchy that represents the item.

setRepeat(timingType, repeatType, control, distributionType, distribution)

Sets a new repeating specification for this item.

This method should not be used to terminate the repeating of an item that is currently playing and already repeating. To do that, use the endRepeat method. Calling this method for an item that is playing and is in the middle of repeating will, for the most part, have no effect.

Parameters:
{integer} timingType: Indicates which type of repeat timing is to be used. It must be one of the "REPEAT_TIMING_PARALLEL" or "REPEAT_TIMING_SERIAL" constants.
{integer} repeatType: Indicates what sort of value is contained in the "control" parameter. Currently must always be set to the "REPEAT_TYPE_COUNT_CONSTANT" constant.
{integer} control: The count of the number of repeats to be performed. If the value is less than or equal to zero, the item will not be played at all.
{integer} distributionType: Indicates what sort of value is contained in the "distribution" parameter. Currently must always be set to the "REPEAT_DISTRIBUTION_CONSTANT" constant.
{integer} distribution: The time length, in milliseconds, by which the start of each repeat is to be offset from the start of the prior repeat. This value only applies to parallel repeats, and must be set to zero for serial repeats.

Classes

Class CompositionItem