After Effects region of interest

I'm working on updating the scripting guide for After Effects CS4. Rather than make you wait until I'm finished with the whole thing before you can see what's new and changed, I figured that it would be a good idea to post a skeletal outline of the new and changed features now. I hope that this bare outline is enough to show those of you already savvy with After Effects scripting how you can get started using the new features.

For information on ScriptUI and other aspects of ExtendScript not specific to After Effects, see the Adobe Scripting Developer Center, which has links (at the bottom of the page) to documents such as Adobe Introduction to Scripting and JavaScript Tools Guide.

When the After Effects CS4 scripting guide is published, there will be a link to it from the After Effects Developer Center. I'll also post a corrected version of the After Effects CS3 scripting guide; the version currently available has many errors. If you're in a hurry, you can get to a copy of the CS3 document that has the errors marked by following the links in this blog post.

Also, be sure to check out the "Scripts" section of After Effects CS4 Help, which provides links to useful scripting resources.

As always, I owe thanks to After Effects team members Jeff Almasol and Keiko Yamada, from whose materials I borrow heavily.

changes to After Effects scripting

• Added Application isoLanguage attribute.
  Note: $.locale returns the OS language, not the language of the After Effects application.
• Deprecated the Application language attribute. It should still work for all languages except Korean.
• Added MarkerValue duration attribute.
• Added OutputModule includeSourceXMP attribute.
• Added ability to access ExternalObject.AdobeXMPScript.
• Added Project xmpPacket attribute.
• Added the following Property methods and attributes related to the Separate Dimensions feature:
  Note: The original, consolidated, multidimensional property is the "separation leader" and the new, separated, single-dimensional properties are its "separation followers".
  • dimensionsSeparated attribute
  • getSeparationFollower method
  • isSeparationFollower attribute
  • isSeparationLeader attribute
  • separationDimension attribute
  • separationLeader attribute
• Added TextDocument access.
  • applyFill attribute : boolean to set/get fill visibility
  • applyStroke attribute : boolean to set/get stroke visibility
  • fillColor attribute : r,g,b value to set/get fill color
  • font attribute : font specified by PostScript name
  • fontSize attribute : font size, in range 0.1 to 1296 (inclusive)
  • justification attribute : enum to set/get paragraph justification:
    • ParagraphJustification.LEFT_JUSTIFY
    • ParagraphJustification.RIGHT_JUSTIFY
    • ParagraphJustification.CENTER_JUSTIFY
    • ParagraphJustification.FULL_JUSTIFY_LASTLINE_LEFT
    • ParagraphJustification.FULL_JUSTIFY_LASTLINE_RIGHT
    • ParagraphJustification.FULL_JUSTIFY_LASTLINE_CENTER
    • ParagraphJustification.FULL_JUSTIFY_LASTLINE_FULL
  • resetCharStyle method : resets text character characteristics in the Character panel
  • resetParagraphStyle method : resets text paragraph characteristics in the Paragraph panel
  • strokeColor attribute : r,g, b value to set/get stroke color
  • strokeOverFill attribute : boolean to set/get stroke/fill order option
  • strokeWidth attribute : stroke width, in range 0 to 1000 (inclusive)
• Now AVItem name, Item name, Layer name, and PropertyBase name attributes can have unlimited length.
• Now the Layer setParentWithJump method can be called with no parameters, which lets you set the parent to None.
• Updated and cleaned up the set of bundled scripts.

Here's a simple script that exercises the new access to properties of a text layer:

var myProject = app.project;
var myComposition = myProject.items.addComp("happy_holidays", 1920, 1080, 1.0, 5, 24);
var myTextLayer = myComposition.layers.addText("new_text_layer");
var myTextDocument = myTextLayer.property("ADBE Text Properties").property("ADBE Text Document")
var textDocument1 = myTextDocument.value;
myString = "Happy holidays!";

textDocument1.resetCharStyle();
textDocument1.fontSize = 60;
textDocument1.fillColor = [1, 0, 0];
textDocument1.strokeColor = [0, 1, 0];
textDocument1.strokeWidth = 2;
textDocument1.font = "TimesNewRomanPSMT";
textDocument1.strokeOverFill = true;
textDocument1.applyStroke = true;
textDocument1.applyFill = true;
textDocument1.text = myString;
textDocument1.justification = ParagraphJustification.CENTER_JUSTIFY;
myTextDocument.setValue(textDocument1);

changes to behavior of embedded panels

• You should no longer need to set foregroundColor for dropdownlist, edittext, listbox, and treeview controls. However, edittext readonly controls will use dark text on a white background, so you might still want to set its foregroundColor to a gray shade that makes it appear to be "read only".

changes to core ExtendScript language

• Added support for triple quotation marks (""" ... """).

changes to ScriptUI

• Added the following types of controls:
  • custom – Added Custom control (customBoundedValue, customButton, and customView types).
  • toggle buttons – Added IconButton toggle creation property. The value attribute sets toggle state.
  • multi-column listboxes – Added numberOfColumns and showHeaders creation properties.
  • tabbed panels – Added type:'tabbedpanel' and type:'tab' attributes for Panel objects.
• Added EditText borderless attribute for creating an edittext control without its border.
• Added EditText scrolling attribute for controlling if a vertical scrollbar appears for multiline edittext controls.
• Added ListItem enabled attribute to enable or disable a list item.
• Added ListItem revealItem() method to scroll a list item into view.
• Added Window borderless creation property for creating borderless windows.
• Added Window findElement() method for retrieving a window object by its name creation property.
• Added Window opacity attribute for creating partially transparent windows.
• Added Window update() method for refreshing the UI (useful for progressbar control updates).
• Added ability to set an element's preferredSize value to -1 to instruct ScriptUI to calculate it for you.
• Added ability to detect key presses.
• Added ability to detect low-level mouse events.