0% found this document useful (0 votes)

12 views

Scripting Guide

Uploaded by

andi.amar05072004

Available Formats

Download as PDF, TXT or read online on Scribd

0% found this document useful (0 votes)

12 views

Scripting Guide

Uploaded by

andi.amar05072004

Available Formats

Download as PDF, TXT or read online on Scribd

You are on page 1/ 250

1

Adobe Systems Incorporated Adobe PDF

Windows

Adobe Acrobat

1 +
Windows Macintosh
2

1
2
3 +
Windows Macintosh

1
•

•
2
3

1
2

Acrobat 6
1
2
PDF
Acrobat 5
1
2

Acrobat

2
3

Adobe After Effects 6.5

After Effects
Adobe After Effects 6.5 Professional

JavaScript
AppleScript Visual Basic
After Effects
JavaScript

After Effects 6.5

After Effects
JavaScript
Rush Render Queue
Rush Render Queue

www.adobeforums.com

After Effects
After Effects

After Effects

After Effects ECMAScript ECMA-262 3 ECMA-262

www.ecma-international.org

3
4

JavaScript

ECMA JavaScript

After Effects
ECMAScript

After Effects

ECMAScript/JavaScript After Effects

Macintosh AppleScript Windows DOS

JavaScript
After Effects

JavaScript After Effects

Attributes
After Effects

•
•
•

4
5

•
•
•
JavaScript
JavaScript

JavaScript
JavaScript
JavaScript JavaScript

JavaScript JavaScript Debugging 16

After Effects Unicode UTF-8

Microsoft
Word 0

After Effects Scripts

6
Photoshop After Effects
After Effects After Effects

After Effects

After Effects
After Effects 6.5

Examples 180

5
| | 6

Adobe After Effects

After
Effects
After Effects
ID

After Effects
9

After Effects 6.5

Unicode UTF-8

Windows EM Editor Windows

UTF-8
Macintosh OS BBEdit OS X
Unicode (UTF-8)

.jsx
After Effects .jsx
JavaScript .js
UTF-8 .jsx

Scripts
After Effects After Effects 6.5
Scripts
Scripts

Windows AppleScript
Macintosh After Effects

.jsx

| | 6
| | 7

Shutdown Startup
Scripts Startup Shutdown 2 After Effects
Startup Shutdown

Startup

After
Effects

After Effects

Application Application object 27

Shutdown

After Effects
Windows AppleScript Macintosh
After Effects

After Effects Windows

After Effects After Effects

After Effects
afterfx.exe -s

afterfx.exe –s "alert(¥"After Effects ¥")"

.jsx
afterfx.exe –r c:¥myDocuments¥Scripts¥yourAEScriptHere.jsx

After Effects AppleScript Macintosh

After Effects AppleScript
After Effects .jsx
3
After Effects AppleScript
DoScript

| | 7
| | 8

tell application "Adobe After Effects 6.5"

DoScript "alert (¥"After Effects ¥")"

end tell

.jsx

set thefile to choose file

tell application "Adobe After Effects 6.5"

DoScript thefile

end tell

.jsx After Effects

.jsx
BBEdit
BBEdit

AppleScript

After Effects

tell application "TextEdit"

set the_script to selection as text

end tell

tell application "Adobe After Effects 6.5"

activate

DoScript the_script

end tell

AppleScript AppleScript: the Definitive Guide Matt Neuberg

O’Reilly & Associates AppleScript 1-2-3 Sal Soghoian Peachpit Press

| | 8
| | 9

After Effects

After Effects JavaScript

JavaScript Debugging 16

ECMA
After Effects ECMA-262 3

ECMAScript
www.ecma-international.org/publications/standards/ECMA-262.HTM Ecma-262.pdf

JavaScript 1.2 After Effects

JavaScript 1 JavaScript 3 David Flanagan
ISBN:4873110270
JavaScript: A Beginner’s Guide John Pollock Osborne 2
JavaScript

After Effects AppleScript Windows

JavaScript

After Effects

1
/

break JavaScript
continue JavaScript
case switch
default case switch

do - while JavaScript
while

false false
for JavaScript

| | 9
| | 10

for - in JavaScript

function

if/if - else JavaScript

new JavaScript
null

return JavaScript
switch JavaScript case

this JavaScript
true true
undefined

var JavaScript
while JavaScript
do-while

with JavaScript

After Effects

new

delete

typeof

void

[]

()

~ NOT

| | 10
| | 11

! NOT
*

>>>

& AND
^ XOR
| OR
&& AND
|| OR
?: 3
=

<<=

>>=

>>>=

&= AND
^= XOR
|= OR
,

| | 11
| | 12

3
— —
[], (), .

new, delete, - , ~, !, typeof, void,++, --

*, /, %

+, -

<<, >>, >>>

<, <=, >, >=

==, !=

=, /=, %=, <<=, >>=, >>>=, &=, ^=, |=, +=, -=, *=

aerender
After Effects 6.5

Examples 180

aerender After Effects

After Effects
aerender
After Effects
-reuse

aerender . aerender.exe
-reuse -project project_path
2 -mem_usage image_cache_percent max_mem_percent
3

-help aerender

| | 12
| | 13

-help

-reuse After Effects

aerender
After Effects
After Effects -reuse
aerender After Effects
aerender After
Effects
After Effects
After Effects
-reuse

-project project_path project_path

URI -project
aerender

-comp comp_name comp_name

-comp aerender
-comp
-project -log -v
-mem_usage -close -RStemplate
-OMtemplate -output -s -e

-RStemplate render_settings_template
render_settings_templa
te

| | 13
| | 14

-OMtemplate output_module_template
output_module_template

-output output_path output_path

URI

-log logfile_path logfile_path

URI stdout

-s start_frame start_frame

-e end_frame end_frame

-i increment increment
1

-1

1
-mem_usage image_cache_percent
image_cache_percent
max_mem_percent max_mem_percent After Effects

-v verbose_flag verbose_flag
ERRORS
ERRORS_AND_PROGRESS
ERRORS_AND_PROGRESS

| | 14
| | 15

-close close_flag close_flag

close_flag DO_NOT_SAVE_CHANGES

close_flag SAVE_CHANGES
close_flag DO_NOT_CLOSE

After Effects
After Effects

After Effects
DO_NOT_SAVE_CHANGES

-sound sound_flag sound_flag

ON OFF
OFF

-version aerender

Comp 1

aerender -project c:¥projects¥proj1.aep -comp "Comp 1" -output c:¥output¥proj1¥proj1.avi

aerender -project c:¥projects¥proj1.aep

1 10

aerender -project c:¥projects¥proj1.aep -comp "Comp 1" -s 1 -e 10

-RStemplate "Multi-Machine Settings"

-OMtemplate "Multi-Machine Sequence"

-output c:¥output¥proj1¥frames[####].psd

| | 15
JavaScript Debugging

JavaScript Debugging
This section describes the JavaScript Debugger, which appears when the Enable JavaScript Debugger
preference is selected in General Preferences (it is deselected by default) and there is an error when executing
a script.
A B C D E F G H

JavaScript Debugger window

A. Stack trace view B. Resume C. Pause D. Stop E. Step over F. Step into
G. Step out H. Breakpoints display I. Command line J. Debug output view
K. JavaScript source view

The current stack trace appears in the upper-left pane of the JavaScript Debugger window. This Stack Trace
view displays the calling hierarchy at the time of the breakpoint. Double-clicking a line in this view changes
the current scope, enabling you to inspect and modify scope-specific data.
All debugging output appears in the upper-right pane of the JavaScript Debugger window. Specifically, output
from the print method of the $ object appears in this Debug Output view.
The currently executing JavaScript source appears in the lower pane of the JavaScript Debugger window.
Double-clicking a line in this JavaScript Source view sets or clears an unconditional breakpoint on that line.
That is, if a breakpoint is in effect for that line, double-clicking it clears the breakpoint, and vice-versa. The
line number display on the left part displays a red dot for all lines with a breakpoint.

16
JavaScript Debugging

If Enable JavaScript Debugger is deselected in General Preferences, you see an error message but not the
JavaScript Debugger itself. This is the typical setup used in situations in which professional roles are divided
between those writing and administering scripts (technical directors, system administrators, and so on) and
those using them (the artist or animators). If you are writing and debugging your own scripts, you will want
to enable the JavaScript Debugger.

Controlling code execution in the JavaScript Debugger

This section describes the buttons that control the execution of code when the JavaScript Debugger window
is active. Most of these buttons also provide a keyboard shortcut.

Resume
Ctrl+R (Windows)
Command+R (Mac OS)

Resume execution of the script with the JavaScript Debugger window open. When the script terminates, the application closes the Jav-
aScript Debugger window automatically. Closing the window manually also causes script execution to resume. This button is enabled
when script execution is paused or stopped.

Pause
Ctrl+P (Windows)
Command+P (Mac OS)

Halt the currently executing script temporarily and reactivate the JavaScript Debugger. This button is enabled when a script is running.
,,Ray, funnyy wrapping on this line . . . -cj>>

Stop
Ctrl+K (Windows)
Command+K (Mac OS)

Stop execution of the script and generate a runtime error. This button is enabled when a script is running.

Step Over
Ctrl+S (Windows)
Command+S (Mac OS)

Halt after executing a single JavaScript statement in the script; if the statement calls a JavaScript function, execute the function in its
entirety before stopping.

Step Into
Ctrl+T (Windows)
Command+T (Mac OS)

Halt after executing a single JavaScript statement in the script or after executing a single statement in any JavaScript function that the
script calls.

17
JavaScript Debugging

Step Out
Ctrl+U (Windows)
Command+U (Mac OS)

When the JavaScript Debugger is paused within the body of a JavaScript function, resume script execution until the function returns.
When the JavaScript Debugger is paused outside the body of a function, resume script execution until the script terminates.

Script Breakpoints Display

Display the Script Breakpoints window.

Using the JavaScript command line entry field

You can use the JavaScript Debugger’s command line entry field to enter and execute JavaScript code interac-
tively within a specified stack scope. Commands entered in this field execute with a time-out of one second. If
a command takes longer than one second to execute, the script terminates and generates a time-out error.

Command line entry field

Enter in this field a JavaScript statement to execute within the stack scope of the line highlighted in the Stack
Trace view. When you’ve finished entering the JavaScript expression, you can execute it by clicking the
Command Line Entry button or pressing the Enter key. Click the button next to the field, or press Enter to
execute the JavaScript code in the command line entry field. The application executes the contents of the
command line entry field within the stack scope of the line highlighted in the Stack Trace view.
The command line entry field accepts any JavaScript code, making it very convenient to use for inspecting or
changing the contents of variables.
Note: To list the contents of an object as if it were JavaScript source code, enter the object.toSource() command.

Setting breakpoints

You can set breakpoints in the JavaScript Debugger itself, by calling methods of the $ object, or by defining
them in your JavaScript code.Setting breakpoints in the JavaScript Debugger
When the JavaScript Debugger window is active, you can double-click a line in the JavaScript Source view to
set or clear a breakpoint at that line. Alternatively, you can click the Script Breakpoints Display button to
display the Script Breakpoints window and set or clear breakpoints in this window as described in “Script
Breakpoints window” on page 19.

Setting breakpoints in JavaScript code

Adding the debugger statement to a script sets an unconditional breakpoint. For example, the following code
causes the script to halt and display the JavaScript Debugger as soon as it enters the setupBox function.
fu n c t i o n s e t u p B ox ( b ox ) {
// break unconditionally at the next line
debugger ;
b ox . w i d t h = 4 8 ;

18
JavaScript Debugging

b ox.heig ht = 48;
b ox . u r l = "none";
}

To execute a breakpoint in runtime code, call the $.bp() method, as shown in the following example:
fu n c t i o n s e t u p B ox ( b ox ) {
b ox . w i d t h = ( b ox . w i d t h = = u n d e fi n e d ) ? $ . b p ( ) : 4 8 ;
b ox . h e i g h t = ( b ox . h e i g h t = = u n d e fi n e d ) ? $ . b p ( ) : 4 8 ;
b ox . u r l = ( b ox . u r l = = u n d e fi n e d ) ? $ . b p ( ) : " n o n e " ;
}

This example breaks into the JavaScript Debugger if any of the width, height, or url attributes of the custom
element are undefined. Of course, you wouldn’t put bp method calls into production code—it’s more appro-
priate for shipping code to set default values for undefined properties, as the previous example does.

Script Breakpoints window

Display of the Script Breakpoints window is controlled by the Script Breakpoints button in the JavaScript
Debugger. This window displays all defined breakpoints. This window does not display temporary break-
points or breakpoints defined by the debugger statement in JavaScript code.
The Script Breakpoints window provides the following controls:
• The Line field contains the line number of the breakpoint.
• The Condition field may contain a JavaScript expression to evaluate when the breakpoint is reached. If the
expression evaluates to false, the breakpoint is not executed.
• Breakpoints set in this window persist across multiple executions of a script. When the application quits or
a script is reloaded, it removes all breakpoints.

To set a breakpoint in the Script Breakpoints window:

1 Click New to create a new breakpoint, or click the breakpoint that you wish to edit.
2 Enter a line number in the Line Number field, or change the existing line number.
3 Optionally, enter a condition such as (i>5) in the Condition field. This can be any valid JavaScript
expression. If the result of evaluating the expression is true, the breakpoint activates.

The $ object
The $ object (Debugger Object) provides properties and methods you can use to debug your JavaScript code.
For example, you can call its methods to set or clear breakpoints programmatically, or to change the language
flavor of the script currently executing. It also provides properties that hold information about the version of
the host platform’s operating system.
Note: The $ object is not a standard JavaScript object.

Properties

Name Type Description

e r ror Error Retrieve the last runtime error. Reading this property returns an Error
object containing information about the last runtime error.

19
JavaScript Debugging

v ersion String Returns the version number of the JavaScript engine as a three-part num-
ber like e.g. "3.1.11". Read only.

os String Outputs the current operating system version. Read only.

Debug output method

Initiate a garbage collection. Garbage collection is the process by which the JavaScript interpreter cleans up
memory it is no longer using. This is done automatically. Occasionally when you’re debugging a script, it may
be useful to call this process.

Returns

None.

21
Reference

Reference
This chapter lists and describes syntax (keywords, statements, operators,classes, objects, methods, attributes,
and global functions) particular to the After Effects scripting engine.
The After Effects Scripting engine supports the 3rd Edition of the ECMA-262 Standard, including its
notational and lexical conventions, types, objects, expressions and statements. For a complete listing of the
keywords and operators included with ECMAScript, please refer to Ecma-262.pdf, available at www.ecma-
international.org/publications/standards/ECMA-262.HTM
For an overview of the most common keywords and statements available from ECMA-262, see
“ÉLÅ[ÉèÅ[ÉhÇ∆ÉXÉeÅ[ÉgÉÅÉìÉgç\ï∂” on page 9.

Objects, methods, attributes, and globals

As you look through this reference section, which is organized alphabetically according to object groupings,
you can refer to the following diagrams for an overview of where the various objects fall within the hierarchy,
and their correspondence to the user interface.

application system file folder socket

settings project item(s) may be any of the following 3 types of item:

compItem OR footageItem OR folderItem

renderQueue item(s)
layer(s) ITEM(S)
proxySource mainSource proxySource
renderQueueItem(s)
properties mainSource & proxySource
may be any of the following 3 types of item:
outputModule(s)
solidSource OR placeholderSource OR fileSource

color file

Hierarchy diagram of the main After Effects scripting objects

22
Reference

The hierarchy of objects in scripting corresponds to the hierarchy in the user interface. The Application contains a Project window that
contains a Composition with a Layer. The source for the Layer can be a footage file, placeholder, or solid, and it is also listed in the Project
window. The Layer in turn contains settings known as Properties, and these can hold individual keyframes. The Render Queue contains
Render Queue Items as well as Render Settings and Output Modules. All of these rules are directly analogous to scripting.

Attributes and properties

Note that in ECMAScript and JavaScript, a named piece of data of a certain type is commonly referred to as a
property. However, After Effects already has a separate definition of a “property”: It is a specific editable value
within a layer. Therefore in this section the synonymous term “attribute” refers to these same pieces of data.

Global functions
This section describes globally available functions that are specific to After Effects. Any JavaScript object or
function can call the functions in this section.

23
Reference

Functions

Function Reference Description

ale r t () see “alert() global function” on page 24 displays an alert dialog displaying a specified
text string

p romp t() see “prompt() global function” on opens a dialog box with a text field into which
page 26 the user can enter a text string

w r i te() see “write() global function” on page 27 writes output to the Info palette, with no line
break added

w r iteL n () see “writeLn() global function” on writes output to the info palette, adding a line
page 27 break at the end

clearOutput() see “clearOutput() global function” on clears the Info palette

page 24

confir m() see “confirm() global function” on prompts the user with a modal dialog and yes/
page 25 no buttons which clear the dialog and return a
boolean

fi l e G e t D i a l o g ( ) see “fileGetDialog() global function” on presents the platform’s standard Open dialog
page 25 box

fi l e Pu t D i a l o g ( ) see “filePutDialog() global function” on presents the platform’s standard Save dialog
page 25 box

fo l d e r G e t D i a l o g ( ) see “folderGetDialog() global function” displays a dialog in which the user can select a
on page 26 folder

alert() global function

ale r t ( te x t )

Description

The Alert global function opens an alert dialog that can contain a text alert. The user then has the option of
clicking OK to close the window.

Parameters

text text string that is displayed in the dialog, which can display up to 240 characters

Example
ale r t ( "Co S A L ives! ");

clearOutput() global function

c learOutput()

Description

The clearOutput global function clears the output in the info palette.

Parameters

None.

24
Reference

confirm() global function

c onfir m( te x t )

Description

The Confirm global function prompts the user with a modal dialog and yes/no buttons that clear the dialog.
These return a boolean; true if yes, false if no.

Parameters

t ext text string; Mac OS user interface can display 256 characters, Windows, 30 characters

Returns

Boolean.

Example
v ar shouldAdd = confir m("Add to Render Queue?");
if ( sho u l d Ad d == "t r u e"){
proj.renderQueue.items.add(myCompItem);
}

fileGetDialog() global function

fi l e G e t D i a l o g ( prompt,t y p eList )

Description

The fileGetDialog global function presents the Open dialog box that is standard for the platform on which
After Effects is running.
The typeList is a semicolon-separated list of four-character Mac OS file types followed by Windows file exten-
sions. For example, a value of "EggP aep" for this argument specifies that the Open dialog box is to display
After Effects project items only; other file types will be grayed out.

Parameters

promp t message that displays on the title bar of the dialog; truncated if too long

t y p eL ist a platform-specific value indicating a list of file types to display

Returns

File object, or null if the user cancels the dialog.

filePutDialog() global function

fi l e Pu t D i a l o g ( prompt,de fault,t y p e )

Description

The filePutDialog global function presents the Save dialog box that is standard for the platform on which After
Effects is running.

25
Reference

Parameters

prompt message that appears on the title bar of the dialog; truncated if too long

d efault default file name to display in the file-saving dialog; this value must observe the file-naming
conventions of the platform on which After Effects is running

type specified file type

Returns

File object, or null if the user cancels the dialog.

folderGetDialog() global function

f o l d e r G e t D i a l o g ( prompt )

Description

The folderGetDialog global function displays a dialog in which the user can select a folder.

Parameters

promp t message that appears on the title bar of the dialog; truncated if too long

Returns

Folder object, or null if the user cancels the dialog.

prompt() global function

p romp t( prompt, de fault )

Description

The prompt global function opens a dialog box with a text field into which the user can enter a text string. The
text string is returned as a value, or is null if the dialog is cancelled.

Parameters

promp t text string that appears in the prompt dialog

default text string that appears by default in the text field

Returns

String, or null if dialog is cancelled. Read-only.

Example
// p resu min g a p ro j ect l o a d ed w i th a t l e a s t on e com p i s op e n :
var myCompItem = app. project.item(1);
var newName = prompt( "What would you like to name the comp?");
// ren a me it

i f ( n e w Na m e ) { / / i f t h e u s e r c a n ce l s , n e w Na m e i s nul l
myComp Item. n a me = n ewNa me; / / n e w Na m e n ow h old s a s t r i n g
}

26
Reference

write() global function

w r i te ( te x t )

Description

The write global function writes output to the Info palette, with no line break added.

Parameters

t ext text string; truncated if too long for the info palette

Example
w r ite ( “ T h i s tex t a p p e a r s i n In f o p a l e t te .” ) ;

See also

“writeLn() global function” on page 27

writeLn() global function

w r iteL n ( te x t )

Description

The write global function writes output to the info palette and adds a line break at the end.

Parameters

t ext text string

Example
w r iteLn(“ This line of text appears in the console w indow w ith a line break at the end.”);

See also

“TextDocument.” on page 179

Application object
ap p.

Description

The application (app) global object enables access to data and functionality within the After Effects appli-
cation. Attributes of the Application object provide access to specific objects within After Effects. Methods of
the Application object can create documents, open existing documents, 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.

27
Reference

Attributes

Attribute Reference Description

p ro je c t see “Application project attribute” on instance of the current After Effects Project
page 35 and “Project object” on and all of its associated methods & attributes
page 122

lan gu a g e see “Application language attribute” on identifies the language in which the applica-
page 33 tion is running

v ersion see “Application version attribute” on identifies the version number of the After
page 37 Effects application

ser ialNumber see “Application serialNumber identifies the serial number of the After Effects
Attribute” on page 36 installation

re g i s te re d Na m e see“Application registeredName identifies the name to which the After Effects

attribute” on page 36 installation is registered

re g i s te re d Com p a ny see “Application registeredCompany identifies the company to which the After
attribute” on page 36 Effects installation is registered

bu ildNa me see “Application buildName attribute” identifies the name of this build of the applica-
on page 30 tion

buildNumber see “Application buildNumber identifies the number of this build of the appli-
attribute” on page 30 cation

isProfessionalVersion see “Application isProfessionalVersion identifies if the After Effects version is the Pro-
attribute” on page 32 fessional Version

isWatchFolder see “Application isWatchFolder boolean that returns true when the local appli-
attribute” on page 32 cation is running in Watch Folder mode

isRenderEng ine see “Application isRenderEngine identifies whether the local After Effects appli-
attribute” on page 32 cation is installed as a render engine

se t t i n g s see “Application settings attribute” on calls settings within After Effects that can be
page 37 and “Settings object” on set via scripting
page 171

on Er ror see “Application onError attribute” on a callback that is called when an error occurs in
page 34 the application

ex it Cod e see “Application exitCode attribute” on Used only when executing script externally
page 32 (i.e., from a command line or AppleScript). Set
to zero, indicates no error occurred; set to a
positive number, indicates an error occurred
while running the script.

exitAfterLaunchAndEval see “Application exitAfterLaunchAndE- specifies whether the application remains

val attribute” on page 31 open after running a script from the command
line on Windows

Methods

Method Reference Description

n ew Pro j e c t ( ) see “Application newProject() method” opens a new project in After Effects
on page 33

op e n ( ) see “Application open() method” on opens a project or an Open Project dialog

page 34

28
Reference

Method Reference Description

q u it ( ) see “Application quit() method” on quits the application

page 35

wat ch Fo lder() see “Application watchFolder() method” starts watch-folder mode; does not return until
on page 38 watch-folder mode is turned off

pauseWatchFolder() see “Application pauseWatchFolder() pauses a current watch-folder process

method” on page 35

endWatchFolder() see “Application endWatchFolder() ends a current watch-folder process

method” on page 31

pu rge () see “Application purge() method” on purges a targeted type of cached information
page 35 (replicates Purge options in the Edit menu)

b e g i n Un d o Gro u p ( ) see “Application beginUndoGroup() groups the actions that follow it into a single
method” on page 29 undoable step

endUndoGroup() see “Application endUndoGroup() ends an undo group; needed only when one
method” on page 30 script contains more than one undo group

b e g i n Su p p re s s D i a l o g s ( ) see “Application beginSuppressDia- begins suppression of dialogs in the user inter-

logs() method” on page 29 face

endSuppressDialog s() see “Application endSuppressDialogs() ends suppression of dialogs in the user inter-
method” on page 30 face

se tMemor yUsageLimits() see “Application setMemoryUsageLim- sets memory usage limits as in the Cache pref-
its() method” on page 37 erences tab

se tSavePreferencesOnQuit() see “Application setSavePreferencesOn- sets whether Preferences are saved when the
Quit() method” on page 37 application is quit

Application beginSuppressDialogs() method

ap p . b e g i n Su p p re s s D i a l o g s ( )

Description

This method begins suppression of dialogs in the user interface.

Parameters

None.

Returns

None.

Application beginUndoGroup() method

ap p . b e g i n Un d o Gro u p ( u n d oSt r i n g )

Description

An undo group allows a script to logically group all of its actions as a single undoable action (for use with the
Edit Undo/Redo menu items). Should be used in conjunction with the application.endUndoGroup() method.
Please note that beginUndoGroup() and endUndoGroup() pairs can be nested. Groups within groups become
part of the larger group, and will undo correctly. In such cases, the names of inner groups are ignored.

29
Reference

Parameters

undoSt r ing (mandatory) the text that will appear for the Undo command in the Edit menu (i.e.,“Undo u n d oS t r i n g ”)

See also

“Application endUndoGroup() method” on page 30

Application buildName attribute

ap p .buildName

Description

The buildName attribute identfies the name of the build of After Effects being run. This attribute is used
primarily by Adobe for testing and troubleshooting purposes.

Type

String; read-only.

Returns

None.

See also

“Application beginUndoGroup() method” on page 29

Application endWatchFolder() method

ap p .endWatchFolder()

Description

The endWatchFolder() method ends watch folder mode.

Parameters

None

See also

“Application version attribute” on page 37

“Application pauseWatchFolder() method” on page 35

Application exitAfterLaunchAndEval attribute

ap p .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 will cause the application to run a script
(from a file and 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.
Note that this attribute only has an effect when After Effects is run, and it has no effect on Mac OS.

Type

Boolean; read/write.

31
Reference

Application exitCode attribute

ap p .exitCo d e

Description

The exitCode attribute is used only when executing a script from outside After Effects (i.e., from a command
line or AppleScript).
On Mac OS and Windows, the exitCode 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, it will be set to a positive integer.

Type

Integer; read/write.

Example
ap p.exitCode = 2; //on quit, if value is 2, no er ror has occur re d

Application isProfessionalVersion attribute

ap p .isProfessionalVersion

Description

The isProfessionalVersion attribute is a boolean used to determine if the locally installed After Effects appli-
cation is the Standard or Professional version.

Type

Boolean; read-only.

Example
v a r P B = a p p. i s Pro d u c t i o n Bu n d l e ;
a l e r t ( " It i s " + P B + " t h a t yo u a re r u n n i n g t h e Pro d u c t i o n Bu n d l e . " ) ;

Application isRenderEngine attribute

ap p .isRenderEng ine

Description

The isRenderEngine attribute is a boolean used to determine if an installation of After Effects is a Render
Engine only installation.

Type

Boolean; read-only.

Application isWatchFolder attribute

ap p .isWatch Folder

Description

The isWatchFolder attribute is a boolean used to determine if the Watch Folder dialog is currently displayed
(and the application is currently watching a folder for rendering). This returns true when the Watch Folder
dialog is open.

32
Reference

Type

Boolean; read-only.

Application language attribute

ap p .language

Description

The language attribute indicates in which language After Effects is running. The codes for the language
attribute are as follows:
• Language.ENGLISH
• Language.FRENCH
• Language.GERMAN
• Language.JAPANESE

Type

Language enumerated type (listed above).

Example
v ar lang = app.language;
if (lang == Language.JAPANESE){
aler t("After E ffects is r u n n in g i n Ja p an e s e . " ) } ;
else if (l a n g == L a n g u a g e. E N GL I S H ){
aler t("After E ffects is r u n n in g i n E n g li s h . " ) } ;
else if (l a n g == L a n g u a g e. FR E N C H ){
aler t("After Effects is r unning in French.")};
else{
aler t("After Effects is r unning in Ger man.")
};

Application newProject() method

ap p. n e w Pro j e c t ( )

Description

The newProject method opens a new project in After Effects, replicating the File > New > New Project menu
command. If a project is already open and has been edited, the user will be prompted to save.
Use app.project.close(CloseOptions.DO_NOT_SAVE_CHANGES) to close an open project before opening
a new one.

Parameters

None.

Returns

Project object; null if the user cancels a Save dialog in response to having an open project that has been edited
since the last save.

33
Reference

Example
ap p.pro j ect. cl o se(C l o seOp tio n s. D O_ N OT _ S AV E _ C HAN G E S ) ;
a p p. n e w Pro j e c t ( ) ;

See also

“Project close() method” on page 124

Application onError attribute

ap p .onEr ror

Description

The onError attribute takes a function to perform an action when an error occurs. By creating a function and
assigning it to onError, you can respond to the error systematically, e.g., close and restart the application,
noting the error in a log file if it occurred during rendering.

Type

Function that takes a string, or null if no function is assigned.

Example
fu n c tion er r(er rSt r ing) (
aler t(er rSt r ing);
)
app.onEr ror = er r

Application open() method

ap p .open()
ap p .open( fi l e )

Description

The open() method opens a project. If the file parameter is null (i.e., if no argument is used) the user will be
presented with a dialog to select and open a file.

Parameters

file (Optional) File object being opened

Returns

Project object (the file specified as a parameter), or null if the user cancels the Open dialog.

Example
v ar my_file = new File("../my_folder/my_test.aep");
if ( my _ fi l e. exi st){
new_pro ject = app. open(my_file);
i f ( n e w _ p ro j e c t ) {
aler t(n ew_ p ro j ect. fi l e. n a me);
}
}

34
Reference

Application pauseWatchFolder() method

ap p .pauseWatchFolder( p a u s e )

Description

The pauseWatchFolder() method pauses searching the target folder for render items.

Parameters

pause boolean (paused - true or false)

See also

“Application version attribute” on page 37

“Application endWatchFolder() method” on page 31

Application project attribute

app.project

Description

This attribute is the project that is currently loaded.

For more information about what is contained in the Project object, see “Project object” on page 122.

Type

Project; read-only.

Application purge() method

ap p .purge(target)

Description

The purge method replicates the functionality and target options of the Purge options within the Edit menu.
The target parameter contains the area of memory to be purged; the options for target are listed as enumerated
variables below.

Parameters

t arg e t the type of elements to purge from memory; use one of Enumerated Types below

Enumerated Types

PurgeTarget.ALL_CACHES purges all data that After Effects has cached to physical memory

Pur g eTa rg et. U N D O_ C AC H E S purges all data saved in the undo cache

Pur g eTa rg et. S NA P S H OT_ C AC H E S purges all data cached as comp/layer snapshots

Pur g eTa rg et. I MAGE _ C AC H E S purges all saved image data

Application quit() method

ap p. quit()

35
Reference

Description

The quit method quits the application.

Parameters

None.

Returns

None.

Application registeredCompany attribute

ap p . re g i s te re d Com p a ny

Description

Text string; name (if any) that the user of the application entered as the registered company at the time of
installation.

Type

Text string; read-only.

Example
v ar company = app. re g isteredCompany ;
aler t(“Your company name is “ + company + “.”);

Application registeredName attribute

ap p . re g i s te re d Na m e

Description

The registeredName attribute contains the text string that the user of the application entered for the registered
name at the time of installation.

Type

Text string; read-only.

Example
v ar userName = app. re g isteredName;
confir m(“Are you “ + userName + “?”);
Application serialNumber Attribute
ap p .ser ialNumber

Description

The serialNumber attribute contains an alphanumeric string that is the serial number of the installed version
of After Effects.

Type

String; read-only.

36
Reference

Example
v ar ser ial = app.ser ialNumber ;
aler t("This copy is ser ial number " + ser ial);

Application setMemoryUsageLimits() method

ap p .setMemor yUsageLimits( i m a g e C a c h e Pe rc e n t a g e , m a x i m u m Me m o r y Pe rc e n t a g e )

Description

This method sets memory usage limits as in the Cache preferences tab.

Parameters

imageCachePercentage floating-point value; percentage of memory assigned to image cache

max imumMemor yPercentage floating-point value; maximum usable percentage of memory

Returns

None.

Application setSavePreferencesOnQuit() method

ap p .setSavePreferencesOnQuit( doSave )

Description

This method sets the toggle that determines whether preferences are saved when the application is closed
(quit).

Parameters

do S ave boolean; if true, preferences are set to save on quit

Returns

None.

Application settings attribute

app.settings

Description

This attribute holds the currently loaded settings.

For more information about what is contained in the Settings object, see “Settings object” on page 171.

Type

Settings; read-only.

Application version attribute

ap p .version

37
Reference

Description

The version attribute returns an alphanumerical string indicating which version of After Effects is running.

Type

String; read-only.

Example
v ar ver = app. version;
aler t("This machine is r unning version " + ver + " of Af ter Effects.");

Application watchFolder() method

ap p .watchFolder( f o l d e r _ o b j e c t _ t o _ w a t c h )

Description

The watchFolder() method starts a watch folder (network rendering) process pointed at a specified folder.

Parameters

f o l d e r _ o b j e c t _ to _ w a tch the Folder object to be watched

Example
v ar theFolder = new Folder(“c:\\tool”);
app.watchFolder(theFolder);

See also

“Application endWatchFolder() method” on page 31

“Application pauseWatchFolder() method” on page 35

AVItem object
ap p.proj e c t . item( i n d e x )

Description

The AVitem object provides access to attributes and methods of audio/visual files imported into After Effects.
AVItem is the base class for both CompItem and FootageItem, so AVItem attributes and methods are also
available when working in CompItem and FootageItem.

Attributes

Attribute Reference Description

n ame see “AVItem name attribute” on page 42 name of the object as shown in the Project
window

w idt h see “AVItem width attribute” on page 45 integer [1 ..30,000] describing the width, in pix-
els of the item

heig ht see “AVItem height attribute” on integer [1 .. 30,000] describing the height, in
page 42 pixels of the item

38
Reference

Attribute Reference Description

pix e l Asp e c t see “AVItem pixelAspect attribute” on pixel aspect ratio; floating-point value [0.01
page 42 ..100]

fr a m e R a te see “AVItem frameRate attribute” on frame rate of the AVItem [1..99]

page 41

fr a m e D u r a t i o n see “AVItem frameDuration attribute” frame rate for the AVItem [1/99 .. 1 ]
on page 40

dur at io n see “AVItem duration attribute” on duration of the AVItem, in seconds [0 .. 10,800]
page 40

u seProxy see “AVItem useProxy attribute” on boolean describing whether a proxySource

page 45 should be used for this item

prox y S o u rce see “AVItem proxySource attribute” on FootageItem used as proxy of the AVItem;
page 43 read-only

t ime see “AVItem time attribute” on page 45 current time of the AVItem in seconds

u se dIn see “AVItem usedIn attribute” on array containing all the CompItems that use
page 45 this AVItem

hasVi d e o see “AVItem hasVideo attribute” on true if the AVItem has an audio component
page 41

hasAu d i o see “AVItem hasAudio attribute” on true if the AVItem has a video component
page 41

fo o t a g e Mi s s i n g see “AVItem footageMissing attribute” true if the AVItem cannot be found or if it is a

on page 40 placeholder

Attributes from Item object (See “Item object” on page 98)

Attribute Reference Description

n ame see “Item name attribute” on page 99 name of the object as shown in the Project
window

comment see “Item comment attribute” on string that holds a comment

page 99

id see “Item id attribute” on page 99 unique integer ID for this item

parentFolder see “Item parentFolder attribute” on parent folder of this item

page 99

se l e c te d see “Item selected attribute” on true if this item is currently selected

page 100

t y p eNa me see “Item typeName attribute” on string corresponding to the type of item
page 100

Methods

Method Reference Description

se t Proxy () see “AVItem setProxy() method” on sets a proxy for the AVItem
page 43

se tProxyWithSequence() see “AVItem setProxyWithSequence() sets a sequence as a proxy for the AVItem
method” on page 44

39
Reference

Method Reference Description

se t Prox y Wi t h S o l i d ( ) see “AVItem setProxyWithSolid() sets a solid as a proxy (feature available only via
method” on page 44 scripting)

se tProxyWithPlaceholder() see “AVItem setProxyWithPlaceholder() sets a placeholder as a proxy

method” on page 43

se tProxyToNone() see “AVItem setProxyToNone() method” removes the proxy

on page 43

Method from Item object (See“Item object” on page 98)

Method Reference Description

remove() see “Item remove() method” on deletes the item from the project
page 100

AVItem duration attribute

ap p.project.ite m(index). dur at i on

Description

The duration attribute returns the duration, in seconds, of the item. This attribute is read-only unless it is a
CompItem.
Permissible range of values is [0..10,800]. In a FootageItem, duration is linked to the duration of the
mainSource; in a CompItem, it is linked to the duration of the composition. This value may be written only
in a CompItem. It is an error to change this value if the item is a FootageItem.
Note: Still footage items have a duration of 0.

Type

Floating-point value; seconds. Read/write when item is a CompItem; otherwise, read-only.

AVItem footageMissing attribute

ap p.project.ite m(index). footageMissing

Description

The footageMissing attribute is true if the AVItem cannot be found or if it is a placeholder.

Type

Boolean; read-only.

AVItem frameDuration attribute

ap p.project.ite m(index). f r a m e D u r a t i o n

Description

The frameDuration attribute returns the length, in seconds, of a frame for this AVItem.
Permitted range is [1/99 .. 1 ]. This is the reciprocal of frameRate. When you set the frameDuration, you are
really storing the reciprocal as a new frameRate.

40
Reference

In the case of a CompItem, the value reflects the value for the comp. In the case of a FootageItem, the value
reflects the value for the mainSource.

41
Reference

Type

Boolean; read-only.

AVItem height attribute

ap p.project.ite m(index). heig ht

Description

The height attribute is the height, in pixels, of the item.

Permitted range is [1 ..30,000]. In a FootageItem, height is linked to the height of the mainSource; in a
CompItem, it is linked to the height of a composition. It is legal to change the height of a CompItem or a
FootageItem whose mainSource is a SolidSource. It is an error to change the height if the item is a FootageItem
whose mainSource is not a SolidSource.

Type

Integer; read-only unless a CompItem.

AVItem name attribute

ap p.project.ite m(index). n a me

Description

The name attribute is the name of the object as shown in the Project window.
In a FootageItem, the name is linked to the mainSource.
It is an error to attempt to change the name if the mainSource is a FileSource; in that case, the name is tied to
the name of the file(s) and may not be changed.

Type

String; read/write.

AVItem pixelAspect attribute

ap p.project.ite m(index). p i xe l Asp e c t

Description

The pixelAspect attribute determines the pixel aspect ratio of a given item.
Permitted range is [0.01 .. 100]. In a FootageItem, pixelAspect is linked to the pixelAspect of the mainSource;
in a CompItem, it is linked to the pixelAspect of a composition.
Certain pixelAspect values are specially known to After Effects, and will be stored/retrieved with perfect
accuracy. These are the set { 1, 0.9, 1.2, 1.07, 1.42, 2, 0.95, 1.9 }. Other values may experience slight rounding
errors when you set them and get them. Thus, the value you retrieve after setting may be slightly different from
the value you supplied.

Type

Floating-point value; read-only unless a CompItem.

42
Reference

AVItem proxySource attribute

ap p.project.ite m(index). proxySource

Description

The proxySource attribute is the FootageSource being used as a proxy.

The attribute is read-only, but it can be changed by calling any of the AVItem methods that change the proxy
source: setProxy(), setProxyWithSequence(), setProxyWithSolid(), and setProxyWithPlaceholder().

Type

FootageSource; read-only.

AVItem setProxy() method

ap p.project.ite m(index) . s e t Prox y ( F i l e fi l e )

Description

The setProxy method sets a file as the proxy of an AVItem.

It loads the given file into a FileSource and establishes this as the new proxySource. It does not preserve the
interpretation parameters, instead using the user preference.
This is different than what happens with a FootageItem's main source, but both are the same behavior as the
user interface. If the file has an unlabeled alpha channel, and the user preference says to ask the user what to
do via a dialog, scripting will guess the alpha interpretation instead of asking the user. After changing the
proxySource, this method will set the value of useProxy to true.

Parameters

File file to be used as a proxy

Returns

None.

AVItem setProxyToNone() method

ap p.project.ite m(index) . setProxy To No ne ( )

Description

The setProxyToNone method removes the proxy from this AVItem. Following this, the value of proxySource
is null.

Returns

None.

AVItem setProxyWithPlaceholder() method

ap p.project.ite m(index) . setProxy Wi thP l a ceh old e r ( name, w idth, he ig ht, frameRate, dura t ion )

43
Reference

Description

The setProxyWithPlaceholder method creates a PlaceholderSource with specifications according to the input
arguments and establishes this as the new proxySource.
Note that there is no direct way to set a placeholder as a proxy in the user interface; this behavior occurs when
a proxy has been set and then moved or deleted.
This method does not preserve the interpretation parameters. After changing the proxySource, the value of
useProxy is set to true.

Parameters

n ame text string

w idth, heig ht pixel dimensions of solid[4..30,000]

fr a m e R a te frames per second [1..99]

d ur a tio n length in seconds [0..10,800] (up to 3 hours)

Returns

None.

AVItem setProxyWithSequence() method

ap p.project.ite m(index) . setProxy Wi thS e q u e n ce ( file, forc eAlphabe t ical )

Description

The setProxy method loads the given sequence into a FileSource and establishes this as the new proxySource.
It loads the given sequence into a FileSource and establishes this as the new proxySource. It does not preserve
the interpretation parameters, instead using the user preference.
If the file has an unlabeled alpha channel, and the user preference says to ask the user what to do via a dialog,
scripting will guess the alpha interpretation instead of asking the user.

Parameters

File file to be used as a proxy.

f orceAlphabetical boolean determining whether to use the “force alphabetical order” option

Returns

None.

AVItem setProxyWithSolid() method

ap p.project.ite m(index) . s e t Prox y Wi t h S o l i d ( c o l o r, n a m e , w i d t h , h e i g h t , p i x e l As p e c t )

Description

The setProxyWithSolid method creates a SolidSource with specifications according to the input arguments
and establishes this SolidSource as the new proxySource.
Note that there is no way, using the user interface, to set a solid as a proxy; this feature is available only via
scripting.

44
Reference

This method does not preserve the interpretation parameters. After changing the proxySource, the value of
useProxy is set to true.

Parameters

color array of 3 floats in the range [0..1] (red, green, and blue values)

w idth, heig ht pixel dimension of solid[1..30,000]

pixe l As p e c t pixel aspect of solid [0.01 .. 100]

Returns

None.

sou r ce see “AVLayer source attribute” on source item for this layer
page 52

isN a m e From S o u rce see “AVLayer isNameFromSource true if the layer has no expressly set name, but
attribute” on page 51 contains a named source

heig ht see “AVLayer height attribute” on height of the layer in pixels

page 51

w idt h see “AVLayer width attribute” on width of the layer in pixels

page 53

audioE n a b l e d see “AVLayer audioEnabled attribute” on true if the layer's audio is enabled
page 48

mo t ionBlur see “AVLayer motionBlur attribute” on true if layer's motionBlur is enabled

page 52

ef f e c t s Ac t ive see “AVLayer effectsActive attribute” on true if the layer's effects are active
page 50

a djust mentLayer see “AVLayer adjustmentLayer attribute” true if this is an adjustment layer
on page 47

g u ideL ayer see “AVLayer guideLayer attribute” on specifies whether this AVLayer is a guide layer
page 51

t h re e D L ayer see “AVLayer threeDLayer attribute” on true if this is a 3D layer

page 53

can S etCo l l a p seTr a n sfo r ma tio n see “AVLayer canSetCollapseTransfor- true if it is legal to change the value of collapse-
mation attribute” on page 49 Transformation on this layer

collapseTr ansfor mation see “AVLayer collapseTransformation true if collapse transformation is on

attribute” on page 50

46
Reference

Attribute Reference Description

fr ameBlending see “AVLayer frameBlending attribute” true if frame blending is enabled

on page 50

can S etTi meRema p E n a bl ed see “AVLayer canSetTimeRemapEn- true if it is legal to change the value of timeR-
abled attribute” on page 50 emap

t imeRemapEnabled see “AVLayer timeRemapEnabled true if time remapping is enabled on this layer
attribute” on page 53

hasAu d i o see “AVLayer hasAudio attribute” on true if the layer contains an audio component
page 51

audioAc t ive see “AVLayer audioActive attribute” on true if the layer's audio is active at the current
page 48 time

blendingMode see “AVLayer blendingMode attribute” blending mode of the layer

on page 48

preser veTr ansparency see “AVLayer preserveTransparency true if preserve transparency is enabled
attribute” on page 52

t r a ckMa tteTy p e see “AVLayer trackMatteType attribute” if layer has a track matte, specifies the way it
on page 53 will be applied

isTr a ck Ma tte see “AVLayer isTrackMatte attribute” on true if this layer is being used as a matte track
page 52 for the layer below it

hasTr a ck Ma tte see “AVLayer hasTrackMatte attribute” true if the layer above is being used as a track
on page 51 matte on this layer

qu alit y see “AVLayer quality attribute” on layer quality setting

page 52

g u ideL ayer see “AVLayer guideLayer attribute” on true if the layer is a guide layer
page 51

Method

Method Reference Description

audioAc t ive At Ti m e ( ) see “AVLayer audioActiveAtTime() given a time, returns whether this layer's audio
method” on page 48 is active at that time

Example

If the first item in the project is a CompItem, and the first layer of that CompItem is an AVLayer, the following
would set the layer quality, startTime, and inPoint.
v ar firstLayer = app. project.item(1).layer(1);
firstLayer. qualit y = LayerQualit y.BEST;
firstLayer.star tTime = 1;
firstLayer.inPoint = 2;

AVLayer adjustmentLayer attribute

ap p.project.ite m(index). adjust mentLayer

Description

The adjustmentLayer attribute returns a value of true if the layer is an adjustment layer.

47
Reference

Type

Boolean; read/write.

AVLayer audioActive attribute

ap p.project.ite m(index). a u d i o Ac t ive

Description

The audioActive attribute returns a value of true if the layer's audio is active at the current time.
To be true, audioEnabled must be true, no other layer with audio may be soloing unless this layer is soloed
too, and the time must be in between the inPoint and outPoint of this layer.
Type
Boolean; read-only.

AVLayer audioActiveAtTime() method

ap p.project.ite m(index) . a u d i o Ac t ive At Ti m e ( t im e )

Description

Given a time, the audioActiveAtTime method returns whether this layer's audio will be active at that
time.
To be true the layer’s audioEnabled attribute must be true, no other layer containing audio may be soloing
unless this layer is soloed too, and the given time must be between this layer's inPoint and outPoint.

Parameters

t ime time, in seconds (floating-point value)

Returns

Boolean.

AVLayer audioEnabled attribute

ap p.project.ite m(index). a u d i o E n a bl ed

Description

The audioEnabled attribute is true if the layer's audio is enabled. This attribute corresponds to the speaker
button in the user interface.

Type

Boolean; read/write.

AVLayer blendingMode attribute

ap p.project.ite m(index). blendingMode.

Description

The blendingMode is the blending mode of the layer.

48
Reference

Type

Enumerated type (read/write); one of the following:

B lendingMode.ADD

BlendingMode.ALPHA_ADD

BlendingMode.CLASSIC_COLOR_BURN

BlendingMode.CLASSIC_COLOR_D OD GE

BlendingMode.CLASSIC_DIFFERENCE

BlendingMode.COLOR

BlendingMode.COLOR_BURN

BlendingMode.COLOR_D OD GE

BlendingMode.DANCING_DISSOLVE

BlendingMode.DARKEN
BlendingMode.DIFFERENCE

BlendingMode.DISSOLVE

BlendingMode.EXCLUSION

BlendingMode.HARD_LIGHT

BlendingMode.HARD_MIX

BlendingMode.HUE

BlendingMode.LIGHTEN

BlendingMode.LINEAR_BURN

BlendingMode.LINEAR_D OD GE

BlendingMode.LINEAR_LIGHT

BlendingMode.LUMINESCENT_PREMUL

BlendingMode.LUMINOSITY

BlendingMode.MULTIPLY

BlendingMode.NORMAL

BlendingMode.OVERLAY
BlendingMode.PIN_LIGHT

BlendingMode.SATURATION

BlendingMode.SCREEN

BlendingMode.SILHOUETE_ALPHA

BlendingMode.SILHOUET TE_LUMA

BlendingMode.SOFT_LIGHT

BlendingMode.STENCIL_ALPHA

BlendingMode.STENCIL_LUMA

BlendingMode.VIVID_LIGHT

AVLayer canSetCollapseTransformation attribute

ap p.project.ite m(index). ca n S etCo l l a p se Tr a n s f or m a t i on

49
Reference

Description

The canSetCollapseTransformation attribute returns a value of true if it is legal to change the value of the
collapseTransformation attribute on this layer.

Type

Boolean; read-only.

AVLayer canSetTimeRemapEnabled attribute

ap p.project.ite m(index). c a n S e t Ti m e Re m a p E n a b l e d

Description

The canSetTimeRemapEnabled attribute returns a value of true if it is legal to change the value of the timeR-
emapEnabled attribute on this layer.

Type

Boolean; read-only.

AVLayer collapseTransformation attribute

ap p.project.ite m(index). collapseTr ansfor mation

Description

The collapseTransformation attribute returns a value of true if collapse transformation is on for this layer.

Type

Boolean; read/write.

AVLayer effectsActive attribute

ap p.project.ite m(index). e f f e c t s Ac t ive

Description

The effectsActive attribute returns a value of true if the layer's effects are active.

Type

Boolean; read/write.

AVLayer frameBlending attribute

ap p.project.ite m(index). fr ameBlending

Description

The frameBlending attribute returns a value of true if frame blending is enabled.

Type

Boolean; read/write.

50
Reference

Boolean; read-only.

AVLayer isTrackMatte attribute

ap p.project.ite m(index). isTr a ckMatte

Description

The isTrackMatte attribute returns a value of true if this layer is being used as a matte track for the layer behind
it.

Type

Boolean; read-only.

AVLayer motionBlur attribute

ap p.project.ite m(index). motionBlur

Description

The motionBlur attribute returns a value of true if the layer's motionBlur is enabled.

Type

Boolean; read/write.

AVLayer preserveTransparency attribute

ap p.project.ite m(index). preser veTr ansparency

Description

The preserveTransparency attribute returns a value of true if preserve transparency is enabled for the layer.

Type

Boolean; read/write.

AVLayer quality attribute

ap p.project.ite m(index). qualit y.

Description

The quality is the layer quality specifying how this layer is to be displayed.

Type

Enumerated type (read/write); one of the following:

La yer Qu a l it y. B E S T
LayerQualit y.DRAFT
LayerQualit y.WIREFRAME

AVLayer source attribute

ap p.project.ite m(index). so u rce

52
Reference

Description

The source attribute is the source AVItem for this layer.

The value of the source will be null in a Text layer.

Type

AVItem; read-only.

AVLayer threeDLayer attribute

ap p.project.ite m(index). t h re e D L ayer

Description

The threeDLayer attribute is true if this is a 3D layer.

Type

Boolean; read/write.

AVLayer timeRemapEnabled attribute

ap p.project.ite m(index). ti meRema p E n a b le d

53
Reference

Type

Floating-point value; read-only.

Collection object
Description

A Collection object acts like an array that provides access to its elements by index. Like an array, a collection
associates a set of objects or values as a logical group and provides random access to them. However, most
collection objects are read-only. You do not assign objects to them yourself—their contents update automat-
ically as objects are created or deleted.
The index numbering of a collection starts with 1, not 0.

Objects

Object Reference Description

I t e mC o l l e c t i o n see “ItemCollection” on page 100 a collection of all of the items (imported files,
folders, solids, etc.) found in the Project win-
dow

La y er Co l l e c t ion see “LayerCollection” on page 111 contains all of the layers in a composition

O MCol l e c t ion see “OMCollection” on page 120 contains all of the OutputModule items in the
project

RQ ItemCo l l e c t i on see “RQItemCollection” on page 165 contains all of the RenderQueue items in the
project

Attributes

len gth the number of objects in the collection (applies to all collections)

Methods

[] retrieves an object or objects in the collection via its index number

CompItem object
ap p.proj ec t .item( i n d e x )

Description

The CompItem object provides access to attributes and methods of Compositions. These are accessed via their
index number.

Attributes

Attribute Reference Description

fr a m e D u r a t i o n see “CompItem frameDuration The duration of a single frame in seconds. This

attribute” on page 59 is the inverse of the framerate.

54
Reference

Attribute Reference Description

w or kAreaStar t see “CompItem workAreaStart the work area start time (in seconds)
attribute” on page 62

w or kAreaDur ation see “CompItem workAreaDuration the work area duration (in seconds)
attribute” on page 62

n umLayers see “CompItem numLayers attribute” on number of layers in the CompItem

page 60

hideShyLayers see “CompItem hideShyLayers corresponds to the value of the Hide All Shy
attribute” on page 59 Layers button in the Composition window

mo t ionBlur see “CompItem motionBlur attribute” if true, motion blur is enabled for this comp
on page 60

dr aft 3 d see “CompItem draft3d attribute” on sets the 3d display mode to Draft quality
page 58

fr ameBlending see “CompItem frameBlending if true, time filtering is enabled for this comp
attribute” on page 58

preser veNested Fr a meR a te see “CompItem preserveNestedFrameR- boolean determining whether the frame rate
ate attribute” on page 60 of nested compositions should be preserved

preser veNestedResolution see “CompItem preserveNestedResolu- boolean determining whether the resolution
tion attribute” on page 61 of nested compositions should be preserved

bgColor see “CompItem bgColor attribute” on background color of the composition

page 57

a ct ive C a mer a see “CompItem activeCamera attribute” current active Camera Layer
on page 57

display S ta r tTime see “CompItem displayStartTime changes the display of the start time in the
attribute” on page 58 Timeline window

resolutionFactor see “CompItem resolutionFactor integer array determining the factor by which
attribute” on page 61 the x and y resolution of the Composition win-
dow is downsampled

shutterAng le see “CompItem shutterAngle attribute” integer value (0 - 720) determining the camera
on page 62 shutter angle

shutterPhase see “CompItem shutterPhase attribute” integer value (0 - 360) determining the camera
on page 62 shutter phase

layers see “LayerCollection” on page 111 LayerCollection containing the layers of the
compItem

se l e c te d L ayer s see “CompItem selectedLayers array containing all selected Layers

attribute” on page 61

se l e c te d Pro p e r t i e s see “CompItem selectedProperties array containing all selected Properties

attribute” on page 61

Attributes inherited from Item object and AVItem object (see “Item object” on page 98 and “AVItem object” on
page 38)

Attribute Reference Description

n ame see “Item name attribute” on page 99 name of the object as shown in the Project
window

comment see “Item comment attribute” on string that holds a comment

page 99

55
Reference

Attribute Reference Description

id see “Item id attribute” on page 99 unique integer ID for this item

par entFolder see “Item parentFolder attribute” on parent folder of this item
page 99

se l e c te d see “Item selected attribute” on true if this item is currently selected

page 100

t y p eNa me see “Item typeName attribute” on string corresponding to the type of item
page 100

w idt h see “AVItem width attribute” on page 45 integer [1 ..30,000] describing the width, in pix-
els, of the item

heig ht see “AVItem height attribute” on integer [1 .. 30,000] describing the height, in
page 42 pixels, of the item

pixe l Asp e c t see “AVItem pixelAspect attribute” on pixel aspect ratio; floating-point value [0.01
page 42 ..100]

fr a m e R a te see “AVItem frameRate attribute” on frame rate of the AVItem [1..99].

page 41

fr a m e D u r a t i o n see “AVItem frameDuration attribute” frame rate for the AVItem [1/99 .. 1 ].
on page 40

dur at io n see “AVItem duration attribute” on duration of the AVItem, in seconds [0 .. 10,800]
page 40

u seProxy see “AVItem useProxy attribute” on boolean describing whether a proxySource

page 45 should be used for this item

prox y S o u rce see “AVItem proxySource attribute” on FootageItem used as proxy of the AVItem;
page 43 read-only

t ime see “AVItem time attribute” on page 45 current time of the AVItem in seconds

u se dIn see “AVItem usedIn attribute” on array containing all the CompItems that use
page 45 this AVItem

hasVi d e o see “AVItem hasVideo attribute” on true if the AVItem has an audio component
page 41

hasAu d i o see “AVItem hasAudio attribute” on true if the AVItem has a video component
page 41

fo o t a g e Mi s s i n g see “AVItem footageMissing attribute” true if the AVItem cannot be found or if it is a

on page 40 placeholder

Methods

Method Reference Description

duplic a te() see “CompItem duplicate() method” on creates and returns a duplicate of this comp
page 58 item

layer () see “CompItem layer() method” on returns the layer using index, relative index or
page 59 name

56
Reference

Methods inherited from Item object and AVItem object (see “Item object” on page 98 and “AVItem object” on
page 38)

Method Reference Description

r emove() see “Item remove() method” on deletes the item from the project
page 100

se t Proxy () see “AVItem setProxy() method” on sets a proxy for the AVItem
page 43

se tProxyWithSequence() see “AVItem setProxyWithSequence() sets a sequence as a proxy for the AVItem
method” on page 44

se t Prox y Wi t h S o l i d ( ) see “AVItem setProxyWithSolid() sets a solid as a proxy (feature available only via
method” on page 44 scripting)

se tProxyWithPlaceholder() see “AVItem setProxyWithPlaceholder() sets a placeholder as a proxy

method” on page 43

se tProxyToNone() see “AVItem setProxyToNone() method” removes the proxy

on page 43

Example

Given that the first item in the project is a CompItem, the following code would result in two alerts. The first
would display the number of layers in the CompItem, and the second would display the name of the last Layer
in the CompItem.
v ar firstComp = app. project.item(1);
aler t( "number of layers is " + firstComp.numLayers );
aler t( "name of last layer is " + firstComp.layer(firstComp.numLayers).name );

CompItem activeCamera attribute

ap p.project.ite m(index). a c t ive C a m e r a

Description

The active camera is the front-most camera layer that is enabled. The value is null if the comp contains no
enabled camera layers.

Type

Layer; read-only.

CompItem bgColor attribute

ap p.project.ite m(index). bgColor

Description

The bgColor attribute specifies the background color of the comp. The value should be an array containing
three floats in the range [0..1] for red, green, and blue.

Type

Array of three floating-point values from 0 to 1: [R, G, B); read/write.

57
Reference

Returns

CompItem.

CompItem frameBlending attribute

ap p.project.ite m(index). fr ameBlending

Description

The frameBlending attribute determines whether frame blending is enabled for this Composition. Corre-
sponds to the value of the frame blending button in the Composition window.

Type

Boolean; if true, frame blending is enabled; read/write.

58
Reference

CompItem frameDuration attribute

ap p.project.ite m(index) . f r a m e D u r a t i o n

Description

The frameDuration attribute returns the duration of a frame, in seconds. This is the inverse of the framerate
(or frames per second). This attribute is read-only.

Type

Floating-point value; read-only.

CompItem hideShyLayers attribute

ap p.project.ite m(index). hideShyLayers

Description

The hideShyLayers attribute determines whether shy layers should be visible in the Timeline window. It corre-
sponds to the value of the Hide All Shy Layers button in the Composition window.
If false, then only layers with "shy" set to false will be shown. If true, then all layers will be shown regardless of
the value of their "shy" attributes.

Type

Boolean; if true, shy layers are visible. Read/write.

CompItem layer() method

ap p.project.ite m(index). l ayer( i n d e x )
ap p.project.ite m(index). l ayer( o t h e r L aye r, re l In d e x )
ap p.project.ite m(index). l ayer( n a m e )

Description

The layer() method returns a specified layer object.

Using the syntax layer(int index) this method returns the layer with the given index. The given
index must be in the range [1,numLayers], where numLayers is the number of layers in the Composition.
Using the syntax l a yer(Layer otherLayer, int re lIndex ) this method returns the layer whose index is that of
the given otherlayer added to the given relindex. Relindex must be in the range [(1-otherlayer.index),
(numlayers-otherlayer.index)].
Using the syntax l a yer(S t r in g n a me) this method returns the layer within the CompItem whose name
matches the given name.

Parameters

Note that there are three separate types of usage possible with layer, with unique syntax for each:

in dex index number of the specified layer; an integer

59
Reference

or
otherLayer index number of the layer to which an offset will be applied

r elIn dex relative position of the layer; the difference between the two index numbers expressed as an
integer

or
n ame name of the specified number; a text string

Returns

Layer object.

CompItem layers attribute

ap p.project.ite m(index). layers

Description

The layers attribute contains the LayerCollection for this composition.

Type

LayerCollection. Read-only.

Boolean; if true, nested frame rate is preserved. Read/write.

CompItem preserveNestedResolution attribute

ap p.project.ite m(index). preser veNestedResolution

Description

The preserveNestedResolution attribute determines whether the resolution of nested compositions is

File Class
The File Class contains methods and attributes common to File objects. A File object corresponds to a disk file.
Also included in this class are all attributes and methods within the FileSystem class, as those apply to Files as
well as Folders.
Note that the difference between the File Class and File object is that the class attributes and methods require
no specific instance of a File, whereas class methods and attributes do.

Class attributes inherited from FileSource object (see “FileSource object” on page 72)

Class attribute Reference Description

fs see “FileSystem fs class attribute” on name of the file system; read-only

page 75

Methods

Method Reference Description

File( ) see “File() Class method” on page 63 constructs a new File object
n e w Fil e()

op e n D i a l o g ( ) see “File openDialog() Class method” on opens the built-in operating-system dialog to
page 68 select an existing file to open

saveD i a l o g ( ) see “File saveDialog() Class method” on opens the built-in operating-system dialog to
page 70 select a file name to save a file into

Class methods inherited from FileSource object (see “FileSource object” on page 72)

Class method Reference Description

de co d e ( ) see “FileSystem decode() class method” decodes the input string from UTF-8
on page 74

en co d e() see “FileSystem encode() class method” encodes the input string in UTF-8
on page 74

File() Class method

File( p a t h )
new File( p a t h )

Description

This function constructs a new File object. If the given path name refers to an already existing folder, a Folder
object is returned instead.
The CRLF sequence is preset to the system default, and the encoding is preset to the default system encoding.

63
Reference

Parameters

Path, expressed as a string. If missing, a temporary name is generated.

Returns

File (or Folder if path refers to an existing folder).

File object
File( “ p a th” )

Description

The File object contains methods and attributes common to File objects. A Folder object corresponds to a
folder.
Also included in this object are all attributes and methods within the FileSystem object, as those apply to Files
as well as Folders.

Attributes

Attribute Reference Description

cr eator see “File creator attribute” on page 66 Macintosh file creator as a four-character string

e n co d i n g see “File encoding attribute” on page 66 gets or sets the encoding for subsequent read/
write operations

e of see “File eof attribute” on page 67 has the value true if a read attempt caused the
current position to be behind the end of the
file

hidden see “File hidden attribute” on page 67 set to true if the file is invisible

len gt h see “File length attribute” on page 67 size of the file in bytes

lin eFe e d see “File lineFeed attribute” on page 67 way line feed characters are written

readonly see “File readonly attribute” on page 70 when set, prevents the file from being altered
or deleted

type see “File type attribute” on page 71 Macintosh file type as a four-character string

Attributes inherited from FileSystem object (see “FileSystem object” on page 75)

Attribute Reference Description

absoluteURI see “FileSystem absoluteURI attribute” full path name for the object in URI notation
on page 76

alias see “FileSystem alias attribute” on returns true if the object refers to a file system
page 77 alias

cre a te d see “FileSystem created attribute” on creation date of the object

page 77

er ror see “FileSystem error attribute” on contains a message describing the last file sys-
page 77 tem error

64
Reference

Attribute Reference Description

e x ist s see “FileSystem exists attribute” on returns true if the path name of this object
page 77 refers to an actually existing file or folder

f sNam e see “FileSystem fsName attribute” on file-system specific name of the object as a full
page 78 path name

mo d i fi e d see “FileSystem modified attribute” on date of the object's last modification

page 78

n ame see “FileSystem name attribute” on name of the object without the path specifica-
page 78 tion

parent see “FileSystem parent attribute” on folder object containing this object
page 79

pat h see “FileSystem path attribute” on path portion of the absolute URI
page 79

re l a t ive U R I see “FileSystem relativeURI attribute” on path name for the object in URI notation, rela-
page 79 tive to the current folder

Methods

Method Reference Description

clo se( ) see “File close() method” on page 66 closes the open file

copy() see “File copy() method” on page 66 copies the file to the given location

op e n ( ) see “File open() method” on page 68 opens the file for subsequent read/write oper-
ations

re a d ( ) see “File read() method” on page 69 reads the contents of the file from the current
position on

readch() see “File readch() method” on page 69 reads one single text character

re a d l n ( ) see “File readln() method” on page 70 reads one line of text

se ek( ) see “File seek() method” on page 71 seeks to a certain position in the file

te l l ( ) see “File tell() method” on page 71 returns the current position in the file as an off-
set in bytes

w r i te() see “File write() method” on page 72 writes the given string to the file

w r ite ln () see “File writeln() method” on page 72 writes the given string to the file and append a
line feed sequence

Methods inherited from FileSystem object (see “FileSystem object” on page 75)

Method Reference Description

ge t Re l a t ive U R I ( ) see “FileSystem getRelativeURI() calculates and returns the relative URI, given a
method” on page 78 base path, in URI notation

remove() see “FileSystem remove() method” on deletes the file or folder that this object repre-
page 79 sents

rename() see “FileSystem rename() method” on renames the object to the new name
page 80

resolve() see “FileSystem resolve() method” on attempts to resolve the file system alias that
page 80 this object points to

65
Reference

File close() method

F i l e ( p a t h ) .close()

Description

The close() method closes the open file. The return value is true if the file was closed, false on I/O errors.

Parameters

None.

Returns

Boolean.

File copy() method

F i l e ( p a t h ) .copy( targe t )

Description

The close() method copies the file to the given location.

You can supply a URI path name as well as another File object. If there is a file at the target location, it is
overwritten.
The method returns true if the copy was successful, false otherwise. The method resolves any aliases to find
the source file.

Parameters

t arg e t File object or String specifying the target location

Returns

Boolean.

File creator attribute

F i l e ( p a t h ) .creator

Description

The creator attribute is the Macintosh file creator as a four-character string. On Windows, the return value is
always "????".

Type

String; read-only.

File encoding attribute

F i l e ( p a t h ) . en co d in g

Description

The encoding attribute gets or sets the encoding for subsequent read/write operations.

66
Reference

The encoding is one of several predefined constants that follow the common Internet encoding names. Valid
names are UCS-2, X-SJIS, ISO-8851-9, ASCII or the like.
A special encoder, BINARY, is used to read binary files. This encoder stores each byte of the file as one Unicode
character regardless of any encoding. When writing, the lower byte of each Unicode character is treated as a
single byte to write. See “” on page 229 for a list of encodings. If an unrecognized encoding is used, the
encoding reverts to the system default encoding.

Type

String; read/write.

File eof attribute

F i l e ( p a t h ) .eof

Description

The File eof attribute has the value true if a read attempt caused the current position to be past the end of the
file.
If the file is not open, the value is true.

Type

Boolean; read-only.

File hidden attribute

F i l e ( p a t h ) .hidden

Description

The File hidden attribute has the value true if the file is invisible. Assigning a Boolean value sets or clears this
attribute.

Type

Boolean; read/write.

File length attribute

F i l e ( p a t h ) .length

Description

The File length attribute is size of the file in bytes. When setting the file size, the file must not be open.

Type

Number; read-only.

File lineFeed attribute

F i l e ( p a t h ) . l i n e Fe e d

67
Reference

Description

The File lineFeed attribute determines the way line feed characters are written. This can be one of the three
values: macintosh, unix or windows (actually, only the first character is interpreted).

Type

String (one of: macintosh, unix, windows); read/write.

File open() method

F i l e ( p a t h ) .open( m od e, t y p e, c rea tor )

Description

The File open() method opens the file for subsequent read/write operations. The type and creator arguments
are optional and Macintosh specific; they specify the file type and creator as two four-character strings. They
are used if the file is newly created. On other platforms, they are ignored.
When open() is used to open a file for read access, the method attempts to detect the encoding of the open
file. It reads a few bytes at the current location and tries to detect the Byte Order Mark character 0xFFFE. If
found, the current position is advanced behind the detected character and the encoding property is set to one
of the strings UCS-2BE, UCS-2LE, UCS4-BE, UCS-4LE or UTF-8. If the marker character cannot be found,
it checks for zero bytes at the current location and makes an assumption about one of the above formats
(except for UTF-8). If everything fails, the encoding property is set to the system encoding. The method
resolves any aliases to find the file.
You should be careful if you try to open a file more than once. The operating system usually permits you to do
so, but if you start writing to the file using two different File objects, you may destroy your data.
The return value is true if the file has been opened successfully, false otherwise.

Parameters

mo de one of r, w or e:

r (read) Opens for reading. If the file does not exist or cannot be found, the call fails.

w (write) Opens an empty file for writing. If the file exists, its contents are destroyed.

e (edit) Opens an existing file for reading and writing.

type The Macintosh file type; a four-byte character string; ignored on non-Macintosh operating systems.

creator The Macintosh file creator; a four-byte character string; ignored on non-Macintosh operating systems.

Returns

Boolean.

File openDialog() Class method

F ile . o p e n D i a l o g ( prompt, s e lect )

Description

The File.openDialog class method presents the Open dialog box that is standard for the platform on which
After Effects is running. This method overlaps somewhat with the easier to use fileGetDialog() global
function.

68
Reference

Parameters

p romp t An optional prompt (expressed as a string) that is displayed as part of the dialog if the dialog permits the
display of an additional message.

se l e c t This argument allows the pre-selection of the files that the dialog displays. Unfortunately, this argument is
different on Mac OS and on Windows.

s e l e c t ( Wi n ) Windows selection string is actually a list of file types with explanative text. This list appears in the bottom
of the dialog box as a drop-down list box so the user can select which types of files to display. The elements
of this list are separated by commas. Each element starts with the descriptive text, followed by a colon and
the file search masks for this text. Again, each search mask is separated by a semicolon. A Selection list that
allowed the selection of all text files (*.TXT and *.DOC) or all files would look like this:

Text Files:.TXT;.DOC,All files:*

A single asterisk character is a placeholder for all files.

s e l e c t ( Ma c On Mac OS, the optional second argument is a callback function. This function takes one argument, which
O S) is a File object. When the dialog is set up, it calls this callback function for each file that is about to be dis-
played. If the function returns anything else than true, the file is not displayed. This is true only for the open-
Dialog() method; the saveDialog() method ignores this callback method.

Returns

File object, or null if the user cancels the dialog.

File readonly attribute

F i l e ( p a t h ) .readonly

Description

The File readonly attribute, when set, prevents the file from being altered or deleted.

Type

Boolean; read/write.

File saveDialog() Class method

F ile . s ave D i a l o g ( prompt, s e lect )

Description

The File.saveDialog class method presents the Save dialog box that is standard for the platform on which After
Effects is running. This method overlaps somewhat with the easier-to-use filePutDialog() global function.

Parameters

p romp t An optional prompt (expressed as a string) that is displayed as part of the dialog if the dialog
permits the display of an additional message.

se l e c t This argument allows the pre-selection of the files that the dialog displays. Unfortunately, this
argument is different on Mac OS and on Windows.

se l e c t ( Wi n ) Windows selection string is actually a list of file types with explanative text. This list is dis-
played in the bottom of the dialog as a drop-down list box so the user can select which types
of files to display. The elements of this list are separated by commas. Each element starts with
the descriptive text, followed by a colon and the file search masks for this text. Again, each
search mask is separated by a semicolon. A Selection list that allowed the selection of all text
files (*.TXT and *.DOC) or all files would look like this:

Text Files:.TXT;.DOC,All files:*

A single asterisk character is a placeholder for all files.

70
Reference

se l e c t ( Ma c O S ) On Mac OS, the optional second argument is a callback function. This function takes one
argument, which is a File object. When the dialog is set up, it calls this callback function for
each file that is about to be displayed. If the function returns anything else than true, the file
is not displayed. This is true only for the openDialog() method; the saveDialog() method
ignores this callback method.

Returns

File object, or null if the user cancels the dialog.

See also

“filePutDialog() global function” on page 25

File seek() method

File(path).seek(pos, mode)

F i l e ( p a t h ) . w r ite l n ( tex t, . . . )

Description

The File writeln() method writes a given string to the file. The parameters of this function are concatenated
to a single string, and a Line Feed sequence is appended. Returns true on success.
If the file is encoded, multiple bytes may be read to create single Unicode characters.

Parameters

text A string or set of strings. All arguments are concatenated to form the string to be written.

Returns

Boolean.

FileSource object
ap p.project.ite m(index) . m a i n S o u rce
ap p.project.ite m(index) .proxySource

Description

The FileSource describes footage that comes from a file. FileSource is a subclass of FootageSource and so it
inherits all attributes and methods of FootageSource.

72
Reference

Attributes

Attribute Reference Description

fi le see “FileSource file attribute” on page 73 specifies the file that defines this FileSource

Methods

Method Reference Description

re l o a d ( ) see “FileSource reload() method” on reloads the asset from the file
page 73

FileSource file attribute

ap p.pro je c t . fi l e

Description

The FileSource file attribute specifies the file that defines this FileSource. The attribute is readOnly.
Note that there are other ways to change the file. If this FootageSource is a proxySource of an AVItem, you can
call setProxy() or setProxyWithSequence() to change files. If this FootageSource is a mainSource of a
FootageItem, you can call replace() or replaceWithSequence() to change files.

Type

File; read-only.

FileSource reload() method

ap p.projec t . m a i n Sou rc e . re l o a d ( )

Description

The FileSource reload() method reloads the asset from the file. This method can be called only on a
mainSource, not a proxySource.

Parameters

None.

Returns

None.

FileSystem Class
File.
F older.

Description

The FileSystem class contains methods and attributes common to both File and Folder objects. A File object
corresponds to a disk file, while a Folder object matches a folder.

73
Reference

This attribute and methods differ from those found under the FileSystemObject in that they can be applied
without referring to a particular instance of a file or folder.

Class attributes

Class attribute Reference Description

fs see “FileSystem fs class attribute” on name of the files system; read-only

page 75

Class methods

Class method Reference Description

de co d e ( ) see “FileSystem decode() class method” decodes the input string from UTF-8
on page 74

en co d e() see “FileSystem encode() class method” encodes the input string in UTF-8
on page 74

75
Reference

/Macintosh HD/dir/name.ext C:\Macintosh HD\dir\name.ext Macintosh HD:dir:name.ext

Thus if you have to use a script with URI notation on both Mac OS and Windows, try to use relative path
names, or try to originate your path names from the home directory. If that is not possible, it is recommended
that you work with Mac OS X aliases and UNC names on Windows, and store files on a machine that is remote
to the Windows machine on which the script is running.

Attributes

Attribute Reference Description

absol uteURI see “FileSystem absoluteURI attribute” full path name for the object in URI notation
on page 76

alias see “FileSystem alias attribute” on returns true if the object refers to a file system
page 77 alias

cre a te d see “FileSystem created attribute” on creation date of the object

page 77

er ror see “FileSystem error attribute” on contains a message describing the last file sys-
page 77 tem error

ex ist s see “FileSystem exists attribute” on returns true if the path name of this object
page 77 refers to an actually existing file or folder

f sNam e see “FileSystem fsName attribute” on file-system specific name of the object as a full
page 78 path name

mo d i fi e d see “FileSystem modified attribute” on date of the object's last modification

page 78

n ame see “FileSystem name attribute” on name of the object without the path specifica-
page 78 tion

parent see “FileSystem parent attribute” on folder object containing this object
page 79

pat h see “FileSystem path attribute” on path portion of the absolute URI
page 79

re l a t ive U R I see “FileSystem relativeURI attribute” on path name for the object in URI notation, rela-
page 79 tive to the current folder

Methods

Method Reference Description

ge t Re l a t ive U R I ( ) see “FileSystem getRelativeURI() calculate and return the relative URI, given a
method” on page 78 base path, in URI notation

remove() see “FileSystem remove() method” on delete the file or folder that this object repre-
page 79 sents

rename() see “FileSystem rename() method” on rename the object to the new name
page 80

resolve() see “FileSystem resolve() method” on attempt to resolve the file system alias that this
page 80 object points to

FileSystem absoluteURI attribute

F i l e ( p a t h ) . absoluteURI

76
Reference

F o l d e r ( p a t h ) . absoluteURI

Description

The absoluteURI attribute of File or Folder is the full path name for the object in URI notation.

Type

String; read-only.

FileSystem alias attribute

F i l e ( p a t h ) . a l ia s
F o l d e r ( p a t h ) . a l ia s

Description

The alias attribute of File or Folder returns true if the object refers to a file system alias.

Type

Boolean; read-only.

FileSystem created attribute

F i l e ( p a t h ) . c re a te d
F o l d e r ( p a t h ) . c re a te d

Description

The created attribute of File or Folder is the creation date of the object. If the object does not refer to a folder
or file on the disk, the value is null.

Type

Date, or null if the object does not refer to a file or folder on disk; read-only.

FileSystem error attribute

The getRelativeURI() method of File or Folder calculates and returns the relative URI, given a base path, in
URI notation. If the base path is omitted, the path of the current folder is assumed.

Parameters

st r ing base path, in URI notation

Returns

String.

FileSystem modified attribute

F i l e ( p a t h ) . m o d i fi e d
F o l d e r ( p a t h ) . m o d i fi e d

Description

The modified attribute of File or Folder is the date of the object's last modification. If the object does not refer
to a folder or file on disk, the value is null.

Type

Date, or null if no valid FileSystem object is referenced; read-only.

FileSystem name attribute

F i l e ( p a t h ) . n a me
F o l d e r ( p a t h ) . n a me

78
Reference

Description

The name attribute of File or Folder is the name of the object without the path specification.

Type

String; read-only.

Parameters

None.

Returns

Boolean.

FileSystem rename() method

F i l e ( p a t h ) .rename( s t r i n g )
F o l d e r ( p a t h ) .rename( s t r i n g )

Description

The rename() method of File or Folder renames the object to a new name. The new name must not have a
path. This method returns true if the object was renamed. The method does not resolve aliases, but rather
renames the alias file.

Parameters

st r ing the new name for the object

Returns

Boolean.

FileSystem resolve() method

F i l e ( p a t h ) . reso lve()
F o l d e r ( p a t h ) . reso lve()

Description

The resolve() method of File or Folder attempts to resolve the file system alias that this object points to. If
successful, a new File or Folder object is returned that points to the resolved file system element. If the object
is not an alias, or if the alias could not be resolved, the return value is null.

Parameters

None.

Returns

FileSystem object (File or Folder) or null if no alias.

Folder class
F older.

80
Reference

Description

The Folder class contains methods and attributes common to Folder objects. A Folder object corresponds to
a folder.
Also included in this class are all attributes and methods within the FileSystem class, as those apply to Folders
as well as Files.
Note that the difference between the Folder Class and Folder object is that the class attributes and methods
require no specific instance of a Folder, whereas class methods and attributes do.

Attributes

Attribute Reference Description

cu r ren t see “Folder current Class attribute” on current folder is returned as a Folder object
page 82

st ar tup see “Folder startup Class attribute” on folder containing the executable image of the
page 82 running application

sy stem see “Folder system Class attribute” on folder containing the operating system files
page 83

temp see “Folder temp Class attribute” on default folder for temporary files
page 83

t r ash see “Folder trash Class attribute” on folder containing deleted items
page 83

Class attributes from FileSystem object (see “FileSystem object” on page 75)

Class attribute Reference Description

fs see “FileSystem fs class attribute” on name of the files system; read-only

page 75

Methods

Method Reference Description

Folder() see “Folder create() method” on page 85 constructs a new Folder object
new Folder()

se l e c t D i a l o g ( ) see “Folder selectDialog() Class method” opens a dialog box that permits you to select a
on page 82 folder using the OS specific folder select dialog

Class methods from FileSystem object (see “FileSystem object” on page 75)

Class method Reference Description

de co d e ( ) see “FileSystem decode() class method” decodes the input string from UTF-8
on page 74

en co d e() see “FileSystem encode() class method” encodes the input string in UTF-8
on page 74

81
Reference

Folder() Class method

F older( p a t h )
new Folder( p a t h )

Description

This function constructs a new Folder object. If the given path name refers to an already existing disk file, a
File object is returned instead.
The folder that the path name refers to does not need to exist. If the argument is omitted, a temporary name
is generated.

Parameters

pat h path for the folder created, expressed as a string

Returns

Folder (or File if path refers to an existing file).

Folder current Class attribute

F older . cu r ren t

Description

The current attribute of Folder is the current folder. It is returned as a Folder object. Assigning either a Folder
object or a string containing the new path name sets the current folder.

Type

Folder; read/write.

Folder selectDialog() Class method

F older . s e l e c t D i a l o g ( prompt, pres e t )

Description

The Folder SelectDialog() method opens a dialog box that permits you to select a folder using the platform-
specific selection dialog box. Both arguments are optional.

Parameters

p romp t String displays a prompt text if the dialog allows the display
of such a message; optional

pre s e t Folder a folder that is pre-selected when the dialog opens

Returns

Folder object pointing to the selected folder, or null if the user cancels the dialog.

Folder startup Class attribute

F older .star tup

82
Reference

Description

The startup attribute of Folder is the folder containing the executable image of the running application.

Type

Folder; read-only.

Folder system Class attribute

F older .system

Description

The system attribute of Folder is the folder containing the operating system files.

Type

Folder; read-only.

Folder temp Class attribute

F older .temp

Description

The temp attribute of Folder is the default folder for temporary files.

Type

Folder; read-only.

Folder trash Class attribute

F older . t r a sh

Description

The trash attribute of Folder is the folder containing deleted items.

Type

Folder; read-only.

Folder object
F older(“path”).

Description

The Folder object contains methods and attributes common to Folder objects. A Folder object corresponds to
a folder.
Also included in this object are all attributes and methods within the FileSystem object, as those apply to
Folders as well as Files.

83
Reference

Attributes inherited from the FileSystem object (see “FileSystem object” on page 75)

Attribute Reference Description

absol uteURI see “FileSystem absoluteURI attribute” full path name for the object in URI notation
on page 76

alias see “FileSystem alias attribute” on returns true if the object refers to a file system
page 77 alias

cr e a te d see “FileSystem created attribute” on creation date of the object

page 77

e r ror see “FileSystem error attribute” on contains a message describing the last file sys-
page 77 tem error

ex ist s see “FileSystem exists attribute” on returns true if the path name of this object
page 77 refers to an actually existing file or folder

f sNam e see “FileSystem fsName attribute” on file-system specific name of the object as a full
page 78 path name

mo d i fi e d see “FileSystem modified attribute” on date of the object's last modification

page 78

n ame see “FileSystem name attribute” on name of the object without the path specifica-
page 78 tion

parent see “FileSystem parent attribute” on folder object containing this object
page 79

pat h see “FileSystem path attribute” on path portion of the absolute URI
page 79

re l a t ive U R I see “FileSystem relativeURI attribute” on path name for the object in URI notation, rela-
page 79 tive to the current folder

Methods

Method Reference Description

create () see “Folder create() method” on page 85 attempts to create a folder at the location the
path name points to

ge t F i l e s ( ) see “Folder getFiles() method” on gets a list of File and Folder objects contained
page 85 in the folder object

Methods inherited from FileSystem object (see “FileSystem object” on page 75)

Method Reference Description

ge t Re l a t ive U R I ( ) see “FileSystem getRelativeURI() calculates and returns the relative URI, given a
method” on page 78 base path, in URI notation

remove() see “FileSystem remove() method” on deletes the file or folder that this object repre-
page 79 sents

rename() see “FileSystem rename() method” on renames the object to the new name
page 80

resolve() see “FileSystem resolve() method” on attempts to resolve the file system alias that
page 80 this object points to

84
Reference

Folder create() method

F o l d e r ( p a t h ) . crea te()

Description

The create() method attempts to create a folder at the location the path name points to.

Parameters

None.

Returns

Boolean; true if the folder was created.

Folder getFiles() method

F older . g e t F i l e s ( m a s k )

Description

The Folder getFiles() method returns a list of File and Folder objects contained in the folder object. The mask
parameter is the search mask for the file names, expressed as a string. It may contain question marks and
asterisks and is preset to * to find all files.
Alternatively, a function may be supplied. This function is called with a File or Folder object for every file or
folder in the directory search. If the function returns true, the object is added to the array.
On Windows, all aliases end with the extension ".lnk". This extension is stripped from the file name when
found to preserve compatibility with other operating systems. You can, however, search for all aliases by
supplying the search mask "*.lnk". This is not recommended, however, because it is not portable.

Parameters

mask String search mask for the files names (see above)

Returns

Array of File & Folder objects or null if the folder does not exist.

FolderItem object
ap p.proj e c t . FolderItem

Description

The FolderItem object corresponds to any folder in your Project window. It can contain various types of items
(footage, compositions, solids) as well as other folders.

Attributes

Attribute Reference Description

it ems see “FolderItem items attribute” on ItemCollection that represents the contents of
page 86 this FolderItem

85
Reference

Attribute Reference Description

n umItems see “FolderItem numItems attribute” on number of items contained in the FolderItem
page 87

Methods

Method Reference Description

it em() see “FolderItem item() method” on returns an Item

page 86

Example

Given that the second item in the project is a FolderItem, the following code puts up one alert for each top-
level item in the folder. The alerts display the name of each top-level item.
v ar secon d Item = a p p. p ro j ect. item(2);
if ( !(secondItem instanceof FolderItem) ) {
aler t( "problem: second item is not a folder");
} else {
for (i = 1; i <= secondItem.numItems; i++ ) {
aler t( "item number " + i + " w ithin the folder is named "
+ secon d Item. item(i ). n a me);
}
}

FolderItem item() method

ap p.proj ec t.folderIte m. item( i n d e x )

Description

The FolderItem item() method returns the top-level item in this FolderItem with the given index. Note that
“top-level” here means top-level within the folder, not necessarily within the project.

Parameters

in dex Integer index number of the FolderItem

Returns

Item.

FolderItem items attribute

ap p.proj ec t.folderIte m. items

Description

The items attribute is the ItemCollection that represents the contents of this FolderItem.
Unlike the ItemCollection that is owned by the Project object, a FolderItem’s ItemCollection contains only the
top-level Items in the FolderItem.
Note that “top-level” indicates top-level within the folder, not necessarily within the project. Only in the case
of the rootFolder are the top-level items in the FolderItem also top-level items in the Project.

86
Reference

Type

ItemCollection; read only.

FolderItem numItems attribute

ap p.proj ec t.folderIte m. nu mItems

Description

The numItems attribute is the number of items contained in the FolderItem.

This number is the number of top-level Items within the folder. In other words, if this FolderItem contains
another FolderItem, then the contained FolderItem counts as one item, even if there are further sub-items
inside the contained folder.

Type

Integer; read only.

FootageItem object
ap p.proj e c t . item( i n d e x )
ap p.proj ec t .items[ i n d e x ]

Description

The FootageItem object represents a footage item imported into the project, which appears in the Project
window.

Attributes

Attribute Reference Description

fi le see “FootageItem file attribute” on footage source file

page 88

main S o u rce see “FootageItem mainSource attribute” contains all settings related to the footage
on page 88 item

Methods

Method Reference Description

re p l a ce ( ) see “FootageItem replace() method” on replaces a footage file with another footage
page 88 file

replaceWithPlaceholder() see “FootageItem replaceWithPlace- replaces a footage file with a placeholder

holder() method” on page 88 object

replaceWithSequence() see “FootageItem replaceWithSe- replaces a footage file with an image sequence
quence() method” on page 89

re p l a ceWi t h S o l i d ( ) see “FootageItem replaceWithSolid() replaces a footage file with a solid

method” on page 89

87
Reference

n ame string name of the placeholder

w idt h integer width of the placeholder [4..30,000]

he ig ht integer height of the placeholder [4..30,000]

fr a m e R a te Floating-point value frame rate of the Placeholder [1..99]

d ur a tio n Floating-point value duration of the Placeholder [0..10,800]

FootageItem replaceWithSequence() method

ap p.project.ite m(index) .replaceWithSequence( file, forc eAlphabe t ical )

Description

Parameters

fi le File object replacement file

forceAlphabetical boolean value of true is equivalent to activating the Force

Alphabetical Order option in the File > Replace >
Footage > File dialog box.

FootageItem replaceWithSolid() method

ap p.project.ite m(index) . re p l a ceWi t h S o l i d ( c o l o r, n a m e , w i d t h , h e i g h t , p i x e l As p e c t )

89
Reference

Description

Parameters

c olor Floating-point array color of the solid (an array of four floating-point values from 0 to
1: [R, G, B, A])

n ame string name of the solid

w idt h integer width of the solid [4..30,000]

he ig ht integer height of the solid [4..30,000]

pix e l As p e c t Floating-point value pixel aspect ratio of the Solid [0.01..100]

FootageSource object
ap p.project.ite m(index). m a i n S o u rce.
ap p.project.ite m(index) .proxySource.

Description

The FootageSource object holds information describing the source of some footage. It is used to hold the
mainSource of a FootageItem, or the proxySource of an AVItem. AVItem is the base class of FootageItem and
CompItem; thus proxySource appears in both these types of Item.

Attributes

Attribute Reference Description

hasAlpha see “FootageSource hasAlpha attribute” specifies if a footage clip or proxy includes an
on page 93 alpha channel

alphaMode see “FootageSource alphaMode specifies the mode of an alpha channel

attribute” on page 91

premulColor see “FootageSource premulColor specifies the color to be premultiplied

attribute” on page 95

inver tAl pha see “FootageSource invertAlpha specifies if an alpha channel in a footage clip or
attribute” on page 94 proxy should be inverted

isStill see “FootageSource isStill attribute” on specifies if footage is a still image

page 94

fi e l d S e p a r a t i o n Ty p e see “FootageSource fieldSepara- specifies the field separation type

tionType attribute” on page 92

90
Reference

Attribute Reference Description

hig h Q u a l i t y F i e l d S e p a r a t i o n see “FootageSource highQualityField- specifies how the fields are to be separated in
Separation attribute” on page 93 a non-still footage.

r emovePulldow n see “FootageSource removePulldown specifies the Pulldown Type for the footage
attribute” on page 95

lo op see “FootageSource loop attribute” on specifies how many times an image sequence
page 94 is set to loop

n at ive Fr a m e R a te see “FootageSource nativeFrameRate the native frame rate of the footage
attribute” on page 94

display Fr a m e R a te see “FootageSource displayFrameRate the effective frame rate as displayed and ren-
attribute” on page 92 dered in compositions by After Effects

confor mFr ameRate see “FootageSource conformFrameRate specifies the rate to which footage should con-
attribute” on page 91 form

Methods

Method Reference Description

g u essAlphaMode() see “FootageSource guessAlphaMode() guesses the alphaMode setting

method” on page 92

g u essPu l l d ow n () see “FootageSource guessPulldown() guesses the pulldownType setting

method” on page 93

FootageSource alphaMode attribute

ap p.project.ite m(index).mainSource. alphaMode
ap p.project.ite m(index).proxySource. alphaMode

Description

The alphaMode attribute of footageSource defines how the alpha information in the footage is to be inter-
preted. If hasAlpha is false, this attribute has no relevant meaning.

Type

AlphaMode; one of the following (read/write):

A lphaMode.IGNORE
AlphaMode.STRAIGHT
AlphaMode.PREMULTIPLIED

FootageSource conformFrameRate attribute

ap p.project.ite m(index).mainSource. confor mFr ameRate
app.project.ite m(index).proxySource. confor mFr ameRate

FootageSource guessAlphaMode() method

ap p.projec t . i te m (i n d ex ). m a i n Sou rc e .guessAlphaMode()
ap p.project.ite m(index).proxySource .guessAlphaMode()

Description

The guessAlphaMode() method sets alphaMode, premulColor, and invertAlpha to the best guesses for this
footage source. If hasAlpha is false, no change will occur.

Parameters

None.

92
Reference

Returns

None.

FootageSource guessPulldown() method

ap p.projec t . i te m (i n d ex ). m a i n Sou rc e . g u e s s Pu lld ow n ( m e t h o d )
ap p.project.ite m(index).proxySource . g ue s s Pu lld ow n ( m e t h o d )

Description

The guessPulldown() method sets the fieldSeparationType and removePulldown to the best guesses for this
footage source. If isStill is true, no change will occur.

Parameters

P ulldow n- used as an input argument to the guessPulldown()method of a FootageSource; use one of Enumerated
Me t h o d Types below

Enumerated Types

PU LLD OW N _ 3_ 2 uses 3:2 pulldown method

ADVAN C E _ 24P uses Advance 24p method

Returns

None.

FootageSource hasAlpha attribute

ap p.project.ite m(index).mainSource. hasAlpha
ap p.project.ite m(index).proxySource. hasAlpha

Description

The hasAlpha attribute of FootageSource is true if the footage has an alpha component.
If true, then the attributes alphaMode, invertAlpha, and premulColor will have relevance. If false, then those
three fields have no relevant meaning for the footage.

Type

Boolean; true if alpha exists. Read-only.

FootageSource highQualityFieldSeparation attribute

ap p.project.ite m(index).mainSource. h i g h Q u a l i t y F i e l d S e p a r a t i o n
ap p.project.ite m(index).proxySource. h i g h Q u a l i t y F i e l d S e p a r a t i o n

FootageSource premulColor attribute

ap p.project.ite m(index).mainSource. premulColor
ap p.project.ite m(index).proxySource. premulColor

Description

The premulColor attribute of footageSource determines the color to be premultiplied. This attribute is valid
only if the alphaType is set to PREMULTIPLIED.

Type

Color (an array of four floating-point values from 0 to 1: [R, G, B, A]); read/write.

FootageSource removePulldown attribute

ap p.project.ite m(index).mainSource. removePu l ldow n
app.project.ite m(index).proxySource. rem ovePu l ldow n

Description

The removePulldown attribute of Footage File Info specifies how the pulldowns are to be removed when field
separation is used.
It is an error to attempt to write to this attribute if isStill is true. It is an error to attempt to set this to a value
other than PulldownPhase.OFF in the case where fieldSeparationType is FieldSeparationType.OFF. The field-
SeparationType must be changed first.

Enumerated Type

PulldownPhase (read/write); one of:

R emovePulldow n.OFF
RemovePu lldow n.WSSWW
RemovePu lldow n.SSWWW
RemovePu lldow n.SWWWS
RemovePu lldow n.WWWSS
RemovePu lldow n.WWSSW
RemovePu lldow n.WSSWW_24P_ADVANCE
RemovePu lldow n.SSWWW_24P_ADVANCE
RemovePu lldow n.SWWWS_24P_ADVANCE
RemovePu lldow n.WWWSS_24P_ADVANCE
RemovePu lldow n.WWSSW_24P_ADVANCE

ImportOptions object
n e w Imp o r t O p t i o n s ( ) ;
n e w Imp o r t O p t i o n s ( Fi l e );

95
Reference

Description

The ImportOptions object provides the ability to create, change, and access options for the importFile()
method. You can create ImportOptions using one of two constructors, one of which takes arguments, the
other which does not.

Constructors

If importFile() is set without arguments, it has a “file” that does not exist unless it is set in another statement:
n e w Im p o r tO p t i o n s ( ) . fi l e = n e w F i l e ( " my fil e . p s d " ) ;

Otherwise importFile can be set with a single argument, which is a File object:
v a r my _ i o = n e w Imp o r tO p t i o n s ( n e w F i l e ( " my fil e . p s d " ) ) ;

Attributes

Attributes Reference Description

imp or tAs see “ImportOptions importAs attribute” contains the ImportAsType

on page 97

se quence see “ImportOptions sequence attribute” boolean to determine whether a sequence or

on page 97 an individual file is imported

forceAlphabetical see “ImportOptions forceAlphabetical boolean to determine whether the Force

attribute” on page 97 Alphabetical Order option is set

fi le see “ImportOptions file attribute” on the file to import

page 97

Methods

Method Reference Description

can Impor tAs() see “ImportOptions canImportAs() sets the ImportAsType, allowing the input to
method” on page 96 be restricted to a particular type

ImportOptions canImportAs() method

imp o r t O p t i o n s .canImpor tAs( Im p o r t As Ty p e )

Description

The canImportAs() method is used to determine whether a given file can be imported as a given Impor-
tAsType, passed in as an argument.

Parameters

ImportAsType; one of:

I mpor tAsTy p e.COMP
Im p o r t As Ty p e . F O OTAG E
Im p o r tAs Ty p e . C O M P _ C RO P PE D _ L AY E R S
Im p o r t As Ty p e . P RO J E C T

Returns

Boolean.

96
Reference

Example
v a r i o = n e w Imp o r tO p t i o n s ( F i l e ( “c : \ \ f o o. p s d ” ) ) ;
i o. c a n Im p o r t As ( Im p o r t As Ty p e . C O M P )

ImportOptions file attribute

imp o r t O p t i o n s . fi l e

Description

The file attribute specifies the file to be imported. This is used to get or change the file that is set in the
constructor.

Type

File; read/write.

ImportOptions forceAlphabetical attribute

imp o r t O p t i o n s .forceAlphabetical

Description

The forceAlphabetical attribute is a boolean. A value of true is equivalent to activating the Force Alphabetical
Order option in the File > Import > File dialog box.

Type

Boolean; read/write.

ImportOptions importAs attribute

imp o r t O p t i o n s .impor tAs

Description

The importAs attribute holds the importAsType for the file to be imported. You can set it by setting a file of
the type you want to import as an argument.

Enumerated Type

ImportAsType; read/write. One of:

I mpor tAsTy p e.COMP_CROPPED_LAYERS
Im p o r t As Ty p e . F O OTAG E
Im p o r t As Ty p e . C O M P
Im p o r t As Ty p e . P RO J E C T

ImportOptions sequence attribute

imp o r t O p t i o n s .sequence

Description

The sequence attribute is a boolean; it determines whether a sequence or an individual file is imported.

97
Reference

Type

Boolean; read/write.

Item object
ap p.project.item(index)
app.project.items[index]

Description

The Item object represents an item that can appear in the Project window. FootageItem, CompItem, and
FolderItem are all types of Item.
Note that numbering of the index for item starts at 1, not 0.

Attributes

Attributes Reference Description

n ame see “Item name attribute” on page 99 name of the object as shown in the Project
window

c omment see “Item comment attribute” on string that holds a comment

page 99

id see “Item id attribute” on page 99 unique integer ID for this item

parentFolder see “Item parentFolder attribute” on parent folder of this item

page 99

se l e c te d see “Item selected attribute” on true if this item is currently selected

page 100

t y p eNa me see “Item typeName attribute” on string corresponding to the type of item
page 100

Methods

Method Reference Description

remove() see “Item remove() method” on deletes the item from the project
page 100

Example

The following example will get the second item from the project and check that the typeName of that item is
"Folder". Then it will remove from that folder any top-level item that is a Solid, but only if it is not currently
selected. The example will also check to make sure that, for each item in the folder, the parentFolder is properly
set to be the correct folder.
v ar my Folder = app. project.item(2);
if (myFolder.t y p eName != "Folder" ) {
aler t("er ror : second item is not a folder");
}
else {
var numInFolder = my Folder.numItems;
// Always r un loops backwards when deleting thing s:
for(i = numInFolder ; i >= 1; i--) {

98
Reference

v ar curItem = myFolder.item(i);
if ( curItem.parentFolder != my Folder) {
aler t("er ror w ithin AE: the parentFolder is not set cor rectly");
}
else {
i f ( ! c u r Item . s e l e c te d & & c u r Item . t y p e Na m e = = " Fo o t a g e " ) {
/ / A h a ! a n u n s e l e c te d s o l i d .
curItem.remove();
}
}
}
}

Item comment attribute

ap p.project.ite m(index). comment

Description

The item comment attribute is a string that holds a comment, up to 15,999 bytes in length after any encoding
conversion. The comment is for the user's purpose only; it has no effect on the Item's appearance or behavior.

Type

String; read/write.

Item id attribute
ap p.project.ite m(index). i d

Description

The item ID attribute is a unique and persistent identification number used to identify an item between
sessions. The value of the ID will not change even after the project is saved to file and read in at a later time.
An ID is thus effectively permanent except when importing a project into another project, in which case new
IDs are assigned to the newly imported items.

Type

ap p.project.ite m(index). s e l e c te d

Description

The selected attribute defines whether an item is selected or not. Multiple Items can be selected simultaneously
at any given time.
The selected attribute is true if this Item is currently selected. Setting this attribute to true will select the item.

Type

Boolean; read/write.

Item typeName attribute

ap p.project.ite m(index). t y p eNa me

Description

The typeName attribute is a string representing a user-readable name of the type. Examples are Folder,
Footage and Composition.

Type

String; read-only.

ItemCollection
ap p.proj ec t .items

100
Reference

101

Description

The ItemCollection object represents a collection of Items. The ItemCollection belonging to a Project object
represents all the Items in the project. The ItemCollection belonging to a FolderItem object represents all the
Items in that folder.

Attributes

le n gth the number of objects in the collection (applies to all collections)

Methods

[] retrieves an object or objects in the collection via its index number

a ddComp() creates a new CompItem and adds it to the ItemCollection

ItemCollection addComp() method

ap p.project.Ite mCollect ion. addComp( n a m e , w i d t h , h e i g h t , p i x e l As p e c t , d u ra t i o n , f ra m e R a t e )

Description

The itemCollection addcomp() method creates a new CompItem and adds it to the ItemCollection.
If the ItemCollection belongs to the project or the root folder, then the new comp's parentFolder will be the
root folder. Otherwise, the new comp's parentFolder will be the FolderItem that owns the ItemCollection.

Parameters

n ame string name of the new CompItem

w idt h integer width of the new CompItem [4.. 30,000]

heig ht integer height of the new CompItem [4.. 30,000]

pixe l As p e c t floating-point value pixel aspect ratio of the Solid [0.01..100]

dur a tio n floating-point value duration of the new CompItem [0 .. 10800 ]

fr a m e R a te floating-point value frame rate of the new CompItem [1 .. 99]

Returns

CompItem.

KeyframeEase object
The KeyframeEase object specifies the KeyframeEase setting of a keyframe, which is determined by its speed
and influence settings.

Attributes

Attribute Reference Description

sp e e d see “KeyframeEase speed attribute” on corresponds to the speed setting for a key-
page 102 frame

101
Reference

102

Attribute Reference Description

in fl uence see “KeyframeEase influence attribute” corresponds to the influence setting for a key-
on page 102 frame in range [0.1..100.0]

Method

Method Reference Description

ke y fr ameE a se() see “KeyframeEase keyframeEase() returns a KeyframeEase

method” on page 102

KeyframeEase keyframeEase() method

m yKe y . ke y fr a meE a se( s p e e d , i n fl u e n c e )

Description

This constructor creates a KeyframeEase value. Both paramters are required. Note that for non-spatial 2D and
3D properties you must set an easeIn and and easeOut for each dimension (see example below). Note also that
there are two types of ease: temporal and spatial.

Parameters

sp e e d Floating-point value; the keyframe speed

in fl uence Floating-point value in range [0.1..100.0]; the keyframe influence

Returns

None.

Example
v ar easeIn = n ew Ke y fr a meE a se(0. 5, 50 ) ;
var easeOut = new Ke y freameEase(0.75, 85);
myPo si ti o n Prop er t y. setTemp o r a l E a seAt Ke y( 2 , [ e a s e In ] , [ e a s e O u t ] ) ;

KeyframeEase influence attribute

m y Ke y, Ke y f ra m e E a s e . influence

Description

This attribute specifies the influence value of the keyframe. The valid range is 0.1 to 100.0.

Type

Floating-point value; read/write.

KeyframeEase speed attribute

m y Ke y, Ke y f ra m e E a s e . s p e e d

Description

This attribute specifies the speed value of the keyframe.

102
Reference

103

Type

Floating-point value; read/write.

Layer object
ap p.project.ite m(index). l ayer ( i n d e x )

Description

The Layer object provides access to a layer within Compositions. It can be accessed either by index number or
by a name string.
Those layers that are AV layers (Comp layers, footage layers, etc.) will be represented as AVLayer objects.
AVLayer is a subclass of Layer and contains additional methods and attributes. (See “AVLayer object” on
page 46 for more information.)
The Layer object is derived from PropertyGroup. All attributes of the PropertyBase and PropertyGroup
objects are available on Layers, as well.

Attributes

Attribute Reference Description

in d ex see “Layer index attribute” on page 106 index of the layer, in the range [1,numLayers]

n ame see “Layer name attribute” on page 108 name of the layer

par ent see “Layer parent attribute” on page 108 parent of this layer

t ime see “Layer time attribute” on page 110 current time of the layer

st ar t Ti me see “Layer startTime attribute” on startTime of the layer, expressed in comp time
page 110

st re tch see “Layer stretch attribute” on time stretch, expressed as a percentage

page 110

in Point see “Layer inPoint attribute” on inPoint of the layer, expressed in comp time
page 106

o utPoint see “Layer outPoint attribute” on outPoint of the layer, expressed in comp time
page 108

en abled see “Layer enabled attribute” on true if the layer is enabled

page 105

solo see “Layer solo attribute” on page 110 true if the layer is soloed

shy see “Layer shy attribute” on page 109 true if the layer is shy

lo cke d see “Layer locked attribute” on page 106 true if the layer is locked

hasVi d e o see “Layer hasVideo attribute” on true if the layer contains a video component
page 106

a c t ive see “Layer active attribute” on page 104 true if the layer is active at the current time

nu l l L ayer see “Layer nullLayer attribute” on true if this is a null layer

page 108

se l e c te d Pro p e r t i e s see “Layer selectedProperties attribute” array containing all selected Property and
on page 109 PropertyGroup objects in Layer

103
Reference

104

Methods

Method Reference Description

r emove() see “Layer remove() method” on deletes the layer from the composition
page 109

mo veTo B e g i n n i n g ( ) see “Layer moveToBeginning() method” moves the layer to the top of the composition
on page 107 (the first layer)

moveTo E n d () see “Layer moveToEnd() method” on moves the layer to the bottom of the composi-
page 107 tion (the last layer)

moveAfter() see “Layer moveAfter() method” on moves the layer below another, specified layer
page 106

moveB efore() see “Layer moveBefore() method” on moves the layer above another, specified layer
page 107

duplic a te() see “Layer duplicate() method” on duplicates the layer

page 105

copyToComp() see “Layer copyToComp() method” on copies the layer to the top and beginning of
page 105 another composition

a c t ive At Ti m e ( ) see “Layer activeAtTime() method” on given a time, returns whether this layer will be
page 104 active at that time

se tParentWithJump() see “Layer setParentWithJump() establishes newParent as the parent of this

method” on page 109 layer

Example

If the first item in the project is a CompItem, the following example would disable the first layer in that
composition (i.e., turn the eyeball icon off) and rename it to "Lord High Imperial Layer."
v ar firstLayer = app. project.item(1).layer(1);
firstLayer. enabled = false;
firstLayer.name = "Lord Hig h Imper ial Layer";

Layer active attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . a c t ive

Description

The Layer active attribute is true if the layer's video is active at the current time.
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 in between the inPoint and outPoint of this layer.
Note that an audio layer will not have active as true; there is a separate audioActive attribute in the AVLayer
object.

Type

Boolean; read-only.

Layer activeAtTime() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . a c t ive At Ti m e ( t im e )

104
Reference

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . h a s Vi d e o

Description

The Layer hasVideo attribute is true if the layer is enabled, false otherwise. This corresponds to the toggle
control in the Layer window.

Type

Boolean; read-only.

Layer index attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .index

Description

The Layer index attribute is the index of the layer, in the range [1,numLayers].

Type

Integer; read-only.

Parameters

None.

Returns

None.

107
Reference

108

Layer name attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . n a m e

Description

The Layer name attribute is the name of the layer. This can be unique from the Source name (which cannot
be changed in the Layer window), although by default they are identical until edited.

Type

String; read/write.

Layer nullLayer attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . nu l l L ayer

Description

The Layer nullLayer attribute is true if the layer was created as a null object, false otherwise.

Type

Boolean; read/write.

Layer outPoint attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .outPoint

Description

The Layer outPoint attribute is the out-point of the layer, expressed in comp time (seconds). Values may be in
the range [-10800, 10800].

Type

Floating-point value; read/write.

Layer parent attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .parent

Description

The Layer parent attribute is the parent of this layer. The value may be null and may be set to null.
Note that, as in the regular application, if you set the parent, there will be no apparent jump in the layer's
transform. This is because offset values will be calculated to counterbalance any transforms above it in the
hierarchy. For example, if the new parent has a rotation of 30 degrees, then the child layer would be given a
rotation of -30 degrees.
If you want to set the parent while keeping the child layer's transform values from changing, use the “Layer
setParentWithJump() method” on page 109.

Type

Layer; read/write.

108
Reference

109

Layer remove() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .remove()

Description

This method deletes the specified layer from the composition.

Parameters

None.

Layer selectedProperties attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . s e l e c te d Pro p e r t i e s

Description

This attribute yields an array containing all of the selected Property and PropertyGroup objects in the layer.

Type

Array of PropertyBase; read-only.

Layer setParentWithJump() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .setParentWithJump(newParent)

Description

The Layer setParentWithJump() method establishes newParent as the parent of this layer.
This method does not change the transform values of the child layer, and as a result, there may be an apparent
jump in the rotation, translation, or scale of the child layer.
If you do not want the child layer to jump, set the parent attribute directly (as in "childLayer.parent =
newParent;"). When you set the parent attribute directly, an offset will be calculated and set in the child layer's
transform fields, which will prevent the jump from occurring.

Parameters

n e wParent replacement parent layer

Returns

None.

Layer shy attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . shy

Description

The Layer shy attribute is true if the layer is shy, and therefore will be hidden in the Layer window if the compo-
sition’s hide all shy layers is toggled on.

Type

Boolean; read/write.

109
Reference

110

Layer solo attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . solo

Description

The Layer solo attribute is true if a layer is soloed, false otherwise.

Type

Boolean; read/write.

Returns
None.

110
Reference

111

LayerCollection
ap p.project.ite m(index). l co l l

Description

The Layer Collection represents a collection of layers. Each CompItem object contains one LayerCollection.
The LayerCollection attributes and methods provide access to and the ability to add new layers.

Attributes

length the number of objects in the collection (applies to all collections)

Methods

Method Reference Description

[] (no cross-reference) retrieves an object or objects in the collection

via its index number

a dd( ) see “LayerCollection add() method” on creates a new AVLayer containing the given
page 111 AVItem and adds it to the CompItem

a d d Nu l l ( ) see “LayerCollection addNull() method” layer returned is a newly created layer in the
on page 113 Comp that owns the LayerCollection

addSolid() see “LayerCollection addSolid() creates a new FootageItem that has a Solid-
method” on page 113 Source according to the specified parameters,
and adds it to the project

a ddText() see “LayerCollection addText() method” creates a new Text layer with the specified
on page 114 source text

a ddCamer a() see “LayerCollection addCamera() creates a new Camera layer with the specified
method” on page 112 name and center point

a ddLi g ht() see “LayerCollection addLight() creates a new Light layer with the specified
method” on page 112 name and center point

byName() see “LayerCollection byName() method” returns the first layer found with the given
on page 114 name

pre com p o s e ( ) see “LayerCollection precompose() collects the layers referred to by the indices
method” on page 114 given in layerIndices, and puts them into a new
CompItem with the given name

Example

Given that the first item in the project is a CompItem and the second item in the project is an AVItem, the
following code shows how to display the number of layers in the CompItem's layer collection, add a new layer
based on an AVItem in the project, and then display the new number of layers in the layer collection.
v ar firstComp = app. project.item(1);
v a r l ayer Co l l e c t i o n = fi r s t Co m p. l ayer s ;
aler t( "number of layers before is " + layerCollection.length);
var anAVItem = app. project.item(2);
l ayer Co l l e c t i o n . a d d ( a n AV Item ) ;
aler t( "number of layers after is " + layerCollection.length);

LayerCollection add() method

ap p.projec t . i te m (i n d ex ). l c ol l . a d d ( ite m , dura t ion )

111
Reference

112

Description

The LayerCollection add() method creates a new AVLayer containing the given AVItem, and adds the new
AVLayer to the containing CompItem.
This method generates an exception if the item cannot be added as a layer to this CompItem.
The duration parameter, if provided, will affect the method only if the given AVItem contains a piece of still
footage; it has no effect on movies, sequences or audio. If duration is provided, then the duration of the newly
created layer will be the passed value. If duration is not provided, then the duration will be determined by the
user preferences.
Note that by default, user preferences proscribe that the duration be set equal to that of the CompItem into
which the layer is being added. The preference can be changed to a specific duration. Choose Edit > Prefer-
ences > Import (Windows) or After Effects > Preferences > Import, and specify options under Still Footage.

Parameters

it em AVItem to be added

d ur a tio n optional floating-point value specifying the length of a still layer

Returns

AVLayer.

LayerCollection addCamera() method

ap p.projec t . i te m (i n d ex ). l c ol l .addCamer a ( n a m e , c e n t e r Po i n t )

Description

This method creates a new camera layer within the LayerCollection.

Parameters

n ame string; name of the new layer

c enterPoint floating-point array; center of the new camera

The layerCollection addSolid() method creates a new FootageItem whose mainSource is a SolidSource
according to the specified parameters, and adds it to the project. This method also creates a new AVLayer that
has that new FootageItem as its source, and adds that layer to the containing CompItem.
Note that by default, user preferences proscribe that the duration be set equal to that of the CompItem into
which the layer is being added. The preference can be changed to a specific durationin the Preferences dialog
box. Choose Edit > Preferences > Import (Windows) or After Effects > Preferences > Import, and specify
options under Still Footage.

113
Reference

114

Parameters

color Establishes the color of the new FootageItem (a solid) contained in the layer. The
color argument must be an array of 3 floats lying in the range [0..1].

n ame Establishes the name of the new layer and the new FootageItem.

w idt h Specifies the width, in pixels, of the new layer and the new FootageItem. Permit-
ted values are in the range [1 .. 30,000].

heig ht Specifies the height, in pixels, of the new layer and the new FootageItem. Permit-
ted values are in the range [1 .. 30,000].

pixe l As p e c t Specifies the pixel aspect ratio for the new FootageItem.

dur a tio n Optional floating-point value specifying the length of a still layer.

Returns

AVLayer.

LayerCollection addText() method

ap p.projec t . i te m (i n d ex ). l c ol l . a d d Tex t ( s ou rc e Te x t )

Description

This method creates a new text layer within the LayerCollection.

Parameters

sou rceText string; optional, serves as the source text of the new layer

Returns

Text layer.

LayerCollection byName() method

ap p.projec t . i te m (i n d ex ). l c ol l . by Na me( n a m e )

Description

The LayerCollection byName() method returns the first layer found with the given name. This method returns
null if no layer with the given name is found.

Parameters

n ame string - the name of the layer being sought

Returns

Layer; null if name is not found.

LayerCollection precompose() method

ap p.projec t . i te m (i n d ex ). l c ol l . p re comp os e ( layerIndic ies, name, moveAl lAtt r i butes )

114
Reference

115

Description

The LayerCollection precompose() method collects the layers referred to by the given indices (first parameter)
and puts them into a new CompItem that has the given name (second parameter). The given layers are
removed from the LayerCollection. The new CompItem is added into the LayerCollection and is also returned
by the precompose() method.

Parameters

la yer In d i ces indices of layers to be collected

n ame establishes the name of the new compItem

mo veAl lAtt r ibutes Optional boolean, defaults to true; may be set to false only if there is only 1 index
in the layerIndices array. Setting this to true corresponds to selecting the Move
All Attributes into the New Composition option in the Pre-Compose dialog box.
Setting it to false corresponds to selecting the Leave All Attributes In option in
the Pre-Compose dialog box.

Returns

CompItem.

MarkerValue object
ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .Mar kerValue

Description

The MarkerValue object holds the representation of a layer marker. It contains four string attributes:
comment, chapter, url, and frameTarget.
For more on the usage of markers see “Using markers” in After Effects Help.

Methods

Method Reference Description

Mar kerValue() see “MarkerValue method” on page 116 Returns a MarkerValue. Sets the comment and,
optionally, the chapter, url and frameTarget
attributes.

Attributes

Attribute Reference Description

comment see “MarkerValue Comment attribute” string comment included with the marker
on page 117

ch a p ter see “MarkerValue Chapter attribute” on string Chapter Link reference point included
page 116 with the marker

url see “MarkerValue URL attribute” on string Uniform Resource Locator included with
page 117 the marker

fr a m e Ta r g e t see “MarkerValue FrameTarget string target (specifying a Web site frame)

attribute” on page 117 included with the marker

115
Reference

116

Examples

To set a marker that says “Fade Up” at the 2 second mark:

v ar my Mar ker = new Mar ker("Fade Up");
myLayer. proper t y("Mar ker").setValueAtTime(2, myMa r ker);

To get a comment value from a particular marker:

v ar commentOfFirstMar ker = app. project.item(1).layer(1).proper t y("Mar ker").ke y Va lue(0).comment;

var commentOfMar kerAtTime4 = app. project.item(1).layer(1).proper t y("Mar ker").value-

AtTime(4.0,TRUE) .comment

var ma r kerProp er t y = a p p. p ro j ect. item ( 1 ) . layer ( 1 ) . p rop e r t y( " Ma r ker " ) ;

var mar kerValueAtTimeClosestToTime4 = mar kerProper t y
.ke yValue(mar kerProper t y.nearestKe y In dex(4.0));
var commentOfMar kerClosestToTime4 = mar kerValueAtTimeClosestToTime4.comment;

MarkerValue method
ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .Mar kerValue( c o m m e n t )
ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .Mar kerValue( c o m m e n t , c h a p t e r )
ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .Mar kerValue( c o m m e n t , c h a p t e r, u r l )
ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .Mar kerValue( c o m m e n t , c h a p t e r, u r l , f ra m e Ta r g e t )

Description

The markerValue method sets between one and four specific attributes of the marker and returns a Marker-
Value.

Parameters

c omment string see “MarkerValue Comment attribute” on page 117

ch a p ter string see “MarkerValue Chapter attribute” on page 116

url string see “MarkerValue URL attribute” on page 117

fr a m e Ta r g e t string see “MarkerValue FrameTarget attribute” on

page 117

Returns

MarkerValue (a marker keyframe containing the above four string values).

MarkerValue Chapter attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . Ma r ke r Va l u e . ch a p ter

Description

attribute” on page 118

color see “MaskPropertyGroup color color used to draw the mask outline in the user
attribute” on page 118 interface

MaskPropertyGroup color attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . m a s k ( i n d e x ) .color

Description

This attribute is the color used to draw the mask outline as it appears in the user interface (Composition
window, Layer window, and Timeline window).

Type

Array of three floating-point values from 0 to 1: [R, G, B); read/write.

Enumerated Types

M ask Mo d e. N ON E None

M ask Mo d e. A D D Add

M askMode.SUBTRAC T Subtract

M ask Mo d e. I N TE R S E C T Intersect

M ask Mo d e. L I GH TE N Lighten

M ask Mo d e. DA R K E N Darken

Mask Mo d e. D I FFE R E N C E Difference

MaskPropertyGroup maskMotionBlur attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . m a s k ( i n d e x ) .maskMotionBlur

Description

This attribute is an enumerated type specifying how motion blur is applied to this mask.

Enumerated Type

MaskMotionBlur.SAME_AS_LAYER Same as Layer

MaskMotionBlur.ON On

MaskMotionBlur.OFF Off

MaskPropertyGroup rotoBezier attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . m a s k ( i n d e x ) . rotoB e z i e r

Description

This attribute is a boolean specifying whether the mask is in RotoBezier mode.

Type

Boolean; read/write.

OutputModule object
ap p.p ro j e c t . re n d e r Q u e u e . i t e m ( i n d e x ) . outputMo dule( i n d e x )

Description

The outputModule object of renderQueueItem generates a single file or sequence via a render, and contains
attributes and methods relating to that file to be rendered. It returns an Output Module with the given index
number. The indexed items are numbered beginning with 1.

119
Reference

120

Attributes

Attribute Reference Description

fi le see “OutputModule file attribute” on path and name of the file to be rendered
page 121

p ostRenderAc tion see “OutputModule postRenderAction one of the postRenderAction types

attribute” on page 121

n ame see “OutputModule name attribute” on name of the Output Module as presented to
page 121 the user

templates see “OutputModule templates array of all Output Module templates

attribute” on page 122

Methods

Method Reference Description

remove() see “OutputModule remove() method” removes the Output Module

on page 121

saveAsTemp l a te() see “OutputModule saveAsTemplate() saves a new Output ModuleTemplate with the
method” on page 122 given name

applyTemplate() see “OutputModule applyTemplate() applies a pre-set Output Module Template

method” on page 120

OMCollection
ap p.p ro j e c t . re n d e r Q u e u e . i t e m s .outputMo dules

Description

The OMCollection contains all of the Output Modules in the project.

Attributes

len gth number of objects in the collection (applies to all collections)

Methods

[] retrieves an object or objects in the collection via its index number

a dd( ) adds an Output Module with a specified template

See also

“Collection object” on page 54

OutputModule applyTemplate() method

ap p.projec t . re n d erQ u eu e. i t e m (i n d ex ). ou t p u t Mo d u le s[ i] . applyTemplate( te mplateName )

Description

Applies an existing Output Module template, identified by name.

120
Reference

121

Parameters

t emplateName name of the template to be applied

Returns

None.

OutputModule file attribute

ap p.projec t . re n d erQ u eu e. i t e m (i n d ex ). ou t p u t Mo d u le s[ i] . fi le

p ostRenderAc tion.NONE
postRenderAc tion.IMPORT
postRenderAc tion.IMPORT_AND_REPLACE_USAGE
postRenderAc tion.SET_PROXY

OutputModule remove() method

ap p.projec t . re n d erQ u eu e. i t e m (i n d ex ). ou t p u t Mo d u le s[ i] . rem ove ( )

Description

Deletes an Output Module.

121
Reference

122

Parameters

None.

Returns

None.

OutputModule saveAsTemplate() method

ap p.projec t . re n d erQ u eu e. i t e m (i n d ex ). ou t p u t Mo d u le s[ i] . s ave As Tem p la te ( n a m e )

Description

Saves an Output Module with the name given as a parameter.

Parameters

n ame name of the new template

Returns

None.

OutputModule templates attribute

ap p.projec t . re n d erQ u eu e. i t e m (i n d ex ). ou t p u t Mo d u le s[ i] . tem p la te s

Description

The templates attribute is an array of strings; these are the names of the templates in the local installation of
After Effects.

Type
A r r ay ; read-only.

PlaceholderSource object
ap p.pro j ect. i tem(in d ex). ma i n S o u rce
app.project.item(index).proxySource

Description

The PlaceholderSource object holds information describing the footage source of a placeholder. It is a subclass
of FootageSource and so it inherits all attributes and methods of the FootageSource object. (See “Footage-
Source object” on page 90.)
There are no attributes or methods in PlaceholderSource other than those inherited from the FootageSource
object.

Project object
ap p . p ro j e c t

122
Reference

123

Description

The project object enables access to data and functionality within a particularAfter Effects project.
Attributes of the Project object provide access to specific objects within an After Effects project, such as
imported files and footage, comps, as well as project settings such as the timecode base.
Methods of the Project object can import footage, can create solids, compositions and folders, and can save
changes.

Attributes

Attribute Reference Description

fi le see “Project file attribute” on page 125 file object of the currently open project

r ootFolder see “Project rootFolder attribute” on folderItem containing all the contents of the
page 128 project; the equivalent of the Project window

it ems see “Project items attribute” on itemCollection representing all items in the
page 127 project

a c t ive Item see “Project activeItem attribute” on currently active item, or null if none is active or
page 124 multiple items are active

bitsPerChannel see “Project bitsPerChannel attribute” color depth of the current project
on page 124

t r ansparencyGr idThumbnails see “Project transparencyGridThumb- determines if thumbnail views should use the
nails attribute” on page 131 transparency checkerboard pattern

t i m e co d e D i s p l ay Ty p e see “Project timecodeDisplayType method with which timecode is set to display

attribute” on page 130

t i m e co d e B a s e Ty p e see “Project timecodeBaseType timecode base as set in the File > Project Set-
attribute” on page 129 tings dialog box

t imeco deNTSCDropFr ame see “Project timecodeNTSCDropFrame equivalent to Drop Frame or Non-Drop Frame
attribute” on page 130 in the File > Project Settings dialog box

t imeco deFilmTy p e see “Project timecodeFilmType method with which timecode is set to display
attribute” on page 130

numItems see“Project numItems attribute” on total number of items contained in the project
page 127

se l e c t i o n see “Project selection attribute” on array of the items selected in the Project win-
page 129 dow

renderQueue see “Project renderQueue attribute” on the project’s render queue

page 128

Methods

Method Reference Description

item() see “Project item() method” on returns an item

page 126

consolidateFootage() see“Project consolidateFootage() replicates the functionality of File > Consoli-

method” on page 125 date All Footage

removeUnu sed Fo o ta g e() see “Project removeUnusedFootage() replicates the functionality of File > Remove
method” on page 128 Unused Footage

123
Reference

124

Method Reference Description

r e d u ce Pro j e c t ( ) see “Project reduceProject() method” on replicates the functionality of File > Reduce
page 127 Project

c lo se( ) see“Project close() method” on closes the project with normal save options
page 124

save( ) see “Project save() method” on page 128 saves the project (or displays a Save dialog box
if project has never been saved)

saveWi t h D i a l o g ( ) see “Project saveWithDialog() method” displays a Save dialog box; returns true if file
on page 129 was saved

imp or tPlaceholder() see “Project importPlaceholder() replicates the functionality of File > Import >
method” on page 126 Placeholder.

imp or tFile() see “Project importFile() method” on replicates the functionality of File > Import >
page 125 File.

imp or tFil eWi thD ia l o g () see “Project importFileWithDialog() displays an Import dialog box; returns an array
method” on page 126 of all imported items

sh owWindow() see “Project showWindow() method” on if true, shows the project window
page 129

Parameters

CloseOptions action to be performed on close (see Enumerated Types, below)

Enumerated Types

C l o s e O p t i o n s . D O _ N OT _ S AV E _ C H A N G E S close without saving

Cl o s e O p t i o n s . P RO M P T _ TO _ S AV E _ C H A N G E S send a prompt asking whether to save changes before close

Cl o s e O p t i o n s . S AV E _ C H A N G E S save automatically on close option

Returns

Boolean. False only in one case: the file has not been previously saved; the user is presented with a Save dialog
box, and cancels the save.

Project consolidateFootage() method

ap p.proj e c t . con s o l i d a te Fo o t a g e ( )

Description

Replicates the functionality of the Consolidate All Footage command.

Parameters

None.

Returns

Integer; the total number of footage items removed.

Project file attribute

ap p.proj ec t . fi l e

Description

The file attribute is a File object representing the project that is currently open.

Type

File Object or null if project has not been saved; read-only.

Project importFile() method

ap p.proj e c t . impor tFile( Im p o r t O p t i o n s )

Description

Replicates the functionality of the Import File dialog box.

Parameters

Im p o r t O p t i o n s options as set in the ImportOptions object

125
Reference

126

Returns

FootageItem

Example
ap p.p ro j e c t . i m p o r t F i l e ( Imp o r tO p t i o n s ( F i l e ( “s a m p l e . p s d ” ) )

See also

“ImportOptions object” on page 95

Project importPlaceholder() method

ap p.proj e c t . impor tPlaceholder( n a m e, w id t h, he ig ht , f ra m e ra t e , d u ra t io n )

Description

Replicates the functionality of File > Import > Placeholder; adds a placeholder footage item of a specified
name, width, height, framerate, and duration to the project.

Parameters

n ame name of the placeholder

w idt h width in pixels of the placeholder footage

he ig ht height in pixels of the placeholder footage

fr amer a te frame rate of the placeholder footage

dur a tio n duration of the placeholder footage, in seconds

Returns

FootageItem.

Project importFileWithDialog() method

ap p.proj e c t . i m p o r t F i l e Wi t h D i a l o g ( )

Description

Replicates the functionality of File > Import > File and produces an Import dialog box for the user. Unlike
importFile(), importWithDialog() does not take arguments.

Returns

Array of Items created during import; or null if the user cancels the dialog.

Project item() method

ap p.proj e c t . item( i n d e x )

Description

This method returns an item with the given index number.

126
Reference

127

Parameters

index integer; the index of the item

Returns

Item.

Project items attribute

ap p.proj ec t .items

Description

This attribute represents all of the items in the project.

Type

ItemCollection; read-only.

Project numItems attribute

ap p.proj ec t . nu mItems

Description

The numItems attribute represents the total number of items contained in the project, including folders and
all types of footage.

Type

Integer; read-only.

Example
n = ap p. pro j e c t . nu m Item s ;
aler t("There are " + n + " items in this project.")

Project reduceProject() method

ap p.proj e c t . re du ce Pro j e c t ( ar ray_of_ite m s )

Description

Replicates the functionality of File > Reduce Project.

Parameters

ar r ay_of_items items to which the project is to be reduced

Returns

Integer; the total number of items removed.

Example
v ar t heItems = n ew Ar r ay ();
theItems[theItems.length] = app. project.item(1);
theItems[theItems.length] = app. project.item(3);

127
Reference

128

ap p.p ro j e c t . re d u ce Pro j e c t ( t h e Item s ) ;

Project removeUnusedFootage() method

ap p.proj e c t . rem oveUnu s e d Fo o t a g e ( )

Description

Replicates the functionality of File > Remove Unused Footage.

Parameters

None.

Returns

Integer; the total number of footage items removed.

Project renderQueue attribute

ap p.proj ec t .renderQueue

Description

This attribute represents the render queue of the project.

Type

RenderQueue; read-only.

Project rootFolder attribute

ap p.proj ec t .rootFolder

Description

The rootFolder attribute is the root folder containing the root contents of the project; this is a conceptual
folder that contains all items in the Project window, but not items contained inside other folders in the Project
window.

Type

FolderItem; read-only.

Project save() method

ap p.proj ec t . save()
ap p.proj ec t . save( Fi l e )

Description

Saves the project (or prompts the user if the file has never previously been saved). Passing in a File object is
equivalent to the Save As command and allows you to save a project to a new file.

Parameters

File File object to save

128
Reference

129

Returns

None.

Project saveWithDialog() method

ap p.proj ec t . s aveWi t h D i a l o g ( )

130
Reference

131

Project transparencyGridThumbnails attribute

ap p.proj ec t .t r ansparencyGr i d

Description

The transparencyGridThumbnails attribute determines if thumbnail views should use the transparency
checkerboard pattern (yes or no).

Type

Boolean (read/write).

Property object
ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . prop er t y

Description

The Property object contains value, keyframe, and/or expression information about a particular property of
the layer. Examples of a Property are position, zoom, and mask feather.
Note that in standard JavaScript descriptions a “property” and an “attribute” are synonymous. Because After
Effects contained this separate use of the term “property” before any scripting support was added, this
documentation refers only to “attributes” when speaking about accessible values within scripting. “Property”
meanwhile remains the term for values attached to layers, effects and masks both within this document and
throughout After Effects.

Attributes

Attribute Reference Description

p rop er t y ValueTy p e see “Property propertyValueType type of value stored in this property
attribute” on page 143

v alue see “Property value attribute” on value of the property at the current time
page 150

hasMi n see “Property hasMin attribute” on true if there is a minimum permitted value
page 136

hasMax see “Property hasMax attribute” on true if there is a maximum permitted value
page 136

min Value see “Property minValue attribute” on minimum permitted value

page 143

max Value see “Property maxValue attribute” on maximum permitted value

page 142

isSpat ia l see “Property isSpatial attribute” on true if property defines a spatial value
page 137

can Var yOverTime see “Property canVaryOverTime true if the property can be keyframed
attribute” on page 135

isTim eVa r y in g see “Property isTimeVarying attribute” true if the property has keyframes or an
on page 137 expression enabled that vary its values

numKe ys see “Property numKeys attribute” on number of keyframes on this property

page 143

131
Reference

132

Attribute Reference Description

u n it sTex t see “Property unitsText attribute” on text description of the units in which the value
page 150 is expressed

e xpression see “Property expression attribute” on the expression string for this property
page 135

e xpressionEnabled see “Property expressionEnabled if true, the expression is used to generate val-
attribute” on page 136 ues for the property

expressionEr ror see “Property expressionError attribute” contains error if the last expression evaluated
on page 136 with an error

Ke y fr ameInter polationTy p e see “Property KeyframeInterpolation- type of interpolation used at a keyframe

Type attribute” on page 137

se l e c te d Ke y s see “Property selectedKeys attribute” on array containing the indices of all selected key-
page 145 frames of the Property

Methods

Method Reference Description

v alueAtTime() see “Property valueAtTime() method” returns value of the property evaluated at
on page 150 given time

se tValue() see “Property setValue() method” on sets the static value of the property
page 148

se tValueAtTime() see “Property setValueAtTime() creates a keyframe at the given time (if none
method” on page 149 exists) for the property

se tValuesAtTimes() see “Property setValuesAtTimes() creates a keyframe that is an array at the given
method” on page 149 time (if none exists) for the property

se tValueAtKe y() see “Property setValueAtKey() method” finds the keyframe with the given index and
on page 149 sets the value of the property at that keyframe

n earestKe yIndex() see “Property nearestKeyIndex() returns the index of the keyframe nearest to
method” on page 143 the given time

ke yTi me() see “Property keyTime() method” on returns the time at which the condition given
page 142 by the arguments occurs

ke yValue() see “Property keyValue() method” on returns the value of the property at the time at
page 142 which the condition given by the arguments
occurs

a ddKe y () see “Property addKey() method” on adds a new keyframe at the given time
page 135

removeKe y() see “Property removeKey() method” on removes the keyframe with the given index
page 144

isInterolationTy p eValid() see “Property isInterpolationTypeValid() true if this property can be interpolated
method” on page 137

se tInter polationTy p eAtKe y() see “Property setInterpolationTypeAt- sets the interpolation type for the key
Key() method” on page 145

ke yIn Inter p o l a tio n Ty p e() see “Property keyInInterpolationType() returns the 'in' interpolationType for the given
method” on page 138 key

ke yOutInter polationTy p e() see “Property keyOutInterpolation- returns the 'out' interpolationType for the
Type() method” on page 139 given key

132
Reference

133

Method Reference Description

set Spa ti a l Ta n g en tsAtKe y () see “Property setSpatialTangentsAt- sets the in and out tangent vectors for the
Key() method” on page 147 given key

k e yInSpatialTangent() see “Property keyInSpatialTangent() returns the 'in' spatial tangent for the given key
method” on page 138

k e yOutSpatialTangent() see “Property keyOutSpatialTangent() returns the 'out' spatial tangent for the given
method” on page 139 key

se tTempor alEaseAtKe y() see “Property setTemporalEaseAtKey() sets the in and out temporal ease for the given
method” on page 148 key

ke yIn Tempor alEase() see “Property keyInTemporalEase() returns the 'in' temporal ease for the given key
method” on page 138

ke yOutTempor alEase() see “Property keyOutTemporalEase() returns the 'out' temporal ease for the given
method” on page 139 key

se tTempor alContinuou- see “Property setTemporalContinuou- specifies whether the keyframe has temporal
sAt Ke y () sAtKey() method” on page 147 continuity

ke yTempor alContinuous() see “Property keyTemporalContinuous() returns whether the keyframe has temporal
method” on page 141 continuity

se tTempor alAutoBezierAtKe y() see “Property setTemporalAutoBezier- specifies whether the keyframe has temporal
AtKey() method” on page 147 auto bezier

ke yTempor alAutoBezier() see “Property keyTemporalAutoBezier() returns whether the keyframe has auto bezier
method” on page 141

se t S p a t i a l Co n t i nu o u s At Ke y ( ) see “Property setSpatialContinuousAt- specifies whether the keyframe has spatial

Key() method” on page 146 continuity

ke y S p a t i a l Co n t i nu o u s ( ) see “Property keySpatialContinuous() returns whether the keyframe has spatial con-
method” on page 141 tinuity

se tSpatialAutoBezierAtKe y see “Property setSpatialAutoBezierAt- specifies whether the keyframe has spatial
Key() method” on page 146 auto bezier

ke ySpatialAutoBezier() see “Property keySpatialAutoBezier() returns whether the keyframe has spatial auto
method” on page 140 bezier

se t Rov i n g AtKe y () see “Property setRovingAtKey() specifies whether the keyframe is roving
method” on page 145

ke yRov i n g () see “Property keyRoving() method” on returns whether the keyframe is roving
page 140

se t S e l e c te d At Ke y ( ) see “Property setSelectedAtKey() sets whether the keyframe is selected

method” on page 146

ke yS e l e c te d ( ) see “Property keySelected() method” on returns whether the keyframe is selected

page 140

Examples

1 Getting and setting the value of an opacity

opacity has propertyValueType of OneD, and is stored as a float.
v ar my Proper t y = myLayer. opacit y ;
myProper t y.setValue(0.5);
/ / T h i s n e w v a r i a b l e my O p a c i t y w il l b e a fl o a t v a l u e .
var myOpacit y = my Proper t y.value;

133
Reference

134

2 Getting and setting the value of a position

position has propertyValueType of ThreeD_SPATIAL and is stored as an array of three floats.
v ar my Proper t y = myLayer. position;
myProper t y.setValue([10,30,0]);
// Th is n ew va r ia bl e my Po si ti o n be a n a r r ay of 3 fl oa t s :
var my Position = my Proper t y.value;

3 Changing the value of a mask shape to be open instead of closed

v ar my Ma sk = my l ayer. ma sk (1);
var myPro p er t y = my Ma sk . ma sk S ha p e;
myShape = my Proper t y.value;
my S h a p e . c l o s e d = f a l s e ;
myProper t y.setValue(myShape);

4 Getting the value of a color at a particular time

A color is stored as an array of four floats (r,g,b,opacity). The following code sets the value of the red
component of a light's color at time 4 to be half of that at time 2:
v ar my Proper t y = myLig ht.color ;
var colorValue = my Proper t y.valueAtTime(2,t r ue);
colorValue[0] = 0.5 * colorValue[0];
myProper t y.setValueAtTime(4,colorValue);

5 How to check that a scale calculated by an expression at time 3.5 is the expected value of [10,50]
v ar my Proper t y = myLayer.scale;
// false value of preExpression means e v aluate the ex pression
var scaleValue = my Proper t y.valueAtTime(3.5,false);
if (scaleValue[0] == 10 && scaleValue[1] == 50) {
aler t("hur r ay");
else {
aler t("oops");
}

6 Keyframing a rotation from 0 to 90 and back again

The animation is 10 seconds, and the middle keyframe is at the 5 second mark. Rotation properties are stored
as a OneD value.
m y Prop e r t y = my L ayer. ro t a t i o n ;
myProper t y.setValueAtTime(0, 0);
myProper t y.setValueAtTime(5, 90);
myProper t y.setValueAtTime(10, 0);

7 Changing the keyframe values for the first three keyframes of some source text
m y Prop e r t y = my Tex t L ayer. s o u rceTex t ;
i f ( my Prop e r t y. nu m Ke ys < 3 ) {
aler t("er ror, I thoug ht there were 3 ke y fr ames");
}
myProper t y.setValueAtKe y(1, new TextDocument("ke y number 1");
myProper t y.setValueAtKe y(2, new TextDocument("ke y number 2");

134
Reference

135

m yProp er t y. setVa l u eAtKe y (3, n ew Text D oc u m e n t ( " ke y nu m b e r 3 " ) ;

8 Setting values using the convenience syntax for position, scale, color, or source text
// T hese two are equivalent. The second fills in a default of 0.
my Layer. p o sitio n . setVa l u e([ 20, 30, 0]) ;
my Layer. p o sitio n . setVa l u e([ 20, 30 ]);
// These two are equivalent. The second fills in a default of 100.
myLayer.scale.setValue([ 50, 50, 100]);
myLayer.scale.setValue([ 50, 50 ]);
// These two are equivalent. The second fills in a default of 1.0
myLig ht.color.setValue([ .8, .3, .1, 1.0]);
myLig ht.color.setValue([ .8, .3, .1]);
/ / T h e s e t wo a re e q u iv a l e n t . T h e s e con d c re a te s a Tex t D o c u m e n t
myTextL ayer. so u rceText. setVa l u e(n ew Tex t D oc u m e n t ( " f oo" ) ) ;
myTextLayer.sourceText.setValue("foo");

Property addKey() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . a d d Ke y ( t im e )

Description

The property addKey method adds a new keyframe at the given time and returns the index of the new
keyframe.

Parameters

t ime floating-point value; the time at which the keyframe is added

Returns

Integer; the index of the new keyframe.

Property canVaryOverTime attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .canVar yOverTime

Description

The Property canVaryOverTime attribute is true if this property can vary over time, in other words, if
keyframe values or expressions can be written to this property.

Type

Boolean; read-only.

Property expression attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .expression

Description

The Property expression attribute is the expression for this property, expressed as a string. This attribute forces
an evalution of the given expression string. The value always changes to the given expression string even if the
string is not a valid expression.

135
Reference

136

If the given string is a valid expression, expressionEnabled becomes true. If the given string is not a valid
expression, an error is generated, and expressionEnabled is set to false. If you set a property’s expression to the
empty string, expressionEnabled will be set to false.

Type

String; read/write.

Property expressionEnabled attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .expressionEnabled

Description

The Property expressionEnabled attribute, if true, uses the expression to generate the value for the property.
If the attribute is false, then the expression is not used; keyframe information or the static value of the property
is used. This attribute can be set to true only if the expression contains a valid expression string.

Type

Boolean; read/write.

Property expressionError attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .expressionEr ror

Description

The Property expressionError attribute contains the error if the last expression string given to the expression
attribute evaluated with an error.
If no expression string has been given to the expression, or if the last expression string given to expression
evaluated without error, it contains the empty string ("").

Type

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . i s S p a t i a l

Description

The Property isSpatial attribute is true if the property defines a spatial value. Examples are position and effect
point controls.

Type

Boolean; read-only.

Property isTimeVarying attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . i s Ti m e Va r y i n g

Description

The Property isTimeVarying attribute is true if the property is time varying. A property is time varying if it
has keyframes or an enabled expression. If isTimeVarying is true, then canVaryOverTime must also be true.

Type

Boolean; read-only.

Property KeyframeInterpolationType attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . s e t In te r p ola t i on Ty p e At Ke y
(1,Ke y fr ameInter polationTy p e.LINEAR,Ke y fr ameInter polationTy p e.BEZIER)

Description

This enumerated type specifies the type of interpolation used at a keyframe.

Enumerated Types

Possible values are:

137
Reference

138

K e y fr ameInter polationTy p e.LINEAR specifies a linear keyframe

K e y fr ameInter polationTy p e.BEZIER specifies a bezier keyframe.

140

Parameters

k e y Index Integer; the keyframe being set

Returns

KeyframeEase expressed as an array.

Property keyRoving() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . ke yRov i n g( ke y In d e x )

Description

This method returns whether the keyframe is roving.

If the PropertyValueType is neither TwoD_SPATIAL nor ThreeD_SPATIAL, an exception is generated.

Parameters

keyIndex Integer; the keyframe being evaluated

Returns

Boolean.

Property keySelected() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . ke yRov i n g( ke y In d e x )

Description

This method returns whether the keyframe is selected.

Parameters

keyIndex Integer; the keyframe being evaluated

Returns

Boolean.

Property keySpatialAutoBezier() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .ke ySpatialAutoBezier( ke y In d e x )

Property keyValue() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .ke yVa lue( ke y In d e x )
ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .ke yVa lue( m a r ke r Co m m e n t )

De s cr i p t io n

The property keyValue method finds the keyframe or marker specified in the arguments and returns the time
at which it occurs.
If no keyframe or marker can be found that matches the argument, this method generates an exception, and
an error is displayed.

Parameters

ke y Index integer; the keyframe index number, (in range 0..numKeys)

mar ker Comment string; the comment attached to a marker (see “MarkerValue Comment attribute” on page 117)

Returns

Floating-point value; the time at which the keyframe or marker occurs.

Property maxValue attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .maxValue

142
Reference

143

Description

The Property maxValue attribute contains the maximum permitted value of the property. If the hasMax
attribute is false, an exception occurs, and an error is generated.

Type

Floating-point value; read-only.

Property minValue attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .proper t y ( n a m e ) .minValue

Description

The Property maxValue attribute contains the minimum permitted value of the property. If the hasMax
attribute is false, an exception occurs, and an error is generated.

Type

Floating-point value; read-only.

Property nearestKeyIndex() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .nearestKe yIn dex( t im e )

P roper t y Va l u eTy p e. ThreeD _ S PATI A L array of three floating point positional values, e.g., Anchor
Pont [10, 20.2, 0]

P rop er t y ValueTy p e.ThreeD array of three floating point quantitative values, e.g., Scale
[100, 20.2, 0]

Proper t yValueTy p e.TwoD_SPATIAL array of 2 floating point positional values, e.g., Anchor Pont
[5.1, 10]

Prop er t y ValueTy p e.TwoD array of 2 floating point quantitative values, e.g., Scale [5.1,
100]

Proper t yValueTy p e.OneD a floating point value

Proper t yValueTy p e.COLOR array of 4 floating point values in the range 0..1, e.g., [.8, .3, .1,
1.0]

Proper t yValueTy p e.CUSTOM_VALUE unimplemented type; you cannot get and set values for
properties with this type

Proper t yValueTy p e.MARKER MarkerValue object (see “MarkerValue object” on page 115)

Proper t yValueTy p e.LAYER_INDEX integer; a value of 0 means none (no layer)

Proper t yValueTy p e.MASK_INDEX integer; a value of 0 means none (no mask)

Proper t yValueTy p e.SHAPE shape object

Proper t yValueTy p e.TEXT_D O CUMENT TextDocument object (see “TextDocument object” on

page 178)

Property removeKey() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .removeKe y ( ke y In d e x )

Description

The property removeKey method removes a keyframe with the given keyIndex. If no keyframe with that
keyIndex exists, this method generates an exception and an error is displayed.

144
Reference

145

Parameters

k e y Index integer; the index of the keyframe being removed

Returns

None.

Property selectedKeys attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . s e l e c te d Ke y s

Description

The Property selectedKeys attribute yields an array of indices of all the selected keyframes in this Property. If
no keys are selected, or if the property has no keyframes, an empty array is returned.

Type

Array of integers; read-only.

Property setInterpolationTypeAtKey() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . s e t In te r p ola t i on Ty p e At Ke y( inTy p e, outTy p e )

Description

This method sets the in and out interpolation types for the given key.
If an outType is not provided, then outType will be set equal to the inType.

Parameters

in Ty p e KeyframeInterpolationType; the incoming interpolation type

o ut Ty p e KeyframeInterpolationType (optional); the outgoing interpolation type

Returns

None.

Property setRovingAtKey() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . s e t Rov i n g At Ke y( ke y In d e x , n e w Va l )

Description

This method specifies whether the keyframe is roving.

If the PropertyValueType is neither TwoD_SPATIAL nor ThreeD_SPATIAL, an exception is generated.
Note: The first and last key in any property never will rove. Setting to true will be ignored and the value will remain
false.

145
Reference

146

Parameters

keyIndex Integer; the keyframe being set

newVal Boolean; if set to true, keyframe is set to be roving

Returns

None.

Property setSelectedAtKey() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . s e t S e l e c te d At Ke y( ke y In d e x , o n O f f )

Description

This method specifies whether the keyframe is selected.

Parameters

keyIndex Integer; the keyframe being specified

onOff the new setting to use; if true, keyframe is selected, if false, deselected

Returns

None.

Property setSpatialAutoBezierAtKey() method

ap p.project.item(index).layer(index).proper t y(name).setSpatialAutoBezierAtKe y(ke yIn dex, newVal)

Description

This method specifies whether the keyframe has spatial continuity.

If the PropertyValueType is neither TwoD_SPATIAL nor ThreeD_SPATIAL, an exception is generated.

Parameters

keyIndex Integer; the keyframe being set

newVal Boolean; if set to true, keyframe is set to be auto-bezier

Returns

None.

Property setSpatialContinuousAtKey() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . s e t S p a t i a l Co n t i nu o u s At Ke y( ke y In d e x , n e w Va l )

Description

This method specifies whether the keyframe has spatial continuity.

If the PropertyValueType is neither TwoD_SPATIAL nor ThreeD_SPATIAL, an exception is generated.

146
Reference

147

Parameters

keyIndex Integer; the keyframe being set

newVal Boolean; if set to true, keyframe is set to be continuous

Returns

None.

Property setSpatialTangentsAtKey() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . s e t S p a t i a lTa n ge n t s At Ke y( ke y In d e x, in Ta n g e n t ,
outTange n t )

Description

This method sets the in and out tangent vectors for the given key.
If no outTangent argument is provided, outTangent will be set equal to inTangent. If the PropertyValueType
is TwoD_SPATIAL, the inputs should be arrays containing 2 floating-point values. If the PropertyValueType
is ThreeD_SPATIAL, the inputs should be arrays containing 3 floating-point values.
If the PropertyValueType is neither TwoD_SPATIAL nor ThreeD_SPATIAL, an exception is generated.

Parameters

ke y Index Integer; the keyframe being set

in Tangent Floating-point value; the in tangent vector for this keyframe

o utTangent Floating-point value (optional); the out tangent vector for this keyframe

Returns

None.

Property setTemporalAutoBezierAtKey() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .setTempor alAutoBezierAtKe y( ke y In d e x , n e w Va l )

Description

This method specifies whether the keyframe has temporal auto-bezier interpolation.
Note that spatial auto bezier has an effect at this keyframe only if keySpatialContinuous(keyIndex) is true.

Parameters

keyIndex Integer; the keyframe being set

newVal Boolean; if set to true, keyframe is set to be continuous

Returns

None.

Property setTemporalContinuousAtKey() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . s e t Te m p or a lCon t i nu ou s At Ke y( ke y In d e x , n e w Va l )

147
Reference

148

Description

This method specifies whether the keyframe has temporal continuity.

Note that temporal continuity has an effect at this keyframe only if the KeyframeInterpolationType is BEZIER
for both keyInInterpolation(keyIndex) and keyOutInterpolation(keyIndex).

Parameters

keyIndex Integer; the keyframe being set

newVal Boolean; if set to true, keyframe is set to be continuous

Returns

None.

Property setTemporalEaseAtKey() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . s e t Te m p or a lE a s e At Ke y( ke y In d e x , i n Te m p o ra l E a s e ,
o u t Te m p o ra l E a s e )

Description

This method sets the in and out temporal ease for the given key.
If outTemporalEase is not provided, then outTemporalEase will be set equal to the inTemporalEase.
InTemporalEase and outTemporalEase are arrays of KeyframeEase objects. The dimension of the array
depends on the dimension of the property's keyframeValueType. For ThreeD, the dimension of the array is 3.
For TwoD, it is 2. For all other keyframeValueTypes, including TwoD_SPATIAL and ThreeD_SPATIAL types,
it is 1.

Parameters

keyIndex Integer; the keyframe being set

inTemporalEase KeyframeEase; the incoming temporal ease setting

outTemporalEase KeyframeEase; the outgoing temporal ease setting

Returns

None.

Property setValue() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .setValue( n e w Va lu e )

Description

The property setValue method sets the static value of the property.
If the property has keyframes, this method cannot be used; see “Property setValueAtTime() method” on
page 149 or “Property setValueAtKey() method” on page 149 instead. If used with a property that has
keyframes, this method generates an exception and an error is displayed.
The type of value to use as an argument depends on the propertyValueType.

148
Reference

149

Parameters

Parameters

[times] floating point value; an array of times at which to set keyframes

[ n e wValues] propertyValueType; an array of values appropriate for the type of property being set

Returns

None.

Property unitsText attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . u n i t s Tex t

Description

The Property unitsText attribute is a text description of the units in which the value is expressed.

Type

String; read-only.

Property value attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .value

Description

The Property value attribute contains the value of the property at the current time. If expressionEnabled is
true, value returns the evaluated expression value; if there are keyframes, value returns the keyframed value at
the current time; in all other cases, value returns the static value for the property.
The type of value returned depends on the propertyValueType of the stream.

Type

Dependent on stream being evaluated; read-only.

Examples

See “Getting and setting the value of an opacity” on page 133, “Getting and setting the value of a position” on
page 134, and “Changing the value of a mask shape to be open instead of closed” on page 134 under Property
Object Examples.

Property valueAtTime() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .valueAtTime( t ime, preEx pression )

150
Reference

151

Description

The property valueAtTime method returns the value of the property as evaluated at the given time. Time is in
seconds with the beginning of the composition represented as zero.
The preExpression option is relevant only if the property has an expression applied; otherwise it is ignored. It
controls whether any expression is used to calculate the value.
Note that the type of value returned is not made explicit; it will be of a different type, depending on the
property evaluated.

Parameters

t ime floating point value; the time at which to set a keyframe

p reExpression boolean; determines whether to evaluate the property before or after applying any active
expression

Returns

Value (type depends on the propertyValueType).

PropertyBase object
ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . prop er t y B ase

Description

PropertyBase is the base class for both PropertyGroup and Property, so PropertyBase attributes and methods
are also available to PropertyGroup and Property. Because PropertyGroup is the base class for Layer, its
attributes and methods are available for Layers as well.

Attributes

Attribute Reference Description

n ame see “PropertyBase name attribute” on name of the property

page 155

match Na me see “PropertyBase matchName special name for the property used to build
attribute” on page 154 unique naming paths

prop er t yIndex see “PropertyBase propertyIndex index of a PropertyBase within its ParentGroup
attribute” on page 156

prop er t y D e p t h see “PropertyBase propertyDepth indicates number of levels of parent Property-

attribute” on page 155 Groups between the PropertyBase and the
layer

prop er t y Ty p e see “PropertyBase propertyType returns the PropertyType describing this Prop-
attribute” on page 156 ertyBase

parentProper t y see “PropertyBase parentProperty returns the PropertyGroup that is the parent of
attribute” on page 155 this PropertyBase

isMo d i fi e d see “PropertyBase isModified attribute” returns true if the PropertyBase has been
on page 154 changed since its creation

can S e t E n a b l e d see “PropertyBase canSetEnabled true if the user interface displays an eyeball
attribute” on page 152 icon for this property

en abled see “PropertyBase enabled attribute” on corresponds to the setting of the eyeball icon,
page 153 if there is one

151
Reference

152

Attribute Reference Description

a c t ive see “PropertyBase active attribute” on determines if PropertyBase is active

page 152

elided see “PropertyBase elided attribute” on returns whether this property is elided (not
page 153 displayed) in the user interface

isEffe c t see “PropertyBase isEffect attribute” on true if this property is an effect PropertyGroup
page 154

isMas k see “PropertyBase isMask attribute” on true if this property is a mask PropertyGroup
page 154

se l e c te d see “PropertyBase selected attribute” on determines whether this PropertyBase is

page 157 selected

Methods

Method Reference Description

prop e r t y Gro u p ( ) see “PropertyBase propertyGroup() returns the parent PropertyGroup

method” on page 156

remove() see “PropertyBase remove() method” on removes the PropertyBase from the project
page 157

moveTo () see “PropertyBase moveTo() method” moves the PropertyBase to the specified
on page 155 newIndex within its PropertyGroup

duplic a te() see “PropertyBase duplicate() method” duplicates the PropertyBase and returns the
on page 153 duplicate

PropertyBase active attribute

This attribute specifies whether this property is enabled. It corresponds to the setting of the eyeball icon, if
there is one.
If there is no eyeball icon, this attribute will default to true; you can write this attribute only if canSetEnabled
is true.

do not always have a “name,” defaulting instead to an empty string, but in all cases, they have a matchName.

Type

String; read-only.

PropertyBase moveTo() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . m ove To( n e w In d e x )

Description

The PropertyBase moveTo method moves the PropertyBase to the specified newIndex within its Property-
Group.
This method is valid only for children of indexed groups; if not, or if newIndex is not valid, an exception is
generated and an error is displayed.

Parameters

newIndex integer; the index within the same PropertyGroup to which the PropertyBase is to be moved.

Returns

None.

PropertyBase name attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . n a m e

Description

The PropertyBase name attribute is the name of the property.

It is an error to attempt to set the name if the property is not a child property of an INDEXED_GROUP.

Type

String; read/write.

PropertyBase parentProperty attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .parentProper t y

Description

The PropertyBase parentProperty returns the PropertyGroup that is the parent of this PropertyBase, or null
if this PropertyBase is a layer.

Type

PropertyGroup; read-only.

PropertyBase propertyDepth attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . p rop e r t y D e p t h

155
Reference

156

Description

The PropertyBase propertyDepth is 0 for a layer. Add 1 (one) for each level of parent PropertyGroup above
this PropertyBase until the layer has been reached.

Type

String; read-only.

PropertyBase propertyGroup() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .proper t yGroup()
ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) .proper t y ( n a m e ) .proper t yGroup( c o u n t Up )

Description

The PropertyBase propertyGroup method returns the parent PropertyGroup, found by moving up the
hierarchy the number of levels proscribed by countUp.
The countUp is optional and defaults to 1 if not provided. Range of countUp must be within [1 ...property-
Depth]. Returns NULL if countUp takes you as far up as the parent of the layer containing this propertyBase.

Parameters

c o u n tUp integer (optional); defaults to 1; the number of levels to ascend within the range 1..property-
Depth.

Returns

PropertyGroup. Null if countUp reaches the layer parent.

PropertyBase propertyIndex attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .proper t yIndex

Description

The PropertyBase propertyIndex is the index of a PropertyBase within its ParentGroup.

Note that some properties, such as Layers or "position," will not have a propertyIndex. Others, such as
individual effects or masks, will have an index within their parent PropertyGroup.

Type

Integer; read-only.

PropertyBase propertyType attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .proper t yTy p e

Description

The PropertyBase propertyType returns the PropertyType describing this PropertyBase.

Enumerated Types

PropertyType is an enumerated type returned by propertyType (read-only). It specifies a particular type of

PropertyBase, as follows:

156
Reference

157

PRO PE RTY specifies a single property such as position or zoom

IND E X E D _ GR OU P specifies a PropertyGroup whose members have an editable name and

an index, e.g., the “Masks” property of a layer, which refers to a variable
number of individual masks by index number.

NAME D _ GROU P specifies a PropertyGroup whose members have an uneditable name

and an index, e.g., a layer

PropertyBase remove() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) .remove()

Description

The PropertyBase remove method removes the PropertyBase from its parent group. If the PropertyBase is a
PropertyGroup, it removes the child properties as well.
This method is valid only for children of indexed groups; if not, an exception is generated and an error is
displayed.
This method may be called on a text animation property (any animator that has been set to a text layer).

Parameters

None.

Returns

None.

PropertyBase selected attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t y ( n a m e ) . s e l e c te d

Description

This attribute specifies whether this PropertyBase is selected. Setting selected to true selects the property;
setting it to false deselects.
The value of this attribute can be read for any Property, PropertyGroup or Layer. The value can be written on
a PropertyGroup only if it is an effect or mask; attempting to set this attribute for any other kind of Property-
Group will generate an exception.
Note that sampling this attribute can slow down system performance if it is used repeatedly to sample a large
number of properties. To read the full set of selected Properties for a Comp or Layer, use the selectedProperties
attribute of Comp or Layer.

Type

Boolean; read/write.

PropertyGroup object
ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . prop er t yGroup

157
Reference

158

Description

The PropertyGroup object represents a group of PropertyBase objects, (i.e., Property objects and/or Proper-
tyGroup objects). PropertyGroups may be nested to provide a chain all the way from the Layer at the top down
to a single Property (such as the mask feather of the third mask).

Attributes

Attribute Reference Description

n u m Prop e r t i e s see “PropertyGroup numProperties number of indexed properties in the group

attribute” on page 159

Methods

Method Reference Description

prop er t y () see “PropertyGroup property() method” returns the child PropertyGroup or Property
on page 159 with the given propertyIndex or name

can Ad d Prop e r t y ( ) see “PropertyGroup canAddProperty() true if a property with the given name can be
method” on page 159 added to the PropertyGroup

a d d Prop e r t y ( ) see “PropertyGroup addProperty() adds a property with the given name to the
method” on page 158 PropertyGroup

PropertyGroup addProperty() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t yGro u p ( i n d e x ) . a d d Prop e r t y ( n a m e )

Description

This method adds a property with the given name to this group.
Properties may only be added to a PropertyGroup whose propertyType is PropertyType.INDEXED_GROUP.
The only exception to this rule is a text animator property, which is contained in a NAMED_GROUP.
This method generates an exception if a property cannot be created with the given name, so it is always a good
idea to call PropertyGroup canAdd Property() method first to check. (See “PropertyGroup canAddProperty()
method” on page 159.)
The following names are supported:
• Any matchName for a property that can be added normally using the user interface. For example, ADBE
Mask Atom, ADBE Paint Atom, ADBE Text Position, ADBE Text Anchor Point.
• When adding to an ADBE Mask Parade: ADBE Mask Atom, Mask.
• When adding to an ADBE Effects Parade, any effect by matchName, such as ADBE Bulge, ADBE Glo2, APC
Vegas.
• Any effect by display name, such as Bulge, Glow, Vegas.
• For text animators and selectors, Text Animator maps to ADBE Text Animator, Range Selector maps to
ADBE Text Selector, Wiggly Selector maps to ADBE Text Wiggly Selector, and Expression Selector maps to
ADBE Text Expressible Selector.

158
Reference

159

Parameters

n ame string; the name to be added to the PropertyGroup

Returns

PropertyBase.

PropertyGroup canAddProperty() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p rop e r t y Grou p ( i n d e x ) . c a n Ad d Prop e r t y ( n a m e )

Description

This method returns true if a property with the given name can be added to this PropertyGroup.

Parameters

n ame string; the name to be added to the PropertyGroup

Returns

Boolean.

Example

The maskGroup can only add masks. The only legal input arguments are as follows:
• mask
• ADBE Mask Atom
Any other argument is illegal. Therefore:
• maskGroup.canAddProperty("mask") returns true
• maskGroup.canAddProperty("ADBE Mask Atom") returns true
Any other input for maskGroup argument is false. For example, maskGroup.canAddProperty("blend")
returns false

PropertyGroup numProperties attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t yGro u p ( i n d e x ) . nu m Prop e r t i e s

Description

This attribute represents the number of indexed properties in this group.

Note: For Layers only, this can appear misleading, as it returns a value of 3. These correspond to the mask, effect,
and motion tracker groups inside the Layer. However, Layers also have a host of other properties available only by
name; see the “PropertyGroup property() method” on page 159.

Type

Integer; read-only.

PropertyGroup property() method

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t yGro u p ( i n d e x ) . prop er t y ( i n d e x )
a p p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p ro p e r t yGro u p ( i n d e x ) . prop er t y ( n a m e )

159
Reference

160

Description

This method finds and returns the child PropertyBase, using either its propertyIndex or its name.
If using a string to provide the name argument, you may use any of the following:
• Any name used in expressions “parenthesis style” syntax, meaning the display name or the compact English
name
• Any match name
• Any expressions intercap sytax
See below for examples of these various types of names. Essentially, the method replicates syntax available with
expressions. In other words, the following are all allowed and are virtually interchangeable (where “mylayer”
is an already identified layer):
• m y l aye r. p o s i t i o n
• m y l aye r ( " p o s i t i o n " )
• m ylayer. p rop er t y ("p o sitio n ")
as well as the following, which are also interchangeable with one another:
• m y l aye r ( 1 )
• m ylayer.proper t y(1)
• Note that some properties of a Layer, such as position and zoom, can be accessed only by name. When using
the name argument to find a property that is multiple levels down, you will need to make more than one
call of this method; for example,
m yLayer. proper t y("ADBE Masks").proper t y(1)
will search two levels down, and return the first mask in the mask group.
If no Property or PropertyGroup can be found with the given name, this method returns a value of null.
Properties that can be accessed using this method with the name argument include:

Properties that can be accessed by name from any • "ADBE Mask Parade", or “Masks”
Layer
• "ADBE Effect Parade", or “Effects”

• "ADBE MTrackers", or “Motion Trackers”

Properties that can be accessed by name from an • "Anchor Point" or "anchorPoint"

AVLayer
• "Position" or "position"

• "Scale" or "scale"

• "Rotation" or "rotation"

• "Z Rotation" or "zRotation" or "Rotation Z" or "rotationZ"

• "Opacity" or "opacity"

• "Marker" or "marker"

Properties that can be accessed by name from a cam- • "Zoom" or "zoom"

era layer
• "Depth of Field" or "depthOfField"

• "Focus Distance" or "focusDistance"

• "Aperture" or "aperture"

• "Blur Level" or "blurLevel"

160
Reference

161

Properties that can be accessed by name from a light • "Intensity" or "intensity"

layer
• "Color" or "color"

• "Cone Angle" or "coneAngle"

• "Cone Feather" or "coneFeather"

• "Shadow Darkness" or "shadowDarkness"

• "Shadow Diffusion" or "shadowDiffusion"

• "Casts Shadows" or "castsShadows"

Properties that can be accessed by name from a 3D • "Accepts Shadows" or "acceptsShadows"

layer
• "Accepts Lights" or "acceptsLights"

• "Ambient" or "ambient"

• "Diffuse" or "diffuse"

• "Specular" or "specular"

• "Shininess" or "shininess"

• "Casts Shadows" or "castsShadows"

• "Light Transmission" or "lightTransmission"

• "Metal" or "metal"

Properties that can be accessed by name from a cam- • "X Rotation" or "xRotation" or "Rotation X" or "rotationX"
era, light or 3D layer
• "Y Rotation" or "yRotation" or "Rotation Y" or "rotationY"

• "Orientation" or "orientation"

Properties can be accessed by name from a text layer • "Source Text" or "sourceText" or "Text" or "text"

Properties that can be accessed from an AVLayer with • "Time Remap" or "timeRemapEnabled"
a non-still source

Properties that can be accessed from an AVLayer with • "Audio Levels" or "audioLevels"
an audio

Properties that can be accessed by name from a Prop- • "ADBE Mask Atom"
ertyGroup "ADBE Mask Parade"

Properties that can be accessed by name from a Prop- • "ADBE Mask Shape", or “maskShape”
ertyGroup "ADBE Mask Atom"
• "ADBE Mask Feather", or “maskFeather”

• "ADBE Mask Opacity", or “maskOpacity”

• "ADBE Mask Offset", or “maskOffset”

Parameters

in dex integer; the propertyIndex of the target PropertyBase, in the range [1..numProperties]

n ame string; the name of the target PropertyBase, which is a child of the current one.

Returns

PropertyBase; or NULL if no property with the given string name can be found.

Examples

1 If a layer (e.g., myLayer) has a Box Blur effect, you can retrieve the effect in any of the following ways:
m yLayer. proper t y(“Effects”).proper t y(“Box Blur”);
myLayer. proper t y(“Effects”).proper t y(“ boxBlur”);

161
Reference

162

m yLayer. proper t y(“Effects”).proper t y(“ADBE Box Blur”);

2 If a layer (e.g., myLayer) has a mask named “Mask 1” you can retrieve it as follows:
m yLayer. proper t y(“Masks”).proper t y(“Mask 1”);
3 To get a Bulge Center value from a Bulge effect, you could use any of the following:
m yLayer. proper t y(“Effects”).proper t y(“Bulge”).proper t y(“Bulge Center”);
myLayer. proper t y(“Effects”).proper t y(“Bulge”).proper t y(“ bulgeCenter”);

RenderQueue object
ap p.proj e c t . renderQueue

Description

The RenderQueue object enables access to data and functionality within the Render Queue area of a particular
After Effects project. This object is pivotal to render automation.
Attributes of the RenderQueue object provide access to items in the Render Queue and their render status.
Methods of the RenderQueue object can start, pause, and stop the render process.
The RenderQueueItem object provides access to the specific settings for an item to be rendered.

Attributes

Attribute Reference Description

r ender ing see “RenderQueue rendering attribute” determines whether a render is in progress
on page 164

n umItems see “RenderQueue numItems attribute” total number of items in the Render Queue
on page 163

items see “ItemCollection” on page 100 collected items in the Render Queue

Methods

Method Reference Description

sh owWindow() see “RenderQueue showWindow() boolean to show/hide the Render Queue win-
method” on page 164 dow

render() see “RenderQueue render() method” on starts the render; does not return until render
page 163 is complete

pauseRender ing() see “RenderQueue pauseRendering() pauses the render

method” on page 163

stopRender ing() see “RenderQueue stopRendering() stops the render

method” on page 164

item() see “RenderQueue Item() method” on returns a RenderQueueItem

page 162

RenderQueue Item() method

ap p.p ro j e c t . re n d e r Q u e u e . item( i n d e x )

162
Reference

163

Description

This method returns a render queue item with the given index number.

Parameters

index integer; the index of the item

Returns

RenderQueueItem.

RenderQueue items attribute

ap p.p ro j e c t . re n d e r Q u e u e .items

ap p.p ro j e c t . re n d e r Q u e u e . ren der()

163
Reference

164

Description

Starts the Render Queue; equivalent to use of the Render button in the Render Queue window. Does not
return until render is complete.
Set the app.onError if you wish to be notified of errors during the rendering process.
Set the RenderQueueItem.onStatusChanged attribute of a particular RenderQueueItem to get updates while
the render is progressing.

165

Description

Stops the Render Queue; equivalent to use of the Stop button in the Render Queue window during a render.
Useful to call in the event of an onStatusChanged callback.

Parameters

None.

Returns

None.

See also

“RenderQueueItem onStatusChanged attribute” on page 168.

RQItemCollection
ap p.proj ec t .renderQueue.items

Description

The RQItemCollection contains all of the Render Queue items. This is the equivalent of all of the items found
in the Render Queue window of a given project.

Attributes

le n gth number of objects in the collection (applies to all collections)

Methods

[] retrieves an object or objects in the collection via its index number

a dd( ) adds a RenderQueueItem for a specified composition

See also

“Collection object” on page 54

RenderQueueItem object
ap p.project.renderQueue.item(index)

Description

The RenderQueueItem object is an individual item in the Render Queue.

Attributes

Attribute Reference Description

numOutputMo dules see “RenderQueueItem numOutput- total number of Output Modules assigned to a
Modules attribute” on page 167 given Render Queue item

render see “RenderQueueItem render boolean that shows true if this item will render
attribute” on page 169 when the queue is started

165
Reference

166

Attribute Reference Description

st ar t Ti me see “RenderQueueItem startTime Date object representing time program began

attribute” on page 170 rendering the item

e l a p s e d S e co n d s see “RenderQueueItem elapsedSeconds time elapsed in the current render, in seconds

attribute” on page 167

t imeSp a n S ta r t see “RenderQueueItem timeSpanStart start time, in seconds, in the comp to be ren-
attribute” on page 171 dered

timeSpanDuration see “RenderQueueItem timeSpanDura- duration of the comp to be rendered, in sec-

tion attribute” on page 170 onds

skipFr a mes see “RenderQueueItem skipFrames number of frames to skip when rendering
attribute” on page 169

comp see “RenderQueueItem comp attribute” composition being rendered by this RQ item
on page 167

o utputMo dules see “RenderQueueItem outputModules collection of the Output Modules

attribute” on page 168

templates see “RenderQueueItem templates array of the Render Settings templates

attribute” on page 170

st atu s see “RenderQueueItem status attribute” current status of a Render Queue item
on page 170

onStatusChanged see “RenderQueueItem onStatus- condition in which the status of an item

Changed attribute” on page 168 changes (e.g., from RENDERING to DONE sta-
tus)

lo g Ty p e see “RenderQueueItem logType returns one of the log types

attribute” on page 167

Methods

Method Reference Description

o utputMo dule() see “RenderQueueItem outputModule() returns an Output Module for the item
method” on page 168

remove() see “RenderQueueItem remove() deletes the item from the Render Queue
method” on page 168

saveAsTemp l a te() see “RenderQueueItem saveAsTem- saves a new Render Settings Template with the
plate() method” on page 169 given name

applyTemplate() see “RenderQueueItem applyTemplate() applies a pre-set Render Settings Template

method” on page 166

RenderQueueItem applyTemplate() method

ap p.p ro j e c t . re n d e r Q u e u e . i t e m . applyTemplate( te mplateName )

Description

The applyTemplate method of renderQueueItem applies a Render Settings template to the item.

Parameters

templateName name of the template to apply

166
Reference

167

Returns

None.

RenderQueueItem comp attribute

ap p.p ro j e c t . re n d e r Q u e u e . i t e m ( i n d e x ) . com p

Description

The comp attribute returns the CompItem object that will be rendered by this Render Queue item. This is a
read-only attribute; to change the Composition, the Render Queue item must be deleted and re-created.

Type

CompItem; read-only.

RenderQueueItem elapsedSeconds attribute

ap p.p ro j e c t . re n d e r Q u e u e . i t e m ( i n d e x ) . e l a p s e d S e co n d s

Description

The elapsedSeconds attribute shows the number of seconds spent rendering the item.

Type

Integer, or null if item has not been rendered; read-only.

RenderQueueItem logType attribute

Description

The outputModules attribute returns the collection of Output Modules for the item.

Type

OMCollection; read-only.

RenderQueueItem outputModule() method

ap p.p ro j e c t . re n d e r Q u e u e . i t e m ( i n d e x ) . outputMo dule( i n d e x )

Description

This method returns an output module with the given index.

Parameters

index integer; the index of the output module

Returns

OutputModule.

RenderQueueItem remove() method

ap p.p ro j e c t . re n d e r Q u e u e . i t e m ( i n d e x ) . rem ove ( )

168
Reference

169

Description

The remove method of renderQueueItem deletes the referenced item from the Render Queue.

Parameters

None.

Returns

None.

RenderQueueItem render attribute

ap p.p ro j e c t . re n d e r Q u e u e . i t e m ( i n d e x ) . ren der

Description

The render attribute determines whether an item will render when the Render Queue is started.

RenderQueueItem status attribute

ap p.p ro j e c t . re n d e r Q u e u e . i t e m ( i n d e x ) . status

Description

The status attribute represents the current render status of the item.

Enumerated Type

RQItemStatus - one of the following attributes:

RQItemStatus.WILL_CONTINUE render has been paused

R Q ItemS ta tu s. N E E D S _ OU TP U T item lacks a valid output path

R QItemStatus.UNQUEUED render item is listed in the Render Queue window but is not ready to render

RQItemStatus.QUEUED composition is ready to render

RQItemStatus.RENDERING composition is rendering

RQ ItemS ta tu s. U S E R _ S TOP PE D rendering process was stopped by the user

RQ ItemS ta tu s. E R R _ S TOP PE D rendering process was stopped due to an error

Settings object
Description

The Settings object provides an easy way to manage settings for scripts. The settings are persistent between
application launches, saved in the After Effects Preferences file.

Methods

Method Reference Description

sa veS e t t i n g ( ) see “Settings saveSetting() method” on can save a default value for a preferences item
page 172

getSetting() see “Settings getSetting() method” on retrieves a setting found in the Prefs file
page 171

haveS e t t i n g ( ) see “Settings haveSetting() method” on used to determine whether a given section
page 172 name and key name have a setting assigned

Settings getSetting() method

ap p.s e t t i n g s . g e t S e t t i n g ( s e c t i o n Na m e , ke y Na m e )

Description

The getSetting method retrieves a setting found in the Prefs file.

Parameters

se c t i o n Na m e text string that holds the name of a section of settings; in the prefs file these are the names
enclosed in brackets and quotation marks

ke y Na me text string that describes an individual setting name; these are listed in quotation marks below
the sectionName

“Settings haveSetting() method” on page 172

172
Reference

173

Shape object
ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p rop e r t y ( 1 ) . p rop e r t y ( i n d e x ) . p rop e r t y( " m a s k S h a p e " ) . v a lu e

Description

The Shape object holds information describing the outline shape of a Mask.

Attributes

Attribute Reference Description

closed see “Shape closed attribute” on specifies whether the shape is a closed curve
page 174

v er t ices see “Shape vertices attribute” on array of floating-point pairs specifying the
page 175 anchor points of the shape

in Tangents see “Shape inTangents attribute” on array of floating-point pairs specifying the tan-
page 174 gent vectors coming into the shape vertices

o utTangents see “Shape outTangents attribute” on array of floating-point pairs specifying the tan-
page 174 gent vectors coming out of the shape vertices

Methods

Method Reference Description

sh ap e() see “Shape Shape() method” on constructor to create a new Shape

page 175

Examples

1 Creating a square mask

A square is a closed shape with 4 points. The inTangents and outTangents for connected straightline segments
are always 0, the default. Since the default values are the desired values, you do not need to set them here.
v a r my S h a p e = n e w S h a p e ( ) ;
my Sha p e. ver tices = [ [0, 0], [0, 1], [1, 1] , [ 1 , 0 ] ] ;
my S h a p e . c l o s e d = t r u e ;

2 Creating a “U” shaped mask

A "U" is an open shape with the same 4 points used in Example 1:
v a r my S h a p e = n e w S h a p e ( ) ;
my Sha p e. ver tices = [ [0, 0], [0, 1], [1, 1] , [ 1 , 0 ] ] ;
my S h a p e . c l o s e d = f a l s e ;

3 Creating an oval
An oval is a closed shape with 4 points and inTangents and outTangents:
v a r my S h a p e = n e w S h a p e ( ) ;
my Sha p e. ver tices = [[300, 50], [200, 150 ] , [ 3 0 0 , 2 5 0 ] , [ 4 0 0 , 1 5 0 ] ] ;
my Sha p e. i n Ta n g en ts = [[55. 23, 0], [0, - 5 5 . 2 3 ] , [ - 5 5 . 2 3 , 0 ] , [ 0 , 5 5 . 2 3 ] ] ;
my Sha p e. o u tTa n g en ts = [[- 55. 23, 0], [0, 5 5 . 2 3 ] , [ 5 5 . 2 3 , 0 ] , [ 0 , - 5 5 . 2 3 ] ] ;
my S h a p e . c l o s e d = t r u e ;

173
Reference

174

Shape closed attribute

ap p.p ro j e c t . i t e m ( i n d e x ) . l ay e r ( i n d e x ) . p rop e r t y ( 1 ) . p rop e r t y ( i n d e x ) .proper t y("maskShape").value.closed

Description

This attribute specifies whether the shape is a closed curve. If true, the first and last vertices will be connected
to form a closed curve. If false, the closing segment will not be drawn.

Type

Boolean; read/write.

Shape inTangents attribute

175
Reference

176

Type

Array of floating-point pairs; read/write.

SolidSource object
ap p.project.ite m(index) . m a i n S o u rce
ap p.project.ite m(index) .proxySource

Description

The SolidSource object holds information describing a solid color footage source. It is a subclass of Footage-
Source and so it inherits all attributes and methods of the “FootageSource object” on page 90.

Attributes

c olor see “SolidSource color specifies the color of the solid

attribute” on page 176

SolidSource color attribute

ap p.project.ite m(index).s olidSource. color

Description

The color attribute of SolidSource specifies the color of the solid. The value is an array of three floats for red,
green, and blue, where those floats are in the range [0..1].

Type

Array of three floating-point values from 0 to 1: [R, G, B]); read/write.

System object
sy stem

Description

The System object provides access to attributes found on the user’s system, such as the user name or the name
and version of the operating system.

Attributes

Attribute Reference Description

u ser Na me see “System userName attribute” on user name logged in to the current session of
page 177 the operating system

ma ch i n eNa me see “System machineName attribute” name of the host machine

on page 177

o sName see “System osName attribute” on name of the operating system currently run-
page 177 ning

o sVersion see “System osVersion attribute” on version of the operating system currently run-
page 177 ning

176
Reference

sy ste m . userName

Description

The userName attribute specifies the name of the user logged on to the system, and is expressed as a text string.

177
Reference

178

Type

String; read-only.

Example
c onfir m( "You are: " + system.userName + " r unning on " + system.machineName + ".");

TextDocument object
Description

The TextDocument object holds a string an attribute named "text." It is used to store values for a text layer's
Source Text property.

Attributes

Attribute Reference Description

t ext see “ TextDocument text attribute” on text string stored in the TextDocument
page 178

Methods

Method Reference Description

Tex t D o c u m e n t ( ) see “TextDocument TextDocument() constructor to create a TextDocument

method” on page 179

Examples

1 Set a value of some source text and then display an alert showing the new value:
v ar my TextDocument = new TextDocument("Happy Cake");
myTextLayer. proper t y("Source Text").setValue(myTextDocument);
aler t(myTextLayer. proper t y("Source Text").getVa lue());

2 Set keyframe values for text that will show different words over time:
v ar textProp = my TextLayer. proper t y("Source Text");
textProp.setValueAtTime(0, new TextDocument("Happy"));
tex t Prop. setVa l u eAtTi me(. 33, n ew Text D oc u m e n t ( " c a ke " ) ) ;
tex t Prop. setVa l u eAtTi me(. 66, n ew Text D oc u m e n t ( " i s " ) ) ;
tex t Prop. setVa l u eAtTi me(1, n ew TextD oc u m e n t ( " yu m my! " ) ) ;

TextDocument text attribute

Tex t D o c u m e n t . text

Description

The actual text string stored in this TextDocument.

Type

String; read/write.

178
Reference

179

TextDocument TextDocument() method

N ew TextD o cu mn en t(d o cText)

Description

This method is the constructor for a new TextDocument.

Parameters

d o c Tex t string; text contents of the TextDocument

Returns

TextDocument.

179
Examples

180

Examples
Following are sample scripts included on your CD with an overview of what they do and a step-by-step
breakdown of how they work. This set of examples is by no means exhaustive, but it does demonstrate some
of scripting’s more complex features in action. It also shows some typical programming constructions from
JavaScript that apply to scripting.
For examples specific to the use of the user interface, see “Creating User Interface Elements” on page 198. For
more examples from Adobe, as well as from other After Effects users, visit Adobe Studio Exchange at http://
share.studio.adobe.com, and choose Scripting under the Adobe After Effects section.

Apply effect
This example is a rather simple one; it first requires that the user select an AVLayer and, if that condition is
met, sets a 10-pixel Fast Blur to the selected layer (or layers), with Repeat Edge Pixels set to true.
The comments that appear on lines beginning with double forward slashes (//) describe what is occurring in
each section of the script. The script does the following, in order:
• checks that at least one selected layer can have effects applied to it
• adds Fast Blur to any selected layer that can
• sets Blurriness to 10 and turns on Repeat Edge Pixels
• returns a boolean stating whether the effect was added
• starts an undo group so that if the effect is being applied to more than one layer, the entire script operation
can be undone in one step rather than several
• sets an error with instructions to the user should the script fail to apply an effect to any layer
{
// T h is fu n cti o n a p p l i es the effect to o n e s i n g le layer
//
function applyFastBlurToLayer(the_layer)
{
v a r a d d e d It = f a l s e ;

// Can only add an effect if there's an effects g roup in the layer.

// Some layers don't have one, like camer a and lig ht layers.
i f ( t h e _ l ayer ( " E f f e c t s " ) ! = nu l l ) {
// Always best to check if it's safe before adding:
if (the_layer("Effects").canAddProper t y("Fast Blur")) {
// add a new Fast Blur effect to the effects g roup of the layer
t h e_layer("E ffects"). a d d Prop er t y ("Fa st B lu r " ) ;

/ / s e t t h e p a r a m e ter v a l u e s
the_layer("Effects")("Fast Blur").blur r iness.setValue(10);
t h e_layer("E ffects")("Fa st B l u r"). rep ea t E d ge P i xe ls . s e t Va lu e ( t r u e ) ;

a d d e d It = t r u e ;
}

180
Examples

181

}
// R e t u r n a b o o l e a n s ay i n g w h e t h e r we a d d e d t h e e f f e c t
re tur n a d d e d It ;
}

// Star t an undo g roup. By using this w ith an endUndoGroup(), you

// allow u sers to u n d o the who l e scr ipt w ith one undo oper ation.
app.beg inUndoGroup("Apply Fast Blur to Selections");

// If we d o n ' t fi n d a ny sel ected l ayers, we ' ll p u t u p a n a le r t a t t h e e n d .

var numLayersChanged = 0;

/ / G e t t h e a c t ive com p
v a r a c t ive Ite m = a p p. p ro j e c t . a c t ive Item ;
i f ( a c t ive Item ! = nu l l & & ( a c t ive Item i n s t a n ce o f Com p Item ) ) {

v a r a c t iveCom p = a c t iveIte m ;

/ / t r y to a p p l y to e ve r y s e l e c te d l ayer
v a r s e l e c te d L ayer s = a c t iveCom p. s e l e c te d L ayer s ;
f o r ( v a r i = 0 ; i < s e l e c te d L ayer s . l e n g t h ; i + + ) {

v a r c u r L ayer = s e l e c te d L ayer s [ i ] ;

/ / T h e m e t h o d re t u r n s t r u e i f i t a d d s t h e e f f e c t , f a l s e o t h e r w i s e .
if (applyFastBlurToLayer(curLayer) == t r ue) {
numLayersChanged++;
}
}
}
// Pr in t a messa g e i f n o l ayers were a ff e c te d
if (numLayersChanged == 0) {
a l e r t ( " P l e a s e s e l e c t a n AV l ayer o r l ayer s a n d r u n s c r i p t a g a i n " ) ;
}

app.endUndoGroup();
}

Replace text
This script performs an action much too specific to be useful as it is, but it shows the basics for a very useful
general operation, which is the automatic editing of text layers. Quite simply, the script looks for selected text
layers that contain the text string “blue” and changes this string to read “monday”--note that “blue” could
appear anywhere in the selected layer, even as part of another word, and still be changed. For example,
“bluejean” will read “mondayjean” after the effect is applied.
The comments that appear on lines beginning with double forward slashes (//) describe what is occurring in
each section of the script. The script does the following, in order:

181
Examples

182

• sets a function that replaces all instances of “blue” with “monday”

• sets a function that applies the first function to a single layer, looking for all Source Text keyframes where
“blue” might appear, evaluating each time whether any text was changed (and returning a boolean stating
whether it was changed)
• sets a single undo group for all changes made by the script
• pops up a warning if no layers were changed, instructing the user how to properly apply the script
{
// T h i s s c r i p t rep l a ce s tex t i n a l l t h e s e l e c te d tex t l ayer s .
//
// It finds all instances of the word "blue" and changes them to "monday"
//

// Th is fu n cti o n ta kes theS t r i n g a n d rep la ce s fi r s t Word w i t h s e con d Word .

// It rep ea ts, so i t w il l rep l a ce a l l in stan ce s of fi r s t Word i n t h e S t r i n g .
// Re t ur n s the cha n g ed st r i n g .
function replaceTextInSt r ing(theSt r ing , firstWord, secondWord)
{
var n ewS t r in g = theS t r i n g ;
while(newSt r ing .indexOf(firstWord) != -1) {
newSt r ing = newSt r ing .replace(firstWord,secondWord);
}
re tur n newSt r ing;
}

// Th is fu n cti o n a p p l i es the cha n g e to on e s i n g le layer

//
function replaceTextInLayer(theLayer, firstWord, secondWord)
{
v a r ch a n g e d S o m e t h i n g = f a l s e ;

// Get the sourceText proper t y, if there is one.

var sou rceText = theL ayer. so u rceText;
i f ( s o u rceTex t ! = nu l l ) {
if ( so u rceText. nu mKe ys == 0) {
// textValue is a TextDocument. Re t r ie ve the st r ing inside
var oldSt r ing = sourceText.value.text;
if (oldSt r ing .indexOf(firstWord) != -1) {
var newSt r ing = replaceTextInSt r ing(oldSt r ing , firstWord, secondWord);
if ( old S t r i n g ! = n ewS t r i n g ) {
source Text.setValue(newSt r ing);
ch a n g e d S o m e t h i n g = t r u e ;
}
}
} else {
// D o i t fo r ea ch ke y fr a me:
for (var ke yIndex = 1; ke yIndex <= source Text.numKe ys; ke yIndex++) {
// textValue is a TextDocument. Re t r ie ve the st r ing inside
var oldSt r ing = sourceText.ke y Value(ke y In dex).text;

182
Examples

183

if (oldSt r ing .indexOf(firstWord) != -1) {

var newSt r ing = replaceTextInSt r ing(oldSt r ing , firstWord, secondWord);
if ( old S t r i n g ! = n ewS t r i n g ) {
sourceText.setValueAtKe y(ke y In dex,newSt r ing);
ch a n g e d S o m e t h i n g = t r u e ;
}
}
}
}
}
/ / Re t u r n a b o o l e a n s ay i n g w h e t h e r we rep l a ce d a ny tex t
re t u r n ch a n g e d S o m e t h i n g ;
}

// Star t an undo g roup. By using this w ith an endUndoGroup(), you

// allow u sers to u n d o the who l e scr ipt w ith one undo oper ation.
app.beg inUndoGroup("Apply Text Change to Selections");

// If we don't make any changes, we'll put up an aler t at the end.

var numLayersChanged = 0;

/ / G e t t h e a c t ive com p
v a r a c t ive Ite m = a p p. p ro j e c t . a c t ive Item ;
i f ( a c t ive Item ! = nu l l & & ( a c t ive Item i n s t a n ce o f Com p Item ) ) {

v a r a c t iveCom p = a c t iveIte m ;

v a r c u r L ayer = s e l e c te d L ayer s [ i ] ;

// Th e metho d re tu r n s t r u e i f it cha n g e s a ny tex t , f a ls e ot h e r w i s e .

if (replaceTextInLayer(curLayer, "blue", "monday") == t r ue) {
numLayersChanged++;
}
}
}
// Pr in t a messa g e i f n o l ayers were a ff e c te d
if (numLayersChanged == 0) {
// No te : if you put quotes in the inter ior of the st r ing ,
// t he y mu st be p reced ed by a ba ck sl a sh , a s i n \ " b lu e \ " b e low.
aler t ( "P l ea se sel ect a text l ayer o r l ayer s con t a i n i n g t h e word \ " b lu e \ " a n d r u n s c r i p t a ga i n " ) ;
}

app.endUndoGroup();
}

183
Examples

184

Save and increment

Although much of the functionality of this script has been superseded by the incremental save feature that is
new to After Effects 6.5, it is still included here because it makes effective use of conditionals, functions, and
the File and FileSystem objects.
This script automatically saves a new copy of the open After Effects project and increments a three-digit
number in its name to distinguish it from preceding versions of the project. This script is saved as
save_and_increment.jsx on your install CD.
The first step is to determine whether the currently open project has ever been saved. This is accomplished
with an opening if/else statement. The first condition, “!app.project.file” is saying that if the project has not
been saved, an alert telling the user to save the project is popped up, and the script ends.
if ( !ap p. p ro j ect. fi l e) {
aler t ("This p ro j ect mu st be save d bef ore r u n n i n g t h i s s c r i p t . " ) ;

Next, if the project has been saved at least once before, we set some variables to point to the name of the file
and to the numbering and file extension that we plan to add to it. The lastIndexOf() JavaScript searches a
string backwards (from end to start) and in this case looks for the dot that separates the name from the
extension.
} e lse {
var cu r rFil e = a p p. p ro j ect. fi l e;
var cu r rFil eNa me = cu r rFil e. n a me;
var extPo s = cu r rFi l eNa me. l a stIn d exO f ( " . " ) ;
v a r ex t = " " ;

Now we set the currFileName variable to the current name, before the dot.
if ( extPo s ! = - 1) {
ext = cur rFileName.subst r ing(extPos, cur rFileName.length);
cur rFileName = cur rFileName.subst r ing(0, extPos);
}

Next we set a variable that will increment versions starting with 0, and we check to see if there is an underscore
character four characters from the end of currFileName. If there is, we assume that the incrementer has run
before, as its job is to assign a 3-digit suffix after an underscore incremented one higher than the last suffix. In
that case we set incrementer to the current numerical string and extract the name without this numerical
extension.
v ar incrementer = 0;
if (cur rFileName.charAt(cur rFileName.length -4) == "_") {
incrementer = cur rFileName.subst r ing(cur rFileName.length - 3, cur rFileName.length);
cur rFileName = cur rFileName.subst r ing(0, cur rFileName.length -4);
}

Now we add an incrementer loop and test for whether numbering has extended to two or three digits (e.g., if
the numbering has reached “_010” or above, or “_100” or above), assigning a zero for each if not.
in cr ementer++;
var ist r ing = incrementer + "";
if (incrementer < 10) {
ist r in g = "0" + i st r i n g ;
}

184
Examples

185

if (incrementer < 100) {

ist r in g = "0" + i st r i n g ;
}

Finally we create a new file using our updated name and extension, display an alert letting the user know the
new file name being saved, and save the project with the new file name.
v ar newFi l e = Fil e(cu r rFi l e. p a th + "/ " + c u r r F i le Na m e + " _ " + i s t r i n g + ex t ) ;
aler t(n ewFi l e. fsNa me);
app.p ro j ect. save(n ewFi l e);
}

Render named items

This script allows you to find compositions in the open project with a particular text string in their names and
send all such compositions to the Render Queue.
To start, we check to see if a default string for rendering has already been set in the user preferences. If so, we
set this as a user prompt, handy if you’re always looking for the same string (for example, “FINAL” or
“CURRENT”). If not, we set a new sectionName and keyName for the preferences file along with a placeholder
value for the string that will be entered by the user.
v a r s e c t i o n Na m e = " A E E x a m p l e S c r i p t s " ;
var ke yName = "Render comps w ith this st r ing";
v a r s e a rch S t r i n g = " " ;

i f ( a p p. s e t t i n g s . h aveS e t t i n g ( s e c t i o n Na m e , ke y Na m e ) ) {
s e a rch S t r i n g = a p p. s e t t i n g s . g e t S e t t i n g ( s e c t i o n Na m e , ke y Na m e ) ;
}

Now we display a prompt to the user asking for what text string we should use.
sear chSt r ing = prompt("What st r ing to render?", searchSt r ing);

We next go through the project looking for the text entered by the user, and seeing if the item that contains
that text is a composition, sending all compositions with that text string in their names to the Render Queue.
If the user cancels, the text is undefined. Otherwise, we save the new setting in preferences, convert it to all
lowercase letters for consistency’s sake (keeping in mind that the search will not be case sensitive).
if ( sea rchS t r i n g ) {

a p p. s e t t i n g s . s aveS e t t i n g ( s e c t i o n Na m e , ke y Na m e , s e a rch S t r i n g ) ;
searchSt r ing = searchSt r ing .toLowerCase();
for (i = 1; i <= app. project.numItems; ++i) {
var curItem = app. project.item(i);
if (cu rItem in sta n ceo f Comp Item) {
if (curItem.name.toLowerCase().indexOf(searchSt r ing) != -1) {
app. project.renderQueue.items.add(curItem);
}
}
}

185
Examples

186

Finally, we make the Render Queue window visible and bring it to the front, ready for the user to assign save
locations for the new render queue items.
ap p.project.renderQueue.showWindow(t r ue);
}

New render locations

This script allows the user to select queued items in the Render Queue and assign a new render destination for
them.
First, we prompt the user for a new folder to use as a render destination.
v ar newLocation = folderGetDialo g ( " S e l e c t a ren d e r d e s t i n a t i o n . . . " ) ;

Next, we make certain that the user entered a new location (and didn’t cancel the dialog). Then we create a
loop for each selected render queue item. If this item is queued, we take the current render location, give it a
new name and location, and then display an alert stating the new file path.
if ( n e w L o c a t i o n ) { / / b o o l e a n to s e e i f t h e u s e r c a n ce l l e d
for (i = 1; i <= app. project.renderQueue.numItems; ++i) {
var curItem = app. project.renderQueue.item(i);
if (curItem.status == RQItemStatus.QUEUED) {
for (j = 1; j <= curItem.numOutputMo dules; ++j) {
var curOM = curItem.outputMo dule(j);
va r o l d L o ca tio n = cu rOM. fi l e;
curOM.file = new File(newLocation.toSt r ing() + "/" + oldLocation.name);
a l er t(cu rOM. fi l e. fsNa me);
}
}
}
}

Smart import
This script allows the user to import the full, nested contents of a folder just by selecting it. It attempts to detect
whether each item is a still, moving footage, or an image sequence. The user still has to make other choices via
dialogs, such as which layer of a multi-layer image (e.g., a .psd file) to import.
First, we prompt the user for a folder whose contents are to be imported, and ascertain that the user chooses
a folder rather than cancelling the dialog. We then call a function that appears below to import all of the files,
one by one.
v ar targetFolder = folderGetDialog("Impor t Items from Folder...");
//ret u r n s a fo l d er o r nu l l
if (targetFolder) {
f u n c t i o n p ro ce s s F i l e ( t h e F i l e ) {
v a r i m p o r t O p t i o n s = n e w Imp o r tO p t i o n s ( t h e F i l e ) ;
/ / c re a te a v a r i a b l e con t a i n i n g Im p o r t O p t i o n s
impor tSafeWithEr ror (impor tOptions);
}

186
Examples

187

Now we add a function to test whether a given file is part of a sequence. This uses Regular Expressions, which
are a special type of JavaScript designed to reduce the number of steps required to evaluate a string. The first
one tests for the presence of sequential numbers anywhere in the file name, followed by another making
certain that the sequential files aren’t of a type that can’t be imported as a sequence (moving image files).
We then check adjacent files to see if a sequence exists, stopping after we’ve evaluated ten files to save
processing time.
fu n c tion testForSequence (files){
var searcher = new Re gExp ("[0-9]+");
var mov ieFil eS ea rcher = n ew Re g E x p ( " ( m ov |av i |m p g) $ " , " i " ) ;
var parseResults = new Ar r ay ;

for (x = 0; (x < files.length) & x < 10; x++) {

//test that we have a sequence, stop parsing after 10 files
var mov ieFileResult = mov ieFileSearch er.exe c(files[x].name);
if (! mov ieFileResult) {
var cur rentResult = searcher.exe c(files[x].name);

If no match is found using the Regular Expression looking for a number string, we get null and assume there
is no image sequence. Otherwise, we want an array consisting of the matched string and its location within
the file name.
i f (cur rentResult) {
//we have a match - the st r ing contains numbers
//the match of those numbers is stored in the ar r ay[1]
//take that number and save it into parseResults
parseResults[parseResults.length] = cur rentResult[0];
}
else {
parseResults[parseResults.length] = nu ll;
}
}
else {
parseResults[parseResults.length] = nu ll;
}
}

Now if all of the files just evaluated indicated that they are part of a numbered sequence, we assume that we
have a sequence and return the first file of that sequence. Otherwise, we end this function.
v a r res u l t = nu l l ;
for (i = 0; i < parseResults.length; ++i) {
if (parseResults[i]) {
if (! result) {
re sult = files[i];
}
} else {
/ / ca se i n which a fi l e n a me d i d n ot con t a i n a nu m b e r
re s u l t = nu l l ;
break;
}

187
Examples

188

}
r etur n result;
}

Next we add a function to pop up error dialogs if there is a problem with any file we are attempting to import.
fu n c t i o n imp o r tS a feWithE r ror (i mp or t O p t i on s ) {
try {
app. p ro j ect. i mp o r tFi l e (i mp o r tOpt i on s ) ;
} catch (er ror) {
aler t(er ror.toSt r ing() + impor tOptions.file.fsName);
}
}

Next comes a function to actually import any image sequence that we discover using testForSequence(),
above. Note that there is an option for forcing alphabetical order in sequences, which is commented out in the
script as written. If you want to force alphabetical order, un-comment the line “importOptions.forceAlpha-
betical = true” by removing the two slashes at the beginning of that line.
fu n c tion processFolder(theFolder) {
var files = theFolder.getFiles();
//Get an ar r ay of files in the target folder
//test whether theFolder contains a sequence
var sequenceStar tFile = testForSequence(files);
//if it does contain a sequence, impor t the sequence
if (sequenceStar tFile) {
var imp o r tOp ti o n s = n ew Imp o r tO p t i on s ( s e q u e n ce S t a r t F i le ) ;
/ / c re a te a v a r i a b l e con t a i n i n g Imp o r t O p t i o n s
impor tOptions.sequence = t r ue;
/ / i m p o r t O p t i o n s . f o rceA l p h a b e t i c a l = t r u e ;
//un-comment this if you want to force alpha order by default
impor tSafeWithEr ror (impor tOptions);
}

//other w ise, impor t the files and re curse

for (index in files) {

//Go thro u g h the a r r ay, set ea ch el e m e n t to s i n g le F i le , r u n t h i s :
if (files[index] instanceof File) {
if (! sequenceStar tFile) {
//if file is already par t of a sequence , don't impor t it indiv i dually
processFile (files[index]);
/ / c a l l s t h e p ro ce s s F i l e f u n c t i o n a b ove
}
}
if (files[index] instanceof Folder) {
processFolder (files[index]); // re cursion
}
}
}

processFolder(targetFolder);

188
Examples

189

Render and email

This script renders all queued items in an open project and sends an email report to indicate when the render
has completed. It makes use of two other scripts that follow, email_methods.jsx (to send the email properly)
and email_setup.jsx (which establishes the sender, recipient, and email server).
We start by establishing conditions under which the script will run. An open project with at least one item
queued is required.
{
v ar sa feTo Ru n S cr ip t = t r u e;

s a f e To Ru n S c r i p t = a p p. p ro j e c t ! = nu l l ;
if ( ! a p p. p ro j ect) {
aler t ("A p ro j ect mu st be o p en to r u n t h i s s c r i p t . " ) ;
}
if ( sa feTo Ru n S cr ip t) {
debugger ;
//check the render queue and make cer tain at least one item is queued
safeTo Ru n S cr i p t = fa l se;
for (i = 1; i <= app. project.renderQueue.numItems; ++i) {
if (app. project.renderQueue.item(i).status ==
RQItemStatus.QUEUED) {
sa feTo Ru n S cr i p t = t r u e;
break;
}
}
if (! sa feTo Ru n S cr i p t) {
aler t ("You do not have any items set to render.");
}
}

Now we check whether we have email settings already saved in the Preferences. If so, we don’t need to prompt
the user. If not, we run the email_setup.jsx script, which prompts the user as to the mail gateway, sender and
recipient addresses. If there are saved settings that you need to change, you can always run email_setup.jsx to
make new settings that overwrite the existing ones.
if ( sa feTo Ru n S cr ip t) {

v a r s e t t i n g s = a p p. s e t t i n g s ;
i f ( ! s e t t i n g s . h aveS e t t i n g ( " E m a i l S e t t i n g s " , " Ma i l S e r ve r " ) | |
! s e t t i n g s . h aveS e t t i n g ( " E m a i l S e t t i n g s " , " Re p l y - to Ad d re s s " ) | |
! s e t t i n g s . h aveS e t t i n g ( " E m a i l S e t t i n g s " , " Re n d e r Rep o r t
Re cipient")){

// We don't have the setting s ye t, so r un email_setup.jsx

// to prompt for them
var email_setupfile = new File("email_setup.jsx");
email_setupfile.open("r");

189
Examples

190

e va l ( ema i l _ setu p fi l e. rea d () );

email_setupfile.close();
}

var myQueue = app. project.renderQueue //creates a shor tcut for RQ

Now we’re ready to render. Once rendering is complete, the script creates a text string for the email message
that contains the start time of the render, the render time of each item in the queue, and the total render time.
m yQueue.render();

v a r p ro j e c t Na m e = " Un s ave d Pro j e c t " ;

if (a p p. p ro j ect. fi l e) {
p ro j e c t Na m e = a p p. p ro j e c t . fi l e . n a m e ;
}
var my Message = "Render ing of " + projectName + " is complete.\n\n";

Now email the message, using the three settings from the email_methods.jsx script that has been automatically
run to prompt the user for the server, above.
if ( ! s e t t i n g s . h aveS e t t i n g ( " E m a i l S e t t i n g s " , " Ma i l S e r ve r " ) | |
! s e t t i n g s . h aveS e t t i n g ( " E m a i l S e t t i n g s " , " Re p l y - to Ad d re s s " ) | |
! s e t t i n g s . h aveS e t t i n g ( " E m a i l S e t t i n g s " , " Re n d e r Rep o r t
Re cipient")){
aler t("Can't send an email, I don't have all the setting s I need.
Ab or ting .");
} else {
// L o a d co d e fro m a fi l e w i th ha n dy e m a i li n g m e t h od s :
var ema i l Co d eFi l e = n ew Fi l e("ema i l_ m e t h od s . js x " ) ;
emailCodeFile.open("r");
e v a l ( ema il Co d eFil e. rea d () );
emailCodeFile.close();

Finally, we send an error if for any reason we are unable to send the mail.
v a r s e r ve r S e t t i n g = s e t t i n g s . g e t S e t t i n g ( " E m a i l S e t t i n g s " , " Ma i l
Ser ver");
v a r f ro m S e t t i n g = s e t t i n g s . g e t S e t t i n g ( " E m a i l S e t t i n g s " , " Re p l y -
to Ad d ress");
v a r to S e t t i n g = s e t t i n g s . g e t S e t t i n g ( " E m a i l S e t t i n g s " , " Re n d e r
Repor t Re cipient");
v a r my Ma i l = n e w E m a i l S o c ke t ( s e r ve r S e t t i n g ) ;
i f ( ! my Ma i l . s e n d ( f ro m S e t t i n g , toS e t t i n g , " A E Ren d e r Com p l e te d " , myMe s s a g e ) ) {
aler t("Sending mail failed");
}
}
}
}

190
Examples

191

Email methods
This script creates an email object for use with the Render and Email script, described above. It uses code that
is specific to the socket object and therefore requires advanced understanding of networking to edit; the
comments below describe its operation.
// C re a te a n e m a i l o b j e c t . T h e f u n c t i o n m ay b e c a l l e d b o t h
/ / a s a g l o b a l f u n c t i o n a n d a s a con s t r u c to r. It t a ke s t h e
// name of the email ser ver, and an optional Boolean that,
// if t r ue, pr ints debugg ing messages.
/ / T h i s o b j e c t i s n o t g u a r a n te e d to wor k f o r a l l S M T P s e r ve r s ,
// some of them may re quire a different set of commands.

// functions:
// send (fromAddress, to Address, subject, text) - send an email
// auth (name, pass) - do an author ization v ia POP3
// both functions re tur n false on er rors

// sam p l e:
// e = new EmailSocke t ("mail.host.com");
// au t h o r ize v ia P OP 3 (n o t a l l ser vers re quire author ization)
// e.auth ("myname", "my pass");
// send the email
// e.sen d ("me@ my. com", "yo u @ yo u . com " , " My Su b je c t " , " Hi t h e re ! " )

// Th is scr i p t ma kes u se o f the S o cket o b je c t , a n d c re a te s a n e w c la s s

// called EmailSocke t that is der ived from Socket. For more infor mation on
// creating new classes in this way, consult chapter 7 of JavaScr ipt, The
/ / D e fi n i t ive Gu i d e , by D av i d F l a n a g a n ( O ' Re i l l y ) .

//This is the const r u ctor for the email socket. It takes as arguments:
//ser ver - the address of the email ser ver (is not ch ecke d for validit y here)
//dbg - a boolean, if t r ue, pr ints additional er ror infor mation

function EmailSocke t (ser ver, dbg) {

var o bj = n ew S o cket;
obj._host = ser ver ;
obj._debug = (dbg == t r ue);
o bj.__ p ro to _ _ = E ma i l S o cke t. p ro to t y p e ;
re tur n o b j ;
}

// cor rect the p ro toy p e cha in to p o in t to t h e S oc ke t p rotot y p e ch a i n

/ / - t h i s i s w h a t a c t u a l l y c a u s e s t h e der iv ation from Socket.

EmailSo cke t. p ro to t y p e. _ _ p ro to _ _ = S oc ke t . p rotot y p e ;

// Th is sets u p the sen d () member fu n c t i on . s e n d ( ) t a ke s a s a r gu m e n t s :

// from - the email address of the sender. This is not validated.
// to - the email address of the re cipient. If there is an er ror,
/ / a n d t h e f ro m a d d re s s i s i n co r re c t , yo u w i l l n o t b e n o t i fi e d .
/ / s u b j e c t - t h e con te n t s o f t h e s u b j e c t fi e l d .

191
Examples

192

// t ex t - the bo dy o f the messa g e.

//
// Re tur ns:
// t r u e i f sen d i n g su cceed ed
// false other w ise (if there was an er ror)
//
/ / No te t h a t t h i s co d e u s e s a l o c a l f u n c t i o n o b j e c t to c re a te
/ / t h e f u n c t i o n t h a t i s a s s i g n e d to s e n d .

E m a i l S o c ke t . p ro to t y p e . s e n d = f u n c t i o n ( f ro m , to, s u b j e c t , tex t ) {
// open the socket on por t 25 (SMTP)
if (!this.open (this._host + ":25"))
re tur n false;
try {
/ / d i s c a rd t h e g re e t i n g
v a r g re e t i n g = t h i s . re a d ( ) ;
if (this._debug)
w r i te ( " R E C V: " + g re e t i n g ) ;
// issue EHLO and other commands
this._SMTP ("EHLO " + from);
this._SMTP ("MAIL FROM: " + from);
t h is. _ S MTP ("RC P T TO: " + to );
t h is. _ S MTP ("DATA ");
// send subject and time stamp
this.w r ite ln ("From: " + from);
t h is. w r ite l n ("To : " + to );
t h is. w r ite l n ("D a te: " + n ew D a te(). toS t r i n g( ) ) ;
i f ( t y p e o f s u b j e c t ! = u n d e fi n e d )
t h i s . w r ite l n ( " Su b j e c t : " + s u b j e c t ) ;
t h is. w r ite l n ();
// send the text
if (t y p eof text != undefined)
t h i s. w r ite l n (text);
// ter minate w ith a sing le dot and wait for response
t h is. _ S MTP (". ");
// ter minate the session
this._SMTP ("QUIT");
this.close();
re tur n t r u e;
}
catch (e) {
this.close();
re tur n false;
}
}

// Author ize v ia POP3. Su pply name and password.

//
// Re tur ns:
// t r u e i f sen d i n g su cceed ed
// false other w ise (if there was an er ror)

192
Examples

193

//
// Arguments:
// name - the userName of the account
// pass - the password

E m a i l S o c ke t . p ro to t y p e . a u t h = f u n c t i o n ( n a m e , p a s s ) {
// op en the con n ectio n o n p o r t 110 (P O P 3 )
if (!this.open (this._host + ":110"))
re tur n false;
try {
/ / d i s c a rd t h e g re e t i n g
v a r g re e t i n g = t h i s . re a d ( ) ;
if (this._debug)
w r i te ( " R E C V: " + g re e t i n g ) ;
// issue POP3 commands
t h is. _ P OP 3 ("U S E R " + n a me);
t h is. _ P OP 3 ("PA S S " + p a ss);
this._POP3 ("QUIT");
this.close();
re tur n t r u e;
}
catch (e) {
this.close();
re tur n false;
}
}

// Users of the EmailSocke t do not need to be concer ned w ith

/ / t h e f o l l ow i n g m e t h o d . It i s a n i m p l e m e n t a t i o n h e l p e r.

// loca l fu n ctio n to sen d a comma n d & ch e c k a P O P 3 rep ly

// throws in case of er ror
E m a i l S o c ke t . p ro to t y p e . _ P O P 3 = f u n c t i o n ( c m d ) {
if (this._debug)
w r i te l n ( " S E N D : " + c m d ) ;
if ( !t hi s. w r ite l n (cmd ))
t h row "E r ror";
var rep l y = this. rea d ();
if (this._debug)
w r ite ("RECV: " + reply);
// the reply star ts by either + or -
if (reply [0] == "+")
re tur n ;
t h row "E r ror";
}

// Users of the EmailSocke t do not need to be concer ned w ith

/ / t h e f o l l ow i n g m e t h o d . It i s a n i m p l e m e n t a t i o n h e l p e r.

// loca l fu n ctio n to sen d a comma n d & ch e c k a S M T P rep ly

// throws in case of er ror

193
Examples

194

EmailS o c ke t . p ro to t y p e . _ S M T P = f u n c t i o n ( c m d ) {
if (this._debug)
w r i te l n ( " S E N D : " + c m d ) ;
if ( !t hi s. w r ite l n (cmd ))
t h row "E r ror";
var rep l y = this. rea d ();
if (this._debug)
w r ite ("RECV: " + reply);
/ / t h e rep l y i s a t h re e - d i g i t co d e f o l l owe d by a s p a ce
var match = reply.match (/^(\d{3})\s/m);
if (match.length == 2) {
var n = Nu mber (ma tch [1]);
if (n >= 200 && n <= 399)
re tu r n ;
}
t h row "E r ror";
}

// n ice to have: a to S t r i n g ()
/ / T h i s f u n c t i o n a l l ow s t h e e m a i l o b j e c t to b e p r i n te d .

E m a i l S o c ke t . p ro to t y p e . to S t r i n g = f u n c t i o n ( ) {
re t u r n " [ o b j e c t E m a i l ] " ;
}

Email setup
A simple script that prompts the user for the server name, email sender, and email recipient that are saved as
Settings for the Render and Email script (above). You can run this script as standalone any time you want to
change the settings. The script will run email_setup.jsx whenever the settings don't exist; under normal
circumstances this would happen only the first time, or if the settings/preferences file is deleted.
This script is a good example of how a script can create settings that are saved in Preferences for the sole use
of scripting (as opposed to altering existing After Effects Preferences settings).
{
// T h i s s c r i p t s e t s u p 3 e m a i l s e t t i n g s .
/ / It c a n b e r u n a l l by i t s e l f , b u t i t i s a l s o c a l l e d
// w i thin "3- Ren d er a n d Ma i l . j sx" if t h e s e t t i n g s a re n ' t ye t s e t .

var ser verValue = prompt("Enter name of mail ser ver :");

var fromValue = prompt("Enter reply-to email address:");
var toValue = prompt("Enter re cipient's email address");
if (ser verValue != nu ll && ser verValue != "") {
a p p. s e t t i n g s . s aveS e t t i n g ( " E m a i l S e t t i n g s " , " Ma i l S e r ve r " ,
ser verVa lue);
}
if (fromValue != nu ll && fromValue != "") {
a p p. s e t t i n g s . s aveS e t t i n g ( " E m a i l S e t t i n g s " , " Re p l y - to Ad d re s s " ,
fromVa lue);
}
if (toValue != nu ll && to Va lue != "") {

194
Examples

195

ap p. s e t t i n g s . s aveS e t t i n g ( " E m a i l S e t t i n g s " , " Re n d e r Rep o r t

Re cipient", toValue);
}
}

Dialogs and console

This script shows how to use the various dialogs (alert(), prompt(), confirm()) and how to write to the info
palette (write(), writeLn() and clearOutput()). Although this script serves no practical use, these dialogs and
info palette prompts are highly useful and should be familiar to all script creators.
// U s e con fi r m ( ) to l e t t h e u s e r te l l u s w h e t h e r h e c a n s e e t h e " i n f o " w i n d ow.
// Depending how the user clicks, t r ue or false is re tur n ed.
if (confir m("Can you see the \"info\" palette?")){

// Star t by clear ing the infor mation area.

clearOutput();

// w r ite and w r iteLn w ill w r ite to the info tab w ith or w ithout a
//'newline'
// at the end.
w r ite("Ro ses a re re d , ");
w r iteLn("v iolets are blue");
w r i te ( " Su g a r i s s we e t , " ) ;
w r iteL n ("a n d so is E qu a l . ");

var reply = prompt( "Did you like my poem?");

if (reply == "yes" || reply == "YES"){
aler t("See the info w indow for a special secret for tune.");
// This gets r id of the old w r iting on the info tab.
clearOutput();
w r iteLn("You have a future as a liter ar y cr itic.");
}
else {
aler t("Hmm, I'll t r y once more...");
w r i teL n (". . . . . . . ");
w r iteLn("Roses are re d, v iolets are blue,");
w r iteLn("I've got some gum, on the sole of my shoe.");
}

aler t("Okay, all done w ith this test.");

}
else {
// aler t() just displays a message in a dialog box.
aler t("P l ea se ma ke it so yo u ca n see t h e i n f o p a le t te a n d r u n t h i s s c r i p t
again");
}

195
Examples

196

File fun
This script shows how to open files, open projects, collect names of the Comps in the scene, prompt a user for
where to write a file, write to a text file, and save the text file. It is useful only as an example of how the
individual methods and attributes operate; it doesn’t serve any useful production purpose.
// Fir st, cl o se a ny p ro j ect tha t mig ht be op e n .
i f ( a p p. p ro j e c t ! = nu l l ) {
// 3 choices here, CloseOptions.D O_NOT_SAVE_CHANGES,
/ / C l o s e O p t i o n s . P RO M P T _ TO _ S AV E _ C H A N G E S , a n d C l o s e O p t i o n s . S AV E _ C H A N G E S
app.p ro j ect. cl o se(C l o seOp ti o n s. D O_ NOT _ S AV E _ C HAN G E S ) ;
}

// Prompt the user to pick a project file:

// First argument is a prompt, second is the file t y pe.
v a r p fi l e = fi l e G e t D i a l o g ( " S e l e c t a p ro j e c t fi l e to o p e n " , " Eg g P a e p " ) ;

i f ( p fi l e = = nu l l ) {
a l e r t ( " No p ro j e c t fi l e s e l e c te d . Ab o r t i n g . " ) ;
} else {
/ / O p e n t h a t fi l e . It b e com e s t h e c u r ren t p ro j e c t .
var my_pro ject = app. open( pfile );

// Build a default text file name from the project's filename.

// Remove the ".aep" file extension (if present), then add
//_compnames.txt.
var default_text_filename;
var suffix_index = pfile.name.lastIndexOf(".aep");
if (suffix_index != -1){
default_text_filename = pfile.name.subst r ing(0,suffix_index);
}else {
default_text_filename = pfile.name;
}
default_text_filename += "_compnames.txt";

// Crea te a n o ther fi l e o bj ect fo r the fi le we ' ll w r i te ou t .

// First argument is the prompt, second is a default file name, third is
/ / t h e fi l e t y p e .
v a r tex t _ fi l e = fi l e Pu t D i a l o g ( " S e l e c t a fi l e to o u t p u t yo u r res u l t s " ,
default_text_filename, "TEXT txt");

i f ( tex t _ fi l e = = nu l l ) {
a l e r t ( " No o u t p u t fi l e s e l e c te d . Ab o r t i n g . " ) ;
} else {
// opens file for w r iting . First argument is mode ("w" for w r iting),
// second argument is file t y pe (for mac only),
// third argument is creator (mac only, "????" is no specific app).
text_file.open("w","TEXT","????");

// Wr ite the heading of the file:

text_file.w r i te ln("Here is a list of all the comps in " +
pfile.name);

196
Examples

197

t ex t_ fi l e. w r ite l n ();
for (var i = 1; i <= app. project.numItems; i++){
if (app. project.item(i) instanceof CompItem){
text_file.w r i te ln(app. project.item(i).name);
}
}

text_file.close();

aler t("All done!");

}
}

197
Creating User Interface Elements

198

Creating User Interface Elements

A JavaScript framework for creating user interface (UI) elements is included in After Effects 6.5.
This framework allows developers to use JavaScript to create UI components such as windows, panels,
buttons, checkboxes, and so on. The framework--called the scripting user interface--is built as an abstraction
layer on top of the windowing framework provided by the host platform on which After Effects is running.
Both Windows and MAC OS X native windowing systems are supported.
The motivation behind the creation of this scripting user interface was twofold:
• To enable JavaScripts to create dialogs and interact with controls. This satisfies a fundamental need on the
part of developers to create parameterized scripts, whose actions can be controlled more directly by the end
user.
• To extend the JavaScript environment to allow scripts to create UI elements dynamically. In this way, devel-
opers can create specialized interactive access to an application’s functionality.

Types of interface elements

The following controls and UI elements are supported:
• Panels (frames) -- (classname Panel) a container to group and organize other control types
• Push buttons -- (classname Button) a button containing a text string
• Radio buttons-- (classname RadioButton) a dual-state control, usually grouped with other radio buttons,
only one of which is set
• Checkbox buttons -- (classname Checkbox) a dual-state control showing a checked box (if true) or an
empty box (if false)
• Edit text -- (classname EditText) an text field that the user can change.
• Static text -- (classname StaticText) a text field that the user cannot change
• Scrollbars -- (classname Scrollbar) a standard scrollbar with a moveable element and stepper buttons to
incrementally move the element.
• Sliders -- (classname Slider) a standard slider with a moveable position indicator
In addition, the given classnames described above can used in window resource specifications to define
controls within a window or panel. See “Creating a window using window resource specifications” on
page 204 for more information.

JavaScript UI interface
This section provides a description of the scripting user interface programming model.

UI objects
The scripting user interface defines Window objects that wrap native windows and various control elements
(Buttons, StaticText, etc.), which wrap simple native controls. These objects share common methods such as
“query the element type”, “move the elements around”, and “set the title, caption or content”. For a complete
list of properties and methods, see “Reference” on page 22.

198
Creating User Interface Elements

199

Creating a window
To create a new window, use the Window constructor function. The constructor takes the desired type of the
window (dialog) as a parameter. You can supply optional arguments to specify an initial window title and
bounds.
The code examples provided in the JavaScript Interface section consist of short segments from a complete
script that is included later in this document. The examples presented build upon each other.
The following example creates an empty dialog with the variable name dlg. This dialog is carried though to
subsequent examples:
// C reate an empt y dialog w indow near upper left of the screen var
var dlg = new Window('dialog', 'Aler t Box Builder', [100,100,480,245]);
d l g . s h ow ( ) ;

.Newly created windows are initially invisible; the show() method makes them visible.

Roughly speaking, the numeric parameters to the constructor correspond to the top left and bottom right
coordinates of the window. The bounds supplied when creating the dialog specify the requested size of the
client area, which is the area of the dialog on which you can create controls. It does not include the title bar
and borders around the client area. The size and position of the dialog as a whole are automatically adjusted
to maintain the requested client area size.
For a more detailed description of window bounds, see “Element size and location” on page 199.

Container elements
All windows are containers, which is to say that they contain other elements such as panels, buttons, and check-
boxes within their boundaries.
Within a window, you can create other types of container elements and add interface components to them,
just as you add elements to a window. Elements added to a container are considered children of that container,
and certain operations performed on a container element also apply to its children. For instance, calling the
container’s hide() method makes the container invisible and makes all of its visible children invisible as well.
Along the same lines, calling the container’s show() method makes the container visible as well as any child
elements that were visible before the container was hidden. The following properties and methods of
containers also apply to all children of that container: visible, enabled, hide(), show().

Element size and location

To set the size and location of windows and controls, use the bounds property. As is typical when working with
window systems, the location of a window is defined as the point (pair of coordinates) where the top left
corner of the window is specified in the screen coordinate system.

199
Creating User Interface Elements

200

The location of an element within a window or other container element is defined as the point where the top
left corner of an element is specified in the window coordinate system, relative to the container the element
lies within. Size is specified by width and height in pixels. A complete bounds specification therefore consists
of 4 integer values that define the position of the upper left corner of the object and its dimensions.
The value of the bounds property can take several forms: a string with special contents, an inline JavaScript
“Bounds” object, or a four-element array. The following examples show equivalent ways of placing a 380-by-
390 pixel window near the upper left corner of the screen:
v ar d l g = n e w W in d o w(‘ d ia l o g ’, ‘A l e r t B o x B u i ld e r ’, [ 1 0 0 , 1 0 0 , 4 8 0 , 4 9 0 ] ) ;
d lg .b o u n d s = [100, 100, 480, 490];
d lg .b o u n d s = {l e ft: 100, t o p : 100, r i g h t : 4 8 0 , b ot t o m : 4 9 0 } ;
d lg .b o u n d s = “ l e ft: 100, t o p : 100, r i g h t : 4 8 0 , b ot t o m : 4 9 0 ” ;

Note that the window dimensions define the size of the “client area” of the window, which is the portion of
the window that an application can directly control. The actual window size will typically be larger, because
the host platform’s window system can add title bars and borders to windows.
When read, the bounds property returns a Bounds object--an array of four values representing the coordinates
of the upper left and lower right corners of the element: [left, top, right, bottom].

Adding elements
To add elements to a window or other container, use the container’s add() method. This method accepts the
type of the element to be created and some optional parameters, depending on the element type. The return
value is the UI object created or null on errors. The value of the element’s visible property defaults to “true”.
The element is initially visible, but it will remain invisible as long as its parent object is invisible.
A second (optional) parameter may be used to specify the initial bounds. The bounds is relative to the working
area of its parent container. For elements that display text, the text may be specified as the third (optional)
parameter--other types of elements have different semantics for a third argument.
For more information on the way in which each type of element interprets optional parameters, see “JavaS-
cript UI reference” on page 214. These optional parameters are positional, meaning that if you want to specify
some text for an element, but don’t care about its bounds, you must still provide an argument for the second
parameter in order to supply a value for the third (text) parameter. You can ‘skip over’ a positional parameter
by specifying the ‘undefined’ value as its argument value. In the example below, a Button element is created
with an initial text value, but no bounds value.
d lg .b t n Pn l = d l g . a d d (‘p a n e l ’, [15, 330 , 3 6 5 , 3 7 5 ] , ‘ Bu i ld i t’ ) ;
d lg .b t n Pn l . testB t n = d l g . b t n Pn l . a d d ( ‘ but ton’, u n defi n e d , ‘ Te s t’ ) ;

Dynamically creating a property such as btnPnl to reference the control object returned by add() is not
required, but can make it easier to later refer to the control. See “Accessing child elements” on page 201 for
more information.

Creation properties
Some element types have attributes that may only--in fact, can only--be specified when the element is created.
These are not normal properties of the element, in that they cannot be changed during the element’s lifetime,
and they are needed only once. For these element types, an optional creation properties argument may be
supplied to the add() method--this argument is an object with one or more properties that control things like
the element’s appearance, or special functions like ‘read-only’ for an edit text element.

200
Creating User Interface Elements

201

All UI elements have a creation property called name, which can be used to assign a name for identifying that
element. In the following example, the new Button element is assigned the name ‘ok’:
d lg .b t n P n l . b u i l d B t n = d l g . b t n P n l . a d d ( ‘ b u t t o n ’, [ 1 2 5 , 1 5 , 2 2 5 , 3 5 ] , ‘ B u i ld ’,
{n a me: ’o k ’});

Accessing child elements

A reference to each element added to a window is appended to the window’s children property.
The children collection is an array containing every defined element, indexed from 0 to the number of
elements minus 1. For controls or other elements that do not have children, the children collection is empty.
The number of child elements in a window is equal to the value of the length property of the children
collection. In the example below, since the ‘msgPnl’ panel was the first element created in dlg, the text for the
panel’s title can be set as follows:
v ar d l g = n e w W in d o w(' d i a l o g ' , ' A l e r t B ox Bu i lder ' , [ 1 0 0 , 1 0 0 , 4 8 0 , 2 4 5 ] ) ;
d lg .ms g Pn l = d l g . a d d (' p a n e l ' , [25, 15 , 3 5 5 , 1 3 0 ] ) ;
d lg .chil d ren [0]. text = ' Messa ges' ;
d lg .sh ow();

Using creation properties, a name can be assigned to a newly created element. If this is done, a child can be
referred to by its name. For instance, the Button in the example in the previous section was named ‘ok’, so the
Button could now be referred to like this:
d lg .b t n Pn l . chil d ren [‘o k’]. text = “ Bu i ld ” ;

An even simpler way to refer to a named child element is to use its name as a property of its parent element.
We can also refer to the Button from the previous example like this:
d lg .b t n Pn l . o k . text = “ Bu i l d ” ;

The value of an element’s internal name property is used by the scripting user interface when a script accesses
a property of the element’s parent object that does not match any of the predefined properties.
In this case, the framework searches the names of the parent element’s children to see if a match exists, and if
so, returns a reference to the matching child object.

Types of UI elements
This section introduces the types of user interface elements you can create within a Window or other type of
container element.

The Panel element

The Panel element is the only type of non-window container that is currently defined. Panels are typically used
to visually organize related controls.

201
Creating User Interface Elements

202

You can also use panels as separators: panels with width = 0 appear as vertical lines and panels with height =
0 appear as horizontal lines. When you create a Panel, you can specify an optional borderStyle property (used
only at creation time) to control the appearance of the border drawn around the panel.
v ar d l g = n e w W in d o w(' d i a l o g ' , ' A l e r t B o x B u i ld e r ' , [ 1 0 0 , 1 0 0 , 4 8 0 , 2 4 5 ] ) ;
d lg .ms g P n l = d l g . a d d (' p a n e l ' , [25, 15 , 3 5 5 , 1 3 0 ] , ' M e s s a g e s ' ) ;
d lg .sho w();

The Static Text element

StaticText elements are typically used to display text strings that are not intended for direct manipulation by
a user, like informative messages or identifying information for other elements. In the following example, a
Panel is created, and several StaticText elements are added to it:
// sa mp l e c o d e f o r se c t io n 2. 6. 2
v ar d l g = n e w W in d o w(' d i a l o g ' , ' A l er t B ox Bu i lder ' , [ 1 0 0 , 1 0 0 , 4 8 0 , 2 4 5 ] ) ;
d lg .ms g Pn l = d l g . a d d (' p a n e l ' , [25, 15 , 3 5 5 , 1 3 0 ] , ' Me s s a ge s ' ) ;
d lg .ms g Pn l . t i tl eS t = d l g . ms g Pn l . a d d ( ' s t a t i c tex t ' , [ 1 5 , 1 5 , 1 0 5 , 3 5 ] ,
' Al er t b ox t i tl e: ' );
d lg .ms g Pn l . ms g S t = d l g . ms g Pn l . a d d ( ' s t a t i c tex t ' , [ 1 5 , 6 5 , 1 0 5 , 8 5 ] ,
' Al er t messa g e: ' );
d lg .show();

The EditText element

EditText elements are typically used to provide a means for users to enter text to be supplied to the script when
the dialog is dismissed. Text in EditText elements can be selected by a user and copied from or pasted into. The
text property can be assigned to in order to display text in the element, and it can be read from to obtain the
current text value.
The textselection property can be assigned to in order to replace the current selection with new text, or to insert
text at the cursor (insertion point). It can be read from to obtain the current selection, if any.
Using the same panel pictured above, the example now adds some EditText elements, with initial values that
a user can accept or replace:
v ar d l g = n e w Win dow(' d i a l o g ' , ' Al er t B ox Bu i lder ' , [ 1 0 0 , 1 0 0 , 4 8 0 , 2 4 5 ] ) ;
d lg .ms g Pn l = d l g . a d d (' p a n e l ' , [25, 15 , 3 5 5 , 1 3 0 ] , ' Me s s a ge s ' ) ;
d lg .ms g Pn l . t i tl eS t = d l g . ms g Pn l . a d d ( ' s t a t i c tex t ' , [ 1 5 , 1 5 , 1 0 5 , 3 5 ] ,
' Al er t b ox t i tl e: ' );
d lg .ms g Pn l . t i tl eEt = d l g . ms g Pn l . a d d ( ' e d i t tex t ' , [ 1 1 5 , 1 5 , 3 1 5 , 3 5 ] , ' S a m p le Aler t ' ) ;
d lg .ms g Pn l . ms g S t = d l g . ms g Pn l . a d d ( ' s t a t i c tex t ' , [ 1 5 , 6 5 , 1 0 5 , 8 5 ] , ' Aler t m e s s a g e : ' ) ;
d lg .ms g Pn l . ms g Et = d l g . ms g Pn l . a d d ( ' e d i t tex t ' , [ 1 1 5 , 4 5 , 3 1 5 , 1 0 5 ] ,
' <yo u r messa g e here>' , {mu l t i l ine : t r u e } ) ;
d lg .show();

202
Creating User Interface Elements

203

Note the creation property on the second EditText field, where multiline:true is specified. multiline:true
indicates that the text in the item should wrap to the next page. In other words, it specifies a field in which a
long text string may be entered, and the text will wrap to appear as multiple lines.

The Button element

Button elements are typically used to initiate some action from a Window when a user clicks the mouse pointer
over the button; for example: accepting a dialog’s current settings, canceling a dialog, bringing up a new dialog
box, etc. The text property provides a label to identify a Button’s function:
v ar d l g = n e w W in d o w(' d i a l o g ' , ' A l e r t B o x B u i ld e r ' , [ 1 0 0 , 1 0 0 , 4 8 0 , 2 4 5 ] ) ;
d lg .b t n P n l = d l g . a d d (' p a n e l ' , [15, 50, 3 6 5 , 9 5 ] , ' B u i ld i t ' ) ;
d lg .b t n P n l . t estB t n = d l g . b t n P n l . a d d ( ' b u t t o n ' , [ 1 5 , 1 5 , 1 1 5 , 3 5 ] , ' Te s t ' ) ;
d lg .b t n Pn l . bu i l d B t n = d l g . b t n Pn l . a d d ( ' but ton ' , [ 1 2 5 , 1 5 , 2 2 5 , 3 5 ] ,
' Bu il d ' , {n a me: ' o k ' });
d lg .b t n Pn l . ca n ce l B t n = d l g . b t n Pn l . a d d ( ' but ton ' , [ 2 3 5 , 1 5 , 3 3 5 , 3 5 ] ,
' Ca n ce l ' , {n a me: ' ca n ce l ' });
d lg .show();

The Slider element

Slider elements are typically used to select within a range of values, allowing the user to hold the mouse pointer
down over a moveable position indicator on the slider and drag this indicator within the range of the slider.
If you click the mouse pointer on a point on the slider bar, the position indicator will jump to that location.
A Slider has a value property that reflects the position of the moveable indicator, and minvalue and maxvalue
properties to define the endpoints of the slider’s range of values.
To make a slider control appear like those used in After Effects, adjust the height of the control until the slider
bar appears as a single line.

The Scrollbar element

Scrollbar elements are similar to Slider elements, in that they are often used to select within a range of values,
and have a moveable position indicator. They have all the properties of sliders, and in addition, they have
‘stepper buttons’ at each end of the scrollbar for moving the position indicator in fixed-size steps.

203
Creating User Interface Elements

204

You can control the size of each ‘step’ by setting the stepdelta property. Clicking ahead of or behind the position
indicator makes the position indicator jump a fixed number of values toward the point where you clicked. You
can control the size of this jump by setting the jumpdelta property.
You can create scrollbars with horizontal or vertical orientation; if width is greater than height, the orientation
is horizontal, otherwise it is vertical. The following example creates a Scrollbar element with associated
StaticText and EditText elements within a panel:
d lg .si z eP n l = d l g . a d d (‘ p a n e l ’, [60, 240 , 3 2 0 , 3 1 5 ] , ‘ D i m e n s i o n s ’ ) ;
d lg .si z eP n l . w i d thS t = d l g . si z eP n l . a d d ( ‘ s t a t i c t e x t ’, [ 1 5 , 1 5 , 6 5 , 3 5 ] ,
‘ W i d th: ’;
d lg .si z eP n l . w i d thS cr l = d l g . si z eP n l . a d d ( ‘ s c r ol lb a r ’,
[75, 15, 195, 35], 300, 300, 800);
d lg .si zePn l . w i d thEt = d l g . sizePn l . a d d ( ‘e d i t tex t’, [ 2 0 5 , 1 5 , 2 4 5 , 3 5 ] ) ;

Note that the last 3 arguments to the add() method that creates the scrollbar define the values for the value,
minvalue and maxvalue properties. Scrollbars are often created with an associated EditText field to display the
current value of the scrollbar, and to allow setting the scrollbar’s position to a specific value.

Creating a window using window resource specifications

A specially formatted string provides a simple and compact means of creating a window and its component
elements as a resource specification. A resource specification allows you to define and configure multiple
window components in one easy-to-reference script.
The special string is passed as the type parameter to the Window constructor function, as follows:
// crea te a n e w d ia l o g from a reso u rce s p e c i fi c a t i on
v ar a l er tBu i l derReso u rce =
“d i a l o g { text: ‘Al er t B ox Bu il der ’, b ou n d s : [ 1 0 0 , 1 0 0 , 4 8 0 , 4 9 0 ] , \
ms g Pn l : Pa n e l { text: ‘Messa ge s’, b ou n d s : [ 2 5 , 1 5 , 3 5 5 , 1 3 0 ] , \
t i tl eS t: S ta t i cText { tex t : ’ Aler t b ox t i t le : ’, \
b o u n d s: [15, 15, 105 , 3 5 ] } , \
t i tl eEt: E d itText { text: ’S a mp l e Aler t’, b ou n d s : [ 1 1 5 , 1 5 , 3 1 5 , 3 5 ] } , \
ms g S t: S ta t i cText { text: ’Al er t m e s s a g e : ’, \
b o u n d s: [15, 65, 105, 85] }, \
ms g Et: E d i tText { text: ’<yo u r m e s s a g e h ere > ’, \
b o u n d s: [115, 45, 315, 10 5 ] , prop er t i e s : { mu lt i li n e : t r u e } } \
}, \
hasB t n sC b: Che ck b ox { text: ’Ha s a l er t but ton s ? ’, a li g n m en t : ’ cen ter ’, \
b o u n d s: [125, 1 4 5 , 2 5 5 , 1 6 5 ] } , \
aler tB t n sPn l : Pa n e l { text: ‘Button a l i g n m en t’, b ou n d s : [ 4 5 , 1 8 0 , 3 3 5 , 2 2 5 ] , \
a l ig n LeftR b: R a d i o Button { text: ’ Lef t’, b ou n d s : [ 1 5 , 1 5 , 9 5 , 3 5 ] } , \
a l ig n Cen terR b: R a d i o Button { tex t : ’ Cen ter ’, \
b o u n d s: [105, 15, 185, 35] }, \
a l ig n Ri g htR b: R a d i o Button { tex t : ’ R i g h t’, b ou n d s : [ 1 9 5 , 1 5 , 2 7 5 , 3 5 ] } \
}, \
sizePn l : Pa n e l { text: ‘D i men sion s’, b ou n d s : [ 6 0 , 2 4 0 , 3 2 0 , 3 1 5 ] , \
w i d thS t: S ta t i cText { text: ’Wid th : ’, b ou n d s : [ 1 5 , 1 5 , 6 5 , 3 5 ] } , \
w i d thS cr l : S cro l l ba r { mi nv a lu e: 3 0 0 , m a x v a lu e : 8 0 0 , \
b o u n d s: [75, 15 , 1 9 5 , 3 5 ] } , \
w id thEt: E d i tText { b o u n d s: [205 , 1 5 , 2 4 5 , 3 5 ] } , \
hei g htS t: S ta t icText { text: ’Hei g h t : ’, b ou n d s : [ 1 5 , 4 5 , 6 5 , 6 5 ] } , \
hei g htS cr l : S cro l l ba r { mi nv a lu e: 2 0 0 , m a x v a lu e : 6 0 0 , \
b o u n d s: [75, 45 , 1 9 5 , 6 5 ] } , \
heig htEt: E d itText { b o u n d s: [205 , 4 5 , 2 4 5 , 6 5 ] } \
}, \
b t n Pn l : Pa n e l { text: ‘Bu i l d it’, b o u n d s : [ 1 5 , 3 3 0 , 3 6 5 , 3 7 5 ] , \
testB t n : Button { text: ’Test’, b o un d s : [ 1 5 , 1 5 , 1 1 5 , 3 5 ] } , \
bu i l d B t n : Button { text: ’Bu il d ’, b ou n d s : [ 1 2 5 , 1 5 , 2 2 5 , 3 5 ] , \
prop er t ies: {n am e : ’ ok’ } } , \

204
Creating User Interface Elements

205

ca n c e l B t n : B u tt o n { t e xt: ’C a n c e l ’, b ou n d s : [ 2 3 5 , 1 5 , 3 3 5 , 3 5 ] , \
p r o p e r t ies: {n am e : ’ c a n c e l’ } } \
} \
} ”;
d lg = n e w W in d o w (a l e r tB u i l d e rR eso u r c e ) ;

The general structure of a window resource specification is a Window type specification (i.e., “dialog”),
followed by a set of braces enclosing one or more property definitions. Controls are defined as properties
within windows and other containers by specifying the classname of the control in a property definition, with
properties of the control enclosed in braces {}, for example: testBtn: Button { text: ‘Test’ }.
Creation properties are specified in a properties property as named properties of an inline object (see example
above). The syntax of window resource specification strings is completely described below.

Window resource specification syntax

The window resource specification syntax is given in BNF (Backus-Naur Form) below:
r e s o u rce S p e c = ‘ ” ’ w i n d ow Ty p e Na m e i n l i n e O b j e c t ‘ ” ’
w i n d owTy p e Na m e = [a modal dialog]
in lin eO bj ect = “ {“ p ro p er ti es L i s t “ } ”
proper tiesList = proper t y De fn { “,” proper t yDefn }
proper t y Defn = proper t y Name “:” proper t yValue
proper t yName = [a JavaScr ipt proper t y name]
proper t y Value = “null” | “t r u e” | “false” | st r ing | number
| i n l i n e Ar r ay | o b j e c t D e f n
st r ing = [a JavaScr ipt st r ing liter al]
number = [any JavaScr ipt integer or real number liter al]
inlineAr r ay = “[“ proper t y Va lue { “,” proper t yVa lue } “]”
objectDefn = ( namedObject | inlineObject )
namedObject = [ a ny o b j e c t c l a s s n a m e ] i n l i n e O b j e c t

Note: To create a UI element, the classname in the namedObject definition above can be any element classname
referred to in “Types of interface elements” on page 198. For example:
“d i a l o g { \
tex t : ‘ From Re s o u rce’, b o u n d s : [ 1 0 , 1 0 , 2 1 0 , 1 1 0 ] , \
b ox : Pa n e l { \
bounds: [10, 10, 190, 90], \
o k : But to n { \
tex t : ‘O K ’, b o u n d s : [ 4 0 , 3 0 , 1 4 0 , 5 0 ] , \
} \
} \
}” ;

Interacting with controls: events and event callbacks

When a script creates a window, it typically adds control elements to the window that a user can manipulate,
for instance, by clicking a button, entering text in a text box, moving a scrollbar, etc.
These user actions or manipulations generate events within the user interface system. The script that creates a
window needs a way to be notified of events from that window or from controls within the window. The
scripting user interface provides a number of event callback methods that a script can define as properties of
any UI element that the script needs to interact with.

205
Creating User Interface Elements

206

Each class of UI element has a set of callback methods defined for it. For windows, there are callbacks like
onClose(), onMove(), and onResize(). For controls, callbacks vary from type to type. A typical callback is
onClick() for button, radiobutton, and checkbox elements, and onChange() for edittext fields, scrollbars, and
sliders.
To handle a given event for some UI element, simply define a property of the same name as the event callback
in the element and assign a JavaScript function you have defined to it. The example below uses "in line"
functions, which employ a unique syntax and do not require a name. However, you can also define the
function elsewhere in the script. In that case, simply assign the name of the function to the event handler
property. The scripting user interface calls these functions on event notifications if defined.
Examples:
/* ‘ ha s b u tt o n s ’ c he c k b o x e n a b l es o r d i s a b le s t h e p a n e l t h a t
d e t e r mi n es the j u st ifi ca t io n o f t h e ‘ a le r t ’ b u t t o n g r ou p * /
d lg .ha sB t n sC b . o n C l ic k =
fu n c t i o n () { thi s. p a r e n t. a l e r tB t n s P n l. en a ble d = t h i s . v a lu e ; } ;

// T he Bu i l d a n d Ca n ce l button s cl o se t h i s d i a lo g
w it h (d l g . b t n Pn l ) {
bu i l d B t n . on Cl i ck =
fu n c t i on () { thi s. p a ren t. p a ren t . clos e ( 1 ) ; } ;
ca n ce l B t n . on Cl i ck =
fu n c t i on () { thi s. p a ren t. p a ren t . clos e ( 2 ) ; } ;
};
Because event callback functions work as methods of the object in which they are defined, the functions have
access to the object via the “this” JavaScript keyword. In the examples above, “this” refers to the UI object a
given callback is defined in, so properties of the UI object can be accessed relative to the “this”. For example,
because each UI object has a parent property which is a reference to its container object, this.parent gets you a
reference to the object’s parent object.
To elaborate further on this point, a button( ) is contained within a panel, which is contained within a window,
all of which are ultimately closed. The progression is from smaller to larger UI moving from left to right.
buildBtn.onClick = function () {this.parent.parent.close(1);};

button

panel

dialog

Also be aware that you can simulate user actions by sending an event notification directly to a UI element, via
the element’s notify() method. In this manner, a script can generate events in the controls of a window, as if a
user was clicking buttons, entering text, moving a window, etc.
radiobutton and checkbox elements have a boolean value property; using notify() to simulate a click on these
elements also changes the value of this property, just like clicking the element would do. For instance, if the
value of a checkbox ‘hasBtnsCb’ in our example above is true, the following example changes the value to false:
if ( d l g . ha sB t n sC b. v a lu e == t r u e)
d l g . ha sB t n sC b. n o t i fy ();
// d l g . ha sB t n sC b. v a lu e is n ow fa l se

For a complete description of the different event callback methods and notify(), see “Common methods and
event handlers” on page 218.

206
Creating User Interface Elements

207

Modal dialogs
A modal dialog is initially invisible. When calling its show() method, the dialog is displayed and starts
executing. The call to show() does not return until the dialog has been dismissed, typically by the user clicking
an OK or Cancel button.
When calling the hide() or close() methods during the execution of a modal dialog, the dialog is dismissed.
The close() method accepts an optional argument that the call to show() returns.
Warning: You cannot use the JavaScript Debugger to debug event callback functions for modal dialogs, because
once the dialog starts executing, it captures all mouse events. Setting a breakpoint in an event callback function for
a modal dialog will result in an apparent application hang if the breakpoint is ever reached.
To work around this restriction, an effective debugging technique is to create your dialog, but not call its show()
method to make it visible. Then use the debugger to call the notify() method on controls whose event callback
functions you wish to debug. It’s considered good design practice to keep the code in the event callback functions
simple, while deferring the primary script logic execution until after the dialog has been dismissed.

Default and Cancel elements

Modal dialogs can usually be dismissed by typing certain keyboard shortcuts. In addition to clicking the ‘OK’
or ‘Cancel’ buttons, typing the ‘Enter’ key normally produces the same results as clicking the ‘OK’ (or default)
button, and typing the ‘Esc’ key is equivalent to clicking the ‘Cancel’ button. In each case, the keyboard
shortcut is the same as if your script had called the notify() method for the associated Button. The dialog
designer has explicit control over which Button elements are notified by these keyboard shortcuts: a newly-
created dialog has defaultElement and cancelElement properties that are initially undefined. The dialog
designer can set these properties to the objects representing the buttons that should be notified when the
respective keyboard shortcut is typed.
The scripting user interface provides reasonable defaults if the defaultElement and cancelElement properties
are still undefined when the dialog is about to be shown for the first time.
Default values for the defaultElement property are determined by the following algorithm:
• The scripting user interface searches the dialog’s buttons for a button whose name property has the string
value “ok” (case is not important). If one is found, defaultElement is set to that object.
• If no matching named object is found, the scripting user interface searches the dialog’s buttons for a button
whose text property has the string value “ok” (case is not important). If one is found, defaultElement is set
to that object.
Default value for the cancelElement property are determined by the following algorithm:
• The scripting user interface searches the dialog’s buttons for a button whose name property has the string
value “cancel” (case is not important). If one is found, cancelElement is set to that object.
• If no matching named object is found, the scripting user interface searches the dialog’s buttons for a button
whose text property has the string value “cancel” (case is not important). If one is found, cancelElement is
set to that object.
These algorithms handle most dialog boxes without the designer having to explicitly set these properties.
When you add buttons to a dialog that will be used to dismiss the dialog, use creation properties to set the name
property of such buttons to ‘ok’ or ‘cancel’, depending on the desired semantics; this precaution makes the
above algorithm work properly even when the text of such buttons is localized. If the scripting user interface
cannot find a matching button for either case, the respective property is set to null, which means that keyboard
shortcuts for default or cancel will not notify any elements.

207
Creating User Interface Elements

208

Guidelines for creating and using modal dialogs

When your script creates a dialog, you typically create controls that the user must interact with in order to
enter values that your script will use. In general, you can minimize the number of event callback functions you
attach to various controls in your dialogs, unless interaction with those controls changes the operation of the
dialog itself. In most cases where you simply want to read the states of various controls when the dialog is
dismissed, you do not need to handle events for them. For instance, you often don’t need onClick() functions
for every checkbox and radiobutton in your dialog: when the dialog is dismissed, read their states using their
value properties.
Some exceptions to this guideline:
• onChange() functions are needed for edittext elements, if users enter values which must be validated (like a
number within a range). The event callback must perform any necessary validation, and interact with the
user on errors.
• Define onClick() for OK and Cancel buttons which close the dialog with a given value.
Note: Perform this function only if you have not defined the defaultElement and/or cancelElement properties or
named these buttons in such a way that they will automatically be identified as the OK and Cancel buttons.

Prompts and Alerts

Some JavaScript environments provide functions on the global window object to display message boxes or
alert boxes and a prompt box that displays one or two lines of text and then allows the user to enter one line
of text.
The scripting user interface defines functions alert(), confirm() and prompt() on the Window class that
provides this standard functionality. The host application controls the appearance of these simple dialog
boxes, so they are consistent with other alert and message boxes displayed by the application. See the “JavaS-
cript UI reference” on page 214 for details.

JavaScript UI example
Having explored the individual scripting components that make up the user interface, you are now ready to
see the parts assembled into real-world JavaScript code that produces a fully functional user interface.
The JavaScript UI code sample described below includes the following functions, which creates a simple user
interface builder window populated with various panels, checkboxes, buttons and controls. When you run the
builder, you can then cause it to create an Alert Box.
• createBuilderDialog() -- Creates an empty dialog window near the upper left of the screen and adds a title
panel, a checkbox, a control panel and a panel with buttons to test parameters and create the Alert Box
specification.
• initializeBuilder() --Sets up initial control states and attaches event callback functions to controls.
• runBuilder() -- Runs the builder dialog and returns the resulting Alert Box UI
• createResource() -- Creates and returns a string containing a dialog resource specification that creates the
Alert Box UI using the parameters entered
• stringProperty() -- Returns a formatted string
• arrayProperty() -- Returns a formatted array
• createTestDialog() -- Creates a new Test dialog
These functions are bundled together into a Main script, which assembles the final Alert Box dialog.

208
Creating User Interface Elements

209

createBuilderDialog
Most of the heavy-lifting for visual components of the JavaScript UI code sample occurs in the createBuilder-
Dialog() function, where the main components of the dialog are configured, as displayed below.
f u n c t i on c rea teBui lder D i a lo g()
{
/ /Cre a te a n emp t y di a lo g w i ndow nea r th e u pp er left of the scre en
v ar d lg = new Wi ndow(' di a lo g' , ' Aler t B ox Bu ilder', [ 100,100,480,490] ) ;
1
/ /Ad d a pa ne l to h old t i tle a nd ' messa ge text' st r ing s
d l g . m s gPnl = d lg .a dd(' pa ne l' , [2 5 ,1 5 ,3 5 5 ,130] , 'Messages') ;
d l g . m s gPnl.t i tleS t = d lg .ms gPnl.a dd(' s ta t i c text', [ 15,15,105,35] , 'Aler t b ox t itle:') ;
d l g . m s gPnl.t i tleEt = d lg .ms gPnl.a dd(' e di ttext', [ 115,15,315,35] , 'S am ple Aler t') ;
d l g . m s gPnl.ms gS t = d lg .ms gPnl.a dd(' s ta t i c text', [ 15,65,105,85] , 'Aler t m essage:') ;
d l g . m s gPnl.ms gEt = d lg .ms gPnl.a dd(' e di ttext', [ 115,45,315,105] , '<you r m essage here>',
{ mu l t i li ne:t r ue});

/ /Ad d a ch e ckb ox to cont rol th e pres ence of buttons to dism iss the aler t b ox
d l g . h a s Bt ns Cb = d lg .a dd(' ch e ckb ox ' , [125,145,255,165] , 'Has aler t buttons?') ; 2
/ /Ad d pa ne l to de ter mi ne a li g nment of buttons on the aler t b ox
d l g . aler tBt ns Pnl = d lg .a dd(' pa ne l' , [45,180,335,225] , 'Button alig nm ent') ;
d l g . aler tBt ns Pnl.a li g nLeftRb = d lg .a ler tBt nsPnl.a dd( 'r a diobutton', [ 15,15,95,35] , 'Left') ;
d l g . aler tBt ns Pnl.a li g nCenter Rb = d lg .a ler tB t nsPnl.a dd( 'r a diobutton', [ 105,15,185,35] , 'Center') ;
d l g . aler tBt ns Pnl.a li g nRi g h tRb = d lg .a ler tBt nsPnl.a dd( 'r a diobutton', [ 195,15,275,35] , 'Rig ht') ;

/ /Ad d a pa ne l w i th cont rols for th e di mensions of the aler t b ox

d l g . s izePnl = d lg .a dd(' pa ne l' , [60,240,320,315] , 'D im ensions') ;
d l g . s izePnl.w i dth S t = d lg .si zePnl.a dd(' s ta t ic text', [ 15,15,65,35] , 'Width:') ;
d l g . s izePnl.w i dth S cr l = d lg .si zePnl.a dd(' s cro l lbar', [ 75,15,195,35] , 300, 300, 800) ;
d l g . s izePnl.w i dth Et = d lg .s i zePnl.a dd(' e di ttext', [ 205,15,245,35] ) ;
d l g . s izePnl.h ei g h tS t = d lg .si zePnl.a dd(' stat ic text', [ 15,45,65,65] , 'Heig ht:') ;
3
d l g . s izePnl.h ei g h tS cr l = d lg .s i zePnl.a dd(' sc rol lbar', [ 75,45,195,65] , 200, 200, 600) ;
d l g . s izePnl.h ei g h tEt = d lg .s i zePnl.a dd(' e dittext', [ 205,45,245,65] ) ;

/ /Ad d a pa ne l w i th buttons to test pa r a me ters and c reate the aler t b ox sp e c ific at ion
d l g . b t nPnl = d lg .a dd(' pa ne l' , [15,330,365,375] , 'Bu ild it') ;
d l g . b t nPnl.tes tBt n = d lg .b t nPnl.a dd(' button', [ 15,15,115,35] , 'Test') ;
d l g . b t nPnl.bui ldBt n = d lg .b t nPnl.a dd(' button', [ 125,15,225,35] , 'Bu ild', { nam e:'ok'} ) ;
4
d l g . b t nPnl.ca nce lBt n = d lg .b t nPnl.a dd(' button', [ 235,15,335,35] , 'Cance l', { nam e:'c ance l'} ) ;

re tu r n d lg;

/ / c re ate Bu i lder D i a lo g

209
Creating User Interface Elements

210

This code snippet, when broken down into smaller segments--and run in the context of the entire UI sample
code that follows--produces the following succession of dialogs, which coalesce into one final Alert Box
window.

Final Dialog
Created

For the final dialog to actually display, supporting code to initialize and run the Alert Box Builder must be
included, as illustrated below.
functio n i ni t i a li z eB ui ld e r (b ui ld e r )
{
// S e t up i ni t i a l c o nt r ol s ta t es
w i th (b ui ld e r ) {
h a sBt ns Cb .v a l ue = t r ue;
a le r tBt ns P nl.a li g nC e nt e r Rb .v a l u e = t r u e;
w i th (si z eP nl) {
w i dth E t.t e x t = w i dth S cr l. v al u e;
h e i g h tE t.t e x t = h e i g h tS cr l.v al u e;
}

210
Creating User Interface Elements

211

// A tta c h e v e nt ca l lb a c k func t i o ns t o c o nt r o ls

/* ' h a s b u tt o ns ' c h e c kb o x e na b les o r disab les the pane l that

d e t e r mi nes th e j ust i fi ca t i o n o f the 'ale r t' b u tt o n g r ou p */

b ui ld e r .h a s Bt ns Cb .o nC li c k =
func t i o n () { th i s .pa r e nt.a le r tB t nsP nl.e nab le d = this.v al u e; } ;

/T h e e di ttex t fie lds a nd s crol lb a rs i n sizePnl are conne c te d /

w i th (bui lder.si zePnl) {
w i dth Et.onCh a nge =
func t i on () { th i s .pa rent.w idthSc r l.v alu e = this.text; } ;
w i dth S cr l.onCh a nge =
func t i on () { th i s .pa rent.w idthEt.text = this.v alu e; } ;
h ei g h tEt.onCh a nge =
func t i on () { th i s .pa rent.heig htSc r l.v alu e = this.text; } ;
h ei g h tS cr l.onCh a nge =
func t i on () { th i s .pa rent.heig htEt.text = this.v alu e; } ;
}

w i th (bui lder.b t nPnl) {

//T h e Tes t button crea tes a t r i a l Aler t b ox from the c u r rent sp e c ific at ions
testBt n.onCli ck =
func t i on () {
Wi ndow.a ler t(' Ty p e Enter or Esc to dism iss the test Aler t b ox') ;
crea teTes tD i a lo g(cre ateResou rce( this.parent.parent) ) ;
};

//T h e Bui ld a nd Ca nce l buttons clo se this dialo g

bui ldBt n.onCli ck =
func t i on () { th i s.pa rent.parent.close( 1) ; } ;
ca nce lBt n.onCli ck =
func t i on () { th i s.pa rent.parent.close( 2) ; } ;
};
} / / ini t i a li zeBui lder

f u n c t i on r unBui lder (bui lder )

{
//Run th e bui lder di a lo g , re tur n i ts resu lt
re tur n bui lder.s h ow();
}

/ *T hi s func t i on crea tes a nd re tur ns a s t r i n g containing a dialog

re s o u rce sp e ci fica t i on th a t w i l l crea te a n Aler t dialo g u sing
t h e pa r a me ters th e us er entere d. */

f u n c t i on crea teResource(bui lder )

{
//D efine th e i ni t i a l pa r t of the resource sp e c w ith dialo g par am e ters
v a r d lgWi dth = Numb er (bui lder.si zePnl.w idthEt.text) ;
v a r d lgHei g h t = Numb er (bui lder.si zePnl.heig htEt.text) ;
v a r res = " di a lo g { " +
s t r i ngProp er t y (" tex t" , bui lder.m s gPnl.t itleEt.text) +
a r r ay Prop er t y (" b ounds" , 0, 0, d lgWidth, d lgHeig ht) +
" \n" ;

//D efine th e a ler t mes s a ge sta t i c tex t e lem ent, s i z i n g i t to the aler t b ox
v a r ma r g i n = 1 5 ; v a r l, t;
v a r ms gWi dth , ms gHei g h t;
v a r h a s Buttons = bui lder.h a sBt ns Cb. v alu e;
v a r b t nsHei g h tUs e d = h a s Buttons ? 20 + m arg in : 0 ;
ms gHei g h t = 6 0 ;
ms gWi dth = d lgWi dth - (ma r g i n * 2) ;

l = ma r g i n;
t = (d lgHei g h t - ms gHei g h t - b t ns Heig htUse d) / 2;
re s + = " m s g: S t a t i cTex t { " +
s t r i ngProp er t y (" tex t" , bui lder.m s gPnl.m s gEt.text) +
a r r ay Prop er t y (" b ounds" , l, t, l + m s gWidth, t + m s gHeig ht) +
" jus t i fy :' center ' , prop er t i es :{mult iline:t r u e} } ";

//D efine buttons i f desi re d

i f (h a s Buttons) {
v a r b t nWi dth = 9 0 ;
//Ali g n buttons a s sp e ci fie d
w i th (bui lder.a ler tBt ns Pnl) {
i f (a li g nLeftRb.v a lue)

211
Creating User Interface Elements

212

l = ma r g i n;
e ls e i f (a li g nC e nt e r Rb .v a l u e)
l = (d lgW i dth - (b t nW idth * 2 + 10) ) / 2;
e lse
l = d lgW i dth - ((b t nW idth * 2 + 10) + m arg in) ;
}
t = d lgH e i g h t - b t ns H e i g h tU s e d;
r es + = " ,\n" +
" o k B t n: B u tt o n { " +
s t r i ngP r o p e r t y (" t e x t" , " OK") +
a r r a y P r o p e r t y (" b ounds " , l , t, l + b t nW idth, t + 20) +
" },\n" ;
l + = b t nWi dth + 1 0 ;
re s + = " c a n ce lBt n: Button { " +
s t r i ngProp er t y (" tex t" , " Cance l") +
a r r ay Prop er t y (" b ounds " , l , t, l + b t nWidth, t + 20) +
" }" ;
}

// Al l done!
res + = " \n}" ;
re tur n res ;
}

f u n c t i on s t r i ngProp er t y (pna me, pv a l)

{
re tur n pna me + " :' " + pva l + " ' , " ;
}

f u n c t i on a r r ay Prop er t y (pna me, l, t, r, b )

{
re tur n pna me + " :[" + l + " ," + t + " , " + r + "," + b + "] , " ;
}

f u n c t i on crea teTestD i a lo g(resource)

{
v a r ta r ge t = new Wi ndow (resource) ;
re tur n ta r ge t.s h ow();
}

/ / ------------- Ma i n scr i p t -------------//

v ar bui lder = crea teBui lder D i a lo g();
i n i t i a li zeBui lder (bui lder );
i f ( r u nBui lder (bui lder ) = = 1 ) {
//Crea te th e Aler t di a lo g res ource s p e c ific at ion st r ing
v a r resS p e c = crea teResource(bui lder) ;
//Wr i te th e resource sp e ci fica t i on s t r ing to a file, u s i n g t h e s t a n d a rd file op en dialo g
v a r fna me = F i le.op enD i a lo g(' S ave resou rce sp e c ific at ion') ;
v a r f = F i le(fna me);
i f (f.op en(' w' )) {
v a r ok = f.w r i te(res S p e c);
i f (ok)
ok = f.close();
i f (! ok)
Wi ndow.a ler t(" Er ror crea t ing " + fnam e + ": " + f . er ror) ;
}
}

Sample code summary

This sample code is used to demonstrate some practical applications of the scripting interface. Here a few of
the major intentions of the script:
• To provide a simple real-world example of creating a user interface with multiple components and controls.
• To show how certain controls such as sliders and edit text boxes can interact.
• To show how radio buttons work and how to set radio buttons to true and initialize them.
• To show a multi-line text edit box as displayed in the messages panel of the dialog box.
• To show how you can associate static text fields with edit text fields and static text with other types of
controls.

212
Creating User Interface Elements

213

• To show how simple event callback functions work and how you can attach event handler functions to any
controls that can generate events.
• To show how to enable and disable sets of controls. For example, in the alert checkbox,
if you unclick the checkbox then everything in the button alignment field suddenly gets greyed out.
• To demonstrate how you typically dismiss a modal dialog by providing an OK and Cancel button.
• To show you can still read property values out of the dialog and its controls after the dialog has been
dismissed.

Resource-specification sample code

To run this JavaScript UI code using a resource specification, change the lines indicated below and include the
resource specification sample code. For more information on resource specifications, refer to “Creating a
window using window resource specifications” on page 204.
Note: This is a complete example of a resource specification string. The alertBuilderResource() code displayed
below is a way to create the same main dialog box created by the createBuilderDialog() function.

213
Creating User Interface Elements

214

/ / ------------- A lt e r na t e di a lo g cr ea t i o n u sing r esou r c e sp e c ifi c at io n -------------//

/*
To us e th i s c o d e, r e pla c e th e li ne a b o v e that sa y s
v a r b ui ld e r = cr ea t eB ui ld e r D i a lo g();
w i th
v a r b ui ld e r = cr ea t eB ui ld e r D i a lo gF r o m R eso u r c e( ) ;
*/

v ar a le r tB ui ld e r R esour c e =
" di a lo g { t e x t: ' Aler t B ox Bui lder ' , b ou nds:[ 100,100,480,490] , \
ms gPnl: Pa ne l { tex t: ' Mes s a ges', b o u nds:[ 25,15,355,130] , \
t i tleS t:S ta t i cTex t { tex t:'Aler t b ox t itle:', b ou nds:[ 15,15,105,35] } , \
t i tleEt:Edi tTex t { tex t:' S am ple Aler t', b o u nds:[ 115,15,315,35] } , \
ms gS t: S ta t i cTex t { tex t :'Aler t m essage:', b o u nds:[ 15,65,105,85] } , \
ms gEt: E di tTex t { tex t:'<you r m essage here>', b o u nds:[ 115,45,315,105] ,
prop er t i es:{mult i li ne:t r u e} } \
}, \
h a sBt ns Cb : Ch e ckb ox { tex t:' Has aler t buttons?', alig nm ent:'center',
b ounds :[125,145,255,165] } , \
a ler tBt ns Pnl: Pa ne l { tex t:' Button alig nm ent', b ou nds:[ 45,180,335,225] , \
a li g nLeftRb :R a di oButton { text:'Left', b ou nds:[ 15,15,95,35] } , \
a li g nCenter Rb :R a di oButton { text:'Center', b o u nds:[ 105,15,185,35] } , \
a li g nRi g h tRb :R a di oButton { text:'Rig ht', b ou nds:[ 195,15,275,35] } \
}, \
s i zePnl: Pa ne l { tex t: ' D i mensi ons', b ou nds:[ 60,240,320,315] , \
w i dth S t:S ta t i cTex t { tex t: 'Width:', b ou nds:[ 15,15,65,35] } , \
w i dth S cr l:S crol lb a r { mi nv alu e:300, m axv alu e:800, b o u nds:[ 75,15,195,35] } , \
w i dth Et:Edi tTex t { b ounds:[ 205,15,245,35] } , \
h ei g h tS t:S ta t i cTex t { tex t:'Heig ht:', b o u nds:[ 15,45,65,65] } , \
h ei g h tS cr l:S crol lb a r { mi nv alu e:200, m axv alu e:600, b o u nds:[ 75,45,195,65] } , \
h ei g h tEt:Edi tTex t { b ounds:[ 205,45,245,65] } \
}, \
b t nPnl: Pa ne l { tex t: ' Bui ld i t' , b o u nds:[ 15,330,365,375] , \
testBt n: Button { tex t:' Test' , b o u nds:[ 15,15,115,35] } , \
bui ldBt n:Button { tex t:' Bui ld' , b o u nds:[ 125,15,225,35] , prop er t ies:{ nam e:'o k'} } , \
ca nce lBt n:Button { tex t:' Ca nce l', b o u nds:[ 235,15,335,35] , prop er t ies:{ nam e:'c ance l'} } \
} \
}";

f u n c t i on crea teBui lder D i a lo gFromRes ource( )

{
//Crea te from resource
re tur n new Wi ndow(a ler tBui lder Reso u rce) ;
} / / c rea teBui lder D i a lo gFromResource

JavaScript UI reference
The JavaScript user interface defines the global elements of the Window object and properties and methods
of all the UI classes.

Global elements of the Window object

The following functions are class methods of the global Window class only; windows created via new Window()
do not have these functions defined.
To call class methods, use the following example syntax: Window.alert("Class method!");

aler t (text)
Displays the specified string in a user alert box that provides an OK button. The alert dialog is not intended
for lengthy messages. When the string argument to the alert method is too long, the alert dialog truncates it.
confir m (text)
Displays the specified string in a self-sizing modal dialog box that provides Yes (default) and No buttons.
When this user clicks one of these buttons, this method hides the dialog and returns a value indicating the
button the user clicked to dismiss the dialog. A return value of true indicates that the user clicked the Yes
button to dismiss the confirm box. The confirmation dialog displays lengthier messages than the alert and
prompt dialogs do, but if this string is too long, the dialog truncates it.

214
Creating User Interface Elements

215

fi n d ( t y p e , t i t l e )
return value: Object
Finds an existing window already created by a script. title is the title of the window and type is modal dialog.
This value is a hint in case more than one window has the same title; if the type is unimportant, null or an
empty string can be passed. If the window was found, the corresponding JavaScript Window object is
generated and returned; if the window cannot be determined, the return value is null.
p rompt (prompt [, default])
Displays a modal dialog that returns the user’s text input. When the dialog opens, it displays the given prompt
text and its text edit field is initialized with any specified default text. When the user clicks OK to dismiss the
dialog, it returns the text the user entered. If the user clicks the Cancel button in this dialog, this method’s
result is the value null.

Common object properties

The following table shows the common properties defined for each element type.

RadioButton
StaticText

Checkbox

Scrollbar
Window

EditText

Button

Slider
Panel

active x x x x x x x

bounds x x x x x x x x x

children x x x x x x x x x

enabled x x x x x x x x x

jumpdelta x

justify x x x x x x x

maxvalue x x

minvalue x x

parent x x x x x x x x x

stepdelta x

text x x x x x x x

textselection x

type x x x x x x x x x

value x x x x

visible x x x x x x x x x

215
Creating User Interface Elements

216

Properties

Following are the properties defined for each element types listed above.
Property Type Description
active Boolean Contains true if the object is active, false otherwise. An active floating dialog
is the front-most dialog. A modal dialog that is visible is by definition the
active dialog. An active control is the one which will accept keystrokes, or in
the case of a Button, be activated (clicked) when the user types a return. Set
this true to make a given control or dialog active.
bounds Bounds Contains a Bounds object describing the location and size of the element as
array values representing the coordinates of the upper left and lower right
corners of the element: [left, top, right, bottom]. These are screen coordinates
for window elements, and window-relative coordinates for other elements.
See “Element Size and Location “

for a definition of the Bounds object.

children Object The collection of UI elements that the UI object contains. This is an array
indexed by number or by a string containing an element’s name. The length
property of this array is the number of child elements for container elements
and is zero for controls; future implementations may return additional ele-
ments for composite controls. Read only.
enabled Boolean Contains true if the object is enabled, false otherwise. If set to true, control
elements will accept input. If set to false, control elements will not accept
input, and all types of elements may change to a ‘grayed-out’ appearance.
jumpdelta Number Contains the value to increment or decrement a Scrollbar element’s position
by, when the user clicks ahead or behind the moveable element of the Scroll-
bar to make the scroll position ‘jump’.
justify String Controls justification of text in static text and edit text controls. The value is
either “left”, “center”, or “right” and the default value is left-justified. Some
implementations may not fully support this property, and it may be ignored
for some types of controls.
maxvalue Number Contains the maximum value that the value property can have. If maxvalue
is reset less than value, value will be reset to maxvalue. If maxvalue is reset less
than minvalue, minvalue will be reset to maxvalue.
minvalue Number Contains the minimum value that the value property can have. If minvalue is
reset greater than value, value will be reset to minvalue. If minvalue is reset
greater than maxvalue, maxvalue will be reset to minvalue.
parent Object The parent object of a UI object. This property returns null for window
objects. Read only.
placement Bounds An alternate name for the bounds property; bounds is the preferred name,
and use of placement is deprecated.
stepdelta Number Contains the value to increment or decrement a Scrollbar element’s position
by, when a stepper button at either end of the scrollbar is clicked.
text String The title, label or text. May be ignored for certain window types. For controls,
its usage depends on the control type. Many controls like buttons use the
text as a label, while other controls, such as edit fields, use the text to access
its content.
textselection String Replace the current text selection with the specified text string, modifying
the value of the text property. If there is no selection, the specified text is
inserted into the text property string at the current insertion point. Reading
the textselection property returns any selected text, or an empty string if
there is no selection.
type String Contains the type name of the element. For Window objects, this is the value
of the first argument to the Window constructor function. For controls, this is
the value of the first argument to the add() method. Read only.
value Boolean (for Checkbox and RadioButton) true if the control has been set (i.e., a check-
box shows a check mark), false if not set.

216
Creating User Interface Elements

217

Property Type Description

value Number (for Scrollbar and Slider) the value of the control, for instance, the position of
the moveable part of a Scrollbar or Slider. If value is reset outside the
bounded range minvalue, maxvalue, value is set to the closest boundary.
visible Boolean Contains true if the object is physically visible, false otherwise. If set to false,
the UI object is hidden, and if set to true, the object is made visible.

Properties found only in Window elements

Window elements contain the following properties, in addition to those described in the previous section.
d efaultElement -- O b j ec t
The element to notify when a user types the Enter key, with the intent to dismiss the dialog as if the “OK”
button had been clicked.
can c elElement -- O b j ec t
The element to notify when a user types the Esc key (or the <Cmd .> combination on a Mac), with the intent
to dismiss the dialog as if the “Cancel” button had been clicked.

Objects used as property values

The values of certain properties are represented by objects that the scripting interface defines. This section
describes those objects. It includes a description of their semantics, ways to create them, and descriptions of
their properties.

The Bounds Object

A Bounds object is used to define the boundaries of a Window or UI element within its coordinate space. You
cannot directly create a Bounds object; one is created when you set an element’s bounds property. Reading the
bounds property always yields a Bounds object. Bounds contains an array describing the position and size of a
UI element. The array values represent the coordinates of the upper left and lower right corners of the element:
[left, top, right, bottom]. These are screen coordinates for window elements, and are relative to the coordinate
space of the parent (container) element for other element types.
You can set an element’s bounds property and indirectly create a Bounds object in any of these ways:
e.b ou n d s = O b j ec t
The object must contain properties named left, top, right, bottom, or x, y, width, height, where each property
has an integer coordinate value.
e.b ou n d s = Ar ray
The array must have integer coordinate values in the order [left, top, right, bottom].
e.b ou n d s = St r i n g
The string must be an executable JavaScript inline object declaration, containing the same property names as
in the object case just described.
See “Element size and location” on page 199 for examples.
A Bounds object may be accessed as an array. In addition, it supports the following properties
Property Type Description
left Number The ‘x’ coordinate value of the left edge of the element.
top Number The ‘y’ coordinate value of the top edge of the element.
r ig ht Number The ‘x’ coordinate value of the right edge of the element.
b ottom Number The ‘y coordinate value of the bottom edge of the element.
x Number Same as left.

217
Creating User Interface Elements

218

Property Type Description

y Number Same as top.
w idt h Number right - left.
h e ig ht Number bottom - top.

Common methods and event handlers

Following are the common methods and event handlers defined for each element type.

RadioButton
StaticText

Checkbox

Scrollbar
Window

EditText

Button

Slider
Panel

add() x x
center() x
close() x
hide() x x x x x x x x x
notify() x x x x x x
show() x x x x x x x x x
onChange() x x x
onClick() x x x
onClose() x
onMove() x
onResize() x

Methods

Descriptions of the common methods and event handlers listed above follow:
Method Returns Description
add (type [, bounds, text, { Object Creates a new UI element and add it to the children
<creation array of its parent Window or Panel element. The
optional parameter bounds is a Bounds object
properties> } ]); describing its position and size. This may also be a
four-element array. The optional parameter text is
assigned to the UI element as the initial text or title.
The UI element itself decides how to use this string; it
may be ignored.

In general, a Button uses the text as its label, while a

edit field uses it as its initial content. Internally, the
text is assigned to the text property of the element.
The optional parameter <creation properties> is an
object with properties that specify attributes of the
UI element that are used only when the element is
created. <creation properties> are specific to the type
of UI element, and are described below in the sec-
tions for each element type. The return value is the
newly created UI element or null on errors.
center([window]) no return value Centers a Window on screen, or optionally, within the
specified window object.
close ([value]) no return value Closes a Window. For modal dialogs, the optional
value is returned as the result of the show() call that
caused the dialog to display and execute.

218
Creating User Interface Elements

219

Method Returns Description

hide() no return value Hides the element. If hide() is called on a modal dia-
log, dismiss the dialog and set the dialog result to 0.
The application may choose to ignore this call for cer-
tain UI object types.

notify([event]) no return value Sends a notification message to whatever listens to

the UI object. notify() effectively lets you control a
dialog programmatically. Calling this method with
no argument on a control simulates the activation of
the control; a Button signals that it has been clicked
via its onClick() method, an EditText element tells its
listener that it contents have changed via its
onChange() method, and so on. You can supply an
optional argument to notify(), which is the name of
the event handler to call. For instance, to simulate a
dialog dlg being moved by a user, you can send a
notification message as follows: dlg.notify(“onMove”).

show() Number Displays the UI object. A Window may choose to

ignore the setting of the visibility state if it is not
applicable, like for inspectors whose visibility is con-
trolled by the application only. If show() is called for a
modal dialog, the dialog is displayed and executed.
The call to show() will not return until the dialog has
been dismissed. The result of show() is the dialog
result as supplied to close(). For all other elements,
the result is 0.

onClick() no return value This method is called when a control has been acti-
vated by clicking it. Not all types of controls imple-
ment this callback. If you are interested in processing
this event, define a function of this name in the con-
trol element.

onChange() no return value This method is called when the content of a control
has been changed. Not all types of controls imple-
ment this callback. If you are interested in processing
this event, define a function of this name in the con-
trol element.

onClose() no return value This method is called when a Window is closed. If you
are interested in processing this event, define a func-
tion of this name in the Window object.

onMove() no return value This method is called when a Window has been
moved. If you are interested in processing this event,
define a function of this name in the Window object.

onResize() no return value

This method is called when a Window has been

resized. If you are interested in processing this event,
define a function of this name in the Window object.

219
Creating User Interface Elements

220

UI object descriptions
This section describes UI objects such as windows, panels, buttons, checkboxes and so on.

Window object

To create a new Window object:

Method Returns Description
n e w Wi n d ow ( “d i a l o g” [ , t i t l e , b o u n d s ] ) ; Object Creates a new Window. The required type argument
contains the requested element type for a modal dia-
log. The optional title argument is used to set the
window title, if specified. Optionally, a Bounds object
or array may be supplied that describes the bounds
of the window. If no bounds are given, a default
bounds is chosen. The return value is the newly cre-
ated window or null on errors.

The panel element

To add a Panel element to a window w:

Method Returns Description
w. a d d ( “p a n e l ” [ , b o u n d s , tex t , Object The optional parameter bounds defines the ele-
{<creation proper ties>} ]); ment’s position and size. The optional parameter text
is the text displayed in the border of the panel. The
optional parameter <creation properties> is an object
that can contain any of the following properties:

To add a border style around a panel.

Method Returns Description
b orderSt y l e String Specifies the appearance of the border drawn
around the panel. It can be one of: none, etched,
raised, sunken, black. The default borderStyle is
etched.

If you specify a Panel whose width is 0, it will appear as a vertical line; a panel whose height is 0 will appear as
a horizontal line. Making a panel invisible will also hide all its children; making it visible again will also make
visible those children that were visible when the panel was made invisible.

The statictext control

To add a StaticText element to a window:

Method Returns Description
w. a d d ( “s t a t i c tex t” [ , b o u n d s , tex t , Object The optional parameter bounds defines the ele-
{<creation proper ties>}]); ment’s position and size. The optional parameter text
is the text displayed by the control. The optional
parameter <creation properties> is an object contain-
ing any of the following properties:
mu l t i l i n e Boolean If false (default) the control accepts a single line of
text. If true, the control accepts multiple lines, in
which case the text wraps within the width of the
control.
scro l l i n g Boolean If false (default), the text displayed cannot be
scrolled. If true, scrolling buttons appear and the text
displayed can be vertically scrolled; this case implies
multiline.

220
Creating User Interface Elements

221

The edittext control

To add an EditText element to a window:

Method Returns Description
w . a d d ( “e d i t text” [ , b o u n d s , tex t , Object The optional parameter bounds defines the ele-
{<creation proper ties>}]); ment’s position and size. The optional parameter text
is the initial text displayed by the control. The
optional parameter <creation properties> is an object
containing any of the following properties:

mu l t i l i n e Boolean If false (default) the control accepts a single line of

text. If true, the control accepts multiple lines, in
which case the text wraps within the width of the
control.
readonly Boolean If false (default), the control accepts text input. If true,
the control will not accept input text, but simply dis-
plays the contents of its text property.
n o e ch o Boolean If false (default), the control displays text that is typed
as input. If true, the control will not display input text
(useful for password fields).

The EditText control calls the onChange() event method if the editable text is changed or if its notify() method
is called. It also has a textselection property to access any text selection within the edit field.

The button control

To add a Button element to a window:

Method Returns Description
w.add (“ bu tton” [, bo u n d s, text]); Object The optional parameter bounds defines the ele-
ment’s position and size. The optional parameter text
is the text displayed inside the button control.

The Button control calls the onClick() event method if the control is clicked or if its notify() method is called.

The checkbox control

To add a Checkbox element to a window w:

Method Returns Description
w.add (“checkbox” [, bounds, Object The optional parameter bounds defines the ele-
text]); ment’s position and size. The optional parameter text
is the text displayed next to the checkbox control.

The Checkbox control calls the onClick() event method if the control is clicked or if its notify() method is called.
It also has a value property which indicates whether the control is set or not.

The radiobutton control

To add a RadioButton element to a window w:

Method Returns Description
w.add (“radiobutton” [, Object The optional parameter bounds defines the ele-
bounds, text]); ment’s position and size. The optional parameter text
is the text displayed next to the radiobutton control.

221
Creating User Interface Elements

222

All RadioButtons in a group must be created sequentially, with no intervening creation of other element types.
Only one RadioButton in a group can be set at a time; setting a different RadioButton unsets the original one.
The RadioButton control calls the onClick() event method if the control is clicked or if its notify() method is
called. It also has a value property which indicates whether the control is set or not.

The scrollbar control

To add a Scrollbar element to a window w:

Method Returns Description
w.add (“scrollbar” [, bounds, Object The optional parameter bounds defines the ele-
value, minvalue, maxvalue]); ment’s position and size. The optional parameter
value is the initial position of the moveable element.
The optional parameters minvalue and maxvalue
define the range of values that can be returned by
changing the position of the moveable element.

The Scrollbar control will have a horizontal orientation if the specified width is greater than its height at
creation time; its orientation will be vertical if its height is greater than its width. It calls the onChange() event
method if the position of the moveable element is changed by the user, or if its notify() method is called. The
value property contains the current position of the scrollbar’s moveable position indicator within the scrolling
area, within the range of minvalue and maxvalue.

The slider control

To add a Slider element to a window w:

Method Returns Description
w.add (“slider” [, bounds, Object The optional parameter bounds defines the ele-
value, minvalue, maxvalue]); ment’s position and size. The optional parameter
value is the initial position of the moveable element.
The optional parameters minvalue and maxvalue
define the range of values that can be returned by
changing the position of the moveable element.

All Slider controls have a horizontal orientation. The Slider control calls the onChange() event method if the
position of the slider is changed by the user, or if its notify() method is called. The value property contains the
current position of the slider’s moveable position indicator, within the range of minvalue and maxvalue.

222
The Socket Object

223

Appendix A: The Socket Object

TCP connections are the basic transport layer of the Internet. Every time your Web browser connects to a
server and requests a new page, it opens a TCP connection to handle the request as well as the server's reply.
The JavaScript Socket object lets you connect to any server on the Internet and to exchange data with this
server.
The Socket object provides basic functionality to connect to a remote computer over a TCP/IP network or the
Internet. It provides calls like open() and close() to establish or to terminate a connection, or read() or write()
to transfer data. The object also contains a listen() method to establish a simple Internet server; the server uses
the method poll() to check for incoming connections.
Many of these connections are based on simple data exchange of ASCII data, while other protocols, like the
FTP protocol, are more complex and involve binary data. One of the simplest protocols is the HTTP protocol.
The following sample TCP/IP client connects to a WWW server (which listens on port 80); it then sends a very
simple HTTP GET request to obtain the home page of the WWW server, and then it reads the reply, which is
the home page together with a HTTP response header.
r eply = "";
conn = new Socket;
// access Ado be' s ho me p a g e
if (conn.open ("www.adobe.com:80")) {
// send a HT TP GET re quest
conn.w r i te ("GET /index.ht ml HT TP/1.0\n\n");
// and read the ser ver's reply
reply = conn.read();
conn.close();
}

After executing above code, the variable homepage contains the contents of the Adobe home page together
with a HTTP response header.
Establishing an Internet server is a bit more complicated. A typical server program sits and waits for incoming
connections, which it then processes. Usually, you would not want your application to run in an endless loop,
waiting for any incoming connection request. Therefore, you can ask a Socket object for an incoming
connection by calling the poll() method of a Socket object. This call would just check the incoming connec-
tions and then return immediately. If there is a connection request, the call to poll() would return another
Socket object containing the brand new connection. Use this connection object to talk to the calling client;
when finished, close the connection and discard the connection object.
Before a Socket object is able to check for an incoming connection, it must be told to listen on a specific port,
like port 80 for HTTP requests. Do this by calling the listen() method instead of the open() method.
The following example is a very simple Web server. It listens on port 80, waiting until it detects an incoming
request. The HTTP header is discarded, and a dummy HTML page is transmitted to the caller.
c onn = new Socket;
// listen on por t 80
if conn.listen (80)) {
// wait fore ver for a connection
var incoming;
do inco mi n g = con n . p o l l ();

223
The Socket Object

224

w h i l e ( i n co m i n g = = nu l l ) ;
// discard the re quest
rea d ( ) ;
// Reply w ith a HT TP header
incoming .w r i te ln ("HT TP/1.0 200 OK");
incoming .w r i te ln ("Content-Ty p e: text/ht ml");
incoming .w r i te ln();
// Tr ansmit a dummy homepage
i n co m i n g . w r ite l n ( " < h t m l > < b o dy > < h 1 > Ho m e p a g e < / h 1 > < / b o dy > < / h t m l > " ) ;
// done!
incoming .close();
delete incoming;
}

Often, the remote endpoint terminates the connection after transmitting data. Therefore, there is a connected
property that contains true as long as the connection still exists. If the connected property returns false, the
connection is closed automatically.
On errors, the error property of the Socket object contains a short message describing the type of the error.
The Socket object lets you easily implement software that talks to each other via the Internet. You could, for
example, let two Adobe applications exchange documents and data simply by writing and executing JavaScript
programs.

JavaScript Reference
Properties

con n e c te d Boolean Contains true if the connection is still active. Read only.

e of Boolean This property has the value true if the receive buffer is empty. Read only.

e r ror String Contains a message describing the last error. Setting this value clears any error mes-
sage.

ho st String Contains the name of the remote computer when a connection is established. If the
connection is shut down or does not exist, the property contains the empty string.
Read only.

t imeout Number The timeout in seconds to be applied to read or write operations. Defaults to 10 (ten
seconds).

Methods
[ n e w] Socket ();

Creates a new Socket object.

Returns

Object.
c lo se( );

224
The Socket Object

225

Terminates the open connection. The return value is true if the connection was closed, false on I/O errors.
Deleting the connection has the same effect. Remember, however, that JavaScript garbage collects the object
at some null time, so the connection may stay open longer than you want to if you do not close it explicitly.

Returns

Boolean
list en (Number por t [, St r ing enco ding]);

Instructs the object to start listening for an incoming connection. The port argument is the TCP/IP port
number where the object should listen on; typical values are 80 for a Web server, 23 for a Telnet server and so
on. The encoding parameter is optional. The call to listen() is mutually exclusive to a call to open(). The result
is true if the connection object successfully started listening, false otherwise.

Parameters

p or t Number The port number to listen on. Valid port numbers are 1 to 65535.

e n co d i n g String The encoding to be used for the connection. Typical values are "ASCII", "binary", or
"UTF-8". This parameter defaults to ASCII.

Returns

Boolean
o pen (St r ing computer [, St r ing enco ding]);

Open the connection for subsequent read/write operations. The computer name is the name or IP address,
followed by a colon and the port number to connect to. The port number is mandatory. Valid computer names
are, for example, "www.adobe.com:80" or "192.150.14.12:80". The encoding parameter is optional; currently,
it can be one of "ASCII", "binary" or "UTF-8". The call to open() is mutually exclusive to a call to listen().

Parameters

ho st String The name or IP address of the remote computer, followed by a colon and the port
number to connect to. The port number is mandatory. Valid computer names are e.g.
"www.adobe.com:80" or "192.150.14.12:80".

en co d i n g String The encoding to be used for the connection. Typical values are "ASCII", "binary", or
"UTF-8". This parameter defaults to ASCII.

Returns

Boolean
poll();

Check a listening object for a new incoming connection. If a connection request was detected, the method
returns a new Socket object that wraps the new connection. Use this connection object to communicate with
the remote computer. After use, close the connection and delete the JavaScript object. If no new connection
request was detected, the method returns null.

Returns

a new Socket object or null.

r e a d ( [ Nu m b e r co u n t ] ) ;

225
The Socket Object

226

Read up to the given number of characters from the connection. Returns a string that contains up to the
number of characters that were supposed to be read. If no count is supplied, the connection attempts to read
as many characters it can get until the remote server closes the connection or a timeout occurs.

Parameters

count Number The number of characters to read. If no count is supplied, the connection attempts to
read as many characters it can get until the remote server closes the connection or a
timeout occurs.

Returns

String
readln();

Read one line of text up to the next line feed. Line feeds are recognized as CR, LF, CRLF or LFCR pairs.

Returns

String
w r ite (S t r i n g text, … );

Write the given string to the connection. The parameters of this function are concatenated to a single string.
Returns true on success.

Parameters

text String All arguments are concatenated to form the string to be written.

Returns

Boolean
w r ite ln (S t r in g text, … );

Write the given string to the connection and append a Line Feed character. The parameters of this function
are concatenated to a single string. Returns true on success.

Parameters

text String All arguments are concatenated to form the string to be written.

Returns

Boolean

Chat server sample

The following sample code implements a very simple chat server. A chat client may connect to the chat server,
who is listening on port number 1234. The server responds with a welcome message and waits for one line of
input from the client. The client types some text and transmits it to the server who displays the text and lets
the user at the server computer type a line of text, which the client computer again displays. This goes back
and forth until either the server or the client computer types the word "bye".

226
The Socket Object

227

fu n c tion chatSer ver() {

fu n ct ion cha tC l i en t() {

v a r con n e c t i o n = n e w S o c ke t ;
// connect to sample ser ver
if (connection.open ("remote-pc.cor p.adobe.com:1234")) {
// then chat w ith ser ver
ch a t ( co n n e c t i o n ) ;
con n e c t i o n . c l o s e ( ) ;
d e l e te con n e c t i o n ;
}
}

f u n c t i o n ch a t ( c ) {
// select a long timeout
c.timeout=1000;
while (true) {
/ / g e t o n e l i n e a n d e ch o i t
w r i te l n ( c . re a d ( ) ) ;
// stop if the connection is broken
i f ( ! c . co n n e c te d )
break;
// read a line of text
w r i te ("cha t: ");
v a r tex t = re a d l n ( ) ;
if (text == "bye")
// stop conversation if the user entere d "bye"
break;
else
// other w ise t r ansmit to ser ver

227
The Socket Object

228

c. w r i te l n (text);
}
}

228
Encoding Names

229

Appendix B: Encoding Names

Supported encoding names
The following list of names is a basic set of encoding names supported by the FileSystem object. Some of the
character encoders are built in, while the operating system is queried for most of the other encoders.
Depending on the language packs installed, some of the encodings may not be available. Names that refer to
the same encoding are listed in one line. Underlines are replaced with dashes before matching an encoding
name.
Note, however, that the FileSystem object cannot process extended Unicode character with values greater than
65535. These characters are left encoded as specified in the UTF-16 standard in as two characters in the range
from 0xD700-0xDFFF.
Built-in encodings are:
U S-ASC I I , A S C I I , I S O646- U S , I S O- 646. I R V: 1 9 9 1 , I S O - I R- 6 , AN S I - X 3 . 4 -
1968,C P 367, I B M367, U S , I S O646. 1991- I RV
U CS-2, U C S 2, I S O- 10646- U C S - 2
U CS2LE , U C S - 2L E , I S O- 10646- U C S - 2L E
U CS2BE , U C S - 2B E , I S O- 10646- U C S - 2B E
U CS-4, U C S 4, I S O- 10646- U C S - 4
U CS4LE , U C S - 4L E , I S O- 10646- U C S - 4L E
U CS4BE , U C S - 4B E , I S O- 10646- U C S - 4B E
U TF-8 , U TF8, U N I C OD E - 1- 1- U TF- 8, U N I C O D E - 2 - 0 - U T F- 8 , X - U N I C O D E - 2 - 0 - U T F- 8
U TF16, U TF- 16, I S O- 10646- U TF- 16
U TF16L E , U TF- 16L E , I S O- 10646- U TF- 1 6 L E
U TF16B E , U TF- 16B E , I S O- 10646- U TF- 1 6 B E
CP125 2, W I N D OWS - 1252, MS - A N S I
ISO -8859- 1, I S O- 8859- 1, I S O- 8859- 1: 19 8 7 , I S O - I R- 1 0 0 , L AT I N 1
MACINTOS H , X - MAC - ROMA N
BINARY

The ASCII encoder raises errors for characters greater than 127, and the BINARY encoder simply converts
between bytes and Unicode characters by using the lower 8 bits. This encoder is convenient for reading and
writing binary data.Additional encodings
In Windows, all encodings use so-called code pages. These code pages are assigned numeric values. The usual
Western character set that Windows uses is, for example, the code page 1252. Windows code pages may be
selected by prepending the number of the code page with "CP" or "WINDOWS- like "CP1252" for the code
page 1252. The File object has a lot of other encoding names built-in that match predefined code page
numbers. If a code page is not present, the encoding cannot be selected.
On Mac OS, encoders may be selected by name rather than by code page number. The File object queries Mac
OS directly for an encoder. As far as Mac OS character sets are identical with Windows code pages, Mac OS
also knows the Windows code page numbers.

Common encoding names

The following encoding names are implemented both on Windows and Mac OS:

229
Encoding Names

230

U TF -7 , U TF7, U N I C OD E - 1- 1- U TF- 7, X - U N I C O D E - 2 - 0 - U T F- 7
ISO -8859- 2, I S O- 8859- 2, I S O- 8859- 2: 19 8 7 , I S O - I R- 1 0 1 , L AT I N 2
ISO -8859- 3, I S O- 8859- 3, I S O- 8859- 3: 19 8 8 , I S O - I R- 1 0 9 , L AT I N 3
ISO -8859- 4, I S O- 8859- 4, I S O- 8859- 4: 19 8 8 , I S O - I R- 1 1 0 , L AT I N 4 , BALT I C
ISO -8859- 5, I S O- 8859- 5, I S O- 8859- 5: 19 8 8 , I S O - I R- 1 4 4 , C Y R I L L I C
ISO-8859-6,ISO-8859-6,ISO-8859-6:1987,ISO-IR-127,ECMA-114,ASMO-708,ARABIC
ISO -8859- 7, I S O- 8859- 7, I S O- 8859- 7: 19 8 7 , I S O - I R- 1 2 6 , E C M A- 1 1 8 , E LOT- 9 2 8 , G R E E K 8 , G R E E K
ISO -8859- 8, I S O- 8859- 8, I S O- 8859- 8: 19 8 8 , I S O - I R- 1 3 8 , HE B R EW
ISO -8859- 9, I S O- 8859- 9, I S O- 8859- 9: 19 8 9 , I S O - I R- 1 4 8 , L AT I N 5 , T U R K I S H
ISO -8859- 10, I S O- 8859- 10, I S O- 8859- 10 : 1 9 9 2 , I S O - I R- 1 5 7 , L AT I N 6
ISO -8859- 13, I S O- 8859- 13, I S O- I R- 179, L AT I N 7
ISO -8859- 14, I S O- 8859- 14, I S O- 8859- 14 , I S O - 8 8 5 9 - 1 4 : 1 9 9 8 , I S O - I R- 1 9 9 , L AT I N 8
ISO -8859- 15, I S O- 8859- 15, I S O- 8859- 15 : 1 9 9 8 , I S O - I R- 2 0 3
ISO -8859- 16, I S O- 885, I S O- 885, MS - E E
CP850 , W I N D OWS - 850, I B M850
CP866 , W I N D OWS - 866, I B M866
CP932 , W I N D OWS - 932, S J I S , S H I FT- JI S, X - S J I S , X - M S - S J I S , M S - S J I S , M S - KAN J I
CP936 , W I N D OWS - 936, GB K , W I N D OWS - 9 3 6 , G B 2 3 1 2 , G B - 2 3 1 2 - 8 0 , I S O - I R- 5 8 , C HI N E S E
CP949 , W I N D OWS - 949, U H C , K S C - 5601 , KS - C - 5 6 0 1 - 1 9 8 7 , KS - C - 5 6 0 1 - 1 9 8 9 , I S O - I R- 1 4 9 , KO R E AN
CP950 , W I N D OWS - 950, B I G5, B I G- 5, B I G - F I V E , B I G F I V E , C N - B I G 5 , X - X - B I G 5
CP125 1, W I N D OWS - 1251, MS - C Y R L
CP125 2, W I N D OWS - 1252, MS - A N S I
CP125 3, W I N D OWS - 1253, MS - GR E E K
CP125 4, W I N D OWS - 1254, MS - TU R K
CP125 5, W I N D OWS - 1255, MS - H E B R
CP1256,WIND OWS-1256,MS-ARAB
CP125 7, W I N D OWS - 1257, W I N BA LTR I M
CP125 8, W I N D OWS - 1258
CP136 1, W I N D OWS - 1361, J OH A B
EU C-J P, E U C J P, X - E U C - J P
EU C-K R , E U C K R , X - E U C - K R
H Z,HZ - GB - 2312
X-MAC- JA PA N E S E
X-MAC- GR E E K
X-MAC- C Y R I L L I C
X-MAC-LATIN
X-MAC-ICELANDIC
X-MAC- TU R K I S H

Additional Windows encoding names

CP437 , I B M850, W I N D OWS - 437
CP709 , W I N D OWS - 709, A S MO- 449, B C O N V 4
EBCD I C
KO I-8R
KO I-8U
ISO -2022- JP
ISO -2022- K R

230
Encoding Names

231

Additional Mac OS encoding names

These names are alias names for encodings that Mac OS might know.
TIS-62 0, TI S 620, TI S 620- 0, TI S 620. 2529 - 1 , T I S 6 2 0 . 2 5 3 3 - 0 , T I S 6 2 0 . 2 5 3 3 - 1 , I S O - I R - 1 6 6
CP874 , W I N D OWS - 874
JP,JIS- C 6220- 1969- RO, I S O646- J P, I S O- I R- 1 4
JIS-X0201, J I S X 0201- 1976, X 0201
JIS-X0208, J I S - X 0208- 1983, JI S - X 0208- 1 9 9 0 , J I S 0 2 0 8 , X 0 2 0 8 , I S O - I R- 8 7
JIS-X0212, J I S - X 0212. 1990- 0, J I S - X 0212 - 1 9 9 0 , X 0 2 1 2 , I S O - I R- 1 5 9
CN,GB- 1988- 80, I S O646- C N , I S O- I R- 57
ISO -IR- 16, C N - GB - I S OI R 165
KSC-5 601, K S - C - 5601- 1987, K S - C - 5601 - 1 9 8 9 , I S O - I R- 1 4 9
EU C-C N , E U C C N , GB 2312, C N - GB
E U C - T W, E U C T W, X - E U C - T W

231
Object Properties
(output of dump_objects.jsx from After Effects 6.5)

===========================================================================
AlphaMode enum
---------------------------------------------------------------------------
AlphaMode.IGNORE
AlphaMode.PREMULTIPLIED
AlphaMode.STRAIGHT
---------------------------------------------------------------------------

===========================================================================
Application object
---------------------------------------------------------------------------
beginSuppressDialogs() no return
beginUndoGroup(string undoName) no return
buildName : string : readOnly
buildNumber : integer : readOnly
endSuppressDialogs(boolean showAlert) no return
endUndoGroup() no return
endWatchFolder() no return
exitAfterLaunchAndEval : boolean : read/write
exitCode : integer : read/write
isProfessionalVersion : boolean : readOnly
isRenderEngine : boolean : readOnly
isUISuppressed : boolean : readOnly
isWatchFolder : boolean : readOnly
language : Language : readOnly
newProject() no return
open([File file]) returns Project
pauseWatchFolder(boolean doPause) no return
project : Project : readOnly
purge(PurgeTarget target) no return
quit() no return
registeredCompany : string : readOnly
registeredName : string : readOnly
serialNumber : string : readOnly
setMemoryUsageLimits(float imageCachePercent,
float maximumMemoryPercent) no return
setSavePreferencesOnQuit(boolean doSave) no return
settings : Settings : readOnly
version : string : readOnly
watchFolder(File file) no return
onError(string errorString,
string severity) no return
---------------------------------------------------------------------------

===========================================================================
AVLayer object
---------------------------------------------------------------------------
(integer propertyIndex) returns PropertyBase
(string propertyName) returns PropertyBase

Page 232
active : boolean : readOnly
activeAtTime(float atTime) returns boolean
addProperty(string propertyName) returns PropertyBase
adjustmentLayer : boolean : read/write
audioActive : boolean : readOnly
audioActiveAtTime(float atTime) returns boolean
audioEnabled : boolean : read/write
blendingMode : BlendingMode : read/write
canAddProperty(string propertyName) returns boolean
canSetCollapseTransformation : boolean : readOnly
canSetEnabled : boolean : readOnly
canSetTimeRemapEnabled : boolean : readOnly
collapseTransformation : boolean : read/write
copyToComp(CompItem intoComp) no return
duplicate() returns AVLayer
effectsActive : boolean : read/write
elided : boolean : readOnly
enabled : boolean : read/write
frameBlending : boolean : read/write
guideLayer : boolean : read/write
hasAudio : boolean : readOnly
hasTrackMatte : boolean : readOnly
hasVideo : boolean : readOnly
height : float : readOnly
inPoint : float : read/write
index : integer : readOnly
isEffect : boolean : readOnly
isMask : boolean : readOnly
isModified : boolean : readOnly
isNameFromSource : boolean : readOnly
isTrackMatte : boolean : readOnly
locked : boolean : read/write
matchName : string : readOnly
motionBlur : boolean : read/write
moveAfter(Layer otherLayer) no return
moveBefore(Layer otherLayer) no return
moveTo(integer index) no return
moveToBeginning() no return
moveToEnd() no return
name : string : read/write
nullLayer : boolean : readOnly
numProperties : integer : readOnly
outPoint : float : read/write
parent : Layer : read/write
parentProperty : PropertyGroup : readOnly
preserveTransparency : boolean : read/write
property(integer propertyIndex) returns PropertyBase
property(string propertyName) returns PropertyBase
propertyDepth : integer : readOnly
propertyGroup([integer countUp]) returns PropertyGroup
propertyType : PropertyType : readOnly
quality : LayerQuality : read/write
remove() no return
selected : boolean : read/write

Page 233
selectedProperties : Array of PropertyBase: readOnly
setParentWithJump(Layer newParent) no return
shy : boolean : read/write
solo : boolean : read/write
source : AVItem : readOnly
startTime : float : read/write
stretch : float : read/write
threeDLayer : boolean : read/write
time : float : readOnly
timeRemapEnabled : boolean : read/write
trackMatteType : TrackMatteType : read/write
width : float : readOnly
---------------------------------------------------------------------------

===========================================================================
BlendingMode enum
---------------------------------------------------------------------------
BlendingMode.ADD
BlendingMode.ALPHA_ADD
BlendingMode.CLASSIC_COLOR_BURN
BlendingMode.CLASSIC_COLOR_DODGE
BlendingMode.CLASSIC_DIFFERENCE
BlendingMode.COLOR
BlendingMode.COLOR_BURN
BlendingMode.COLOR_DODGE
BlendingMode.DANCING_DISSOLVE
BlendingMode.DARKEN
BlendingMode.DIFFERENCE
BlendingMode.DISSOLVE
BlendingMode.EXCLUSION
BlendingMode.HARD_LIGHT
BlendingMode.HARD_MIX
BlendingMode.HUE
BlendingMode.LIGHTEN
BlendingMode.LINEAR_BURN
BlendingMode.LINEAR_DODGE
BlendingMode.LINEAR_LIGHT
BlendingMode.LUMINESCENT_PREMUL
BlendingMode.LUMINOSITY
BlendingMode.MULTIPLY
BlendingMode.NORMAL
BlendingMode.OVERLAY
BlendingMode.PIN_LIGHT
BlendingMode.SATURATION
BlendingMode.SCREEN
BlendingMode.SILHOUETE_ALPHA
BlendingMode.SILHOUETTE_LUMA
BlendingMode.SOFT_LIGHT
BlendingMode.STENCIL_ALPHA
BlendingMode.STENCIL_LUMA
BlendingMode.VIVID_LIGHT
---------------------------------------------------------------------------

Page 234
===========================================================================
CloseOptions enum
---------------------------------------------------------------------------
CloseOptions.DO_NOT_SAVE_CHANGES
CloseOptions.PROMPT_TO_SAVE_CHANGES
CloseOptions.SAVE_CHANGES
---------------------------------------------------------------------------

===========================================================================
CompItem object
---------------------------------------------------------------------------
activeCamera : Layer : readOnly
bgColor : Array of float : read/write
comment : string : read/write
displayStartTime : float : read/write
draft3d : boolean : read/write
duplicate() returns CompItem
duration : float : read/write
footageMissing : boolean : readOnly
frameBlending : boolean : read/write
frameDuration : float : read/write
frameRate : float : read/write
hasAudio : boolean : readOnly
hasVideo : boolean : readOnly
height : integer : read/write
hideShyLayers : boolean : read/write
id : integer : readOnly
layer(integer layerIndex) returns Layer
layer(string layerName) returns Layer
layer(Layer otherLayer, integer relativeIndex) returns Layer
layers : LayerCollection: readOnly
motionBlur : boolean : read/write
name : string : read/write
numLayers : integer : readOnly
parentFolder : FolderItem : readOnly
pixelAspect : float : read/write
preserveNestedFrameRate : boolean : read/write
preserveNestedResolution : boolean : read/write
proxySource : FootageSource : readOnly
remove() no return
resolutionFactor : Array of integer : read/write
selected : boolean : read/write
selectedLayers : Array of Layer : readOnly
selectedProperties : Array of PropertyBase: readOnly
setProxy(File proxyFile) no return
setProxyToNone() no return
setProxyWithPlaceholder(string name,
integer width,
integer height,
float frameRate,
float duration) no return
setProxyWithSequence(File proxyFile,

Page 235
boolean forceAlphabetical) no return
setProxyWithSolid(ArrayOfFloat color,
string name,
integer width,
integer height,
float pixelAspecRatio) no return
shutterAngle : integer : read/write
shutterPhase : integer : read/write
time : float : read/write
typeName : string : readOnly
useProxy : boolean : read/write
usedIn : Array of CompItem : readOnly
width : integer : read/write
workAreaDuration : float : readOnly
workAreaStart : float : readOnly
---------------------------------------------------------------------------

===========================================================================
FieldSeparationType enum
---------------------------------------------------------------------------
FieldSeparationType.LOWER_FIELD_FIRST
FieldSeparationType.OFF
FieldSeparationType.UPPER_FIELD_FIRST
---------------------------------------------------------------------------

===========================================================================
FileSource object
---------------------------------------------------------------------------
alphaMode : AlphaMode : read/write
conformFrameRate : float : read/write
displayFrameRate : float : readOnly
fieldSeparationType : FieldSeparationType : readOnly
file : File : readOnly
guessAlphaMode() no return
guessPulldown(PulldownMethod pulldownMethod) no return
hasAlpha : boolean : readOnly
highQualityFieldSeparation : boolean : read/write
invertAlpha : boolean : read/write
isStill : boolean : readOnly
loop : integer : read/write
nativeFrameRate : float : readOnly
premulColor : Array of float : read/write
reload() no return
removePulldown : PulldownPhase : readOnly
---------------------------------------------------------------------------

===========================================================================
FolderItem object
---------------------------------------------------------------------------
comment : string : read/write
id : integer : readOnly

Page 236
item(integer itemIndex) returns Item
items : ItemCollection : readOnly
name : string : read/write
numItems : integer : readOnly
parentFolder : FolderItem : readOnly
remove() no return
selected : boolean : read/write
typeName : string : readOnly
---------------------------------------------------------------------------

===========================================================================
FootageItem object
---------------------------------------------------------------------------
comment : string : read/write
duration : float : readOnly
file : File : readOnly
footageMissing : boolean : readOnly
frameDuration : float : readOnly
frameRate : float : readOnly
hasAudio : boolean : readOnly
hasVideo : boolean : readOnly
height : integer : read/write
id : integer : readOnly
mainSource : FootageSource : readOnly
name : string : read/write
parentFolder : FolderItem : readOnly
pixelAspect : float : read/write
proxySource : FootageSource : readOnly
remove() no return
replace(File proxyFile) no return
replaceWithPlaceholder(string name,
integer width,
integer height,
float frameRate,
float duration) no return
replaceWithSequence(File proxyFile,
boolean forceAlphabetical) no return
replaceWithSolid(ArrayOfFloat color,
string name,
integer width,
integer height,
float pixelAspecRatio) no return
selected : boolean : read/write
setProxy(File proxyFile) no return
setProxyToNone() no return
setProxyWithPlaceholder(string name,
integer width,
integer height,
float frameRate,
float duration) no return
setProxyWithSequence(File proxyFile,
boolean forceAlphabetical) no return
setProxyWithSolid(ArrayOfFloat color,

Page 237
string name,
integer width,
integer height,
float pixelAspecRatio) no return
time : float : readOnly
typeName : string : readOnly
useProxy : boolean : read/write
usedIn : Array of CompItem : readOnly
width : integer : read/write
---------------------------------------------------------------------------

===========================================================================
ImportAsType enum
---------------------------------------------------------------------------
ImportAsType.COMP
ImportAsType.COMP_CROPPED_LAYERS
ImportAsType.FOOTAGE
ImportAsType.PROJECT
---------------------------------------------------------------------------

===========================================================================
ImportOptions object
---------------------------------------------------------------------------
new ImportOptions(File fileToImport) returns ImportOptions
canImportAs(ImportAsType asType) returns boolean
file : File : read/write
forceAlphabetical : boolean : read/write
importAs : ImportAsType : read/write
sequence : boolean : read/write
---------------------------------------------------------------------------

===========================================================================
ItemCollection object
---------------------------------------------------------------------------
addComp(string name,
integer width,
integer height,
float pixelAspectRatio,
float duration,
float frameRate) returns CompItem
---------------------------------------------------------------------------

===========================================================================
KeyframeEase object
---------------------------------------------------------------------------
new KeyframeEase(float speed,
float influence) returns KeyframeEase
influence : float : read/write
speed : float : read/write
---------------------------------------------------------------------------

Page 238
===========================================================================
KeyframeInterpolationType enum
---------------------------------------------------------------------------
KeyframeInterpolationType.BEZIER
KeyframeInterpolationType.HOLD
KeyframeInterpolationType.LINEAR
---------------------------------------------------------------------------

===========================================================================
Language enum
---------------------------------------------------------------------------
Language.ENGLISH
Language.FRENCH
Language.GERMAN
Language.JAPANESE
---------------------------------------------------------------------------

===========================================================================
Layer object
---------------------------------------------------------------------------
(integer propertyIndex) returns PropertyBase
(string propertyName) returns PropertyBase
active : boolean : readOnly
activeAtTime(float atTime) returns boolean
addProperty(string propertyName) returns PropertyBase
canAddProperty(string propertyName) returns boolean
canSetEnabled : boolean : readOnly
copyToComp(CompItem intoComp) no return
duplicate() returns Layer
elided : boolean : readOnly
enabled : boolean : read/write
hasVideo : boolean : readOnly
inPoint : float : read/write
index : integer : readOnly
isEffect : boolean : readOnly
isMask : boolean : readOnly
isModified : boolean : readOnly
locked : boolean : read/write
matchName : string : readOnly
moveAfter(Layer otherLayer) no return
moveBefore(Layer otherLayer) no return
moveTo(integer index) no return
moveToBeginning() no return
moveToEnd() no return
name : string : read/write
nullLayer : boolean : readOnly
numProperties : integer : readOnly
outPoint : float : read/write
parent : Layer : read/write
parentProperty : PropertyGroup : readOnly

Page 239
property(integer propertyIndex) returns PropertyBase
property(string propertyName) returns PropertyBase
propertyDepth : integer : readOnly
propertyGroup([integer countUp]) returns PropertyGroup
propertyType : PropertyType : readOnly
remove() no return
selected : boolean : read/write
selectedProperties : Array of PropertyBase: readOnly
setParentWithJump(Layer newParent) no return
shy : boolean : read/write
solo : boolean : read/write
startTime : float : read/write
stretch : float : read/write
time : float : readOnly
---------------------------------------------------------------------------

===========================================================================
LayerCollection object
---------------------------------------------------------------------------
add(AVItem theItem,
[float duration]) returns AVLayer
addCamera(string name,
ArrayOfFloat centerPoint) returns Layer
addLight(string name,
ArrayOfFloat centerPoint) returns Layer
addNull([float duration]) returns AVLayer
addSolid(ArrayOfFloat color,
string name,
integer width,
integer height,
float pixelAspectRatio,
[float duration]) returns AVLayer
addText([TextDocument textDoc]) returns AVLayer
addText(string text) returns AVLayer
byName(string name) returns Layer
precompose(ArrayOfInteger layerIndices,
string name,
[boolean moveAllAttributes]) returns CompItem
---------------------------------------------------------------------------

===========================================================================
LayerQuality enum
---------------------------------------------------------------------------
LayerQuality.BEST
LayerQuality.DRAFT
LayerQuality.WIREFRAME
---------------------------------------------------------------------------

===========================================================================
LogType enum
---------------------------------------------------------------------------

Page 240
LogType.ERRORS_AND_PER_FRAME_INFO
LogType.ERRORS_AND_SETTINGS
LogType.ERRORS_ONLY
---------------------------------------------------------------------------

===========================================================================
MarkerValue object
---------------------------------------------------------------------------
new MarkerValue(string comment,
[string chapter],
[string url],
[string frameTarget]) returns MarkerValue
chapter : string : read/write
comment : string : read/write
frameTarget : string : read/write
url : string : read/write
---------------------------------------------------------------------------

===========================================================================
MaskMode enum
---------------------------------------------------------------------------
MaskMode.ADD
MaskMode.DARKEN
MaskMode.DIFFERENCE
MaskMode.INTERSECT
MaskMode.LIGHTEN
MaskMode.NONE
MaskMode.SUBTRACT
---------------------------------------------------------------------------

===========================================================================
MaskMotionBlur enum
---------------------------------------------------------------------------
MaskMotionBlur.OFF
MaskMotionBlur.ON
MaskMotionBlur.SAME_AS_LAYER
---------------------------------------------------------------------------

===========================================================================
MaskPropertyGroup object
---------------------------------------------------------------------------
(integer propertyIndex) returns PropertyBase
(string propertyName) returns PropertyBase
active : boolean : readOnly
addProperty(string propertyName) returns PropertyBase
canAddProperty(string propertyName) returns boolean
canSetEnabled : boolean : readOnly
color : Array of float : read/write
duplicate() returns MaskPropertyGroup
elided : boolean : readOnly

Page 241
enabled : boolean : readOnly
inverted : boolean : read/write
isEffect : boolean : readOnly
isMask : boolean : readOnly
isModified : boolean : readOnly
locked : boolean : read/write
maskMode : MaskMode : read/write
maskMotionBlur : MaskMotionBlur : read/write
matchName : string : readOnly
moveTo(integer index) no return
name : string : read/write
numProperties : integer : readOnly
parentProperty : PropertyGroup : readOnly
property(integer propertyIndex) returns PropertyBase
property(string propertyName) returns PropertyBase
propertyDepth : integer : readOnly
propertyGroup([integer countUp]) returns PropertyGroup
propertyIndex : integer : readOnly
propertyType : PropertyType : readOnly
remove() no return
rotoBezier : boolean : read/write
selected : boolean : read/write
---------------------------------------------------------------------------

===========================================================================
OMCollection object
---------------------------------------------------------------------------
add() returns OutputModule
---------------------------------------------------------------------------

===========================================================================
OutputModule object
---------------------------------------------------------------------------
applyTemplate(string templateName) no return
file : File : read/write
name : string : readOnly
postRenderAction : PostRenderAction : read/write
remove() no return
saveAsTemplate(string templateName) no return
templates : Array of string: readOnly
---------------------------------------------------------------------------

===========================================================================
PlaceholderSource object
---------------------------------------------------------------------------
alphaMode : AlphaMode : read/write
conformFrameRate : float : read/write
displayFrameRate : float : readOnly
fieldSeparationType : FieldSeparationType : read/write
guessAlphaMode() no return
guessPulldown(PulldownMethod pulldownMethod) no return

Page 242
hasAlpha : boolean : readOnly
highQualityFieldSeparation : boolean : read/write
invertAlpha : boolean : read/write
isStill : boolean : readOnly
loop : integer : read/write
nativeFrameRate : float : readOnly
premulColor : Array of float : read/write
removePulldown : PulldownPhase : read/write
---------------------------------------------------------------------------

===========================================================================
PostRenderAction enum
---------------------------------------------------------------------------
PostRenderAction.IMPORT
PostRenderAction.IMPORT_AND_REPLACE_USAGE
PostRenderAction.NONE
PostRenderAction.SET_PROXY
---------------------------------------------------------------------------

===========================================================================
Project object
---------------------------------------------------------------------------
activeItem : Item : readOnly
bitsPerChannel : integer : read/write
close(CloseOptions closeOptions) returns boolean
consolidateFootage() returns integer
file : File : readOnly
importFile(ImportOptions importOptions) returns Item
importFileWithDialog() returns ArrayOfItem
importPlaceholder(string itemName,
integer itemWidth,
integer itemHeight,
float frameRate,
float duration) returns FootageItem
item(integer itemIndex) returns Item
items : ItemCollection : readOnly
numItems : integer : readOnly
reduceProject(ArrayOfItem itemsToPreserve) returns integer
removeUnusedFootage() returns integer
renderQueue : RenderQueue : readOnly
rootFolder : FolderItem : readOnly
save(File toFile) returns boolean
saveWithDialog() returns boolean
selection : Array of Item : readOnly
showWindow(boolean doShow) no return
timecodeBaseType : TimecodeBaseType : read/write
timecodeDisplayType : TimecodeDisplayType : read/write
timecodeFilmType : TimecodeFilmType : read/write
timecodeNTSCDropFrame : boolean : read/write
transparencyGridThumbnails : boolean : read/write
---------------------------------------------------------------------------

Page 243
===========================================================================
Property object
---------------------------------------------------------------------------
active : boolean : readOnly
addKey(float atTime) returns integer
canSetEnabled : boolean : readOnly
canVaryOverTime : boolean : readOnly
duplicate() returns Property
elided : boolean : readOnly
enabled : boolean : readOnly
expression : string : read/write
expressionEnabled : boolean : read/write
expressionError : string : readOnly
hasMax : boolean : readOnly
hasMin : boolean : readOnly
isEffect : boolean : readOnly
isInterpolationTypeValid(
KeyframeInterpolationType type) returns boolean
isMask : boolean : readOnly
isModified : boolean : readOnly
isSpatial : boolean : readOnly
isTimeVarying : boolean : readOnly
keyInInterpolationType(integer keyIndex) returns
KeyframeInterpolationType
keyInSpatialTangent(integer keyIndex) returns ArrayOfFloat
keyInTemporalEase(integer keyIndex) returns
ArrayOfKeyframeEase
keyOutInterpolationType(integer keyIndex) returns
KeyframeInterpolationType
keyOutSpatialTangent(integer keyIndex) returns ArrayOfFloat
keyOutTemporalEase(integer keyIndex) returns
ArrayOfKeyframeEase
keyRoving(integer keyIndex) returns boolean
keySelected(integer keyIndex) returns boolean
keySpatialAutoBezier(integer keyIndex) returns boolean
keySpatialContinuous(integer keyIndex) returns boolean
keyTemporalAutoBezier(integer keyIndex) returns boolean
keyTemporalContinuous(integer keyIndex) returns boolean
keyTime(integer keyIndex) returns float
keyTime(string markerName) returns float
keyValue(integer keyIndex) returns type-stored-in-
property
keyValue(string markerName) returns type-stored-in-
property
matchName : string : readOnly
moveTo(integer index) no return
name : string : readOnly
nearestKeyIndex(float atTime) returns integer
numKeys : integer : readOnly
parentProperty : PropertyGroup : readOnly
propertyDepth : integer : readOnly
propertyGroup([integer countUp]) returns PropertyGroup
propertyType : PropertyType : readOnly

Page 244
propertyValueType : PropertyValueType : readOnly
remove() no return
removeKey(integer keyIndex) no return
selected : boolean : read/write
selectedKeys : Array of integer : readOnly
setInterpolationTypeAtKey(integer keyIndex,
KeyframeInterpolationType inType,
[KeyframeInterpolationType outType]) no return
setRovingAtKey(integer keyIndex,
boolean isRoving) no return
setSelectedAtKey(integer keyIndex,
boolean isSelected) no return
setSpatialAutoBezierAtKey(integer keyIndex,
boolean isAutoBezier) no return
setSpatialContinuousAtKey(integer keyIndex,
boolean isContinuous) no return
setSpatialTangentsAtKey(integer keyIndex,
ArrayOfFloat inTangent,
[ArrayOfFloat outTangent]) no return
setTemporalAutoBezierAtKey(integer keyIndex,
boolean isAutoBezier) no return
setTemporalContinuousAtKey(integer keyIndex,
boolean isContinuous) no return
setTemporalEaseAtKey(integer keyIndex,
ArrayOfKeyframeEase inEase,
[ArrayOfKeyframeEase outEase]) no return
setValue(type-stored-in-property newValue) no return
setValueAtKey(integer keyIndex,
type-stored-in-property newValue) no return
setValueAtTime(float atTime,
type-stored-in-property newValue) no return
setValuesAtTimes(ArrayOfFloat atTimes,
ArrayOf-type-stored-in-property newValues) no return
unitsText : string : readOnly
value : type-stored-in-property: readOnly
valueAtTime(float atTime,
bool preExpression) returns type-stored-in-
property
---------------------------------------------------------------------------

===========================================================================
PropertyGroup object
---------------------------------------------------------------------------
(integer propertyIndex) returns PropertyBase
(string propertyName) returns PropertyBase
active : boolean : readOnly
addProperty(string propertyName) returns PropertyBase
canAddProperty(string propertyName) returns boolean
canSetEnabled : boolean : readOnly
duplicate() returns PropertyGroup
elided : boolean : readOnly
enabled : boolean : readOnly
isEffect : boolean : readOnly

Page 245
isMask : boolean : readOnly
isModified : boolean : readOnly
matchName : string : readOnly
moveTo(integer index) no return
name : string : readOnly
numProperties : integer : readOnly
parentProperty : PropertyGroup : readOnly
property(integer propertyIndex) returns PropertyBase
property(string propertyName) returns PropertyBase
propertyDepth : integer : readOnly
propertyGroup([integer countUp]) returns PropertyGroup
propertyIndex : integer : readOnly
propertyType : PropertyType : readOnly
remove() no return
selected : boolean : readOnly
---------------------------------------------------------------------------

===========================================================================
PropertyType enum
---------------------------------------------------------------------------
PropertyType.INDEXED_GROUP
PropertyType.NAMED_GROUP
PropertyType.PROPERTY
---------------------------------------------------------------------------

===========================================================================
PropertyValueType enum
---------------------------------------------------------------------------
PropertyValueType.COLOR
PropertyValueType.CUSTOM_VALUE
PropertyValueType.LAYER_INDEX
PropertyValueType.MARKER
PropertyValueType.MASK_INDEX
PropertyValueType.NO_VALUE
PropertyValueType.OneD
PropertyValueType.SHAPE
PropertyValueType.TEXT_DOCUMENT
PropertyValueType.ThreeD
PropertyValueType.ThreeD_SPATIAL
PropertyValueType.TwoD
PropertyValueType.TwoD_SPATIAL
---------------------------------------------------------------------------

===========================================================================
PulldownPhase enum
---------------------------------------------------------------------------
PulldownPhase.OFF
PulldownPhase.SSWWW
PulldownPhase.SWWWS
PulldownPhase.SWWWW_24P_ADVANCE
PulldownPhase.WSSWW

Page 246
PulldownPhase.WSWWW_24P_ADVANCE
PulldownPhase.WWSSW
PulldownPhase.WWSWW_24P_ADVANCE
PulldownPhase.WWWSS
PulldownPhase.WWWSW_24P_ADVANCE
PulldownPhase.WWWWS_24P_ADVANCE
---------------------------------------------------------------------------

===========================================================================
PulldownMethod enum
---------------------------------------------------------------------------
PulldownMethod.ADVANCE_24P
PulldownMethod.PULLDOWN_3_2
---------------------------------------------------------------------------

===========================================================================
PurgeTarget enum
---------------------------------------------------------------------------
PurgeTarget.ALL_CACHES
PurgeTarget.IMAGE_CACHES
PurgeTarget.SNAPSHOT_CACHES
PurgeTarget.UNDO_CACHES
---------------------------------------------------------------------------

===========================================================================
RenderQueue object
---------------------------------------------------------------------------
item(integer itemIndex) returns RenderQueueItem
items : RQItemCollection : readOnly
numItems : integer : readOnly
pauseRendering(boolean doPause) no return
render() no return
rendering : boolean : readOnly
showWindow(boolean doShow) no return
stopRendering() no return
---------------------------------------------------------------------------

===========================================================================
RenderQueueItem object
---------------------------------------------------------------------------
applyTemplate(string templateName) no return
comp : CompItem : readOnly
elapsedSeconds : float : readOnly
logType : LogType : read/write
numOutputModules : integer : readOnly
outputModule(integer outputModuleIndex) returns OutputModule
outputModules : OMCollection : readOnly
remove() no return
render : boolean : read/write
saveAsTemplate(string templateName) no return

Page 247
skipFrames : integer : read/write
startTime : float : readOnly
status : RQItemStatus : readOnly
templates : Array of string: readOnly
timeSpanDuration : float : read/write
timeSpanStart : float : read/write
onStatusChanged() no return
---------------------------------------------------------------------------

===========================================================================
RQItemCollection object
---------------------------------------------------------------------------
add(CompItem compToAdd) returns RenderQueueItem
---------------------------------------------------------------------------

===========================================================================
RQItemStatus enum
---------------------------------------------------------------------------
RQItemStatus.DONE
RQItemStatus.ERR_STOPPED
RQItemStatus.NEEDS_OUTPUT
RQItemStatus.QUEUED
RQItemStatus.RENDERING
RQItemStatus.UNQUEUED
RQItemStatus.USER_STOPPED
RQItemStatus.WILL_CONTINUE
---------------------------------------------------------------------------

===========================================================================
Settings object
---------------------------------------------------------------------------
getSetting(string sectionName,
string sectionKey) returns string
haveSetting(string sectionName,
string sectionKey) returns boolean
saveSetting(string sectionName,
string sectionKey,
string newValue) no return
---------------------------------------------------------------------------

===========================================================================
Shape object
---------------------------------------------------------------------------
new Shape() returns Shape
closed : boolean : read/write
inTangents : Array of float[2] : read/write
outTangents : Array of float[2] : read/write
vertices : Array of float[2] : read/write
---------------------------------------------------------------------------

Page 248
===========================================================================
SolidSource object
---------------------------------------------------------------------------
alphaMode : AlphaMode : read/write
color : Array of float : read/write
conformFrameRate : float : readOnly
displayFrameRate : float : readOnly
fieldSeparationType : FieldSeparationType : readOnly
guessAlphaMode() no return
guessPulldown(PulldownMethod pulldownMethod) no return
hasAlpha : boolean : readOnly
highQualityFieldSeparation : boolean : readOnly
invertAlpha : boolean : read/write
isStill : boolean : readOnly
loop : integer : readOnly
nativeFrameRate : float : readOnly
premulColor : Array of float : read/write
removePulldown : PulldownPhase : readOnly
---------------------------------------------------------------------------

===========================================================================
System object
---------------------------------------------------------------------------
machineName : string : readOnly
osName : string : readOnly
osVersion : string : readOnly
userName : string : readOnly
---------------------------------------------------------------------------

===========================================================================
TextDocument object
---------------------------------------------------------------------------
new TextDocument(string text) returns TextDocument
text : string : read/write
---------------------------------------------------------------------------

===========================================================================
TimecodeBaseType enum
---------------------------------------------------------------------------
TimecodeBaseType.FPS100
TimecodeBaseType.FPS24
TimecodeBaseType.FPS25
TimecodeBaseType.FPS30
TimecodeBaseType.FPS48
TimecodeBaseType.FPS50
TimecodeBaseType.FPS60
---------------------------------------------------------------------------

===========================================================================

Page 249
TimecodeDisplayType enum
---------------------------------------------------------------------------
TimecodeDisplayType.FEET_AND_FRAMES
TimecodeDisplayType.FRAMES
TimecodeDisplayType.TIMECODE
---------------------------------------------------------------------------

===========================================================================
TimecodeFilmType enum
---------------------------------------------------------------------------
TimecodeFilmType.MM16
TimecodeFilmType.MM35
---------------------------------------------------------------------------

===========================================================================
TrackMatteType enum
---------------------------------------------------------------------------
TrackMatteType.ALPHA
TrackMatteType.ALPHA_INVERTED
TrackMatteType.LUMA
TrackMatteType.LUMA_INVERTED
TrackMatteType.NO_TRACK_MATTE
---------------------------------------------------------------------------

Page 250