redefinery

Effects

This section describes how to work with effects on a layer. The following topics are covered:

Also available is the Effect Match Names Reference.


Checking if a layer can have effects applied

Some types of layers, such as cameras and lights, do not use effects. Before you apply an effect to a layer, first check that the layer can accept effects. Although you can check the layer’s type for supported layers, a more future-proof way is checking if the layer has an Effects property group (PropertyGroup object).

The following code shows how to check a layer for an Effects property group and if the effect (in this example, Levels) can be applied.

// given:
// layer = Layer object
//
var effectsGroup = layer("Effects");             // Get the PropertyGroup for the effects
// This PropertyGroup can also be retrieved by using 
// layer.property("Effects") or layer.property("ADBE Effect Parade")
if (effectsGroup !== null)                       // Filter out layers that cannot use effects
{
    if (effectsGroup.canAddProperty("Levels"))   // First check if the effect can be applied
    {
        // Apply the effect here 
    }
}

Applying an effect to a layer

To apply (add) an effect to a layer, you need to know the effect’s display name or matchName. With this information, you then add a property of that name to the PropertyGroup associated with the layer’s effects.

The following code shows how to apply an effect (in this example, Layers) to a layer successfully.

// given:
// layer = Layer object, and the layer can have effects applied
// effectsGroup = PropertyGroup associated with the layer's effects
//
var effectBase = effectsGroup.addProperty("Levels");
if (effectBase !== null)
{
    // The effect was applied successfully
}

Retrieving all effects applied to a layer

The effects applied to a layer are the properties of the layer’s Effects PropertyGroup.

The following code shows how to iterate over the properties of a layer’s Effects PropertyGroup and store them in an array for retrieval or use elsewhere in your code.

// given:
// layer = Layer object, and the layer can have effects applied
//
var effectsGroup = layer("Effects");
var effectsOnLayer = new Array();                // Store effects in an array; starts as empty
if (effectsGroup !== null)
{
                                                 // Iterate through properties of effectsGroup
                                                 // Append effect to the array
    for (var i = 1; i <= effectsGroup.numProperties; i++)
        effectsOnLayer[effectsOnLayer.length] = effectsGroup.property(i);
}
// The effectsOnLayer array now contains the list of effects
// The number of effects applied is effectsOnLayer.length 

Retrieving the selected effects on a layer

If your script needs to operate on the selected effects on a layer, you need to check if the selected attribute for the effect (Property) is true.

The following code shows how to iterate over the properties of a layer’s Effects PropertyGroup, and store only the properties whose selected attribute is true in an array for retrieval or use elsewhere in your code. This code is very similar to the code for retrieving the effects applied to a layer, with the extra check for the selected attribute value.

// given:
// layer = Layer object, and the layer can have effects applied
//
var effectsGroup = layer("Effects");
var selectedEffects = new Array();               // Store effects in an array; starts as empty
if (effectsGroup !== null)
{
                                                 // Iterate through properties of effectsGroup
                                                 // Append selected effect to the array
    for (var i = 1; i <= effectsGroup.numProperties; i++)
        if (effectsGroup.property(i).selected)
            selectedEffects[selectedEffects.length] = effectsGroup.property(i);
}
// The selectedEffects array now contains the list of selected effects 
// in top-to-bottom order

Selecting or deselecting an effect

Selecting or deselecting an effect is as simple as changing the Boolean value of the selected attribute for the effect’s PropertyBase.

Note: Changing the selection of an effect does not affect the selection state of other effects.

The following code shows how to select and deselect an effect.


// given:
// effect = PropertyBase associated with the layer effect to select or deselect
//
effect.selected = true;                          // Select the effect

effect.selected = false;                         // Deselect the effect

Rearranging an effect on a layer

Reordering an effect within the stack of effects (as listed in the Effect Controls window or in the Timeline window) applied to a layer is as simple as specifying the intended position in the stack with the moveTo() method for the effect (PropertyBase). Use a value of 1 to move an effect to the top of the stack, or a value equal to the number of effects on the layer to move an effect to the bottom.

The following code shows how to move a specific effect to the top and bottom of the stack.

// given:
// effect = PropertyBase associated with the layer effect to rearrange
// effectsGroup = PropertyGroup associated with the layer's effects
//
effect.moveTo(1);                                // Move to the top (1 = top of stack)

effect.moveTo(effectsGroup.numProperties);       // Move to the bottom

Removing an effect from a layer

Removing an effect from the stack of effects on a layer is as simple as calling the remove() method for the effect (PropertyBase).

Note: If you want to remove all effects from a layer, index the effect’s PropertyGroup in reverse. Otherwise, incrementing through the PropertyBase’s properties will cause your script to access indices that no longer exist as effects are deleted.

The following code shows how to remove a single effect, as well as all effects on a layer.

// given:
// layer = Layer object, and the layer can have effects applied
// effectsGroup = PropertyGroup associated with the layer's effects
// effect = PropertyBase associated with the layer effect to remove
//
effect.remove();                                 // Removes a specific effect

                                                 // Remove all effects on the layer
for (var i = effectsGroup.numProperties; i >= 1; i--)
    effectsGroup.property(i).remove();
// ... or ...
while (effectsGroup.numProperties > 0)           // Continually remove effects until no more
    effectsGroup.property(effectsGroup.numProperties).remove();