Application object

Provides access to objects and application settings within the After Effects application. The single global object is always available by its name, app. Attributes of the Application object provide access to specific objects within After Effects. Methods of the Application object can create a project, open an existing project, control Watch Folder mode, purge memory, and quit the After Effects application. When the After Effects application quits, it closes the open project, prompting the user to save or discard changes as necessary, and creates a project file as necessary.

Syntax

app

Attributes

Attribute	Description
project	The current After Effects project.
isoLanguage	The locale (language and region) in which the application is running.
version	The version number of the After Effects application.
buildName	The name of this build of the application.
buildNumber	The number of this build of the application.
isWatchFolder	When true, the local application is running in Watch Folder mode.
isRenderEngine	When true, the local After Effects application is running as a render engine.
settings	Application settings that can be set via scripting.
onError	A callback function that is called when an error occurs in the application.
exitCode	A numeric status code used when executing a script externally (that is, from a command line or AppleScript). 0 if no error occurred. A positive number indicates an error that occurred while running the script.
exitAfterLaunchAndEval	When true, the application remains open after running a script from the command line on Windows.
saveProjectOnCrash	When true, the project is saved if the application closes unexpectedly.
memoryInUse	Memory in use by this application.
effects	The effects available in the application.
activeViewer	The currently focused or last-focused viewer panel.

Methods

Method	Description
newProject()	Creates a new project in After Effects.
open()	Opens a project or an Open Project dialog box.
quit()	Quits the application.
watchFolder()	Starts Watch Folder mode; does not return until Watch Folder mode is turned off.
pauseWatchFolder()	Pauses a current watch-folder process.
endWatchFolder()	Ends a current watch-folder process.
purge()	Purges a targeted type of cached information (replicates Purge options in the Edit menu).
beginUndoGroup()	Groups the actions that follow it into a single undoable step.
endUndoGroup()	Ends an undo group; needed only when a script contains more than one undo group.
beginSuppressDialogs()	Begins suppression of dialogs in the user interface.
endSuppressDialogs()	Ends suppression of dialogs in the user interface.
setMemoryUsageLimits()	Sets memory usage limits as in the Memory & Cache preferences area.
setSavePreferencesOnQuit()	Sets whether preferences are saved when the application is quit.
activate()	Brings the After Effects main window to the front of the screen.
scheduleTask()	Schedules a JavaScript script for delayed execution.
cancelTask()	Cancels a scheduled task.
parseSwatchFile()	Loads a color swatch from an Adobe Swatch Exchange (ASE) file.

activate() method

Syntax: app.activate()

Description: Opens the application main window if it is minimized or iconified, and brings it to the front of the desktop.

Parameters: None.

Returns: Nothing.

activeViewer attribute

Syntax: app.activeViewer

Description: The Viewer object for the currently focused or active-focused viewer (Composition, Layer, or Footage) panel. Returns null if no viewers are open.

Type: Viewerobject; read-only.

beginSuppressDialogs() method

Syntax: app.beginSuppressDialogs()

Description: Begins suppression of script error dialog boxes in the user interface. Use endSuppressDialogs() to resume the display of error dialogs. See “Application endSuppressDialogs() method” on page 21.

Parameters: None.

Returns: Nothing.

beginUndoGroup() method

Syntax app.beginUndoGroup(undoString)

Description: Marks the beginning of an undo group, which allows a script to logically group all of its actions as a single undoable action (for use with the Edit > Undo/Redo menu items). Use the endUndoGroup() method to mark the end of the group. (See “Application endUndoGroup() method” on page 21.) beginUndoGroup() and endUndoGroup() pairs can be nested. Groups within groups become part of the larger group, and will undo correctly. In this case, the names of inner groups are ignored.

Parameters * undoString The text that will appear for the Undo command in the Edit menu (that is, “Undo undoString”)

Return Nothing.

buildName attribute

Syntax: app.buildName

Description: The name of the build of After Effects being run, used internally by Adobe for testing and troubleshooting.

Type: String; read-only.

buildNumber attribute

Syntax: app.buildNumber

Description: The number of the build of After Effects being run, used internally by Adobe for testing and troubleshooting.

Type: Integer; read-only.

cancelTask() method

Syntax: app.cancelTask(taskID)

Description: Removes the specified task from the queue of tasks scheduled for delayed execution.

Parameters: * taskID An integer that identifies the task, as returned by app.scheduleTask().

Returns: Nothing.

effects attribute

Syntax: app.effects

Description: The effects available in the application.

Type: Array, with each element containing the following properties; read-only: * displayName String representing the localized display name of the effect as seen in the Effect menu. * category String representing the localized category label as seen in the Effect menu. This can be "" for synthetic effects that aren’t normally shown to the user. * matchName String representing the internal unique name for the effect. This name does not change between versions of After Effects. Use this value to apply the effect.

Example:

var effectName = app.effects[12].displayName;

endSuppressDialogs() method

Syntax: app.endSuppressDialogs(alert)

Description: Ends the suppression of script error dialog boxes in the user interface. Error dialogs are displayed by default; call this method only if beginSuppressDialogs() has previously been called. See “Application beginSuppress-Dialogs() method” on page 19.

Parameters: * alert Boolean; when true, errors that have occurred following the call to beginSuppressDialogs() are displayed in a dialog box.

Returns: Nothing.

endUndoGroup() method

Syntax: app.endUndoGroup()

Description: Marks the end of an undo group begun with the app.beginUndoGroup() method. You can use this method to place an end to an undo group in the middle of a script, should you wish to use more than one undo group for a single script. If you are using only a single undo group for a given script, you do not need to use this method; in its absence at the end of a script, the system will close the undo group automatically. Calling this method without having set a beginUndoGroup() method yields an error.

Parameters: None.

Returns: Nothing.

endWatchFolder() method

Syntax: app.endWatchFolder()

Description: Ends Watch Folder mode.

Parameters: None.

Returns: Nothing.

exitAfterLaunchAndEval attribute

Syntax: app.exitAfterLaunchAndEval

Description: This attribute is used only when executing a script from a command line on Windows. When the application is launched from the command line, the –r or –s command line flag causes the application to run a script (from a file or from a string, respectively). If this attribute is set to true, After Effects will exit after the script is run; if it is false, the application will remain open. This attribute only has an effect when After Effects is run from the Windows command line. It has no effect in Mac OS.

Type: Boolean; read/write.

exitCode attribute

Syntax: app.exitCode

Description: A numeric status code used when executing a script externally (that is, from a command line or AppleScript).

In Windows, the value is returned on the command line when After Effects was launched on the command line (using the afterfx or afterfx –m command), and a script was specified with the –r or –s option.
in Mac OS, the value is returned as the AppleScript DoScript result for each script. In both Mac OS and Windows, the value is set to 0 (EXIT_SUCCESS) at the beginning of each script evalu- ation. In the event of an error while the script is running, the script can set this to a positive integer that indicates what error occurred.

Type: Integer; read/write.

Example:

app.exitCode = 2; //on quit, if value is 2, an error has occurred

isoLanguage attribute

Syntax: app.isoLanguage

Description: A string indicating the locale (language and regional designations) After Effects is running. NOTE: $.locale returns the operating system language, not the language of the After Effects application.

Type: String; read-only. Some common values include:

en_US for English (United States)
de_DE for German (Germany)
es_ES for Spanish (Spain)
fr_FR for French (France)
it_IT for Italian (Italy)
ja_JP for Japanese (Japan)
ko_KR for Korean (Korea)

Example:

var lang = app.isoLanguage;
if (lang == "en_US")
alert("After Effects is running in English.");
else if (lang == "fr_FR")
alert("After Effects is running in French.");
else
alert("After Effects is not running in English or French.");

isRenderEngine attribute

Syntax: app.isRenderEngine

Description: True if After Effects is running as a render engine.

Type: Boolean; read-only.

isWatchFolder attribute

Syntax: app.isWatchFolder

Description: True if the Watch Folder dialog box is currently displayed and the application is currently watching a folder for rendering.

Type: Boolean; read-only.

memoryInUse attribute

Syntax: app.memoryInUse

Description: The number of bytes of memory currently used by this application.

Type: Number; read-only.

newProject() method

Syntax: app.newProject()

Description: Creates a new project in After Effects, replicating the File > New > New Project menu command. If the current project has been edited, the user is prompted to save it. If the user cancels out of the Save dialog box, the new project is not created and the method returns null. Use app.project.close(CloseOptions.DO_NOT_SAVE_CHANGES) to close the current project before opening a new one. See “Project close() method” on page 116.

Parameters: None.

Returns: A new Project object, or null if no new project is created.

Example

app.project.close(CloseOptions.DO_NOT_SAVE_CHANGES);
app.newProject();

onError attribute

Syntax: app.onError

Description: The name of a callback function that is called when an error occurs. By creating a function and assigning it to this attribute, you can respond to errors systematically; for example, you can close and restart the application, noting the error in a log file if it occurred during rendering. See “RenderQueue render() method” on page 161. The callback function is passed the error string and a severity string. It should not return any value.

Type: A function name string, or null if no function is assigned; read/write.

Example:

function err(errString) {
    alert(errString);
}
app.onError = err;

open() method

Syntax: * app.open() * app.open(file)

Description: Opens a project.

Parameters: * file Optional. An ExtendScript File object for the project file to open. If not supplied, the method prompts the user to select a project file.

Returns: A new Project object for the specified project, or null if the user cancels the Open dialog box.

Example

var my_file = new File("../my_folder/my_test.aep");
if (my_file.exists){
    new_project = app.open(my_file);
    if (new_project){
        alert(new_project.file.name);
    }
}

parseSwatchFile() method

Syntax: app.parseSwatchFile(file)

Description: Loads color swatch data from an Adobe Swatch Exchange (ASE) file.

Parameters: * file The file specification, an ExtendScript File object.

Returns: The swatch data, in this format:

Format	Description
data.majorVersion data.minorVersion	The ASE version number.
data.values	An array of SwatchValue.
SwatchValue.type	One of "RGB", "CMYK", "LAB", "Gray"
SwatchValue.r SwatchValue.g SwatchValue.b	When type = "RGB", the color values in the range [0.0..1.0]. 0, 0, 0 is Black.
SwatchValue.c SwatchValue.m SwatchValue.y SwatchValue.k	When type = "CMYK", the color values in the range [0.0..1.0]. 0, 0, 0, 0 is White.
SwatchValue.L SwatchValue.a SwatchValue.b	When type = "LAB", the color values. L is in the range [0.0..1.0]. a and b are in the range [-128.0..+128.0] 0, 0, 0 is Black.
SwatchValue.value	When type = "Gray", the value range is [0.0..1.0]. 0.0 is Black.

pauseWatchFolder() method

Syntax: app.pauseWatchFolder(pause)

Description: Pauses or resumes the search of the target watch folder for items to render.

Parameters: * pause True to pause, false to resume.

Returns: Nothing.

project attribute

Syntax: app.project

Description: The project that is currently loaded. See “Project object” on page 114.

Type: Project object; read-only.

purge() method

Syntax: app.purge(target)

Description: Purges unused data of the specified types from memory. Replicates the Purge options in the Edit menu.

Parameters:

target: The type of elements to purge from memory; a PurgeTarget enumerated value, one of:

PurgeTarget.ALL_CACHES: Purges all data that After Effects has cached to physical memory.
PurgeTarget.UNDO_CACHES: Purges all data saved in the undo cache.
PurgeTarget.SNAPSHOT_CACHES: Purges all data cached as composition/layer snapshots.
PurgeTarget.IMAGE_CACHES: Purges all saved image data.

Returns: Nothing.

quit() method

Syntax: app.quit()

Description: Quits the After Effects application.

Parameters: None.

Returns: Nothing.

saveProjectOnCrash attribute

Syntax: app.saveProjectOnCrash

Description: When true (the default), After Effects attempts to display a dialog box that allows you to save the current project if an error causes the application to quit unexpectedly. Set to false to suppress this dialog box and quit without saving.

Type: Boolean; read/write.

scheduleTask() method

Syntax: app.scheduleTask(stringToExecute, delay, repeat)

Description: Schedules the specified JavaScript for delayed execution.

Parameters: * stringToExecute A string containing JavaScript to be executed. * delay A number of milliseconds to wait before executing the JavaScript. A floating-point value.

Returns: Integer a unique identifier for this task, which can be used to cancel it with app.cancelTask().

setMemoryUsageLimits() method

Syntax: app.setMemoryUsageLimits(imageCachePercentage, maximumMemoryPercentage)

Description:

Sets memory usage limits as in the Memory & Cache preferences area. For both values, if installed RAM is less than a given amount (n gigabytes), the value is a percentage of the installed RAM, and is otherwise a percentage of n. The value of n is: 2 GB for 32-bit Windows, 4 GB for 64-bit Windows, 3.5 GB for Mac OS.

Parameters: * imageCachePercentage Floating-point value, the percentage of memory assigned to image cache. * maximumMemoryPercentage Floating-point value, the maximum usable percentage of memory.

Returns Nothing.

setSavePreferencesOnQuit() method

Syntax: app.setSavePreferencesOnQuit(doSave)

Description: Set or clears the flag that determines whether preferences are saved when the application is closed.

Parameters: * doSave When true, preferences saved on quit, when false they are not.

Returns: Nothing.

settings attribute

Syntax: app.settings

Description: The currently loaded settings. See “Settings object” on page 170.

Type: Settings object; read-only.

repeat When true, execute the script repeatedly, with the specified delay between each execution. When false the script is executed only once.

version attribute

Syntax: app.version

Description: An alphanumeric string indicating which version of After Effects is running.

Type: String; read-only.

Example:

var ver = app.version;
alert("This machine is running version " + ver + " of After Effects.");

watchFolder() method

Syntax: app.watchFolder(folder_object_to_watch)

Description: Starts a Watch Folder (network rendering) process pointed at a specified folder.

Parameters: * folder_object_to_watch The ExtendScript Folder object for the folder to watch.

Returns: Nothing.

Example

var theFolder = new Folder(“c:/tool”);
app.watchFolder(theFolder);