LayerCollection object

app.project.item(index).layers

Description

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 object. All methods and attributes of Collection, in addition to those listed below, are available when working with LayerCollection.

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

Methods

LayerCollection.add()

app.project.item(index).layers.add(item[, duration])

Description

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 du r at i on 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;


LayerCollection.addBoxText()

app.project.item(index).layers.addBoxText([width, height])

Description

Creates a new paragraph (box) text layer with TextDocument.lineOrientation set to LineOrientation.HORIZONTAL and adds the new TextLayer object to this collection. To create a point text layer, use the LayerCollection.addText() method.

Parameters

[width, height]

An Array containing the dimensions of the new text box.

Returns

TextLayer object.


LayerCollection.addCamera()

app.project.item(index).layers.addCamera(name, centerPoint)

Description

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.


LayerCollection.addLight()

app.project.item(index).layers.addLight(name, centerPoint)

Description

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.


LayerCollection.addNull()

app.project.item(index).layers.addNull([duration])

Description

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


LayerCollection.addShape()

app.project.item(index).layers.addShape()

Description

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.


LayerCollection.addSolid()

app.project.item(index).layers.addSolid(color, name, width, height, pixelAspect[, duration])

Description

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 Footage Item 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 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 (MacOS), and specify options under Still Footage.

Returns

AVLayer object.


LayerCollection.addText()

app.project.item(index).layers.addText([sourceText])

Description

Creates a new point text layer with TextDocument.lineOrientation set to LineOrientation.HORIZONTAL and adds the new TextLayer object to this collection. To create a paragraph (box) text layer, use LayerCollection.addBoxText().

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.

Returns

TextLayer object.


LayerCollection.addVerticalBoxText()

app.project.item(index).layers.addVerticalBoxText([width, height])

Note

This functionality was added in After Effects 24.2.

Description

Creates a new paragraph (box) text layer with TextDocument.lineOrientation set to LineOrientation.VERTICAL_RIGHT_TO_LEFT and adds the new TextLayer object to this collection. To create a point text layer, use the LayerCollection.addText() or LayerCollection.addVerticalText() methods.

Parameters

[width, height]

An Array containing the dimensions of the new text box.

Returns

TextLayer object.


LayerCollection.addVerticalText()

app.project.item(index).layers.addVerticalText([sourceText])

Note

This functionality was added in After Effects 24.2.

Description

Creates a new point text layer with TextDocument.lineOrientation set to LineOrientation.VERTICAL_RIGHT_TO_LEFT and adds the new TextLayer object to this collection. To create a paragraph (box) text layer, use the LayerCollection.addBoxText() or LayerCollection.addVerticalBoxText() methods.

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.

Returns

TextLayer object.


LayerCollection.byName()

app.project.item(index).layers.byName(name)

Description

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.


LayerCollection.precompose()

app.project.item(index).layers.precompose(layerIndicies, name[, moveAllAttributes])

Description

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.