PropertyBase object
app.project.item(index).layer(index).propertySpec
Properties are accessed by name through layers, using various kinds of expression syntax, as controlled by application preferences. For example, the following are all ways of access properties in the Effects group:
var effect1 = app.project.item(1).layer(1).effect("Add Grain")("Viewing Mode");
var effect1again = app.project.item(1).layer(1).effect.addGrain.viewingMode;
var effect1againtoo = app.project.item(1).layer(1)("Effects").addGrain.viewingMode;
var effect1againtoo2 = app.project.item(1).layer(1)("Effects")("Add Grain")("Viewing Mode");
See also “PropertyGroup property() method” on page 157.
- PropertyBase is the base class for both Property and PropertyGroup, so PropertyBase attributes and methods are available when working with properties and property groups. See “Property object” on page 124 and “PropertyGroup object” on page 155.
Reference invalidation
When something occurs that changes an object sufficiently for the reference to become invalid, script refer- ences to that object can generate errors. In simple cases this is straightforward. For example, if you delete an object, a reference to the deleted object generates the warning "Object is Invalid":
var layer1 = app.project.item(1).layer(1);
layer1.remove();
alert(layer1.name); // invalid reference to deleted object
Similarly, if you reference an AE property in a deleted object, the warning occurs:
var layer1 = app.project.item(1).layer(1);
var layer1position = layer1.transform.position;
layer1.remove();
alert(layer1position.value); // invalid reference to property in selected object
A less straightforward case is when a property is removed from a property group. In this case, After Effects generates the "Object is Invalid" error when you subsequently reference that item or other items in the group, because their index positions have changed. For example:
var effect1 = app.project.item(1).layer(1).effect(1);
var effect2 = app.project.item(1).layer(1).effect(2);
var effect2param = app.project.item(1).layer(1).effect(2).blendWithOriginal;
effect1.remove();
alert(effect2.name); // invalid reference because group index positions have changed
Attribute List
| Attribute | Reference | Description |
|---|---|---|
| name | “PropertyBase name attribute” on page 152 | Name of the property. |
| matchName | “PropertyBase matchName attribute” on page 152 | A special name for the property used to build unique naming paths. |
| propertyIndex | “PropertyBase propertyIndex attribute” on page 153 | Index of this property within its parent group. |
| propertyDepth | “PropertyBase propertyDepth attribute” on page 153 | The number of levels of parent groups between this property and the containing layer. |
| propertyType | “PropertyBase propertyType attribute” on page 154 | The property type. |
| parentProperty | “PropertyBase parentProperty attribute” on page 153 | The immediate parent group of this property. |
| isModified | “PropertyBase isModified attribute” on page 151 | When true, the property has been changed since its creation. |
| canSetEnabled | “PropertyBase canSetEnabled attribute” on page 150 | When true, the user interface displays an eyeball icon for this property. |
| enabled | “PropertyBase enabled attribute” on page 151 | When true, this property is enabled. |
| active | “PropertyBase active attribute” on page 149 | When true, this property is active. |
| elided | “PropertyBase elided attribute” on page 150 | When true, this property is not displayed in the user interface. |
| isEffect | “PropertyBase isEffect attribute” on page 151 | When true, this property is an effect. |
| isMask | “PropertyBase isMask attribute” on page 151 | When true, this property is a mask. |
| selected | “PropertyBase selected attribute” on page 154 | When true, this property is selected. |
Method List
| Method | Reference | Description |
|---|---|---|
| propertyGroup() | “PropertyBase propertyGroup() method” on page 153 | Gets the parent group for this property. |
| remove() | “PropertyBase remove() method” on page 154 | Removes this from the project. |
| moveTo() | “PropertyBase moveTo() method” on page 152 | Moves this property to a new position in its parent group. |
| duplicate() | “PropertyBase duplicate() method” on page 150 | Duplicates this property object. |
active attribute
app.project.item(index).layer(index).propertySpec.active
When true, this property is active. For a layer, this corresponds to the setting of the eyeball icon and if the current time is between the layer’s in and out points. For an effect and all properties, it is the same as the enabled attribute, except that it’s **read-only
Type: Boolean read-only
canSetEnabled attribute
app.project.item(index).layer(index).propertySpec.canSetEnabled
When true, you can set the enabled attribute value. Generally, this is true if the user interface displays an eyeball icon for this property; it is true for all layers.
Type: Boolean read-only
duplicate() method
app.project.item(index).layer(index).propertySpec.duplicate()
If this property is a child of an indexed group, creates and returns a new PropertyBase object with the same attribute values as this one. If this property is not a child of an indexed group, the method generates an exception and displays an error. An indexed group has the type PropertyType.INDEXED_GROUP; see “PropertyBase propertyType attribute” on page 154.
Paramters: None.
Returns: PropertyBase object.
elided attribute
app.project.item(index).layer(index).propertySpec.elided
When true, this property is a group used to organize other properties. The property is not displayed in the user interface and its child properties are not indented in the Timeline panel.
For example, for a text layer with two animators and no properties twirled down, you might see:
- Text
- Path Options
- More Options
- Animator 1
- Animator 2
In this example, “Animator 1” and “Animator 2” are contained in a PropertyBase called “Text Animators.” This parent group is not displayed in the user interface, and so the two child properties are not indented in the Timeline panel.
Type: Boolean read-only
enabled attribute
app.project.item(index).layer(index).propertySpec.enabled
When true, this property is enabled. It corresponds to the setting of the eyeball icon, if there is one; otherwise, the default is true.
Type: Boolean read/write if canSetEnabled is true, read-only if canSetEnabled is false.
isEffect attribute
app.project.item(index).layer(index).propertySpec.isEffect
When true, this property is an effect PropertyGroup.
Type: Boolean read-only
isMask attribute
app.project.item(index).layer(index).propertySpec.isMask
When true, this property is a mask PropertyGroup.
Type: Boolean read-only
isModified attribute
app.project.item(index).layer(index).propertySpec.isModified
When true, this property has been changed since its creation.
Type: Boolean read-only
matchName attribute
app.project.item(index).layer(index).propertySpec.matchName
A special name for the property used to build unique naming paths. The match name is not displayed, but you can refer to it in scripts. Every property has a unique match-name identifier. Match names are stable from version to version regardless of the display name (the name attribute value) or any changes to the application. Unlike the display name, it is not localized.
An indexed group may not have a name value, but always has a matchName value. (An indexed group has the type PropertyType.INDEXED_GROUP; see “PropertyBase propertyType attribute” on page 154.)
Type: String read-only
moveTo() method
app.project.item(index).layer(index).propertySpec.moveTo(newIndex)
Moves this property to a new position in its parent property group. This method is valid only for children of indexed groups; if it is not, or if the index value is not valid, the method generates an exception and displays an error. (An indexed group has the type Proper- tyType.INDEXED_GROUP; see “PropertyBase propertyType attribute” on page 154.)
NOTE: Using this method invalidates existing references to other children in the same indexed group. For example, if you have three effects on a layer, each effect assigned to a different variable, moving one of the effects invalidates the references for all of these variables. You will need to reassign them.
Paramters:
- newIndex The new index position at which to place this property in its group. An integer.
Returns: Nothing.
name attribute
app.project.item(index).layer(index).propertySpec.name
The display name of the property. (Compare “PropertyBase matchName attribute” on page 152.) It is an error to set the name value if the property is not a child of an indexed group (that is, a property group that has the type PropertyType.INDEXED_GROUP; see “PropertyBase propertyType attribute” on page 154).
Type: String read/write for a child of an indexed group; otherwise read-only
parentProperty attribute
app.project.item(index).layer(index).propertySpec.parentProperty
The property group that is the immediate parent of this property, or null if this PropertyBase is a layer.
Type: PropertyGroup object or null read-only
propertyDepth attribute
app.project.item(index).layer(index).propertySpec.propertyDepth
The number of levels of parent groups between this property and the containing layer. The value 0 for a layer.
Type: Integer read-only
propertyGroup() method
app.project.item(index).layer(index).propertySpec.propertyGroup()
app.project.item(index).layer(index).propertySpec.propertyGroup(countUp)
Gets the PropertyGroup object for an ancestor group of this property at a specified level of the parent-child hierarchy.
Paramters:
- countUp Optional. The number of levels to ascend within the parent-child hierarchy. An integer in the range [1..propertyDepth]. Default is 1, which gets the immediate parent.
Returns: PropertyGroup object, or null if the count reaches the containing layer.
propertyIndex attribute
app.project.item(index).layer(index).propertySpec.propertyIndex
The position index of this property within its parent group, if it is a child of an indexed group (a property group that has the type PropertyType.INDEXED_GROUP; see “PropertyBase propertyType attribute” on page 154).
Type: Integer read-only
propertyType attribute
app.project.item(index).layer(index).propertySpec.propertyType
The type of this property.
Type: A PropertyType enumerated value read/write One of:
- PropertyType.PROPERTY A single property such as position or zoom.
- PropertyType.INDEXED_GROUP A property group whose members have an editable name and an index. Effects and masks are indexed groups. For example, the masks property of a layer refers to a variable number of individual masks by index number.
- PropertyType.NAMED_GROUP A property group in which the member names are not editable. Layers are named groups.
remove() method
app.project.item(index).layer(index).propertySpec.remove()
Removes this property from its parent group. If this is a property group, it removes the child properties as well. This method is valid only for children of indexed groups; if it is not, or if the index value is not valid, the method generates an exception and displays an error. (An indexed group has the type Proper- tyType.INDEXED_GROUP; see “PropertyBase propertyType attribute” on page 154.) This method can be called on a text animation property (that is, any animator that has been set to a text layer).
Paramters: None.
Returns: Nothing.
selected attribute
app.project.item(index).layer(index).propertySpec.selected
When true, this property is selected. Set to true to select the property, or to false to deselect it. Sampling this attribute repeatedly for a large number of properties can slow down system performance. To read the full set of selected properties of a composition or layer, use the selectedProperties attribute of a Comp or Layer object.
Type: Boolean read/write.