JavaScript OSA

JavaScript OSA Home

Download & Installation

QuickStart

Project Status

Documentation

Object Reference

	Core
	MacOS
	MacOS.AEDesc
	MacOS.AEApp
	MacOS.AEClass
	MacOS.AEColl
	MacOS.FileSpec
	MacOS.OSA
	MacOS.MacOSError

Sending Raw AppleEvents

Responding to AppleEvents

AppleEvent to JavaScript Value Conversion

How-Tos

	Open Handler
	Folder Actions Handlers
	Write Some Text
	Calling JavaScript from REALbasic
	Using JavaScript Libraries

FAQ

Mailing List

JavaScript Language Documentation & Links

Products
	Script Debugger 4.5

Site Contents
	Mark’s Blog
	Product Registration
	Bug Reporting
	Freeware
	Contacting Us

MacOS.AEClass object

The MacOS.AEClass object represents a reference to an object within another application. While MacOS.AEClass has a series of standard properties, it also provides JavaScript properties and methods corresponding to the properties and AppleEvents defined for the object in the application's dictionary ('aete').

Method/Property	Description
MacOS.AEClass.valueOf(desiredType)	sends a Get AppleEvent to the target application asking for the default value of the object. If a desired type is specified, the target application is asked to return the value in that data type. The desired type may be expressed using one of the symbolic names in the _types object or as a 4-character string containing the 4-character AppleEvent data type code.
MacOS.AEClass.toString() MacOS.AEClass.toSource()	returns an AEPrint formatted string describing the object within the target application this MacOS.AEClass instance refers to
MacOS.AEClass.newReference (objectSpecifier)	returns an MacOS.AEClass referring to the object specifier passed as an instance of MacOS.AEDesc
MacOS.AEClass._types	returns an object containing properties named after all the classes defined in the application's dictionary
MacOS.AEClass._constants	returns an object containing properties named after each constant (enumeration) appearing in the application's dictionary
MacOS.AEClass.next	returns a MacOS.AEClass object referring to the next element in the collection
MacOS.AEClass.atNext MacOS.AEClass.toText	returns an instance of MacOS.AEDesc containing an insertion location suitable for use with the at parameter of make, copy, duplicate and move events
MacOS.AEClass.previous	returns a MacOS.AEClass object referring to the previous element in the collection
MacOS.AEClass.toPrevious MacOS.AEClass.atPrevious	returns an instance of MacOS.AEDesc containing an insertion location suitable for use with the at parameter of make, copy, duplicate and move events
MacOS.AEClass.before	returns a MacOS.AEClass object representing an insertion location before an MacOS.AEClass instance
MacOS.AEClass.atBefore MacOS.AEClass.toBefore	returns an instance of MacOS.AEDesc containing an insertion location suitable for use with the at parameter of make, copy, duplicate and move events
MacOS.AEClass.after	returns a MacOS.AEClass object representing an insertion location after an MacOS.AEClass instance
MacOS.AEClass.atAfter MacOS.AEClass.toAfter	returns an instance of MacOS.AEDesc containing an insertion location suitable for use with the at parameter of make, copy, duplicate and move events
MacOS.AEClass.beginning	returns a MacOS.AEClass object representing an insertion location before all objects in this container
MacOS.AEClass.atBeginning MacOS.AEClass.toBeginning	returns an instance of MacOS.AEDesc containing an insertion location suitable for use with the at parameter of make, copy, duplicate and move events
MacOS.AEClass.end	returns a MacOS.AEClass object representing an insertion location after all objects in this container
MacOS.AEClass.atEnd MacOS.AEClass.toEnd	returns an instance of MacOS.AEDesc containing an insertion location suitable for use with the at parameter of make, copy, duplicate and move events
MacOS.AEClass.atReplace MacOS.AEClass.toReplace	returns an instance of MacOS.AEDesc containing an insertion location suitable for use with the at parameter of make, copy, duplicate and move events

Getting Properties

To read the value of an application property, use the standard JavaScript dot (.) notation to name the property you want to read. For instance, the following example reads the name property from the MacOS Finder's application object.

Sample

var appName = MacOS.finder().name;

// in AppleScript, this would be expressed as
//
// tell application "Finder"
// set appName to name
// end tell

NOTE: application dictionaries may define names containing spaces. JavaScript OSA translates all spaces in dictionary names to underscores (_).

If you want to read the "default value" of an object, use the MacOS.AEClass.valueOf() method.

Sample

with (MacOS.appBySignature("R*ch")) // BBEdit
theWord = document[1].word[1];

// in AppleScript, this would be expressed as
//
// tell application "BBEdit"
// set theWord to word 1 of document 1
// end tell

Specifying a Desired Type

The Get AppleEvent allows you to optionally specify a desired type when reading a property. In AppleScript this is done using the as parameter of the get comment (e.g. get contents of document 1 as styled text).

JavaScript OSA supports this by providing a xxxAs(requestedType) method for each property where xxx is the property name. When reading the default value of an object, you can specify a desired type as a parameter to the valueOf() function.

The desired type may be expressed using one of the symbolic names in the _types object or as a 4-character string containing the 4-character AppleEvent data type code (e.g. ..._types.integer or "long").

Sample

with (MacOS.finder())
folder[1].file[1].valueOf(_types.alias); // as an Alias rather than an object specifier

// in AppleScript, this would be expressed as
//
// tell application "Finder"
// file 1 of folder 1 as alias
// end tell

Setting Properties

To modify the value an application property, use a standard JavaScript assignment statement:

Sample

MacOS.finder().frontmost = true;

// in AppleScript, this would be expressed as
//
// tell application "Finder"
// set frontmost to true
// end tell

To set an object's "default value", use the JavaScript assignment operator (=):

Sample

var bbEdit = MacOS.appBySignature("R*ch");

with (bbEdit.document[1])
{
    x = word[1].valueOf();
    word[1] = x + "Hello";
}

// in AppleScript, this would be expressed as
//
// tell application "BBEdit"
//     set x to word 1
//     set word 1 to x & "Hello"
// end tell

Accessing Elements (collections)

The MacOS.AEClass also provides properties named after each element of a class which return MacOS.AEColl objects. These properties allow you to navigate through an application's containment network and locate other objects. Element names can be either the singular (e.g. the Finder's "file" element) or plural (e.g. the Finder's "files" element) in cases where the application's dictionary defines a plural form of the class.

For instance, in the MacOS Finder, the collection of files on the desktop is represented by the file property. The following sample counts the number of files on the desktop. For further details, please refer to MacOS.AEColl.

Sample

MacOS.finder().file.length;

// or

MacOS.finder().files.length;

// in AppleScript, this would be expressed as
//
// tell application "Finder"
// count files
// end tell

Sending AppleEvents

The MacOS.AEClass provides a function named after each AppleEvent defined for the object represented by the MacOS.AEClass instance in the target application's dictionary. When any of these functions are called, the corresponding AppleEvent is sent to the target object within the target application.

Two methods of sending AppleEvents are provided. The first uses the standard positional JavaScript function call and the second allows you to specify the AppleEvent parameters by name.

Positional Parameters

When the positional form is used (which is the default), parameters appearing in the JavaScript function call are added to the AppleEvent in the order that they appear in the Application's dictionary definition for the AppleEvent. If you want to omit a parameter from the AppleEvent, specify Null as its value in the function's parameter list.

For example, the Finder's Move command is defined as follows:

	move reference	the object(s) to move
	to location reference	the new location for the object(s)
	[replacing boolean]	Specifies whether or not to replace items in the destination that have the same name as items being moved
	[positioned at list]	Gives a list (in local window coordinates) of positions for the destination items
	[routing suppressed Boolean]	Specifies whether or not to autoroute items (default is false). Only applies when moving to the system folder

The following example shows the MacOS Finder's Move AppleEvent being invoked with positional parameters in JavaScript.

Sample

with (MacOS.finder())
files["JavaScript"].move(folders["untitled folder"], false);

// in AppleScript, this would be expressed as
//
// tell application "Finder"
// move file "JavaScript" to folder "untitled folder" without replacing
// end tell

Parameter 1 (folder["untitled folder"]) is sent as the "to" parameter and parameter 2 (false) is sent as the "replacing") parameter.

The direct object (sometimes called the subject, target or reference) parameter is supplied by default by the MacOS.AEClass object. If you want to override this parameter, you must use Named Parameters and specify the parameter as "ae_----".

The MacOS.AEApp class, which is a special form of the MacOS.AEClass class representing the application's application object requires that the direct object parameter, if it is included in the AppleEvents definition in the application's dictionary, be included as the first parameter in AppleEvent function calls. This is because AppleEvents invoked on the application object typically do not include a direct object parameter, or if they do, the direct object parameter may be something other than an object reference.

Named Parameters

To send an AppleEvent using named parameters, prefix the AppleEvent name with an underscore (_).

When the named form is used, parameters are placed into a JavaScript object as properties. Property names must correspond to the parameter names appearing in the AppleEvent's definition in the application dictionary. The order of properties within the object definition is not important.

Sample

with (MacOS.finder())
files["JavaScript"]._move({to: folders["untitled folder"], replacing: false});

Using _constants

Some properties and AppleEvent parameters accept enumerations as their values. JavaScript OSA provides the _constants property as a way of accessing application defined constants. Each constant in the application's dictionary is defined as a property of the _constants property.

Sample

var bbEdit = MacOS.appBySignature("R*ch");

with (bbEdit)
    if (document["untitled"].exists())
        document["untitled"].line_breaks = _constants.Unix;

// in AppleScript, this would be expressed as
//
// tell application "BBEdit"
//     if document "untitled" exists then
//         line breaks of document "untitled" = Unix
//     end if
// end tell

The type of value returned for each property of the _constants object is an instance of MacOS.AEDesc containing the constant value.

Using _types

Some properties and AppleEvent parameters accept data types as their values. JavaScript OSA provides the _types property as a way of accessing application data types. Each data type and class in the application's dictionary is defined as a property of the _types property.

Sample

<<sample script to be inserted>>

The type of value returned for each property of the _types object is MacOS.AEDesc.

Responding To Errors

If an AppleEvent results in an error, a JavaScript exception is thrown containing a MacOS.MacOSError object. This object contains the details of the error. You can catch errors using a JavaScript try - catch construct. The MacOS.MacOSError page contains an example illustrating how to catch exceptions.

Issues & Workarounds

JavaScript, unlike AppleScript, was not designed with AppleEvents in mind. Because of this, there are a few places where the syntax of the JavaScript language and common AppleEvent terms collide.

The AppleEvent class property conflicts with the JavaScript class reserved word. Therefore, it is not possible to send an AppleEvent requesting the class of an object using normal JavaScript syntax.

Sample

function getItemClass(index)
{
with (MacOS.finder())
return items[index].class; // produces compilation error
}

JavaScript will flag the word class with an error. The workaround is to use JavaScript�s array syntax to specify the property name.

Sample

function getItemClass(index)
{
with (MacOS.finder())
return items[index]["class"];
}

Similarly, the standard Delete AppleEvent collides with JavaScript's delete reserved word. As with the Class example above, use the array syntax to define the AppleEvent you want to send

Sample

with (MacOS.filder())
items["File To Delete.txt"]["delete"]();