Layer object
app.project.item(index).layer(index)
The Layer object provides access to layers within compositions. It can be accessed from an item’s layer collection either by index number or by a name string.
- Layer is the base class for CameraLayer, LightLayer, and AVLayer, so Layer attributes and methods are available when working with all layer types. See “AVLayer object” on page 38, “CameraLayer object” on page 50, and “LightLayer object” on page 100. Layers contain AE properties, in addition to their JavaScript attributes and methods. For examples of how to access properties in layers, see “PropertyBase object” on page 148.
Example
If the first item in the project is a CompItem, this example disables the first layer in that composition and renames it. This might, for example, turn an icon off in the composition.
var firstLayer = app.project.item(1).layer(1);
firstLayer.enabled = false;
firstLayer.name = "Disabled Layer";
Attributes
| Attribute | Reference | Description |
|---|---|---|
| index | “Layer index attribute” on page 90 | The index position of the layer. |
| name | “Layer name attribute” on page 92 | The name of the layer. |
| parent | “Layer parent attribute” on page 92 | The parent of this layer. |
| time | “Layer time attribute” on page 94 | The current time of the layer. |
| startTime | “Layer startTime attribute” on page 94 | The start time of the layer. |
| stretch | “Layer stretch attribute” on page 94 | The time stretch percentage of the layer. |
| inPoint | “Layer inPoint attribute” on page 90 | The “in” point of the layer. |
| outPoint | “Layer outPoint attribute” on page 92 | The “out” point of the layer. |
| enabled | “Layer enabled attribute” on page 89 | When true, the layer is enabled. |
| solo | “Layer solo attribute” on page 94 | When true, the layer is soloed. |
| shy | “Layer shy attribute” on page 93 | When true, the layer is shy. |
| locked | “Layer locked attribute” on page 90 | When true, the layer is locked. |
| hasVideo | “Layer hasVideo attribute” on page 89 | When true, the layer contains a video component. |
| active | “Layer active attribute” on page 87 | When true, the layer is active at the current time. |
| nullLayer | “Layer nullLayer attribute” on page 92 | When true, this is a null layer. |
| selectedProperties | “Layer selectedProperties attribute” on page 93 | All selected AE properties in the layer. |
| comment | “Layer comment attribute” on page 88 | A descriptive comment for the layer. |
| containingComp | “Layer containingComp attribute” on page 88 | The composition that contains this layer. |
| isNameSet | “Layer isNameSet attribute” on page 90 | When true, the layer’s name has been explicitly set. |
Methods
| Method | Reference | Description |
|---|---|---|
| remove() | “Layer remove() method” on page 93 | Deletes the layer from the composition. |
| moveToBeginning() | “Layer moveToBeginning() method” on page 91 | Moves the layer to the top of the composition (makes it the first layer). |
| moveToEnd() | “Layer moveToEnd() method” on page 91 | Moves the layer to the bottom of the composition (makes it the last layer). |
| moveAfter() | “Layer moveAfter() method” on page 90 | Moves the layer below another layer. |
| moveBefore() | “Layer moveBefore() method” on page 91 | Moves the layer above another layer. |
| duplicate() | “Layer duplicate() method” on page 89 | Duplicates the layer. |
| copyToComp() | “Layer copyToComp() method” on page 89 | Copies the layer to the top (beginning) of another composition. |
| activeAtTime() | “Layer activeAtTime() method” on page 87 | Reports whether this layer will be active at a specified time. |
| setParentWithJump() | “Layer setParentWithJump() method” on page 93 | Sets a new parent for this layer. |
| applyPreset() | “Layer applyPreset() method” on page 88 | Applies a named collection of animation settings to the layer. |
active attribute
app.project.item(index).layer(index).active
When true, the layer's video is active at the current time. For this to be true, the layer must be enabled, no other layer may be soloing unless this layer is soloed too, and the time must be between the inPoint and outPoint values of this layer. This value is never true in an audio layer; there is a separate audioActive attribute in the AVLayer object.
Type: Boolean read-only
activeAtTime() method
app.project.item(index).layer(index).activeAtTime(time)
Returns true if this layer will be active at the specified time. To return true, the layer must be enabled, no other layer may be soloing unless this layer is soloed too, and the time must be between the inPoint and outPoint values of this layer.
Parameters:
- time The time in seconds, a floating-point value.
Returns: Boolean
applyPreset() method
appapp.project.item(index).layer(index).applyPreset(presetName);
Applies the specified collection of animation settings (an animation preset) to the layer. Predefined animation preset files are installed in the Presets folder, and users can create new animation presets through the user interface.
Parameters:
- presetName An ExtendScript File object for the file containing the animation preset.
Returns: Nothing.
comment attribute
app.project.item(index).layer(index).comment
A descriptive comment for the layer.
Type: String read/write
containingComp attribute
app.project.item(index).layer(index).containingComp
The composition that contains this layer.
Type: CompItem object; read-only.
copyToComp() method
app.project.item(index).layer(index).copyToComp(intoComp)
Copies the layer into the specified composition. The original layer remains unchanged. Creates a new Layer object with the same values as this one, and prepends the new object to the layers collection in the target CompItem. Retrieve the copy using intoComp.layer(1). Copying in a layer changes the index positions of previously existing layers in the target composition. This is the same as copying and pasting a layer through the user interface.
Parameters:
- intoComp The target composition, and CompItem object.
Returns: Nothing.
duplicate() method
app.project.item(index).layer(index).duplicate()
Duplicates the layer. Creates a new Layer object in which all values are the same as in this one. This has the same effect as selecting a layer in the user interface and choosing Edit > Duplicate, except the selection in the user interface does not change when you call this method.
Parameters: None.
Returns: Layer object
enabled attribute
app.project.item(index).layer(index).enabled
When true, the layer is enabled; otherwise false. This corresponds to the video switch state of the layer in the Timeline panel.
Type: Boolean read/write
hasVideo attribute
app.project.item(index).layer(index).hasVideo
When true, the layer has a video switch (the eyeball icon) in the Timeline panel; otherwise false.
Type: Boolean read-only
index attribute
app.project.item(index).layer(index).index
The index position of the layer.
Type: Integer in the range [1..numLayers] read-only
inPoint attribute
app.project.item(index).layer(index).inPoint
The “in” point of the layer, expressed in composition time (seconds).
Type Floating-point value in the range [-10800.0..10800.0] minus or plus three hours read/write
isNameSet attribute
app.project.item(index).layer(index).isNameSet
True if the value of the name attribute has been set explicitly, rather than automatically from the source.
Type: Boolean read-only
locked attribute
app.project.item(index).layer(index).locked
When true, the layer is locked; otherwise false. This corresponds to the lock toggle in the Layer panel.
Type: Boolean read/write
moveAfter() method
app.project.item(index).layer(index).moveAfter(layer)
Moves this layer to a position immediately after (below) the specified layer.
Parameters:
- layer The target layer, a layer object in the same composition.
Returns: Nothing.
moveBefore() method
app.project.item(index).layer(index).moveBefore(layer)
Moves this layer to a position immediately before (above) the specified layer.
Parameters:
- layer The target layer, a layer object in the same composition.
Returns: Nothing.
moveToBeginning() method
app.project.item(index).layer(index).moveToBeginning()
Moves this layer to the topmost position of the layer stack (the first layer).
Parameters: None.
Returns: Nothing.
moveToEnd() method
app.project.item(index).layer(index).moveToEnd()
Moves this layer to the bottom position of the layer stack (the last layer).
Parameters: None.
Returns: Nothing.
name attribute
app.project.item(index).layer(index).name
Description
The name of the layer. By default, this is the same as the Source name (which cannot be changed in the Layer
panel), but you can set it to be different.
Type
String; read/write.
nullLayer attribute
app.project.item(index).layer(index).nullLayer
When true, the layer was created as a null object; otherwise false.
Type: Boolean read-only
outPoint attribute
app.project.item(index).layer(index).outPoint
The “out” point of the layer, expressed in composition time (seconds).
Type: Floating-point value in the range [-10800.0..10800.0] minus or plus three hours read/write
parent attribute
app.project.item(index).layer(index).parent
The parent of this layer; can be null. Offset values are calculated to counterbalance any transforms above this layer in the hierarchy, so that when you set the parent there is no apparent jump in the layer's transform. For example, if the new parent has a rotation of 30 degrees, the child layer is assigned a rotation of -30 degrees. To set the parent without changing the child layer's transform values, use the setParentWithJump method.
Type: Layer object or null read/write
remove() method
app.project.item(index).layer(index).remove()
Deletes the specified layer from the composition.
Parameters: None.
Returns: Nothing
selectedProperties attribute
app.project.item(index).layer(index).selectedProperties
An array containing all of the currently selected Property and PropertyGroup objects in the layer.
Type: Array of PropertyBase objects; read-only.
setParentWithJump() method
app.project.item(index).layer(index).setParentWithJump()
app.project.item(index).layer(index).setParentWithJump(newParent)
Sets the parent of this layer to the specified layer, without changing the transform values of the child layer. There may be an apparent jump in the rotation, translation, or scale of the child layer, as this layer’s transform values are combined with those of its ancestors. If you do not want the child layer to jump, set the parent attribute directly. In this case, an offset is calculated and set in the child layer's transform fields, to prevent the jump from occurring.
Parameters:
- newParent Optional a layer object in the same composition. If not specified, it sets the parent to None.
Returns: Nothing.
shy attribute
app.project.item(index).layer(index).shy
When true, the layer is “shy,” meaning that it is hidden in the Layer panel if the composition’s “Hide all shy layers” option is toggled on.
Type: Boolean read/write
solo attribute
app.project.item(index).layer(index).solo
When true, the layer is soloed, otherwise false.
Type: Boolean read/write
startTime attribute
app.project.item(index).layer(index).startTime
The start time of the layer, expressed in composition time (seconds).
Type: Floating-point value in the range [-10800.0..10800.0] minus or plus three hours read/write
stretch attribute
app.project.item(index).layer(index).stretch
The layer’s time stretch, expressed as a percentage. A value of 100 means no stretch. Values between 0 and 1 are set to 1, and values between -1 and 0 (not including 0) are set to -1.
Type: Floating-point value in the range [-9900.0..9900.0] read/write
time attribute
app.project.item(index).layer(index).time
The current time of the layer, expressed in composition time (seconds).
Type Floating-point value read-only