Knowledge Base

Clip Object

by Community Manager on 07-07-2011 08:55 AM - last edited on 09-16-2011 08:08 AM

Represents a Test Clip within the Composition.

Clip Properties

  • name (string)

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 the given item. The item cannot have started playing yet, cannot have started repeating yet, and no other actions for it can have occurred yet (e.g. no other properties of it can have been set).
  • The name specified by the script must, of course, 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.

All of the following Clip properties are read-only:

  • parent (object)

The parent Track.

  • propertyList (object)

A PropertyList object that allows access to all of the Custom Properties contained in this Clip.

  • systemPropertyList (read only – object)

A SystemPropertyList object that allows access to all of the System Properties contained in this object.

  • type (string)

The string "MessageClip".

  • children (array of objects)

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

  • targets (array of objects)

An array of Target objects representing all of the Targets referenced by this Clip.  Null if there are no Targets.

  • index (read only – integer)

Returns the position (zero-based index) of this item’s parent’s array of children.

  • nextItem (read only – object)

Returns the next item after this one in this item’s parent’s array of children, or null if 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.

  • previousItem (read only – object)

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.

  • forEachValue (read only – string, number, date/time, or null)

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.

  • repeatIndex (read only – integer)

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).

  • playNumber (read only – integer)

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.

  • playNumberBeforeRenewal (read only – integer)

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 playNumberBeforeRenewal will be equal to the value of playNumber. If this item does not repeat in parallel, the value will be zero.

For example, if parallel repeat number 5 of the item ends, but the Renew parallel repeats checkbox 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.

This property is always 0 for Composition, Checkpoint, Delay, and Target.

  • REPEAT_TIMING_PARALLEL (read only – int)

 

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

  • REPEAT_TIMING_SERIAL (read only – int)

 

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

  • REPEAT_TYPE_COUNT_CONSTANT (read only – int)

 

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

  • REPEAT_DISTRIBUTION_CONSTANT (read only – int)

 

A constant that can be passed in calls to the "setRepeat" method.  (See the description of the "setRepeat" method.)
  • dynamicResourceCache (readable and settable – array of Strings)

If Dynamic-resource Caching is enabled for the Clip, this property contains the list of URLs currently in the cache.  This list changes as Pages are played and dynamic resources are extracted from responses to the Main Message.

The value is null if the Dynamic-Resource Cache is not enabled, or if the cache is empty.

This property can be set to replace the entire cache.  This can be done to modify the existing list of URLs, or to create an entirely new list of URLs.

The value of the property is an array of Strings.  Each String is the fully-qualified URL of a Page dynamic resource.  The list that is returned is sorted.  Any new list that is provided need not be sorted.  Null entries in any new list provided are ignored.

  

Here is an example Script that retrieves the current cache and displays it in the Result:

var urls = $context.currentClip.dynamicResourceCache;
if (urls == null)
{
  $context.result.postMessage($context.result.LEVEL_INFO, "Cache is empty.");
}
else
{
  var text = "";
  for each (var url in urls))
  {
    text += url + "\n";
  }

  $context.result.postMessage($context.result.LEVEL_INFO, urls.length + " URLs", text);
}

Here is an example Script that replaces the entire current cache with a new list that contains two URLs:

var newList = new Array();

newList[0] = "http://somewhere.com/somepage.html";
newList[1] = "http://someplace.com/index.html";

$context.currentClip.dynamicResourceCache = newList;

Here is an example Script that removes a specific URL from the cache, if it is there:

var list = $context.currentClip.dynamicResourceCache;

if (list != null)
{
  for (var i = 0; i < list.length; i++)
  {
    if (list[i] == "http://somewhere.com/somepage.html")
    {
      list[i] = null;
      $context.currentClip.dynamicResourceCache = list;
      $context.result.postMessage($context.result.LEVEL_INFO, "URL removed.");
      break;
    }
  }
}

Here is an example Script that adds a new URL to the current cache:

var list = $context.currentClip.dynamicResourceCache;

if (list == null)
  list = new Array();

list[list.length] = "http://somewhere.com/somepage.html";

   $context.currentClip.dynamicResourceCache = list;

Clip Methods

getChild

Returns a specific child object by name, or null if there is no child with the specified name.

object getChild(string childName)

getTarget Method

Returns a specific Target object by name, or null if there is no Target with the specified name.

object getTarget(string targetName)

getItemViaPath Method

Given a type of item and the path to that item in the Composition object hierarchy, returns the object in the hierarchy that represents that item.

The "itemType" parameter value indicates the type of item (not case sensitive):

  • "Composition"
  • "Band"
  • "Track"
  • "Clip"
  • "Chain"
  • "Message"
  • "Browser Action"
  • "Delay"
  • "Checkpoint"
  • "Target"

The "path" parameter contains a path as specified for In Situ Substitution Specifications.  The path can be relative to the current item (for example to specify another item in the same Clip, the Band, Track and Clip portions of the path can be omitted).


object getItemViaPath(string itemType, string path)

clearRepeat

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

 

 void clearRepeat()

setRepeat Method

Sets a new repeating specification for this item.

The "timingType" parameter indicates which type of repeat timing is to be used.  It must be one of the following values:

  • REPEAT_TIMING_PARALLEL
  • REPEAT_TIMING_SERIAL
  • The "repeatType" parameter indicates what sort of value is contained in the "control" parameter.  Currently the "repeatType" parameter must always be set to "REPEAT_TYPE_COUNT_CONSTANT".
  • The "control" parameter is 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.
  • The "distributionType" parameter indicates what sort of value is contained in the "distribution" parameter.  Currently the "distributionType" parameter must always be set to "REPEAT_DISTRIBUTION_CONSTANT".
  • The "distribution" parameter is a 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.
 void setRepeat(int timingType, intRepeat Type, long control, int distributionType, long distribution)

 

end Method

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

Note that this is not an “abort” – play will be ended after any currently playing item(s) in the Clip complete.

void end(String optionalErrorText)

endRepeat Method

Requests that repeating for this Clip be ended.  If this Clip 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 Clip completes.

This method is permitted for serial repeating only, it is not supported for parallel repeating and an error will be generated if it is attempted to call this method for a parallel repeat.

void endRepeat()

0