LayerCollection object
app.project.item(index).layers
The LayerCollection object represents a set of layers. The LayerCollection belonging to a CompItem object contains all the layer objects for layers in the composition. The methods of the collection object allow you to manipulate the layer list.
- LayerCollection is a subclass of Collection. All methods and attributes of Collection, in addition to those listed below, are available when working with LayerCollection. See “Collection object” on page 51.
Example
Given that the first item in the project is a CompItem and the second item is an AVItem, this example shows the number of layers in the CompItem's layer collection, adds a new layer based on an AVItem in the project, then displays the new number of layers.
var firstComp = app.project.item(1);
var layerCollection = firstComp.layers;
alert("number of layers before is " + layerCollection.length);
var anAVItem = app.project.item(2);
layerCollection.add(anAVItem);
alert("number of layers after is " + layerCollection.length);
Method List
| Method | Reference | Description |
|---|---|---|
| add() | “LayerCollection add() method” on page 96 | Creates a new AVLayer and adds it to this collection. |
| addNull() | “LayerCollection addNull() method” on page 97 | Creates a new, null layer and adds it to this collection. |
| addSolid() | “LayerCollection addSolid() method” on page 98 | Creates a new layer, a FootageItem with a SolidSource, and adds it to this collection. |
| addText() | “LayerCollection addText() method” on page 98 | Creates a new point text layer and adds it to this collection. |
| addBoxText() | “LayerCollection addBoxText() method” on page 96 | Creates a new paragraph (box) text layer and adds it to this collection. |
| addCamera() | “LayerCollection addCamera() method” on page 96 | Creates a new camera layer and adds it to this collection. |
| addLight() | “LayerCollection addLight() method” on page 97 | Creates a new light layer and adds it to this collection. |
| addShape() | “LayerCollection addShape() method” on page 97 | Creates a new shape layer and adds it to this collection. |
| byName() | “LayerCollection byName() method” on page 99 | Retrieves the layer object with a specified name. |
| precompose() | “LayerCollection precompose() method” on page 99 | Collects specified layers into a new composition. |
Detailed Descriptions
add() method
app.project.item(index).layers.add(item, duration)
Creates a new AVLayer object containing the specified item, and adds it to this collection. The new layer honors the Create Layers at Composition Start Time preference. This method generates an exception if the item cannot be added as a layer to this CompItem.
Parameters:
- item The AVItem object for the item to be added.
- duration Optional the length of a still layer in seconds, a floating-point value. Used only if the item contains a piece of still footage. Has no effect on movies, sequences or audio. If supplied, sets the duration value of the new layer. Otherwise, the duration value is set according to user preferences. By default, this is the same as the duration of the containing CompItem. To set another preferred value, choose Edit > Preferences > Import (Windows) or After Effects > Preferences > Import (Mac OS), and specify options under Still Footage.
Returns: AVLayer object
addBoxText() method
app.project.item(index).layers.addBoxText(sourceText)
Creates a new paragraph (box) text layer and adds the new TextLayer object to this collection. To create a point text layer, use the addText() method. For more information, see “LayerCollection addText() method” on page 98.
Parameters:
- sourceText Optional a string containing the source text of the new layer, or a TextDocument object containing the source text of the new layer. See “TextDocument object” on page 182.
Returns: TextLayer object
addCamera() method
app.project.item(index).layers.addCamera(name, centerPoint)
Creates a new camera layer and adds the CameraLayer object to this collection.
The new layer honors the Create Layers at Composition Start Time preference.
Parameters:
- name A string containing the name of the new layer.
- centerPoint The center of the new camera, a floating-point array [x, y]. This is used to set the initial x and y values of the new camera’s Point of Interest property. The z value is set to 0.
Returns: CameraLayer object
addLight() method
app.project.item(index).layers.addLight(name, centerPoint)
Creates a new light layer and adds the LightLayer object to this collection.
The new layer honors the Create Layers at Composition Start Time preference.
Parameters:
- name A string containing the name of the new layer.
- centerPoint The center of the new light, a floating-point array [x, y].
Returns: LightLayer object.
addNull() method
app.project.item(index).layers.addNull(duration)
Creates a new null layer and adds the AVLayer object to this collection. This is the same as choosing Layer > New > Null Object.
Parameters:
-
duration Optional the length of a still layer in seconds, a floating-point value.
If supplied, sets the duration value of the new layer. Otherwise, the duration value is set according to userpreferences. By default, this is the same as the duration of the containing CompItem. To set another preferredvalue, choose Edit > Preferences > Import (Windows) or After Effects > Preferences > Import (Mac OS), and specifyoptions under Still Footage.
Returns: AVLayer object
addShape() method
app.project.item(index).layers.addShape()
Creates a new ShapeLayer object for a new, empty Shape layer. Use the ShapeLayer object to add properties, such as shape, fill, stroke, and path filters. This is the same as using a shape tool in "Tool Creates Shape" mode. Tools automatically add a vector group that includes Fill and Stroke as specified in the tool options.
Parameters: None.
Returns: ShapeLayer object
addSolid() method
app.project.item(index).layers.addSolid(color, name, width, height, pixelAspect, duration)
Creates a new SolidSource object, with values set as specified; sets the new SolidSource as the mainSource value of a new FootageItem object, and adds the FootageItem to the project. Creates a new AVLayer object, sets the new FootageItem as its source, and adds the layer to this collection.
Parameters:
- color The color of the solid, an array of three floating-point values, [R, G, B], in the range [0.0..1.0].
- name A string containing the name of the solid.
- width The width of the solid in pixels, an integer in the range [4..30000].
- height The height of the solid in pixels, an integer in the range [4..30000].
- pixelAspect The pixel aspect ratio of the solid, a floating-point value in the range [0.01..100.0].
-
duration Optional the length of a still layer in seconds, a floating-point value.
If supplied, sets the duration value of the new layer. Otherwise, the duration value is set according touser preferences. By default, this is the same as the duration of the containing CompItem. To set anotherpreferred value, choose Edit > Preferences > Import (Windows) or After Effects > Preferences > Import (MacOS), and specify options under Still Footage.
Returns: AVLayer object
addText() method
app.project.item(index).layers.addText(sourceText)
Creates a new point text layer and adds the new TextLayer object to this collection. To create a paragraph (box) text layer, use the addBoxText() method. For more information, see “LayerCol- lection addBoxText() method” on page 96.
Parameters:
- sourceText Optional a string containing the source text of the new layer, or a TextDocument object containing the source text of the new layer. See “TextDocument object” on page 182.
Returns: TextLayer object
byName() method
app.project.item(index).layers.byName(name)
Returns the first (topmost) layer found in this collection with the specified name, or null if no layer with the given name is found.
Parameters:
- name A string containing the name.
Returns: Layer object or null
precompose() method
app.project.item(index).layers.precompose(layerIndicies, name, moveAllAttributes)
Creates a new CompItem object and moves the specified layers into its layer collection. It removes the individual layers from this collection, and adds the new CompItem to this collection.
Parameters:
- layerIndices The position indexes of the layers to be collected. An array of integers.
- name The name of the new CompItem object.
-
moveAllAttributes Optional. When true (the default), retains all attributes in the new composition.
This is the same as selecting the “Move all attributes into the new composition” option in the Pre-compose dialog box. You can only set this to false if there is just one index in the layerIndices array. This is the same as selecting the “Leave all attributes in” option in the Pre-compose dialog box.
Returns: CompItem object.