Create a Nib File

To create a new nib file, perform these steps:

1. Open the Mail Search project in Xcode.

2. Double-click one of the nib file icons (such as MainMenu.nib) in the Files list in the Groups & Files list to start Interface Builder.

3. In Interface Builder, choose New from the File menu. Interface Builder opens the dialog shown in Figure 7-5.

   

4. Select Empty in the Cocoa section and click New. The new nib file is shown in Figure 7-6. The icons in the Instances pane visible in Figure 7-6 are described in Interface Creation.

   

5. Choose Save As from the File menu and navigate to the English.lproj directory in your Mail Search project. Save the file as Message.nib (you just type “Message” and Interface Builder adds the extension). You will be prompted for a nib file format. Your three choices are:

   • Pre-10.2 format: Use this if you want your application to run in Mac OS X versions earlier than 10.2.

   • 10.2 and later format: Use this if you want your application to run in Mac OS X version 10.2 and later.

   • Both formats: Use this if you want to run your application in all versions of Mac OS X.

   Select the option for 10.2 and later.

6. After saving the file, you should be prompted to add the file directly to the Mail Search project. Click Add to add the nib file to the project.

   If for any reason you don’t have the opportunity to automatically add the new nib file to the Mail Search project, you can add it directly by opening the project in Xcode, and dragging it into the Resources group in the Groups & Files list, which is shown in Figure 7-1, or by choosing Add Files from the Project menu, navigating to the Message.nib file, and choosing that file. If you use Add Files, you should then drag the icon for the nib file to the Resources group.

Add the Message Window to the Nib File

To add a message window to the nib file, perform these steps:

1. In Interface Builder, click the Cocoa Windows button in the Palette window toolbar. The Palette window, showing the Cocoa Windows palette, is shown in Figure 7-7.

   

2. Drag an instance of Window from the Palette window to any convenient space on your desktop. You’ll see a window that looks similar to the image you dragged from the Palette window. You’ll also see an icon for the window added to the Message.nib window, as shown in Figure 7-8.

   

3. Double-click the word “Window” in the window instance in the nib window and type “Message” to change the instance name.

4. You need to provide an AppleScript name for the window too, so you can access it in scripts. To do so, click in the nib window to select the Message window instance, then 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. The result is shown in Figure 7-9.

   

   To name the window, simply type “message” in the Name field. Remember that this is the object’s AppleScript name, which you can use in a script to identify the object. It is a different entity than the name of the window object in the nib window, and is also different from the window’s title in the running application.

   If it makes sense, you can use the same AppleScript name for objects of different types in the same window (such as a button and a text field), or for objects of the same type (such as buttons) in different windows. However, if you name two buttons in the same window “button,” you won’t be able to differentiate between them by name in an application script.

   

5. Save the changes to the Message.nib file. You should save changes periodically as you work through this tutorial.

   When you are finished with a nib file, you should also close its window to avoid a clutter of nib-related windows as you work through the tutorial.

Set Up Interface Objects in the Message Window

To set up interface objects in the message window (in this case, there is just one object, a text view), perform these steps:

1. Click the Cocoa Text Views button in the Palette window toolbar. The Cocoa-Text palette is shown in Figure 7-11.

   

2. Drag a text view object (the item containing Latin text and one scroll bar) from the Palette window to the message window you created previously. Drag it to the top-left corner of the window (below the title bar). Interface Builder provides feedback to aid in alignment and resizing, as shown in Figure 7-12. The text view is actually enclosed within a scroll view with one scroll bar.

   

3. Drag the bottom-right corner of the text view object to resize it until it fills the whole window. Again, you get resizing feedback from Interface Builder. The result is shown in Figure 7-13. The small dots below the title bar and just inside the other sides of the window indicate that the text view is still selected.

   

4. To provide an AppleScript name for the text view, open the Info window and display the AppleScript pane. The result is similar to Figure 7-9. Type “message” in the Name field.

5. To support Undo in the text view, you’ll have to modify its default attributes. While the Info window is still open, use the pop-up menu at the top of the window (or type Command-1) to display the Attributes pane.

6. In the Options section, select the “Undo allowed” checkbox. The result is shown in Figure 7-14.

   

7. As always, save the nib file after completing your changes.

Adjust the Size and Attributes of the Status Dialog

You need to change certain window attributes to use the window as a pane. You also need to reduce the size of the status dialog so that it looks appropriate when it appears below the title bar of the search window. The previously designed status dialog, shown again in Figure 7-15, is smaller than the minimum size for a default window in Interface Builder, so you have to adjust the minimum size.

To make these changes, perform the following steps:

1. Select the Status window instance in the StatusPanel.nib window, then display the Attributes pane in the Info window.

2. In the Window Title field, change the title from Panel to Status. The result is shown in Figure 7-16.

   

3. With the Info window still open, use the pop-up menu at the top of the window to display the Size pane. The result is shown in Figure 7-17.

   

4. In the Min Size section, type 110 for the width and 50 for the height. (These values just have to be at least as small as the values you’ll enter in the next step.)

5. In the Content Rect section, type 260 for the width and 75 for the height. The resized status dialog that results from these changes is shown in Figure 7-18.

   

Set Up a Progress Bar

To set up a progress bar in the status dialog, do the following:

1. Click the Controls button in the Palette window toolbar. The Cocoa-Controls palette is shown in Figure 7-19.

   

2. Drag a progress bar object (the horizontal striped cylinder near the bottom of the window) from the Palette window to the status dialog you just created and position it as shown in Figure 7-20.

   

3. Select the progress bar, then grab the lower-right corner and resize it. Use Interface Builder’s feedback to help you resize the progress bar, as shown in Figure 7-21.

   

4. You need to provide an AppleScript name for the progress bar so you can access it in scripts. To do so, select the progress bar, then open the Info window to the AppleScript pane. The result is similar to Figure 7-9.

   To name the progress bar, simply type “progress” in the Name field.

Set Up a Text Field

To set up a text field to display progress text in the status dialog, do the following:

1. Drag a text field object (a rectangular, unlabeled field with a white background) from the Cocoa-Text palette (shown in Figure 5-10) in the Palette window to the status dialog. Position the text field above the progress bar you added in a previous step. Use Interface Builder’s feedback to help you align the left side of the text field with the progress bar and just above it, as shown in Figure 7-22.

   

2. Select the text field, then grab the middle selection handle on the right and resize the field, as shown in Figure 7-23.

   

3. You don’t want a user to enter text in the text field and you do want the field (though not the status messages that get written to it) to be invisible. To choose the correct settings, select the text field and open the Info window to the Attributes pane. The result is shown in Figure 7-24.

   

   Now make these adjustments, in the order shown:

   1. Deselect the Editable checkbox.

   2. Deselect the Selectable checkbox.

   3. Select the Small option in the Size pop-up menu.

   4. In the Border section, click the button on the left to select no border.

   5. In the Backgrnd Color section, deselect the Draw checkbox.

   6. In the Layout section, select the Wraps radio button. The resulting invisible text field is shown in Figure 7-25.

   

4. You need to provide an AppleScript name for the text field so you can access it in scripts. To do so, display the AppleScript pane in the Info window, then type “statusmessage” in the Name field.

5. Save all the changes to the StatusPanel.nib file.

Set Up a Popup Button

Mail Search uses a popup button to provide a pop-up menu of search locations (in the To, From, or Subject fields of messages or in the message contents). To set up a popup button in the search window (the Mail Search window instance in the Document nib), perform these steps:

1. With the search window still open as shown in Figure 7-26, drag a popup button from the Cocoa-Controls palette in the Palette window (shown in Figure 7-19) to the search window. Use the automatic feedback to position the button in the top left corner of the window. As the button nears the corner, Interface Builder provides dashed feedback lines to help align the object according to the Aqua guidelines, as shown in Figure 7-27.

   

2. You need to provide menu items in the popup button for the possible search locations: Contents, Subject, To, and From. Double-click the button to reveal its default contents, as shown in Figure 7-28.

   

3. To add a fourth item, simply choose Copy from the Edit menu (copying the selected Item1) and then Paste from the Edit menu. The result is shown in Figure 7-29.

   

4. To rename the first item, double-click it, type “Contents” as the new text, then tab to the next field. The result is shown in Figure 7-30.

   

5. Rename the remaining three items as Subject, To, and From. Figure 7-31 shows the renamed items.

   

6. Open the Info window for the popup button to the Attributes pane and select the Small checkbox in the Options section. The result is shown in Figure 7-32.

   

7. Adjust the size of the button so that it is just large enough for the item with the longest name, Contents. To do so, select the popup button, then drag the middle selection handle on the right side. As you resize, Interface Builder again provides alignment guides, as shown in Figure 7-33.

   

8. You should also follow the same steps you used in Set Up a Progress Bar to display the AppleScript pane in the Info window, then type “where” in the Name field to supply an AppleScript name for the popup button.

Set Up a Text Field

Mail Search uses a text field to allow a user to provide text to search for. To set up a text field in the search window, perform these steps:

1. Drag a text field from the Cocoa-Text palette in the Palette window to the search window. Use the automatic feedback to position the field in the top left corner of the window next to the previously placed popup button, as shown in Figure 7-34.

   

2. To resize the text field, select it, then grab the middle selection handle on the right. Stretch the text field across the window, leaving room on the right for the find button. The result is shown in Figure 7-35

   

3. While the text field is still selected, open the Info window to the Attributes pane. In the Send Action On section, click the radio button for Enter only. With this setting, the Mail Search application begins searching if a user types search text and presses the Return or Enter keys, in addition to when a user clicks the find button. The keystrokes only initiate a search when the text field has the focus. (See Setting the Keyboard Focus for related information.)

4. In the same window, select the Small option in the Size pop-up menu, as you did previously for the popup button.

5. While you still have the Info window open for the text field, display the AppleScript pane, then type “what” in the Name field to supply an AppleScript name for the text field.

Set Up a Button

Mail Search uses a button to initiate a search. To set up a button in the search window, perform these steps:

1. Drag a round button from the Cocoa-Controls palette in the Palette window to the search window. Use the automatic feedback to position the button in the top right corner of the window next to the previously placed text field, as shown in Figure 7-36.

   

2. Open the Info window for the button, display the AppleScript pane, then type “find” in the Name field to supply an AppleScript name for the button.

3. In Create a Project, you added an image file named find.tiff to the Mail Search project. That image file contains an image of a magnifying glass that you will now add to the button. With the Info window still open from the previous step, display the Attributes pane, then type “find” (the name of the image file, without the extension) into the “Icon:” field, as shown in Figure 7-37.

   

   Alternatively, you can simply drag the image from the Images pane in the nib window to the find button.

   To center the icon, click the middle button in the top row under “Icon Position” in the Info window shown in Figure 7-37. The result is shown in Figure 7-38.

   

4. You have a couple of options for correctly positioning the button in relation to the right side of the window. You can drag the button to the right and use Interface Builder’s alignment guides to align it with the edge of the window, then expand the text field toward the button until it is also aligned. Or you can resize the window itself, moving the right edge toward the button, again using Interface Builder’s alignment guides to align the window edge. Figure 7-39 shows the latter process.

   

Set Up an Outline View

Mail Search uses an outline view to show the Mail folders that can be searched. It can be difficult to determine in Interface Builder whether you have selected an outline view or the scroll view that contains it. Single-clicking selects the containing scroll view, while double-clicking selects the outline view. The tutorial steps that follow describe visual cues to determine which view is selected.

To be certain whether an outline view or the containing scroll view is selected, you can also open an Info window to the AppleScript pane. When that pane is displayed, the window title for the Info window shows the class of the selected item: either NSScrollView if the scroll view is selected, or NSOutlineView if the outline view is selected (or NSTableView when a table view is selected).

As a final alternative, you can display the objects in a nib window in outline view (as described in Examining an Object Hierarchy in the Nib View), find the object (either an outline view, a scroll view, or any other object) in the view hierarchy, and double-click the object to select it in its window and to display it in the Info window.

To set up an outline view in the search window, perform these steps:

1. Drag an outline view from the Cocoa-Data palette in the Palette window to the search window. The outline view is in the upper-left corner with “Name” and “Description” columns.

   Use the automatic feedback to position the outline view in the top left corner of the search window, below the previously placed popup button. Align it with the left side of the window, as shown in Figure 7-40.

   When you release the outline view, it takes on a more generic format, as shown (after resizing) in Figure 7-41.

   

2. To resize the outline view, click to select it, then drag the lower-right corner. The text field should stretch all the way across the window and about half the way down (leaving room for a table view to display the search results), as shown in Figure 7-41.

   

3. By default, a new outline view has two columns, but you only need one column to display mailboxes. To change the number of columns, double-click the outline view. The result is shown in Figure 7-42.

   

   Now open the Info window to the Attributes pane. The result is shown in Figure 7-43. Make the following changes to the default settings:

   1. In the Allow section, select the Multiple Selection checkbox.

   2. In the Display section, deselect Horizontal Scroller.

   3. In the Options section, select the “Autoresizes Columns to fit” checkbox; deselect the Allows Reordering checkbox.

   4. Set the row height to 14.

   5. Set the number of columns to 1.

   

4. While you still have the Info window open for the outline view, display the AppleScript pane, then type “mailboxes” in the Name field to supply an AppleScript name for the outline view.

5. To add a column title to the outline view, double-click the view to select it, then double-click the title row at the top. You can then type “Mailboxes” for the column title. The result is shown in Figure 7-44.

   

6. Mail Search also requires an AppleScript name for the scroll view that contains the outline view. To provide this name, single-click the outline view, open the Info window (for the scroll view) to the AppleScript pane, then type “mailboxes” in the Name field. The result is shown in Figure 7-45.

   

7. If you haven’t saved the Document.nib file recently, do so now.

Set Up a Table View

Mail Search uses a table view to show search results—the messages that contain the search text.

To set up a table view in the search window, perform these steps:

1. Drag a table view from the Cocoa-Data palette in the Palette window to the search window. The table view is in the lower-left corner with “Address” and “Name” columns.

   Use the automatic feedback to position the table view below the previously placed outline view. Align it with the left side of the window, as shown in Figure 7-46.

   When you release the table view, it takes on a more generic format.

   

2. To resize the table view, click to select it, then drag the lower-right corner. The text field should stretch all the way across the window and all the way to the bottom.

3. By default, a new table view has two columns, but you need three columns (for From, Subject, and Mailbox). Use the same steps described in Set Up an Outline View to open the Info window for the table view. Make the following changes to the default settings:

   1. In the Display section, deselect the Horizontal Scroller checkbox.

   2. In the lower options section, select the “Autoresizes Columns to fit” checkbox.

   3. Set the row height to 14.

   4. Set the number of columns to 3.

      The resulting Info window is shown in Figure 7-47.

      

4. While you still have the Info window open for the table view, display the AppleScript pane, then type “messages” in the Name field to supply an AppleScript name for the table view.

5. To resize a column in the table view, double-click the view to select it, then position the cursor over the column divider in the title row. The cursor changes to indicate when you can resize. Simply click and drag to resize a column.

   Start by moving the right-most column divider to the left, which reduces the size of the middle column. Then move the left-most divider to the right, increasing the size of the left column. Adjust the column sizes as needed so that the Subject and Mailbox columns are wider than the From column.

6. To add column titles to the table view, use the same steps described in Set Up an Outline View. You can tab from column title to column title as you add titles. The result is shown in Figure 7-48.

   

7. Mail Search also requires an AppleScript name for the scroll view that contains the table view. To name the scroll view, follow the same steps you used in Set Up an Outline View:

   1. Single-click the table view to select the scroll view that contains it.

   2. In the AppleScript pane of the Info window for the scroll view, type “messages” in the Name field.

8. If you haven’t saved the Document.nib file recently, do so now.

Group the Outline View and Table View in a Split View

Mail Search uses a split view to combine the outline and table views you’ve previously installed. The split view allows a user to adjust the size of either view, depending on how much space they want to devote to the available mailboxes (in the outline view) and how much to the found messages (in the table view).

To group the outline view and table view in a split view, perform these steps:

1. In the search window you have been working on, click to select the table view. The view should have selection handles (small dots) on all sides, and you should see “NSTableView Info” as the title of the Info window. Shift-click to also select the outline view. The outline view should have selection handles and the Info window should display “Multiple Selection” in the Attributes pane.

2. In the Layout menu, choose Split View in the “Make subviews of” submenu to make these two views into subviews of a split view. The result is shown in Figure 7-49. The distinguishing feature of a split view is the handle for modifying the relative sizes of the contained outline and table views.

   

3. Mail Search also requires an AppleScript name for the split view that contains the outline and table views. To name the split view, you follow similar steps to those listed in Set Up an Outline View:

   1. Single-click to select the split view. You may have to click on another object, then click the split view to select it.

   2. In the AppleScript pane of the Info window for the split view, type “splitter” in the Name field.

4. Congratulations—you’ve completed Mail Search’s user interface. If you haven’t saved recently, do so now.