redefinery

Project

This section describes how to work with items in an After Effects project (the Project panel). The following topics are covered:


Checking if a project is currently open (AE 6.5 and earlier)

Before you can access the objects within an After Effects project, you need to make sure a project is currently open. Although After Effects starts up with an empty project, the user can close it, so you need to handle that condition in your scripts.

Note: As of AE version 7.0, a project is always available, even on startup and if you close the previous project.

The following code shows how to check for the existence of a project.

// given:
// app = Application object representing After Effects
//
if (app.project !== null)
{
    // Project is available
}

Retrieving the Solids folder in the Project panel

As of version 6.0, After Effects creates solid footage in a Solids folder in the Project panel. If you need to create new solid footage in your scripts, you might need to retrieve the location of this folder.

The following code shows how to iterate over the contents (Item objects) of the Project panel, looking for a folder (FolderItem object) whose name is “Solids”. Note that the code iterates over the top level (root folder) items first before iterating recursively. This is done because the Solids folder will be at the top level, unless the user has moved it to a subfolder.

// given:
// app = Application object representing After Effects
// app.project = Project object representing the current project
//
var solidsFolder = null;                         // Assume no Solids folder found

// Check the root folder for a "Solids" folder
var projItems = app.project.rootFolder.items;    // Get the items in top level (root folder)
var folderItem;

for (var i = 1; i <= projItems.length; i++)      // Iterate over the top level's items
{
    folderItem = projItems[i];
                                                 // Look for a folder named "Solids"
    if ((folderItem instanceof FolderItem) && (folderItem.name === "Solids"))
    {
        solidsFolder = folderItem;
        break;
    }
}

// If it doesn't exist at the root level, try looking in all subfolders
// The first Solids folder found is used
if (solidsFolder === null)
{
    projItems = app.project.items;
    for (var i = 1; i <= projItems.length; i++)
    {
        folderItem = projItems[i];
        if ((folderItem instanceof FolderItem) && (folderItem.name === "Solids"))
        {
            solidsFolder = folderItem;
            break;
        }
    }
}
// If a Solids folder was found, the solidsFolder variable will point to a FolderItem object
// Otherwise, it'll be null

Retrieving the subfolders of the current item in the Project panel

If you need to retrieve the contents nested in subfolders of the current folder, you need to first get the subfolders.

The following code shows how to iterate over the items in the current folder (based on a specified Item object) looking for subfolders (FolderItem objects) and store them in an array for retrieval or use elsewhere in your code.

// given:
// currItem = Item object representing the current project item
//
var subfolders = new Array();                    // Store subfolders in an array; start empty
var currFolder = currItem.parentFolder;          // Get the project item's parent folder
var projItem;

for (var i = 1; i <= currFolder.numItems; i++)   // Iterate over the folder's contents
{
    projItem = currFolder.items[i];
    if (projItem instanceof FolderItem)          // Store folder items in the array
        subfolders[subfolders.length] = projItem;
}
// The subfolders array now contains the list of subfolder items in top-to-bottom listed order
// The number of subfolders is subfolders.length 

Retrieving all folders in the Project panel

If you need to access all folders in the Project panel, iterate over the Project object’s items attribute (which points to all Items in the Project panel) looking for folders (FolderItem objects).

The following code shows how to iterate over the project’s items looking for folders, and store them in an array for retrieval or use elsewhere in your code.

// given:
// app = Application object representing After Effects
// app.project = Project object representing the current project
//
var folders = new Array();                       // Store folders in an array; start as empty
var projItems = app.project.items;               // Get all items in the Project panel
var projItem;

for (var i = 1; i <= projItems.length; i++)      // Iterate over the project's items
{
    projItem = projItems[i];
    if (projItem instanceof FolderItem)          // Store folder items in the array
        folders[folders.length] = projItem;
}
// The folders array now contains the list of folders in top-to-bottom listed order
// The number of folders is folders.length 

Retrieving the selected folders in the Project panel

If your script needs to operate on the selected folders in the Project panel, you need to check which of the selected project items are folders.

The following code shows how to iterate over the project’s selected Item objects, and store only those that are FolderItem objects in an array for retrieval or use elsewhere in your code.

// given:
// app = Application object representing After Effects
// app.project = Project object representing the current project
//
var selectedFolders = new Array();               // Store folders in an array; start as empty
var selectedItems = app.project.selection;       // Get selected items in the Project panel
var projItem;

for (var i = 0; i < selectedItems.length; i++)   // Iterate over the project's selected items
{                                                // Note: selection array starts at 0
    projItem = selectedItems[i];
    if (projItem instanceof FolderItem)          // Store selected folder items in the array
        selectedFolders[selectedFolders.length] = projItem;
}
// The selectedFolders array now contains the list of selected folders 
// in top-to-bottom listed order

Selecting the parent folders of the current item in the Project panel

If you have a project item nested within several folders, you might want to identify where it is located in the Project folder. This can be done by either selecting the item (which expands any parent folders) or selecting its parent folders.

The following code shows how to select an item’s parent folders.

// given:
// app = Application object representing After Effects
// app.project = Project object representing the current project
// projItem = Item object representing the current project item
//
var currItem = projItem;
                                                 // Are we at the top level (root folder)?
while (currItem.parentFolder !== app.project.rootFolder)
{
    currItem = currItem.parentFolder;            // Select the current item's parent folder
    currItem.selected = true;
}

Deselecting all items in the Project panel

If you need to operate on a specific set of items in the Project panel, you might need to deselect any items that are currently selected.

The following code shows how to iterate over the project’s selected items (Item objects), and deselects them.

// given:
// app = Application object representing After Effects
// app.project = Project object representing the current project
//
var selectedItems = app.project.selection;

for (var i = 0; i < selectedItems.length; i++)   // Note: selection array starts at 0
    selectedItems[i].selected = false;