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.

Controls the formatting of numbers or dates.

A number formatter controls number formatting and a date formatters provide a similar function for dates. For information on specific formatter classes in Cocoa, see NSNumberFormatter and NSDateFormatter.

Figure 2-3 shows a number formatter you can drag from the Cocoa-Text pane of Interface Builder’s Palette window. You can drag either a number formatter or a date formatter from the Palette window into a text field in your AppleScript Studio application to format the text in that field.

Figure 2-3  A number formatter in Interface Builder

Figure 2-4 shows the Formatter pane in Interface Builder’s Info window, where you can adjust the format for a formatter. When you drag a formatter to a text field, Interface Builder automatically switches the Info window to the formatter pane, where you can adjust the format for that field. (You can open the Info window by typing Command-Shift-I.)

Figure 2-4  Interface Builder’s Info window for a number formatter

You can use these steps to connect an event handler to a formatter object in Interface builder:

1. put the nib window for the window object that contains the formatter into outline mode by clicking the small outline icon (visible in Figure 2-1) above the right scroll bar.

2. Use the disclosure triangles to open the window and other objects until the formatter object is visible.

3. Select the formatter, then connect the event handler in the AppleScript pane of the Info window.

Events supported by formatter objects

A formatter object supports handlers that can respond to the following events:

Examples

Through AppleScript Studio version 1.4, formatter objects have no scriptable properties or elements. However you can use the call method command to extract information from a formatter. You can also use call method to get a reference to a formatter from classes, such as control and cell, that have a formatter property.

The text field class inherits from the control class, so assuming you have added a formatter to a text field and given the text field the AppleScript name “formatted”, you can use the following call to get a reference to the formatter object:

set theFormatter to call method "formatter"

    of (text field "formatted" of window 1)

Suppose the formatted text currently displayed is “$54.00” and you would like to get that exact string from the text field. The following clicked handler first gets a reference to the formatter, then uses call method again to call the stringForObjectValue: method of Cocoa’s NSFormatter class to obtain the formatted text from the formatter. The handler uses a try, on error block to handle errors, and several log statements to log various steps:

on clicked theObject

    tell (window of theObject)

        try

            set theValue to contents of text field "formatted"

            (* get formatter, then formatted text *)

            set theFormatter to call method "formatter"

                of object (text field "formatted")

            log "Got formatter"

            set theString to call method "stringForObjectValue:"

                of object theFormatter with parameter theValue

            log ("Got string: " & theString)

        on error

            log "Error getting formatted text."

        end try

        (* Perform any operations with the formatted text. *)

    end tell

end clicked

You can use the call method command to make other calls to methods of Cocoa’s NSFormatter class.

Represents an image.

You don’t typically script an image—instead you work with an image view that contains the image.

The application object has an icon image property to provide access to the application icon, as well as image elements. The button and button cell objects have image and alternate image properties, which can also be used to store icon images, or any other image. For related information, see the document Cocoa Drawing Guide.

Figure 2-5 shows the Images tab in the default MainMenu.nib window for a new AppleScript Studio application in Interface Builder. The default application icon image is available automatically. You can insert an image view object in an application window by dragging it from the Cocoa-Controls palette. You can then drag an image from the Images tab to the image view. You can also drag an image onto a button.

Figure 2-5  Application icon image in the Images tab in a main nib window in Interface Builder

You can add images to your application by dragging an image file into the Images pane of a nib window in Interface Builder, or by dragging it into the Files list in the Users & Groups pane in the Xcode project for the application. You can then use the load image command to load an image and the image view class to display it. For information on how to free an image, see the Discussion section of the load image command.

Events supported by image objects

Though you can drag an image into an image view in Interface Builder, you cannot connect any event handlers to an image.

Examples

For examples of working with an image object, see the image view class.

Properties of item objects

An item object has these properties (see the Version Notes section for this class for the AppleScript Studio version in which a particular property was added):

Commands supported by item objects

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

Events supported by item objects

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

Examples

It is common to refer to objects by name in AppleScript Studio scripts. For example:

set userInput to contents of text field "input" of window  "main"

You provide an AppleScript name for an object in Interface Builder with these steps:

1. With the object selected, open the Info window by choosing Show Info from the Tools menu or by typing Command-Shift-I.

2. Use the pop-up menu at the top of the Info window or (type Command-6) to display the AppleScript pane.

3. Type the name in the Name field.

You can use the following script in Script Editor to get the ids of every view in every open window of a simple document-based application. For testing purposes, each document window contains a number of buttons and text fields. Similar statements will work within an AppleScript Studio application script (though you won’t need the tell application statement).

tell application "SimpleDocTest"

    id of every view of every window

end tell

Running this script with three open windows resulted in the following list of lists, containing one list of ids for each window:

{ {1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11},

{12, 13, 14, 15, 16, 17, 18, 19, 20, 21, 22},

{23, 24, 25, 26, 27, 28, 29, 30, 31, 32, 33} }

You can replace “id” with “name” in the script above to get the AppleScript name of every view (that has a name) in every open window.

For an example that uses item to access items in a list, see the sample script in the Discussion section for the load image command.

The following statements demonstrate how to retrieve a script, change a property of the script, and reset the script:

-- Get a copy of the script

set buttonScript to script of button 1 of window 1

-- Change the value of the foo property

set foo of buttonScript to "new value of foo"

-- Update the script with the changed script

set script of button 1 of window 1 to buttonScript

Version Notes

The script property was added in AppleScript Studio version 1.3.

Events supported by movie objects

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

Examples

For an example that loads a movie into a movie view, see the Examples section for the movie view class.

Properties of pasteboard objects

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

Events supported by pasteboard objects

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

Examples

To get data from a pasteboard, you should first set the preferred type property of the pasteboard (by default the preferred type will be “string”, but the preferred type may have been changed).To get the data from the general pasteboard as a string, you can use the following:

set preferred type of pasteboard "general" to "string"

set myString to contents of pasteboard "general"

To set data for a pasteboard, you should also first set the preferred type property of the pasteboard. To set the data for the general pasteboard to a string, you can use the following (but see also the Version Notes section for this class):

set preferred type of pasteboard "general" to "string"

set contents of pasteboard "general" to "Testing"

You can list the pasteboards for an application with a script such as the following (you can use the same statements within an AppleScript Studio application, but you won’t need the tell block):

tell application "myApp"

    pasteboards

end tell

The following will get the types for a pasteboard:

tell application "myApp"

    types of pasteboard "general"

end tell

The following awake from nib handler (from the Drag and Drop sample application, available at <Xcode>/Examples/AppleScript Studio) uses the register command to register the drag types an object can respond to.

on awake from nib theObject

    -- Enable support by registering the appropriate types.

    tell theObject to

        register drag types {"string", "rich text",  "file names"}

end awake from nib

Starting with AppleScript Studio version 1.3, you can use the preferred type property to set the contents of a pasteboard, as shown in the following script statements:

-- In case the default wasn't already "string":

set preferred type of pasteboard "general" to "string"

-- Now put a string on the pasteboard:

set contents of pasteboard "general" to "Testing"

For additional examples, see the Drag and Drop sample application.

Discussion

You can use the content and contents properties interchangeably, with one exception. Within an event handler, contents of theObject returns a reference to an object, rather than the actual contents. To get the actual contents of an object (such as the text contents from a text field) within an event handler, you can either use contents of contents of theObject or content of theObject.

For a sample script that shows the difference between content and contents, see the Version Notes section for the control class.

Version Notes

Starting with AppleScript Studio version 1.3, you can use the preferred type property to set the contents of a pasteboard, as shown in the Examples section for this class.

The pasteboard class and the Drag and Drop sample application were added in AppleScript Studio version 1.2.

Prior to version 1.2.1, you must do some preparation before you can set the contents of a pasteboard directly with new data. To do so, you invoke the call method command. The parameters to call method should be a list of types (described above) and the owner (usually 0 to represent nil), as shown in the following example:

call method "declareTypes:owner:" of pasteboard "general"

    with parameters {{"string"}, 0}

set contents of pasteboard "general" to "Testing"

Properties of responder objects

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

Events supported by responder objects

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

Examples

The responder class is an abstract class that you don’t typically target in your scripts. However, see the Examples section for the window class for one situation where you might script a responder. See also the first responder, key, and main properties of the window class.

Represents a sound that can be loaded and played.

You don’t typically script a sound directly, but you can use the load sound command to load a sound and the play command to play it. You can play any sound files supported by the NSSound class, including AIFF and WAV files. For related information, see the document Sound Programming Topics for Cocoa.

The application object has sound elements, while button and button cell objects have sound properties.

Figure 2-6 shows sounds in a nib window in Interface Builder. You can drag a sound from the Sounds tab to an object that supports sounds, such as a button object.

You can add sounds to your application by dragging a sound file into the Sounds pane of a nib window in Interface Builder, or by dragging it into the Files list in the Users & Groups pane in the Xcode project for the application. To actually play the sound, you will have to load it with the load sound command and play it with the play command. For information on freeing sound objects, see the Discussion section for the load image command.

Figure 2-6  Sounds in the Sounds tab in a nib window in Interface Builder

Properties of sound objects

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

Commands supported by sound objects

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

Events supported by sound objects

Though you can drag a sound onto an object that supports sounds in Interface Builder, you cannot connect any event handlers to it.

Examples

The load sound command provides an example that shows how an application can load and play a sound. The slider class provides an example that uses a slider to let a user set the sound volume.

Version Notes

The playing property was added in AppleScript Studio version 1.1.

Allows a titled window to display a toolbar just below its title bar.

Starting in AppleScript Studio version 1.4, you can create a toolbar and add it to a window in your application by assigning it to the toolbar property of a window object. Figure 2-7 shows such a toolbar, containing several toolbar items. You can only create a toolbar dynamically in your application—you can not currently add a toolbar to a window in Interface Builder.

AppleScript Studio supports various standard toolbar items, such as the print and separator items, listed in the toolbar item class. You can also create custom toolbar items using images you supply.

To respond to user actions involving a toolbar you have created, you use the clicked toolbar item and update toolbar item event handlers in the window class (also added in AppleScript Studio version 1.4).

For related information, see the document Toolbar Programming Topics for Cocoa.

Figure 2-7  An AppleScript Studio application window with a simple toolbar

Properties of toolbar objects

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

Events supported by toolbar objects

You do not connect event handlers to a toolbar. Instead, you use the toolbar handlers supported by the window class, clicked toolbar item and update toolbar item.

Examples

Because a toolbar is associated with a window object, a logical place to create a toolbar and assign it to a window is in the awake from nib event handler for the window. When you create a toolbar in a script, you must supply a unique identifier and specify the configuration for the toolbar, including the allowed and default identifiers. You can do this in several steps. The following script statement shows how you can create a toolbar with the identifier documentToolbar.

set documentToolbar to make new toolbar at end with properties {name:"document 
toolbar", identifier:"document toolbar identifier", 
allows customization:true, auto 
sizes cells:true, display mode:default display mode, size mode:default 
size mode}

You can use a statement like the following to set the allowed identifiers for the toolbar. In this example, all likely toolbar item identifiers are allowed.

set allowed identifiers of documentToolbar to {"compile item 
identifier", "run 
item identifier", "stop item identifier", "print 
item identifier", "customize 
toolbar item identifier", "flexible space item identifier", 
"space item identifier", 
"separator item identifier"}

You can use a statement like the following to set the default toolbar items for the toolbar. In this case, the items are Compile, Run, and Stop items.

set default identifiers of documentToolbar to {"compile item  identifier", "run  item identifier", "stop item identifier"}

You will also need to create the toolbar items themselves, and assign them to the toolbar. You can do that with statements like the following, which supply the name, label, tooltip text, and other information for the toolbar item:

make new toolbar item at end of toolbar items of documentToolbar 
with properties 
{identifier:"compile item identifier", name:"compile 
item", label:"Compile", 
palette label:"Compile", tool tip:"Compile", 
image name:"CompileScript"}

make new toolbar item at end of toolbar items of documentToolbar 
with properties 
{identifier:"run item identifier", name:"run item", 
label:"Run", palette 
label:"Run", tool tip:"Run", image name:"RunScript"}

make new toolbar item at end of toolbar items of documentToolbar 
with properties 
{identifier:"stop item identifier", name:"stop item", 
label:"Stop", palette 
label:"Stop", tool tip:"Stop", image name:"StopScript"}

Finally, you must assign the toolbar you have created to the window. Assuming you have placed this code in the awake from nib handler for the window, you can use a statement like the following:

set toolbar of theObject to documentToolbar

These examples are taken from the Simple Toolbar sample application, available in AppleScript Studio version 1.4. For related examples, see the clicked toolbar item and update toolbar item event handlers.

Version Notes

The toolbar class was added in AppleScript Studio version 1.4.

Properties of toolbar item objects

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

Events supported by toolbar item objects

You do not connect event handlers to a toolbar item. Instead, you use the toolbar handlers supported by the window class, clicked toolbar item and update toolbar item.

Examples

You can dynamically change the target and action of a toolbar item in your application or change the Cocoa method that is executed when the action is triggered, as shown in the following example:

set toolbarItem to toolbar item 1 of toolbar of window 1

set target of toolbarItem to view "webview" of scroll  view 1 of window 1

set action method of toolbarItem to "stopLoading:"

After executing these statements, when you click on the toolbar item, it sends the Cocoa method stopLoading: to the target, which in this case is a web view.

For an example that shows how to create a toolbar, how to add toolbar items to it, and how to respond to actions involving the toolbar items, see the Examples section for the toolbar class. The examples are based on the Simple Toolbar sample application, available in AppleScript Studio version 1.4.

Version Notes

The toolbar item class was added in AppleScript Studio version 1.4.

Provides access to the application’s user defaults values (commonly used to store user preferences for the application).

The user defaults system in Mac OS X stores default values as key-value pairs, where the key is simply a name string. There are several domains for default values. Default values in the global domain are accessible to any application. For example, during development, an application can set a user default value that a debugger checks to determine whether to display certain debug information. Default values in the application domain are commonly used to store preferences information for applications.

When an AppleScript Studio application is launched, it populates the application-specific defaults with all the defaults values it can obtain from both the application domain and the global domain, which contains defaults that apply to all of a user’s applications. So an application can not only add its own defaults entries, it can make changes that override the loaded global defaults within its own domain. For example, the application could change the default date format (see the Examples section for more information). Such changes will not change global defaults for other applications.

Changes to the defaults system are automatically registered periodically, so that the next time the application is launched, the new values will be present.

To access user defaults definitions in your AppleScript Studio scripts, you can use the user defaults property that is associated with every application object. Note that user-defaults is the class name, while user defaults specifies an object of that class.

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.

For more information on the defaults system, see default entry, 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).

Elements of user-defaults objects

An user-defaults object can contain the elements listed below. Your script can access most elements with any of the key forms described in “Standard Key Forms.”

Events supported by user-defaults objects

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

Examples

You can get a list of all of the named default entries with the following script statement. The list includes any entries you’ve added, as well as those provided by the Mac OS, such as “AppleKeyboardUIMode” and “NSDateFormatString”:

set defaultsNames to name of every default entry of user defaults

Similarly, you can get the values for the entries with the following statement:

set defaultsContents to contents of every default entry of user  defaults

The previous script statements access the user defaults property of the application object. For related information, see the Examples section for the default entry class.

To use the user defaults system to store and retrieve preferences, your application should follow these guidelines:

1. Attempt to make new default entries for all preferences before attempting to retrieve the user’s current settings from the defaults system. You make a default entry with a statement like the following:

   make new default entry at end of default entries

   of user defaults with properties

   {name:"defaultName", contents:"Testing"}

   You don’t have to worry that this will replace any existing user preferences, because 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. (See the default entry class for information on how to change an entry when you need to.)

   A good place to perform this step is in a will finish launching event handler connected to your application object. The application object is represented in Interface Builder by the File’s Owner instance in the Instances pane of the MainMenu.nib window. This handler is called just before the application is launched. See the Discussion section for the awake from nib event handler for information on the order in which event handlers are called on application start up.

2. Once you have set default values for preferences, you should attempt to read any existing user preferences from the user defaults system. You do so with statements like the following:

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

   Note that the returned value is Unicode text and you cannot simply cast a returned value to a boolean. For information on how to obtain a boolean value, see the Discussion section of the default entry class.

3. Your application can make new defaults entries or change existing ones as the user changes their preference settings.

4. Cocoa applications can call a method, synchronize, to specifically cause changes to be written out to the user defaults system. AppleScript Studio’s register command was originally intended to serve that purpose, but through AppleScript Studio version 1.4, the command does nothing to register defaults (although it is used as part of drag-and-drop support). However, the Cocoa framework periodically calls the synchronize method, so user defaults in AppleScript Studio applications do get registered.

   You can also use the call method command to call Cocoa’s synchronize method directly, as follows:

   call method "synchronize" of object user defaults

5. The application should update its state to reflect any preference changes made by the user.

The Archive Maker application, available at <Xcode>/Examples/AppleScript Studio starting with AppleScript Studio version 1.1, provides a detailed example of how to use the user defaults system to work with user preferences.

Version Notes

The user-defaults class was added in AppleScript Studio version 1.1.

Starting with AppleScript Studio version 1.2, you can successfully use lists as a data type with default entries. In AppleScript Studio version 1.1, you could initially assign the contents of a default entry to a list and read it back, but trying to assign a new list to the contents of the default entry would not provide the correct result.

The Archive Maker application, available at <Xcode>/Examples/AppleScript Studio, was first distributed with AppleScript Studio version 1.1.

Prior to AppleScript Studio version 1.2, this document listed register as a command supported by the user-defaults class. In fact, using the register command with a user-defaults object does nothing.

Represents a window on screen.

A window object manages an on-screen window, coordinating the display and event handling for its views. You can create and set up windows in Interface Builder, but you can also control many window properties directly in scripts. Figure 2-8 shows a simple window.

Figure 2-8  A simple window

When you create an AppleScript Studio application from the AppleScript Application template in Xcode, the application automatically contains a default window instance, stored in the MainMenu.nib nib file in the project’s Resources group (shown in Figure 2-9). You use this application template for applications that don’t need documents.

When you create an application from the AppleScript Document-based Application template, the application automatically contains a default window instance, stored in the Document.nib nib file. Document-based applications are set up to allow the user to create windows for multiple document instances.

Any application is free to define additional window nibs and to use them to create one or more window instances. You will find several predefined window objects (for windows, panels, and drawers) in the Cocoa-Windows pane of Interface Builder’s Palette window, shown in Figure 3-3.

In Interface Builder’s Info window, you can set many attributes for windows, such as the kind of button controls it contains (Miniaturize, Close, and Resize), its size and resizing properties, and whether it is visible at launch time. To make a floating window (or utility window), for example, you use the window instance labeled “Panel” in Figure 3-3, then open the Attributes pane of the Info window and select the “Utility window” checkbox. In the version of Interface Builder distributed with Mac OS X version 10.2, you can even set the Textured Window attribute to specify the brushed-metal look for a window.

Figure 2-9  The Files list in the Groups & Files list in a non-document AppleScript Studio project

In some cases, such as for a progress panel, you may only instantiate the window once, then show and hide it as needed (using either the show and hide commands, or by directly setting the window’s visible property).

In other cases, you may want to instantiate a new window repeatedly and free it when the user is done with it (which you can do by setting the window’s released when closed property in Interface Builder). The Mail Search application, available at <Xcode>/Examples/AppleScript Studio, provides nibs and code for creating a one-time status panel, as well as a message window that is instantiated multiple times. (Prior to AppleScript Studio version 1.1, Mail Search was named Watson.)

For more information, see the document Window Programming Guide for Cocoa.

Properties of window objects

In addition to the properties it inherits from the responder class, a window 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 window objects

A window object can contain the elements listed below. Your script can access most elements with any of the key forms described in “Standard Key Forms.”

Commands supported by window objects

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

Events supported by window objects

A window object supports handlers that can respond to the following events:

Examples

Applications may need to perform additional initialization before showing the main window. One place you can do so is in the launched event handler, which is called when the application is finished launching (and after the awake from nib handler—another possible choice for performing additional initialization).

You can set a window’s visible property to false in Interface Builder, then set it to true in the launched handler (as shown here) to show the window. For a more complete example, see the Assistant sample application, available at <Xcode>/Examples/AppleScript Studio (starting with AppleScript Studio version 1.1). The startup-time calling order for application event handlers, including the launched handler, is listed in the description for the awake from nib event handler.

This script assumes the window has the AppleScript name “main”, which you set in the AppleScript pane of Interface Builder’s Info window.

on launched theObject

    -- Perform any initialization before making window visible

    -- ...

    set visible of window "main" to true

end launched

Many common user interface classes (including subclasses of the control class) inherit from the view class, which has a window element that identifies the window that contains the view. AppleScript Studio event handlers typically have a parameter that specifies the object for which the handler is called. If the object is an instance of a class that inherits from view (as it generally is), you can conveniently do the following, shown in a clicked handler, to get access to the current window:

on clicked theObject

    set theWindow to window of theObject

    --Use the reference to the enclosing window as needed in the  handler.

end clicked

To give the keyboard focus to an object such as a text field, you set the first responder property of its window to the object; for example, you could use the following line to give keyboard focus to a named text field:

set first responder of window 1 to text field "myText"  of window 1

The following script statements set a window’s background color to green and make the new color visible:

set background color of window "main" to {0, 65535, 0}

tell window "main" to update

The following script shows how to set a window’s minimized image. The script first chooses an image file, then loads the image and sets the minimized image for the window.

tell application "StudioTest"

    set imagePath to POSIX path of (choose file)

    set minImage to load image imagePath

    set minimized image of window 1 to minImage

end tell

Discussion

The stacking of windows depends on window level— windows at a higher level are shown in front of those at a lower level; windows at the same level can be displayed in front of or behind each other, but they cannot be displayed behind a window at a lower level.

Through version 1.3 AppleScript Studio does not define enumerated constants for setting window level, but as a convenience, Table 2-1 shows the current values for Cocoa’s window level constants. You can use the values, but not the constants, in your scripts. Be aware that using these hard-coded values is not guaranteed to work in future versions of AppleScript Studio.

Version Notes

The toolbar property and the clicked toolbar item and update toolbar item events were added in AppleScript Studio version 1.4.

Starting in AppleScript Studio version 1.3, you can access many of the properties that are defined for the window class in Cocoa’s Standard suite, such as titled.

Starting in AppleScript Studio version 1.3, the first responder property returns an object such as current field editor of window 1. Previously, it did not return any useful object.

The miniaturized property is not supported, through AppleScript Studio version 1.4:

The clip view element is not supported, through AppleScript Studio version 1.4.

Support for the current field editor property was added in AppleScript Studio version 1.2.1.

Support for the following properties was added in AppleScript Studio version 1.2.1 (you could not use them in version 1.2):

• auto display

• maximum size

• minimum size

• needs display

Support for the background color property was added in AppleScript Studio version 1.2.

Support for the center, hide, and show commands was added in AppleScript Studio version 1.2.

Support for the will open and will zoom event handlers was added in AppleScript Studio version 1.2.

Support for the Textured Window attribute, which you can use to specify the brushed-metal look, was added to the version of Interface Builder distributed with Mac OS X version 10.2.