Retired Document
Important: This document may not represent best practices for current development. Links to downloads and other resources may no longer be valid.
Mail Search Tutorial: Connect the Interface
Mail Search is a fairly complex AppleScript Studio application that searches for specified text in messages in the Mac OS X Mail application. In previous chapters you’ve designed the application, created a project, and built the user interface with the Interface Builder application. In this chapter, you connect objects in the interface to handlers in the application’s script file.
This chapter assumes you have completed previous Mail Search tutorial chapters.
Connect the Interface
Now that you’ve built Mail Search’s interface, you need to perform additional steps in Interface Builder to connect objects in the interface to event handlers in the project. In Event Handlers in Mail Search, you identified handlers that would be needed for various objects. You don’t need any handlers for the status dialog or the message window, but you do need to make connections for Mail Search’s application object and search window. For the search window, you also need to connect data source objects to provide data to the search results and mailbox views. (A data source object, described in more detail below, is a special object supplied by AppleScript Studio that provides row and column data to a table or outline view.) The next sections describe how to make these connections.
Connect the Application Object
The application object in an AppleScript Studio application is represented by the File’s Owner object in the Instances tab in the MainMenu.nib window. This object is described in Interface Creation and shown in Figure 8-1. Your application can use this object to connect handlers that are called at various interesting times, such as when the application is launched or activated. For a look at the available handlers, see Figure 8-2.
Mail Search uses the will finish launching
handler to perform necessary initialization after the application has created its interface but has not yet completed launching. To connect this handler, perform the following steps:
Select the File’s Owner object in the Instances tab in the MainMenu.nib window, as shown in Figure 8-1.
Choose Show Info from the Tools menu or type Command-Shift-I to open the Info window. Use the pop-up menu at the top of the window to display the AppleScript pane. Then click the disclosure triangle to reveal the handlers in the Application group. The result is shown in Figure 8-2.
To connect the handler, perform the following steps:
Select the
will finish launching
checkbox.Select the file
Mail Search.applescript
in the Script list.Click the Edit Script button.
When you click the Edit Script button, Interface Builder inserts an empty
will finish launching
handler in the script file and opens the file in an Xcode editor window. The handler is shown in Listing 8-1. You add statements to this handler in Application Object Handler.Listing 8-1 A new handler declaration for the
will finish launching
handleron will finish launching theObject
(*Add your script here.*)
end will finish launching
When you create a new event handler for an object, you should also insert a comment that specifies which object initiates calls to the handler. In this case, you could add the line
(* "Called from the application object just prior to completion of launching." *)
. In some cases, more than one object of the same type may be connected to the handler. This situation is described in Deciding How Many Script Files to Use.To verify that the handler is correctly connected, you can replace the comment
(*Add your script here.*)
withdisplay dialog "In the will finish launching handler."
You can build and run the application by typing Command-R, choosing Build and Run from the Build menu, or clicking the Build and Run button. You should see the dialog after the application launches.
As you work through additional sections that connect handlers, you can use the same techniques to verify that the handlers are working.
As always, save the nib file after completing your changes.
As noted in Add the Message Window to the Nib File, the first time you make a change in the AppleScript pane, Interface Builder adds a new instance named AppleScript Info to the nib window.
Connect Interface Items in the Search Window
The search window is the main place where you connect Mail Search’s interface to event handlers. You also need to connect data source objects to provide data to the search results and mailbox views. To make these connections, perform these steps, which are described in detail in the sections that follow:
Connect event handlers to the search window.
Connect an event handler to the text field.
Connect an event handler to the find button.
Connect an event handler to the search results view.
Connect data source objects to the mailboxes view and the search results view.
Connect the Search Window
As described in Plan the Code, Mail Search needs to know when a search window is opened, activated, or closed. To add these handlers, perform the following steps:
If the Document.nib file is not already open in Interface Builder, open it.
Select the Mail Search instance in the nib window.
Choose Show Info from the Tools menu or type Command-Shift-I to open the Info window. Use the pop-up menu at the top of the window to display the AppleScript pane. Then click the disclosure triangle to reveal the handlers in the Window group. The result is shown in Figure 8-3.
To connect the handlers, perform the following steps:
Select the checkboxes for
became main
,will close
, andwill open
.To connect the handlers, select the checkbox for the script file
Mail Search.applescript
in the Script list.Click the Edit Script button.
When you click the Edit Script button, Interface Builder inserts empty handlers for the three event handlers in the script file and opens the file in an Xcode editor window. The handlers are shown in Listing 8-2. You add statements to these handlers in Search Window Handlers.
Listing 8-2 New handler declarations for several handlers
on became main theObject
(*Add your script here.*)
end became main
on will close theObject
(*Add your script here.*)
end will close
on will open theObject
(*Add your script here.*)
end will open
To verify that the handlers are correctly connected, you can add
display dialog
statements, as described in Connect the Application Object. You may also wish to add comments that thetheObject
parameter will be a search window object.
Connect the Text Field
A user types text to search for in the text field in the search window. In this section, you connect an action handler to the text field so that when a user presses the Enter key, Mail Search initiates a search. To add this handler, perform the following steps:
In Interface Builder, open the Info window for the Mail Search window instance and display the AppleScript pane, as described in Connect the Application Object.
Select the text field in the search window.
Click to open the Action group, then select the checkbox for the
action
handler. The result is shown in Figure 8-4.Action handlers get their name from a Cocoa concept known as target-action. In this case, pressing the return key can cause a text field object to send an action message to its target (in Cocoa, the target is a method, but here it is a handler). Other examples of action events are
clicked
anddouble-clicked
.Connect the handler as in previous sections by selecting the file
Mail Search.applescript
in the Script list, then click the Edit Script button to open the script in an Xcode editor window.The resulting handler declaration is shown in Listing 8-3. You add statements to this handler in Text Field Handler.
Listing 8-3 A new
action
handler for a text fieldon action theObject
(*Add your script here.*)
end action
To verify that the handler is correctly connected, you can add
display dialog
statements, as described in Connect the Application Object. You may also wish to add a comment that thetheObject
parameter will be a text view object.
Connect the Find Button
A user clicks the find button in Mail Search’s search window to initiate a search. To enable this behavior, you connect a clicked
handler for the find button. To do so, perform steps similar to those you’ve used in previous sections:
select the find button
open the Info window
display the AppleScript pane
select the checkbox for the
clicked
handlerTo connect the handlers, select the checkbox for the script file
Mail Search.applescript
; the result is shown in Figure 8-5.click the Edit Script button to insert a
clicked
handler declaration in the script file
You can examine the resulting handler declaration in Xcode. You add statements to the handler in Find Button Handler.
Connect the Search Results View
Mail Search uses a table view to show search results—the found messages that contain the search text. When a user double-clicks a found message in the table view, Mail Search displays the message in a separate window. To support this behavior, the table view object needs a double-clicked
handler.
To connect a double-clicked
handler for the table view in the search window, perform the same steps you’ve used in previous sections:
click, then double-click (and double-click again if necessary) to select the table view
open the Info window
display the AppleScript pane
select the checkbox for the
double-clicked
handlerselect the checkbox for the script file
Mail Search.applescript
click the Edit Script button to insert a
double-clicked
handler declaration in the script file
The result before clicking the Edit Script button is shown in Figure 8-6.
In Figure 8-6, the Action group and clicked checkboxes have dashes while the double clicked checkbox has a checkmark. A handler checkbox (such as the double clicked checkbox) can have one of three states:
Empty: Indicates there is no handler with that name in the currently selected script.
Dashed: Indicates that there is an event handler with that name in the currently selected script, but that the current object isn’t connected to it (so presumably some other object is).
Checked: Indicates there is an event handler with that name in the currently selected script (or that such a handler will be added when you edit the script), and it is (or will be) connected to the current object in the Info window.
A group checkbox (such as the Action group checkbox) can have one of the same three states:
Empty: Indicates no event handler in that group is checked.
Dashed: Indicates at least one event handler in that group is checked.
Checked: Indicates every event handler in that group is checked.
You can examine the resulting double-clicked
handler declaration in Xcode. You add statements to the handler in Search Results Table View Handler.
Provide a Data Source Object for the Mailboxes View
Mail Search uses an outline view to display a list of all mailboxes from all accounts. An outline view can display hierarchical data, similarly to the way the Finder displays directories and files in a list view. The outline view needs to be connected to a data source object—a special object supplied by AppleScript Studio that provides row data (in this case, mailbox names) to a table or outline view.
To create a data source object and connect it to the outline view in the search window, perform these steps (assuming you still have the search window from the Document.nib
file open in Interface Builder, along with the Info window):
Click the AppleScript button in the Palette window toolbar to select the AppleScript pane. There currently is a single image in that pane, representing a data source object.
Drag a data source object from the Palette window to the Document.nib window. The result is shown in Figure 8-7. The letters “ASK” come from AppleScriptKit, the framework that defines this data source.
Double-click the name (“ASKDataSource”) and change it to “Mailboxes”.
Double-click to select the outline view in the search window. Be sure the view appears as in Figure 7-42, so that you know it’s selected.
Press and hold the Control key and drag from the outline view to the data source object in the Document.nib window. This step is shown in Figure 8-8.
At this point, the Info window displays the Connections pane. Double-click the dataSource outlet. This connects the outline view to the data source object. The result is shown in Figure 8-9.
Even though you named the data source “Mailboxes,” the destination of the connection in Figure 8-9 is still “ASKDataSource.”
Mail Search also needs an identifier for the column header (which has the column title Mailboxes) in the outline view. Data source objects use identifiers specify columns and rows, since they can be shuffled. To provide an identifier, perform these steps:
With the outline view still selected in the search window, click to select the column header.
Choose the Attributes pane in the Info window.
Type “mailboxes” in the Identifier text field. The result is shown in Figure 8-10.
Don’t forget to periodically save the nib file.
Examining an Object Hierarchy in the Nib View
In Group the Outline View and Table View in a Split View, you saw that once you have a series of deeply nested views, it can become difficult to select one of them. However, Interface Builder provides a mechanism to make it easier to display view hierarchies and connections, and to select nested objects. That mechanism consists of displaying the nib window in outline view. In this case, “outline view” refers to a mode of window display, not an outline view object.
Figure 8-11 shows the Document.nib window after connecting a data source for the outline view object.
By clicking the small outline view icon on the right-hand side of the view, you can display contents of the window in outline view, as shown in Figure 8-12.
In this case, the window shows the expanded hierarchy for the search window. Instead of interface objects (such as buttons), it shows the Cocoa classes for the objects (NSButton). You can view the hierarchy for any object in the nib window. Double-clicking an object (such as NSOutlineView (Mailboxes)) in the Instances tab selects the object in its window, providing a simple way to select a nested item such as an outline view within a scroller within a split view. If the Info window is open, it also displays the object in the Info window.
To examine the connections for an object, you click the small triangles next to it in the right-hand column. For example, Figure 8-13 shows the connections for the NSOutlineView object (the mailboxes outline view).
Provide a Data Source Object for the Search Results View
Mail Search uses a table view to display the messages found by a search. The table includes columns for the message sender, the message subject, and the message mailbox. The table view needs to be connected to a data source object that provides row data to the table view.
To create a data source object and connect it to the table view in the search window, perform the same series of steps you used to connect a data source to the outline view in Provide a Data Source Object for the Mailboxes View. Assuming you still have the search window from the Document.nib
file open in Interface Builder, along with the Info window, the steps include:
Drag a data source object from the AppleScript pane in the Palette window to the Document.nib window.
Change the name of the data source object from “ASKDataSource” to “Messages”.
Select the table view in the search window, then press and hold the Control key and drag from the table view to the Messages data source object in the Document.nib window.
Double-click the dataSource outlet in the Connections pane of the Info window. to connect the table view to the data source object. The result is shown in Figure 8-14.
You also need to provide an identifier for each column header (the column headers are titled From, Subject, and Mailbox) in the table view. To do so, perform these steps:
With the table view still selected in the search window, click to select the column header.
Choose the Attributes pane in the Info window.
Type the name (either “from,” “subject,” or “mailbox”) in the Identifier text field. Save your results after typing each new identifier. The result for the From column header is shown in Figure 8-15.
As always, save the Document nib file after completing your changes.
You have now completed connecting the interface for the Mail Search application.
Copyright © 2001, 2011 Apple Inc. All Rights Reserved. Terms of Use | Privacy Policy | Updated: 2011-01-07