Manages an the main event loop of an application object, as well as resources used by all of the application's objects.

The main purpose of an application object is to receive events and distribute them to the appropriate objects that can respond to them (typically view subclasses). For example, all keyboard and mouse events go directly to the window object associated with the event. In an AppleScript Studio application, these events can be dispatched to script event handlers you connect in Interface Builder. See the responder class for more information about how an application handles mouse and key events.

Every AppleScript Studio (and Cocoa) application has exactly one instance of the application object, created automatically as part of the application project in Xcode. Figure 2-1 shows the File’s Owner instance in the main nib window. In the main nib file, File’s Owner always represents NSApp, a global constant that references the NSApplication object for the application. The application object serves as the master controller for the application. You attach handlers to an application object in Interface Builder through the File’s Owner instance. For more information on nibs and File’s Owners, see the awake from nib command.

Figure 2-1  File’s Owner instance (representing the application object) in an Interface Builder nib window

The application object supplies shared instances of a color-panel, font-panel, open-panel, and save-panel that you can use in your application scripts. For related information, see Choosing Colors With Color Wells and Color Panels. The application object also provides elements for storing items such as image, movie, and sound objects with the application.

Starting in AppleScript Studio version 1.4, the application class provides enhanced coordinate system support. In previous versions, all coordinates for windows and views were returned as a list of four numbers, {left, bottom, right, top}. The origin of a window or bounds was in the bottom left corner. This differs from standard AppleScript, which uses a list of four numbers, {left, top, right, bottom}, with the top left of the window as the origin. To supply a backward compatible mechanism that supports the expected AppleScript way of specifying bounds, the application class now has a coordinate system property, which takes one of the enumerated values specified in Coordinate System.

The default value for the coordinate system property is classic coordinate system, which defines bounds as {left, bottom, right, top} with the origin in the bottom left; that is, it matches the coordinate system in previous versions of AppleScript Studio. For related information, see the bounds property of the window class.

In addition to specifying the coordinate system in a script, you can add the following entry to your application's Info.plist:

<key>ASKCoordinateSystem</key>

<string>ASKClassicCoordinateSystem</string>

If a script accesses the bounds and no coordinate system has been specified, AppleScript Studio will look for the ASKCoordinateSystem entry in the main bundle’s Info.plist and will use the specified value.

The Coordinate System sample application, available starting in AppleScript Studio version 1.4, demonstrates this feature.

Properties of application objects

In addition to the properties it inherits from the responder class, an application object has these properties (see the Version Notes section for this class for the AppleScript Studio version in which a particular property was added):

Elements of application objects

An application object can contain the elements listed below. Your script can access most elements with any of the key forms described in “Standard Key Forms.” See the Version Notes section for this class for the AppleScript Studio version in which a particular element was added.

Commands supported by application objects

Your script can send the following commands to an application object:

Events supported by application objects

An application object supports handlers that can respond to the following events. Note that Key and Mouse commands may be handled by other objects without ever propagating their way back to the application object.

Examples

The following launched handler, connected to the application object through the File’s Owner instance in Interface Builder, sets the color of the application’s color panel to red and makes the panel visible when the application is launched. AppleScript Studio script statements can refer to application properties without explicitly targeting the application object.

on launched theObject

    set color of color panel to {65535, 0, 0}

    set visible of color panel to true

end launched

You can use the following script in Script Editor to get the titles of the menu items in the main menu for the Drag Race application, available at <Xcode>/Examples/AppleScript Studio. Similar statements will work within an AppleScript Studio application script (though you won’t need the tell statements).

tell application "Drag Race"

    title of menu items of main menu

    -- result: {"", "File", "Edit",  "Window", "Help"}

end tell

Your script can dig down to get information about the menu items of the main menu as well. For example, the following line (inserted in the previous tell statement) gets the title of a menu item in the File menu:

title of menu item 10 of sub menu of menu item 2 of main menu

    -- result: "Page Setup…"

It can be convenient to use Script Editor (or a third party script application) to target an AppleScript Studio application, as shown here, to help determine the correct terminology for identifying objects in the application, especially in the case where you haven’t given AppleScript names to the objects in Interface Builder. If you did name the menu items, then you could use a line like the following:

title of menu item "page setup" of sub menu item "file"  of main menu

Version Notes

The coordinate system property was added in AppleScript studio version 1.4.

The following elements were added to the application object in AppleScript Studio version 1.2: drag info, pasteboard.

The following properties were added to the application object in AppleScript Studio version 1.1: color panel, font panel, open panel, save panel, user defaults.

The following elements were added to the application object in AppleScript Studio version 1.1: data source, item, sound.

Properties of bundle objects

In addition to the properties it inherits from the item class, a bundle object has these properties:

Commands supported by bundle objects

Your script can send the following commands to a bundle object:

Events supported by bundle objects

This class is not accessible in Interface Builder, and you cannot connect any event handlers to it.

Examples

The following clicked handler shows how to use a bundle’s scripts path property obtain the path to the scripts directory in an application’s main bundle. It uses the log command to display the result.

on clicked theObject

    set thePath to scripts path of main bundle

    log thePath

end clicked

Depending on the name and location of the project, the results of the previous handler would be something like the following:

2002-09-03 19:59:56.032 test project[667] "/Volumes/Projects/test  project// build/test project.app/Contents/Resources/Scripts"

The Examples section of the path for command shows how to get the full, slash-delimited path of the compiled main script in an AppleScript Studio application, and how to find and load a script from the application’s main bundle.

The following clicked handler shows how to use the call method command to access an external bundle, in this case the Terminal application that ships with Mac OSX. It uses the log command to display the result. Once you have a reference to the external bundle, you can get information from it through its properties or with the path for command.

This example uses the call method command to get the path to the bundle because, as noted in the Properties section above, the path property wasn’t supported before AppleScript Studio version 1.2.1. This handler uses a try, on error block to handle the case where call method may be unable to return a bundle (if, for example, the Terminal application is not present in the Utilities directory).

on clicked theObject

    set theBundle to call method "bundleWithPath:" of  class "NSBundle"

        with parameter "/Applications/Utilities/Terminal.app"

    try

        set thePath to call method "bundlePath" of object  theBundle

        log thePath

    on error

        log "Problem getting path to Terminal.app"

    end try

end clicked

The following example shows how to target a bundle outside the application:

on clicked theObject

    set myLibBundle to call method "bundleWithPath:" of  class "NSBundle"

        with parameter "/Users/MyUser/MyStudioLib/build/MyStudioLib.app"

    try

        tell myLibBundle

            set scriptPath to path for script "MyStudioLib"

                extension "scpt"

        end tell

        log scriptPath

    on error

        log "Problem getting path to MyStudio.app"

    end try

end clicked

Between the examples shown here and the example in the Examples section of the path for command, it is possible to load an external bundle and find and load scripts from the bundle. That means you can package frequently used scripts in a form that is easily accessible to any AppleScript Studio applications you write.

The following provides a simple example of how you might do this.

First, create an AppleScript Studio project in Xcode, using the AppleScript Application template. Name the application “MyStudioLib” and, for this example, save it in your user folder (/Users/yourname/). In the main script file for the project, MyStudioLib.applescript, define handlers that return any scripts you want to implement. In this example, there is one handler, named makeLibScript1, which creates a script named acknowledgeReceipt. Although there is no return statement, makeLibScript1 effectively returns the script acknowledgeReceipt.

on makeLibScript1()

    script myLibScript1

        -- Handlers

        on acknowledgeReceipt()

            display dialog "The acknowledgeReceipt script greets  you."

        end acknowledgeReceipt

    end script

end makeLibScript1

Next, build the project, which causes a compiled script named MyStudioLib.scpt to be stored in the application bundle. You can define multiple handlers to return any scripts you want to make accessible from your script library, though this example supplies just one script.

Finally, you can add the following script statements to any AppleScript Studio project that needs to use any of the scripts in your MyStudioLib project. These statements:

• define properties (initialized to the constant missing value) to make scripts accessible throughout the file

• implement a loadLibraryScripts handler that loads the script file from the MyStudioLib application and extracts a specific script object from the script

• implement a will finish launching event handler that simply calls loadLibraryScripts when the application is launched

• implement a clicked handler to demonstrate how to call a loaded script; your application can make similar calls from throughout its script file

property libraryScript : missing value

property libScript1 : missing value

on loadLibraryScripts()

    set scriptPath to missing value

    set myLibBundle to call method "bundleWithPath:" of  class "NSBundle" with  parameter "/Users/yourname/MyStudioLib/build/MyStudioLib.app"

    -- Log what we got for the bundle.

    log myLibBundle

    -- Use try, on error block to handle possible errors.

    try

        tell myLibBundle

            set scriptPath to path for script "MyStudioLib"  extension "scpt"

        end tell

    -- scriptPath is slash-delimited; use POSIX file from the standard

    --      scripting additions to convert it to a colon-delimited  path,

    --      which is expected by load script

        set libraryScript to load script POSIX file (scriptPath)

        set libScript1 to makeLibScript1() of libraryScript

    on error

        log "Problem getting library script."

    end try

end loadLibraryScripts

on will finish launching theObject

    loadLibraryScripts()

end will finish launching

on clicked theObject

    tell libScript1 to acknowledgeReceipt()

end clicked

Version Notes

Prior to AppleScript Studio version 1.2.1, you could not use the path property directly in a script, though you could obtain its value with a call method command, as shown above in the description for the path property, and also demonstrated in the Examples section above.

Version Notes

The data class was added in AppleScript Studio version 1.2, although it doesn’t do anything in that version.

Specifies an entry in the Mac OS X user defaults system (a mechanism for storing default values as key-value pairs, where the key is simply a name string).

You use this class in script statements to get, set, or remove the value for an entry in the application-specific defaults, which are typically used to store user preferences for the application.

For more information on the defaults system, see user-defaults, as well as the document User Defaults Programming Topics for Cocoa. You can also view man page information about the defaults system, using the Open Man Page menu from the Help menu in Xcode (available starting with Mac OS X version 10.2) to display defaults, or by typing man defaults in a Terminal window (the Terminal application is located in /Applications/Utilities).

Warning:  You should not delete entries from the user defaults system in AppleScript Studio version 1.2. Doing so may cause your application to crash. This was fixed in version 1.2.1.

Properties of default entry objects

In addition to the properties it inherits from the item class, a default entry object has these properties:

Events supported by default entry objects

This class is not accessible in Interface Builder, and you cannot connect any event handlers to it.

Examples

The application class has a user defaults property which you can use to manipulate user defaults entries. For example you could use the following to create a new entry in the user defaults. (An AppleScript Studio application script doesn’t need to explicitly target the application—it’s assumed within the script.)

make new default entry at end of default entries of user defaults  with properties  {name:"defaultName", contents:"Testing"}

If you attempt to make a new entry for a key that already exists, no new entry is created and the value for the key is not changed. The assumption is that if the key already exists, it represents a saved value that you may want to preserve. However, you can change the value, if necessary, as shown below.

Defaults information for your application is stored in its plist file. For example, if the identifier for your application (which you set in Xcode) is “com.acme.application”, the previous script statement results in a “defaultName” entry with value “Testing” in the file (where “~/” indicates the path to your user directory)

    ~/Library/Preferences/com.acme.application.plist

Warning:  You can use the Property List Editor application, available in Applications/Utilities/, to examine property list files. However, due to a bug, some versions of Property List Editor may display property list information incorrectly. However, you can also examine a property list’s XML in any text editor.

To get the value of any given entry in the user defaults, you simply refer to it by name. For example, given the previous make new statement, the following line returns the string value “Testing”:

set myName to contents of default entry "defaultName"  of user defaults

Attempting to access an entry that doesn’t exist will return an error, so you should enclose statements that access default entries within a try, on error block, as shown in the example in the Discussion section below.

To change a value, you use terminology like the following:

set contents of default entry "defaultName" of user defaults  to "Check"

The following awake from nib handler uses the statement tell user defaults to target the user-defaults property of the application object. After creating a new default entry object, it uses an another tell statement to log the contents of the entry, change the contents, and log the new contents.

on awake from nib theObject

    tell user defaults -- targets property of application

        make new default entry at end of default entries              with properties {name:"test", contents:"testing"}

        tell default entry "test"

            log contents as string

            set contents to "completed"

            log contents as string

        end tell

    end tell

end awake from nib

The previous handler results in log entries like the following:

2002-08-12 13:46:32.260 Test3[477] "testing"

2002-08-12 13:46:32.340 Test3[477] "completed"

For related examples, see user-defaults.

Discussion

The contents of a default entry is Unicode text (as is the value returned by the localized string command). You may need to convert the Unicode text to plain text—for example, to use in a command to another application that expects plain text, or to cast a retrieved string (such as “true” or “false”) to a boolean value. The following handler, from the SOAP Talk sample application, available at <Xcode>/Examples/AppleScript Studio, shows how to convert Unicode text to plain text. SOAP Talk convert strings to plain text because prior to AppleScript 1.9, Applescript’s call xmlrpc command won’t accept Unicode text.

on getPlainText(fromUnicodeString)

    set styledText to fromUnicodeString as string

    set styledRecord to styledText as record

    return «class ktxt» of styledRecord

end getPlainText

The following fragment shows how to get the contents of a default entry, call getPlainText to convert it to plain text, and cast the result to a boolean value. You could use similar statements to convert a numeric string to a number. The try, on error block deals with possible errors in getting the contents of the entry.

set tempString to contents of default entry "openFile"  of user defaults

try

    set shouldOpen to getPlainText(tempString) as boolean

    if shouldOpen then

        -- Do whatever is needed to open.

    else

        -- Do what is needed when shouldOpen is false

    end

on error

    display dialog "Error getting should open value."

end

As an alternative to converting the Unicode text to plain text, you can compare the text directly, as in this example:

set shouldOpen to contents of default entry "openFile"  of user defaults

try

    if shouldOpen is equal to "true" then

        -- Do whatever is needed to open.

    else

        -- Do what is needed when shouldOpen is false

    end

on error

    display dialog "Error getting should open value."

end

Version Notes

The default entry class was added in AppleScript Studio version 1.1.

Prior to AppleScript Studio version 1.2.1, deleting a default entry could result in a crash.

The content property was added in AppleScript Studio version 1.2. For information on the difference between content and contents, see the Version Notes section for the control class.

The getPlainText handler was added to the SOAP Talk sample application in AppleScript Studio version 1.2.

Properties of event objects

In addition to the properties it inherits from the item class, an event object has these properties:

Events supported by event objects

This class is not accessible in Interface Builder, and you cannot connect any event handlers to it.

Examples

The following mouse down handler shows how to determine, from the passed event parameter, whether the Option key was pressed during the mouse down. Your handler can use such information to determine which actions to perform.

on mouse down theObject event theEvent

    if option key down of theEvent then

        log "the option key was used"

    else

        log "the option key wasn't used"

    end if

end mouse down

The following mouse down handler uses the event’s time stamp property to determine whether a user double-clicked. Of course, you could just connect a double clicked handler to an object if you don’t need this level of control. On the other hand, you may think of other uses for measuring the time between events.

This handler uses a script-global property to keep track of the previous timestamp, initializing it to the constant missing value to indicate that on startup it has not been set. It assumes that two clicks in less than a second constitutes a double click. Because the time stamp property is a real, you could measure for time in fractions of a second.

property lastTimeStamp : missing value

on mouse down theObject event theEvent

    if lastTimeStamp is missing value then

        set lastTimeStamp to time stamp of theEvent

    else

        if (time stamp of theEvent) - lastTimeStamp < 1 then

            display alert "You double clicked!"

        else

            set lastTimeStamp to time stamp of theEvent

        end if

    end if

end mouse down

Examples

You can set the font family, typeface, size, and color for text field, text view, and related classes in Interface Builder with the Font panel, shown in Figure 2-2.

Figure 2-2  The Font panel in Interface Builder

You can use the Extras pop-up to preview fonts, edit font sizes, open a color panel and choose a color for a font, and perform other operations. The Use Family and Typeface pop-up lets you choose from various preconfigured system fonts.

To make changes for a specific object, such as a text field, you select that object, open the Font panel by navigating to it from the Format menu (or by pressing Command-T), then make your choices.