An Orientation

When you use Interface Builder, its windows--and the windows of the application under construction--share the screen. Figure 3-1 gives you an idea how this looks.

Figure 3-1

Interface Builder's windows frame an area of the workspace where you build your application. At the upper left is the main menu, which gives you access to Interface Builder's tools and commands, and at the upper right is the Palettes window.

The Palettes window is the source of objects (NSButtons, NSSliders, NSWindows, and so on) that you can drag into your application. The Palettes window is described in detail in "Using the Palettes" on page 3-27.

Below the Palettes window is the Inspector panel. You use this panel to set the attributes of an object, to connect it to other objects, and to review the attachments between objects and help messages. The Inspector panel is described in "The Inspector Panel" on page 3-21.

At the bottom left is the nib file window. The nib file window displays your application's top-level objects (its windows, main menu, and so on) and gives you access to the image, sound, and class resources that are available to your application. For a description of the nib file window and its various displays, see "The Nib File Window" on page 3-10.

Building an Application with Interface Builder

The Application Kit defines a library of user-interface objects that you can select from for your application. Interface Builder makes the selection process a graphical one: You simply drag the object you need from the Palettes window into the application you are building. By building an application in this way, you can be sure that its interface will work properly and will, in a broad sense, conform to the interface standards for OpenStep applications. See "Using the Palettes" on page 3-27 for a description of the Palettes window and the objects available to you on the OpenStep palettes.

Specifying Object Attributes

Once an object is added to your application, you can adjust the values of many of its instance variables directly. For example, to change the size of a button, you drag one or more of its sides to a new position. Changing the image on the screen changes the value of the NSButton object's frame instance variable. For attributes that are not easily represented graphically, Interface Builder provides the Inspector panel that lets you set the values for particular instance variables.

You set the maximum and minimum values of a slider with the NSSlider Size inspector, for example. The Inspector panel is described in "The Inspector Panel" on page 3-21.

Interconnecting Objects

Interface Builder also lets you interconnect objects so that they can communicate with one another. For example, a button can be connected to the window it is displayed in so that when the button is clicked on, the window closes. Such connections are made through an object's outlets and actions.

An outlet is an instance variable that identifies another object in the application. Common examples of outlets include an NSControl's target or an NSApplication or NSWindow object's delegate. An NSTextField object may have an instance variable nextText that points to another NSTextField object.

An action is a message that one object sends to another when it receives a certain message of its own. For example, an NSButton object sends an action messages when it receives the performClick: message (when the user clicks on the button).

Adding Code to Your Application

The objects in the Application Kit are general-purpose and fill the needs of a wide cross-section of applications. What makes your application unique is the code you write. For example, the Application Kit provides the NSButton objects and other NSView objects you need to implement an interface for a calculator, but you have to create the computational engine. Interface Builder helps you declare classes that encapsulate the code that is unique to your application.

Interface Builder and the Objective C language encourage a style of programming that puts your application's unique code in one or more objects of your own design. The application's user-interface objects handle routine business, such as displaying the main menu or hiding the application, and also serve to interpret the user's actions for the objects you design. If the user clicks on the calculator's Add button, the Application Kit highlights the button and then sends a message to your calculator object to perform the addition.

Using this style of programming, your application will generally contain a number of standard Application Kit objects and one or more subclasses of NSObject and NSView. Most often, the subclasses of NSObject embody the logic that is unique to your application, and the NSView subclasses contain the drawing code that is unique to your application. You will rarely need to create subclasses of other Application Kit classes.

Composing the Interface

To compose your application's interface, you just drag objects off a palette, drop them on a window or other "surface," and then manipulate and arrange them into an effective user interface. This section introduces you to Interface Builder by showing how to compose the elements of your interface.

Opening a Nib File

To open your application's nib file, do one of the following:

• Double-click a nib file in Project Builder.

Or

• Double-click a nib file in the nib file window.

Or

• In Interface Builder, choose the Open command and select a file in the Open Panel.

You will usually open a nib file in Project Builder, as shown in Figure 3-2, since that is the central tool for application development. When you create an application in Project Builder, an empty nib file is automatically created for you and added to the project's Interfaces suitcase. This file has the same name as your application project and, like all nib files, ends with the extension .nib.

Figure 3-2

You can also open nib files directly in the Workspace's File Viewer by double-clicking on them. And you can open nib files from within Interface Builder by choosing the Open command from the Document menu; in the Open panel locate and select the file as shown in Figure 3-3.

Figure 3-3

Nib files (so called because of their .nib extension) archive the class definitions, objects, and the connections between objects when you create an interface in Interface Builder. See "What Is in a Nib File" on page 3-24 for some conceptual background on nib files.

When Interface Builder Starts

When you open a nib file, Interface Builder displays several windows and panels on your screen.

The Palette Window

The palette window, shown in Figure 3-4, holds all currently loaded palettes of objects. You select a palette by clicking on its icon (if it is not already visible). Then drag objects from the palette to the appropriate surface.

Figure 3-4

The Application Kit palettes as described in detail in "Using the Palettes" on page 3-27.

The Interface Window

The interface window or panel displays the actual interface on which you are working. If this is the first time you have opened a main nib file in Project Builder, an empty window is displayed. Figure 3-5 shows an example of an interface window.

Figure 3-5

The Nib File Window

The nib file window, shown in Figure 3-6, contains multiple views that display the contents of the nib file. Selected by clicking on a folder tabs, these views show archived objects; the connections among objects, the current class hierarchy (including any custom classes that you may have created), and the images and sounds stored in the nib file.

Each window in the nib file is represented by a window icon in the nib file window. By double-clicking on a window icon, you can bring the window it represents to the front so that the objects it contains are visible. The nib file window also contains icons that represent the file's owner object and a first responder object, objects that are discussed in "The Nib File's Owner" on page 3-18 and "The First Responder Object" on page 3-20.

Figure 3-6

The nib file window contains five displays:

• Instances display in icon mode
• Instances display in outline mode
• Classes display
• Images display
• Sounds display
• IDL display

Icon Mode of Instances Display To display the object of your application's interface as icons, use the icon mode of the nib file window's Instances display, shown in Figure 3-7.

Figure 3-7

Only the top level of your interface's object hierarchy is displayed in icon mode. Object hierarchy is the hierarchy of objects in your interface. For example, any button on a window is displayed below that window in the object hierarchy. Icon mode would display only the window, not the button.

To display all of the objects in the object hierarchy, use the outline mode of the Instances display (see "Outline Mode of Instances Display" on page 3-12).

To select an object in icon mode, click on it. To display an object in the workspace, double-click on it.

Outline Mode of Instances Display For a view of all of the objects in your application's interface, use the outline mode of the nib file window's Instances display shown in Figure 3-8.

Figure 3-8

Outline mode displays the entire object hierarchy of your interface. For example, any button in a window is displayed below that window in the object hierarchy. Outline mode shows the button indented below the window that contains it.

Click on the button to the left of an object's name to see the objects that this object owns. Click on the button again to hide these objects. If the button is empty and shaded, the object it represents does not own any objects.

The buttons to the right of each object show connections to and from that object. Click on the left button to see the object's outlets and the action messages sent to the object. Click on the right button to see which objects have outlets into the object and the action messages the object sends to other objects.

To select an object in outline mode, click on it. To display an object in the workspace, double-click on it.

Classes Display Use the Classes display of the nib file window, shown in Figure 3-9, to do the following:

• Subclass OpenStep classes
• Add already-defined subclasses to the nib file
• Change the definition of a class
• Delete classes

Figure 3-9

See "Creating a Class" on page 3-137 for information on using this display to add, modify, and delete subclasses.

The Classes display shows the classes known to your interface. Black titles are used for classes you have added to the interface. These are the only classes you can modify and delete. Gray titles are used for OpenStep classes.

Images Display Use the Images display of the nib file window, shown in Figure 3-10, to add images to your interface and to add an image to an object in your interface. The images display shows the images known to your interface.

Figure 3-10

A new nib file contains images for radio buttons, switches, and the return symbol, which you can add to a button to have it perform a click when the user presses the Return key.

Black titles are used for images local to the nib file. You can rename these images, and you can delete an image by selecting it and pressing the Backspace key. Gray titles are used for standard images and images added to the project using Project Builder.

To see what an image looks like before you add it to your interface, select it, then choose Tools from the Interface Builder menu, and choose Inspector from the Tools menu. For information on the attributes of an image that are displayed in the Inspector window, see "Managing Sounds and Images" on page 3-78.

---

Note - You can also add an image to your interface by dragging a TIFF or EPS file from the File Viewer.

---

Sounds Display Use the Sounds display of the nib file window, shown in Figure 3-11, to add sounds to your interface and to add a sound to an object in your interface. The Sounds display shows the sounds known to your interface.

Figure 3-11

All nib files contain a subset of the sounds in the standard sounds directory, /usr/openstep/Library/Sounds. Also, all sounds you add to the project using Project Builder are added to the nib file.

Black titles are used for sounds local to the nib file. You can delete a sound by selecting it and choosing Cut from the Edit menu. Gray titles are used for standard sounds and sounds added to the project using Project Builder.

To hear a sound before you add it to your interface, select it, choose Tools from the Interface Builder menu, then choose Inspector from the Tools menu. For information on the attributes of a sound that are displayed in the Inspector window, see "Managing Sounds and Images" on page 3-78.

---

Note - You can also add a sound to your interface by dragging a file with the extension .snd or .au from the File Viewer.

---

IDL Display Use the IDL display of the nib file window, shown in Figure 3-12, to do the following:

• Parse IDL (Interface Definition Language) interface files
• Instantiate IDL template objects in the nib file

Figure 3-12

The IDL display shows the IDL types known to your interface. You can instantiate template objects from these IDL interfaces (see "Adding IDL Template Objects to Your Interface" on page 3-164). Then you can connect these IDL objects to outlets in instances of custom classes you have defined (see "Connecting Objects" on page 3-113).

The Nib File's Owner The nib file's owner is an object that is external to the nib file and that is the conduit for messages between the objects that will be unarchived from the nib file at run time and the other objects in your application. In general, the core objects in your application access the objects unarchived from the nib file

indirectly through the owner object. In turn, the unarchived objects communicate with the other objects in your application by sending messages to the owner object.

Each nib file has one--and only one--owner. For small applications, the owner is generally NSApp, the application object itself, although it can be an object of any class. You can change the type of object that owns an auxiliary nib file using the Inspector window.

The owner is the only external object that may be the explicit target of action messages from NSControls within the nib file. The owner may also have outlets that will be initialized at run time to point to the objects within the nib file.

The owner of a nib file is represented by an icon in the nib file window, shown in Figure 3-13. You use this icon to make connections between objects stored in separate nib files. When the application object is the file's owner, the icon is a terminal.

Figure 3-13

The owner must exist before the interface objects are loaded. For example, Project Builder generates a main file that follows this sequence of messaging to create the owner, load the interface information, and then run the following:

NSApplication *app = [NSApplication sharedApplication];
if ([NSBundle loadNibNamed: @"CustServ.nib" owner: app])
    [app run];

---

Note - NSApp is a global variable that identifies the NSApplication object, the object that is created by the message in the first line of the example above. (For more information on the loadNibSection:owner:withNames: method--and especially on the search path it uses for locating the appropriate nib file to load--see the specification for the NSApplication class.)

---

What happens when the nib file is loaded at run time is described in "When You Load a Nib File" on page 3-27.

The First Responder Object The First Responder icon in the nib file window, shown in Figure 3-14, represents the object within a window that will be the first to receive keyboard events, mouse-moved events, and action messages from NSControl objects that do not have an explicit target.

Figure 3-14

In most cases, a window's first responder is either one of its NSText objects or one of the objects that use NSText objects (such as NSForm, NSTextField, and NSScrollView objects). Clicking on one of these objects generally makes it that window's first responder.

Over time, many different objects can become the first responder, but at any one time, only one object has this status. The First Responder icon stands for the object that has this status, no matter which actual object it is within your application. In this respect, the First Responder icon is really a fiction since it identifies no one particular object, but rather any object having a particular status. This fiction, however, is very useful.

The object represented by the icon changes when the position of the text pointer changes. For example, if you click on the pointer in a text field labeled Name and start to type, the Name text field receives the keystrokes. It is the first responder. If you move the pointer to a field labeled Address and start to type, Address receives the keystrokes, so it is the first responder.

You can use the First Responder icon to send messages to any object that currently contains the text pointer. For example, the Cut, Copy, and Paste commands in the Edit menu send messages to the first responder object.

Having First Responder in the nib file window lets you connect an object, such as the NSMenuCell that sends the copy: message, so that it sends its action message to a target whose identity changes over time. Thus, for example, the Copy command can be set up to work with any NSTextField in a window, as long as the NSTextField is the first responder. If you create a new application

in Project Builder, open its nib file, and check the connections in the application's Edit menu, you will discover that all Edit commands are connected to the First Responder.

The ability to let the target of a message be defined at run time rather than at compile time is an example of dynamic binding in Objective C. For more information on Objective C, see Chapter 8, "The Objective C Language," and Chapter 9, "The Objective C Extensions.")

The Inspector Panel

The Inspector panel, shown in Figure 3-15, is a multiform panel that displays the attributes, connections, and size of a selected object. It also presents the object's resizing characteristics and its associated help.

Figure 3-15

You can control whether the palette window and the Inspector panel appear when Interface Builder starts by checking the appropriate boxes in the Preferences panel.

You use the Inspector panel to edit the properties of both NSView and non-NSView objects in your application. You can use the panel to do the following:

• Display information about an object
• Set an object's attributes
• Connect two objects
• Display a help topic attached to an object or attach a help topic to an object

The Inspector panel is displayed when you choose the Inspector command in Interface Builder's Tools menu.

The panel has many personalities. Its contents are determined by Interface Builder's selection: If an NSButton object is selected, the Inspector panel displays the NSButton Inspector; if an NSWindow is selected, the panel displays the NSWindow inspector. (The Inspector panel's title announces the class of the selected object.) In addition, the panel itself has four displays--Attributes, Connections, Size, and Help--which are accessible through the pop-up list at the top of the panel. These four displays are discussed in "Setting Object Attributes" on page 3-63, "Sizing Windows and Panels" on page 3-36, "Positioning and Sizing Precisely" on page 3-40, "Automatically Resizing Objects" on page 3-98, "Making and Managing Connections" on page 3-109, and .

Creating a Nib File

To create a new nib file, do one of the following:

• Choose one of the panels in the New Modules submenu of the Document menu.

Or

• Choose New Empty from the New Modules submenu, then drag a window or panel from the Windows palette.

Or

• Choose New Application from the Document menu.

Nib files are created for you automatically when you create applications in Project Builder. But sometimes you need to create nib files directly in Interface Builder, typically when you want to add additional windows and panels to your application.

To create a new panel (and the nib file that contains it) choose the desired panel type from the New Module submenu of the Document menu. For example, if you choose New Info Panel, you get the template panel shown in Figure 3-16.

Figure 3-16

Most commands of the New Module submenu create new nib files that contain a special kind of ready-made panel; your application can later load these nib files when it needs them. The New Empty command just creates an empty nib file; you must create the windows and panels for it by dragging these objects from the Windows palette. The New Application command in the Document menu can create your application's main nib file (a nib file with the owner of Application) if that has not already been done for you in Project Builder.

---

Note - You can have auxiliary nib files, such as an Info panel, that you load into your program only when you need to.

---

Saving the Nib File

An UNTITLED nib file window is displayed for each newly-created nib file. After you make changes to an interface, remember to save the nib file. Choose Save from the Document menu and specify a path and file name in the Save Panel as shown in Figure 3-17. Interface Builder may ask if you want to insert the file into your project; you usually confirm by clicking on Yes.

Figure 3-17

What Is in a Nib File

When you save an interface in Interface Builder, it is archived to a nib file. Every application has a main nib file, which contains the main menu and often a window and other objects. A nib file (actually a file package) has the extension .nib. This nib file contains the following:

• Archived objects, in their hierarchy
• Sound and image data
• Information on custom classes
• Connection information

Archived Objects

The nib file stores encoded information on kit objects such as those shown in Figure 3-18, including their size, location, and position in the object hierarchy (for NSView objects, determined by superview/subview relationship). At the

top of the hierarchy of archived objects is the File's Owner object, a proxy object that points to the actual object that owns the nib file. (For a description of File's Owner, see "The Nib File's Owner" on page 3-18.)

Figure 3-18

Sounds and Images

Any sound or image files (TIFF or EPS) that you drag and drop over the nib file window are stored in the nib file and represented by the icons shown in Figure 3-19. The Sounds and Images displays of the nib file window are described in "Sounds Display" on page 3-16 and "Images Display" on page 3-15.

Figure 3-19

Class References

Interface Builder can store the details of kit objects and objects that you palettize (static palettes), but it does not know how to archive instances of your custom classes since it does not have access to the code. For these classes, Interface Builder stores a proxy object to which it attaches class information, as shown in the example in Figure 3-20 on page 3-26.

Figure 3-20

Connection Information

A nib file also contains information (such as that represented in Figure 3-21) about how objects within the object hierarchy are interconnected. Connector objects special to Interface Builder store this information. When you save the document, connector objects are archived in the nib file along with the objects they interconnect.

Figure 3-21

When You Load a Nib File

The following things take place when you load a nib file with the loadNibSection:owner:withNames: method:

• The run-time system unarchives the objects from the object hierarchy, allocating memory for each object and sending it a read: message. After its unarchived, an object receives awake and finishUnarchiving messages.
• It unarchives each proxy object and queries it to determine the identity of the class that the proxy represents. Then it creates an instance of this custom class (alloc and init) and frees the proxy.
• The system unarchives the connector objects and allows them to reestablish connections, including connections to File's Owner.
• As the final step, the run-time system sends awakeFromNib to all objects that were derived from information in the nib file, signalling that the loading process is complete.

Using the Palettes

Palettes store ready-made objects that you can add to your interface. Drag the object from the palette to add it to your interface.

When the grid in your interface is turned on and you add or move an object, the object snaps to the grid. Similarly, when you add a new object to the window or resize an object, the dimensions of the object snap to the grid.

The Palette window displays the palettes available to you. The window usually is displayed in the upper right corner when you start Interface Builder (see Figure 3-1). Choose Palettes from the Palettes submenu to display the Palette window if it is not visible. The Tools menu contains the Palettes submenu.

Each palette is represented in the window by an icon. If more than four palettes are loaded, a horizontal scroll bar gives access to those palette icons that are not visible. Click on an icon to display that palette.

The palettes for the Application Kit--the Menus palette, the Views palette, the TextViews palette, and the Windows palette--are loaded by default. These palettes provide windows, panels, browsers, scroll views, buttons, text fields, and a number of other interface objects.

You can create your own palettes of objects. Custom palettes that you create fall into two categories: static palettes, which are created as separate projects, and dynamic palettes, which you create while you create your interface. For more information on creating palettes, see "Adding Custom Palettes, Inspectors, and Editors" on page 3-169.

The Menus Palette

Add a menu cell to your interface by dragging it from the Menus palette, shown in Figure 3-22, into your interface's menu.

.

Figure 3-22

All of the menu cells on this palette create standard OpenStep menus except for the Item and Submenu cells.

See OpenStep Programming Reference for the types of messages a menu cell can receive.

The Views Palette

Create an NSView object by dragging it from the Views palette into a window or panel in your interface. The Views palette, shown in Figure 3-23, contains objects created from subclasses of the NSView classes.

Figure 3-23

You can create an NSMatrix from an NSTextField, NSForm, NSSlider, or NSButton object by holding down the Alt key and dragging one of the resize handles of the selected object until several copies are made. You can also add and delete rows and columns in the same manner.

The individual objects within an NSMatrix are NSTextFieldCells, NSFormCells, NSSliderCells, or NSButtonCells. You can set attributes for the NSMatrix object that apply to all of the cells, or for each cell individually.

Copying an NSView object copies all of the NSView objects within that object (its subviews) as well.

NSView objects that display text appear on the TextViews palette (see "The TextViews Palette" on page 3-30).

Use the NSCustomView object to create an object from a subclass of NSView that does not appear on the Views palette or the TextViews palette.

The TextViews Palette

Add a text viewer to your interface by dragging it from the TextViews palette, shown in Figure 3-24, onto a window or panel in your interface.

Figure 3-24

The Windows Palette

Add a window or a panel to your interface by dragging it from the Windows palette, shown in Figure 3-25, to anywhere in the workspace.

Figure 3-25

To use a subclass of NSWindow other than NSPanel, drag an NSWindow object into the workspace, select it, and change its class using the Inspector panel.

See OpenStep Programming Reference for the types of messages an NSWindow or NSPanel object can receive.

Adding an Object from a Palette to Your Interface

To add an object from a palette to your application's interface, do the following, as shown in Figure 3-26:

1. Choose the palette you want.

2. Drag an object from the palette to the appropriate "surface."

3. Release the mouse button.

Figure 3-26

---

Note - Where you "drop" a window or panel is important, since that sets its initial position on the screen, the location where it is displayed when the application starts or when its nib file is loaded.

---

"Where Palette Objects Go" on page 3-34 illustrates the proper "surfaces" for interface objects.

Placing Interface Objects

To move an interface object within a window or panel in your application's interface, do the following, as shown in Figure 3-27:

1. Select the object you want to move.

2. Drag the object to the new location in the window or panel.

Figure 3-27

To move an object around the "surface" of a window or panel, select the object and drag it with the mouse. The currently selected object has resizing handles around its perimeter.

When you move an object, make sure that the mouse pointer is inside the object and not on a resize handle.

For greater precision, select an object and press the arrow keys; this moves the object an incremental distance in the required direction. If the alignment grid is off, this distance is one pixel; if it is on, it is the distance of the grid.

You can adjust the size and location of objects precisely by specifying their origins, width, and height in the Size display of the object's Inspector. See "Positioning and Sizing Precisely" on page 3-40 for details.

Selecting Multiple Objects

You can select multiple objects and then move, copy, or do other things with them as a group. There are two ways to select more than one object:

• Hold down the Shift key while you click on objects in succession.
• Click in an empty area, then draw a "rubberbanding" rectangle around all objects you want selected.

After making the selection, press (do not momentarily click) the mouse pointer on one of the objects and drag the group to the new location. (Or do another suitable operation, such as copy and paste.)

To deselect an object in a grouped selection, hold down the Shift key and click on that object.

You cannot do sizing operations on multiple selected objects.

To select all objects in a window or panel, first select the window or panel, and then choose the Select All command from the Edit menu. You can select all items in the Instances or Classes display by choosing Select All from the Edit menu. The command-key equivalent for Select All is Command-a.

Where Palette Objects Go

You can put windows and panels anywhere in the work space as shown in Figure 3-28. Nothing contains them except the screen.

Figure 3-28

You put items from the Views and TextViews palettes-- buttons, labels, pop-up menus, fields, boxes, text fields, scroll views, browsers, custom NSViews-- anywhere within the bounds of a window or panel as shown in Figure 3-29.

Figure 3-29

You drag a menu cell from the Menu palette and drop it in the application's menu as shown in Figure 3-30. When you release the mouse button, Interface Builder inserts the cell between the two menu commands underneath it.

Figure 3-30

Sizing Windows and Panels

After you drag a window or panel from the Windows palette and drop it on the screen, you will probably want to resize the object to a suitable dimension. To resize a window or panel, do one of the following:

• Drag the resize bar in the direction you want the window to grow.

Or

• Bring up the Inspector panel and enter the dimensions in the Size display.

To resize a window, drag the resize bar in the required direction as shown in Figure 3-31.

Figure 3-31

Many panels and some windows are not set for resizing and therefore do not have a resize bar visible. To make this bar temporarily visible for resizing in Interface Builder, check the miniaturize switch button in the Controls section of the Attributes inspector for the window.

You can also resize windows and panels with greater precision by entering the exact dimensions in the Size display of the Inspector panel as shown in Figure 3-32. To bring up the Size Inspector for a window, select the window by clicking on its title bar, then choose Inspector from the Tools menu (or press Command-3).

Figure 3-32

You can also use the Inspector panel to size NSView objects with numerical exactness. See "Positioning and Sizing Precisely" on page 3-40 for further information.

Also see "The Coordinate System in Interface Builder" on page 3-49 for some conceptual background.

Initializing Text

Many of the palette objects include text as a component. Buttons of all sorts usually have titles, boxes usually name the elements they group, and so on. Interface Builder initially sets the text in most of these objects to the name of the object itself (such as "Button" or "Text"). After you drag the palette object onto a window or panel, you will probably want to delete these text strings or rename them to something meaningful. This text is what is initially displayed when your application loads the nib file; your application can later change the text.

To change the text in an interface object, do the following, as shown in Figure 3-33:

1. Select the object.

2. Double-click on the text inside the interface object.

3. Edit the text.

4. Deselect the text by clicking outside of it.

Figure 3-33 NSButton

Once text is selected, you can move the pointer among the characters by pressing the left and right arrow keys; you can delete characters by pressing the Delete key. Text fields are initialized to "Text" (which you will almost always want to delete). To delete this, double-click on it and press the Delete key.

Matrices--compound objects, such as radio buttons and form fields--need a slightly different procedure for selecting text for initialization: You must double-click on the embedded text item twice, the first time to select the embedded object, and the second time to select the text inside the object.

Figure 3-34 NSMatrix

"Creating Matrices of Objects" on page 3-58 describes how to create these compound objects. Also see "Compound Objects" on page 3-91 for a conceptual summary of NSMatrix objects and other compound objects.

Sizing Interface Objects

Interface objects in Interface Builder scale to any practical dimension. You can, for instance, increase the size of a button so it fills a window. Most interface objects, however, do not scale below a certain minimum size of usefulness.

To size an interface object, do the following:

1. Select an object.

2. Drag a resize handle in the desired direction.

To size an object you must first select it. A selected object has resize handles--small, gray rectangles--around its perimeter. Drag one of these handles in the direction you want the object to increase (or decrease) in size.

Figure 3-35

To affect just one dimension of the object, drag a top, bottom or side handle. To adjust both dimensions simultaneously, drag one of the corner handles. To size both dimensions proportionally, hold down the Shift key while you drag a corner resize handle.

You can adjust the size and location of objects precisely by specifying their origins, width, and height in the Size display of the object's Inspector panel.

See "Positioning and Sizing Precisely"; below for details.

Positioning and Sizing Precisely

You can move and resize objects in your interface with numerical exactness using the Inspectors for those objects. You will occasionally find need for such exactness, such as when you want to size a custom view to the same dimensions as the image that it will display. More frequently you will use this method to align objects or make sure they are the same size.

To position or size an object precisely, do the following:

1. Select an object.

2. Choose the Size Inspector for that object.

3. Modify the object's origin point or its dimensions.

To size and move objects with precision, select a reference object and then choose the Inspector option from the Tools menu. Choose Size from the pop-up menu at the top of the Inspector panel. (You can also bring up the Size display by pressing Command-3.) Note the position and dimensions of the reference object.

Figure 3-36

When you press Return in an origin or dimension field, the object moves to the new position or expands or contracts to the new size.

---

Note - You can also move selected objects incrementally--and precisely--by pressing the arrow key that points in the required direction. Each incremental "nudge" moves the object the distance of the grid or, if the grid is turned off, one pixel.

---

Duplicating Objects

You can duplicate an object in your application's interface by doing the following:

1. Select an object.

2. Copy the object to the pasteboard.

3. Paste the object back to the interface.

4. Position the new object.

To duplicate an object, select it (see Figure 3-37) and then copy and paste it just as you would with geometric shapes in a drawing application. The copied object has the dimensions and most other attributes of the original object.

Figure 3-37

Choose Copy from the Edit menu, then choose Paste from the Edit menu.

Figure 3-38

The new object is offset slightly from the original one to help you select it, as shown in Figure 3-38. Move the new object to its new location.

In addition to the objects that appear on the interface, you can copy your custom non-UI objects--represented as cubes in the icon mode of the nib file window--as well as your windows and panels. Just click to select them and then copy and paste them.

---

Note - Instead of choosing Copy and Paste from the menu, you can press Command-c (Copy) and Command-v (Paste).

---

You can also duplicate groups of selected objects by copying them and then pasting them. See "Selecting Multiple Objects" on page 3-34 for details on making multiple selections of objects.

Moving Objects to Other Windows

You can move an object from one window or panel in your application's interface to another by doing the following:

1. Select one or more objects.

2. Alt-drag the objects to the other window or panel.

To move objects from one window or panel to another, drag them between windows while holding down the Alt key, as shown in Figure 3-39.

Figure 3-39

If you want to copy rather than move the selected objects (in other words, the original objects remain in the original location), you have two alternatives:

• Copy the objects using the Copy command; click in the other window or panel to activate it, and use the Paste command to copy the objects from the pasteboard.
• Copy and paste the objects in one window, then Alt-drag the duplicated objects to their new window or panel.

Copying Objects to Other Interfaces

With the same Alt-drag technique, you can copy objects between different nib files. Simply select a group of objects in one nib file and, while pressing the Alt key, drag and drop those objects on the appropriate "surface" of the other nib file.

Both nib files must be open when you initiate the copy operation. You can copy entire windows or panels as well as custom, non-UI objects between interfaces.

The surface onto which you drop objects must be compatible in the following ways:

• Non-UI objects must be dropped over the Instances display of the nib file window.
• View objects are dropped over a window or panel or over the Instances display.
• Windows and panels can be dropped anywhere on the screen.

The basic technique of Alt-drag also copies the connections among selected objects.

Arranging Objects

When you compose your interface, you usually want to arrange the objects in that interface in some appealingly regular way. You want buttons, for instance, to be aligned on the same invisible horizontal or vertical line. Or you want the distance between text fields in a form application to be exactly the same. Interface Builder gives you a set of tools for arranging objects.

To arrange objects in your application's interface, do the following:

1. Set the characteristics of the grid in the Alignment panel.

2. Turn on the grid.

3. Align objects with the grid.

Every window or panel has a grid associated with it. You may turn this grid off and on. When it is on and you move an object, an edge of that object "snaps," like a nail to a magnet, to the adjacent intersecting lines of the grid.

Using the Alignment Panel

You set the dimensions of this grid and the edges of alignment in Interface Builder's Alignment panel, shown in Figure 3-40. To bring up this panel, choose the Alignment command in the Align menu (the Align menu is a submenu of the Format menu).

Figure 3-40

The buttons in the Align section of the Alignment panel determine what point or edge of interface objects snaps to the grid (see Figure 3-41).

Figure 3-41

Once you have your grid set up, make sure the grid is turned on: Choose Format

Align

Set Grid On. If you also want the grid visible, choose Show

Grid from the same menu.

Now align the objects, either individually or as a group, using the grid, as shown in Figure 3-42.

Figure 3-42

There are other ways to align objects that do not require using the mouse. With the grid turned off, you can drag view objects from a palette and visually align them as precisely as possible. Then set the grid spacing, turn the grid on, and choose the Align To Grid command.

Once the grid is set and on, align the objects, either individually or as a group, as shown in Figure 3-43.

Figure 3-43

With the Align To Grid command, the direction of alignment is toward the origin point of the window or panel (in other words, toward the lower-left corner). You should be aware of this when placing objects for later alignment.

---

Note - You can align selected objects to a grid, singly or as a group, by pressing the arrow keys in the direction of alignment. When the grid is turned on, the unit of increment changes from one pixel to whatever the grid spacing is.

---

Making Columns and Rows of Objects

It is more efficient to align groups of objects than to align single objects successively. With the Make Column and Make Row commands, Interface Builder aligns groups of selected objects to a reference object. You designate the reference object by the way you select multiple objects:

• If you press the Shift key while clicking on objects in succession, the first object clicked on is the reference object (see Figure 3-44).
• If you draw a selection rectangle around a group of objects, and so select objects simultaneously, the topmost object in the selection (usually the most recently added object) is the reference object.

For most purposes, Shift-clicking on objects is the preferred method because it permits more control.

Figure 3-44

Removing Objects

To delete an object or objects from your application's interface, do the following:

1. Select one or more objects.

2. Choose Cut from the Edit menu.

To delete objects from an interface, select the objects and choose the Cut command, as shown in Figure 3-45.

Figure 3-45

You can also delete an object by pressing the Delete key, but the differences between the Delete key and the Cut command are significant. The Cut command saves the selected objects to the pasteboard, so you can retrieve the objects with the Paste command (Command-v). The Delete key permanently deletes the selected items.

The Coordinate System in Interface Builder

The Size display of an object's Inspector panel shows that object's precise location and dimensions. The x and y fields hold the origin point (horizontal and vertical) for the object within the drawing context of its enclosing window or panel. The w and h fields hold the width and height. All values are in pixels.

Within a window or panel, the lower left corner is origin 0,0. This is the point of reference for objects within that window or panel.

Therefore, when you move or size objects downward or to the left, the values in the Size display are decremented.

Figure 3-46 illustrates Interface Builder's coordinate system. The point of reference for a window or panel (or origin 0,0) is the lower-left corner of the screen. This means that the same relationship applies: if you decrement its x value in the Size display, it moves to the left; if you decrement its y value, it moves toward the bottom of the screen; decrement its w or h values and it becomes smaller.

Figure 3-46

OpenStep's Basic UI Design Philosophy

Composing a user interface involves much more than techniques for placing, sizing, and arranging objects on a window. When you put your application's UI together in Interface Builder, keep in mind the following principles.

Make It Consistent

When all applications share the same basic interface, each application benefits. Consistency makes each application easier to learn, and so increases the likelihood of acceptance and use. Just as with so many natural "interfaces" in life, conventions count for a great deal. Although different applications are designed to accomplish different tasks, they all share, to some degree, a set of common operations such as selecting, editing, scrolling, and setting options. Reliable conventions are possible only when these operations are carried out the same way for all applications.

Make it Feel Natural

Try to make the screen a visual metaphor for the real world, so that the objects in it reflect the way the represented things actually behave. That is what an "intuitive" interface is--it behaves as we expect based on our experience with objects in the real world.

Modeled objects do not have to mimic every detail of their real counterparts, but they should behave in similar ways. For example, objects in the real world stay where we put them; they do not disappear and reappear again, unless someone causes them to do so. Users should immediately recognize the objects in your interface and should use them for the sorts of operations for which people typically use their real counterparts.

Put the User in Charge

Users should have the widest freedom of action. If an action makes sense, your application should allow it. In particular, avoid setting up arbitrary modes, periods during which only certain actions are permitted. On occasion, however, modes are a reasonable way of solving a problem, particularly in the following forms:

• attention panels

• modal tools
• "spring-loaded" mode (while mouse or key down)

But these modes should be freely chosen, provide an easy way out, be visually apparent, and keep the user in control.

At the same time, you should try to anticipate what users will do and ease their way, reducing the actions they must perform. Give them freedom, but still act on their behalf without waiting for their instructions. These helping actions should be simple and convenient, like, in the Open panel, preselecting a directory that is probably in the path of the final selection.

Focus on the Mouse

The mouse is the most appropriate instrument for a graphical interface. The keyboard is principally used for entering text, but the mouse is the instrument by which users manipulate the objects of your interface. Your user interface should support the following three paradigms of mouse action:

• Direct manipulation
• Targeted action
• Modal tool

See User Interface Guidelines for more on action paradigms and much more information important to the design of your user interface.

Making Interface Objects the Same Size

To lend a look of consistency to your interface, you often want to make similar objects the same size. Buttons across the bottom of an attention panel, for instance, should be the same exact size. Interface Builder gives you an easy way to do this, allowing you resize selected objects to a reference object. You designate the reference object differently, depending on your method of selection:

• If you press the Shift key while clicking objects in succession, the first object clicked is the reference object.
• If you draw a selection rectangle around a group of objects, selecting the objects simultaneously, the topmost object in the selection (usually the most recently added object) is the reference object.

To make one or more objects the same size as a reference object, do the following:

1. Select the reference object.

2. Add to the same selection the objects that you want resized.

3. Choose the Same Size command.

Making objects the same size involves identifying and selecting a reference object and selecting several other objects (as shown in Figure 3-47), and choosing a command.

Figure 3-47

Choose Same Size from the Size submenu (you can find the Size submenu on the Format menu). The objects become the same size as the reference object, as shown in Figure 3-48.

Figure 3-48

---

Note - In most situations, you should select multiple objects by Shift-clicking them because this method gives you more control (you do not always have to keep track of the topmost object as the reference object).

---

Shrinking Objects to their Minimum Size

To conserve screen real estate, or to enhance the appearance of your interface, you might want to have NSView objects just large enough for any text they contain. You can do this with the Size to Fit command.

To make an object or objects the size needed to accommodate their text contents, do the following (see Figure 3-49):

1. Select one or more objects.

2. Choose Size to Fit.

Figure 3-49 NSView

The Size to Fit command has no affect on matrices, custom views, and some other objects. If you delete the text from a button, text field, or other object that holds text, and then apply the Size to Fit command to it, that object shrinks to its minimum (and probably unusable) size.

Grouping Objects

You can group a set of objects in your application's interface by doing the following:

1. Select the objects you want grouped.

2. Choose the Group command.

When you group objects, Interface Builder draws a box around them. The box has a title (initially "Title"). You select, move, copy, and cut and paste the objects within the box as a group. Interface Builder gives you two ways to group objects.

In the first method, you select the objects of the group and choose a menu command (see Figure 3-50).

Figure 3-50

The default title of the box around the grouped objects is "Title." To change this, double-click the title to select it (as in the window on the right side of Figure 3-50). Then type the new name for the grouped objects.

To ungroup the objects, making each object individually selectable again, select the group and choose Ungroup from the Group submenu.

You can also use the NSBox object in the Views palette to group objects (see Figure 3-51.

1. First, drag a box onto a window or panel.

2. Then add its contents.

Figure 3-51 NSBox

The default title of the NSBox object is "Box." To change this, double-click the title to select it. Then type the new name. You can change the position of the title, or eliminate the title altogether, using the NSBox Attributes inspector (see Figure 3-74).

The Group submenu has two other interesting commands. With the Group in ScrollView command, you can automatically bind an NSText object (or your own custom NSView object) to horizontal and vertical scrollbars. With the Group in SplitView, you can group two related views (often a custom view and a browser object) in a split view, which has a sizing bar between the views.

See the specifications of the NSScrollView and NSSplitView classes in OpenStep Programming Reference.

Layering Objects

Every object on a window or panel in Interface Builder is on its own layer. That is why when you move one object over another object, the first object moves in front of the second or moves behind it. The most recently added object is generally on the topmost layer.To change the layering order of an object, do the following:

1. Select an object.

2. Choose Bring To Front or Send To Back.

Occasionally, you need to alter the layering order to make an object visible or to have it appear behind other objects. To do this, apply the Bring To Front command or the Send To Back command (on the Format menu) to selected objects.

For example, assume you want two buttons to partly overlay a NSScrollView object, as shown in Figure 3-52.

Figure 3-52 NSScrollView

Creating Matrices of Objects

You can easily transform certain objects in the standard Interface Builder palettes into matrices of those objects. A matrix (defined by class NSMatrix) imposes a regular size and intervening distance on a set of identical objects. Matrices afford an easy way to compose forms, arrays of buttons and sliders, and multiple-column browsers.

You can create a matrix of objects by doing the following:

1. Drag a suitable object from the Views or TextViews palette.

2. Alt-drag a resize handle of the object.

To create a matrix, drag one of these objects to a window or panel:

• text field
• button
• switch button
• radio button
• form field
• slider (vertical or horizontal)
• browser

Then size the object to the maximum dimension you anticipate for a cell in the matrix. Next create the matrix, as shown in Figure 3-53.

Figure 3-53

---

Note - You can create a horizontal, vertical, or two-dimensional matrix of text fields, buttons, or sliders. A matrix of form fields can only be expanded vertically, adding fields at the bottom of the form.

---

---

Note - To make a browser with more than one column, drag a browser object from the TextFields palette onto your interface; then Alt-drag the right resize handle until the desired number of columns appear.

---

Creating Menus

Menus are just as important as windows and panels for an interface. Menu commands initiate most of the standard functions of an application, such as printing, opening files, or cutting and pasting text. That is why Interface Builder's Menu palette holds a number of ready-made submenus and menu cells.

To add a menu cell from the Menu palette to your application's menu, do the following, as shown in Figure 3-54:

1. Drag a menu cell from the Menu palette.

2. Drop it between two menu cells in your application's menu.

Figure 3-54

Click on several menu cells in your application's main menu and note how some cells in the submenus are dimmed. Dimmed cells indicate that, as the default, the command is inactive until some condition occurs in your code that causes your application to activate the command.

Deleting a Menu Cell

You delete a menu cell just as you do with any other object in Interface Builder: select it, then choose the Cut command from the Edit menu (Command-x) or press the Delete key.

Changing Titles of Menu Cells

Also, as with other Interface Builder objects that display text, you can easily change the titles of menu cells by doing the following:

1. Double-click on the text to select it.

2. Type the new title or edit the old one.

3. Click outside the cell to set the new title.

Resequencing Menu Cells and Assigning Command Key Equivalents

You can also do two special tasks with menu cells: re-sequencing and assigning Command keys. By re-sequencing, you change the order in which cells are listed in a menu (see Figure 3-55). By assigning a Command key to a cell, you give the user of your application a command key equivalent--a shortcut way to invoke the command (as Command-x is a shortcut for invoking the Edit menu's Cut command) (see Figure 3-56).

Figure 3-55

Figure 3-56

Custom Menus

In addition to the standard menu commands and submenus, Interface Builder makes it easy for you to compose your own custom menus. Use the Submenu cell in the Menu palette to create custom submenus (see Figure 3-57) and use the Item cell for custom menu commands. The Print command is frequently added as a custom cell.

Figure 3-57

To create a custom submenu, do the following:

1. Change the title of Submenu and click on the cell to expand it.

2. Then add Item cells from the Menu palette to the new submenu and change their titles.

You can make menu cells active or inactive by default. Select the cell and set the Disabled button in the Attributes display of the cell's Inspector. See "Setting Object Attributes"; for more information on using the Inspector panel.

See "Making and Managing Connections" on page 3-109 tolls with the objects that are to handle menu commands.

Setting Object Attributes

All objects on Interface Builder's standard palettes have attributes that you can initialize through the Inspector panel. This section describes many of those attributes, especially the effect they have on appearance and behavior.

The Attributes display of the Inspector panel lets you set the selected object's basic characteristics. For example, Figure 3-58 shows the Attributes display of the NSButton Inspector.

Figure 3-58 NSButton

Conceptually, each of the characteristics in the Attributes display corresponds to an Objective C message to which the selected object responds. For example, Table 3-1 on page 3-65 shows the correspondence between some of the attributes displayed in the illustration above and messages that an NSButton object understands.

Table 3-1

Attribute	Message
Title	setTitle:
Alt. Title	setAlternateTitle:
Icon	setImage:
Alt. Icon	setAlternateImage:
Sound	setSound:
Type	setType:
Icon Position	setImagePosition:

The Attributes displays for the selected OpenStep classes are discussed in the following sections. If you have questions about any of the attributes displayed for a selected object, consult the class specification for that object in OpenStep Programming Referencet.

The Attributes display for the File's Owner, for Custom NSViews, and for custom objects that you instantiate in the nib file window lets you set the class of these objects.

Examining an Object's Attributes

You can examine the attributes of any object, whether that object is a graphical object such as a button or panel, or a non-UI object in the Instances display. To examine an object's attributes, do the following:

1. Select an object in the interface.

2. Choose Inspector from the Tools menu.

---

Note - You can also bring up the Attributes display of the Inspector panel by pressing Command-1.

---

The attributes for the selected object are then displayed in the Inspector panel.

Once the Inspector panel is visible on the screen, it stays there until you close it. As you select different objects, their attributes are displayed (or dimensions or connections or help links--whatever Inspector display is current).

You can also select objects in the Instances display and examine their attributes. Some of these objects (like First Responder) have no attributes. Others, like an instance of a custom class, have only one attribute.

Click on an object in the Instances display to select it, as shown in Figure 3-59.

Figure 3-59

If the Inspector panel is not visible, choose Tools Inspector or press Command- 1. As before, the attributes for the selected object are displayed (see Figure 3-60).

Figure 3-60

Customizing Windows and Panels

You can customize windows and panels in the following ways:

• Set the window title.
• Determine how the Window Server buffers window contents.
• Choose the window's controls.
• Set the window's options.

A single Attributes display of the Inspector panel serves for both windows and panels, as shown in Figure 3-61.

Figure 3-61

Window Backing

When a window is partially covered by another window and then is re-exposed, its backing--its type of backup buffer--determines how the system re-draws the exposed part.

• Nonretained: The application is responsible for all drawing on the screen because there is no buffer. If the application does not do anything when the window is uncovered, the re-exposed part is replaced by the background color. Nonretained windows are appropriate for transitory images that you do not need to save.

• Retained: Pixels are copied to the buffer for all covered parts of the window. When an obscured part of the window is later revealed, only that part of the window is redrawn--using the contents of the buffer--the rest of the window is not redrawn. A retained window is the appropriate choice for most situations.
• Buffered: The window is drawn first in the buffer and then copied to the screen. When an obscured part of the window is revealed, the entire window is refreshed using the buffer. A buffered window is appropriate when you do not want users watching complicated images being rendered on-screen. It is also the best choice for animation or for redrawing lines of rapidly typed text.

Changing Class and Custom Windows

In the Class section of the Attributes display, you can change the class of a window to NSWindow, NSPanel, or any custom subclass of NSWindow.

Window Controls

You can choose that the window or panel have any of the three controls shown in Figure 3-62.

.

Figure 3-62

Window Options

You can select any of the window options listed in Table 3-2.

Table 3-2

Option	Description
Free when closed	The window is to be freed when it is closed.
Hide on deactivate	The window should disappear when the application is deactivated.
Visible at launch time	The window should appear when the application is launched.
Deferred	A window device for this object is deferred until it is placed on-screen.
One shot	The window device is freed when the window is removed from the screen.
Dynamic depth limit	The window's depth limit can change to match the depth of the screen.
Wants to be color	The window is displayed on a color screen (two-monitor system only).

What is the Difference Between a Window and a Panel?

A panel is a window that serves an auxiliary function within an application. Because it is intended for a supporting role, a panel typically has these features:

• A panel can be the key window, but never the main window.
• When the application is deactivated, the panel moves off-screen (it is removed from the screen list). When the application is reactivated, the panel is displayed again.
• When a panel is closed, it moves off-screen; it is not destroyed.
• Unlike a window, a panel forwards Command key-down events (like carriage returns) to its views.
• When instantiated programmatically, panels have a grey background by default, while programmatically created windows have a white background.

Also, a panel usually has fewer controls: sometimes only a close button; rarely a resize bar; and sometimes no controls at all.

You can make some panels exhibit the following types of special behavior for specialized roles:

• A panel can be precluded from becoming the key window until the user makes a selection in it.
• Some panels (for example, palettes) can float above windows and other panels.
• You can have a panel receive mouse and keyboard events while an attention panel is on-screen. Actions within the panel can thus affect the attention panel.

Setting Button Attributes

The Attributes display for buttons enables you to set a button's type, title, icon, alternate title and icon, and various other characteristics. The object labeled Button on the Views palette is only one style of button (albeit the most common style). The palette also holds radio buttons and switch buttons. Using the Attributes display for buttons (see Figure 3-63), you can customize any palette button, making it something that is uniquely suitable for a particular circumstance.

Figure 3-63 NSButton

The Anatomy of a Button

A button is essentially a two-state NSControl object. When a user clicks on a button, an action message is sent to a target object. It is two-state because it is either on or off, and when it is on, it typically sends its action message. For a button, the states are also known as "normal" (off) and "alternate" (on).

You can set a button's attributes so that the normal and alternate states show different images, or so that in the alternate state the button is highlighted. You can configure a button to send its message continuously rather than discretely. You can associate a command key-equivalent with a button.

A button is actually a compound object: a NSButton object and a NSButtonCell object. Because they inherit from NSActionCell, NSButtonCells hold the target outlet and the action message to be sent to it. By being an NSCell subclass, they also carry the state value of a button. NSButtonCells also draw the text and image of a button.

Most of NSButton's methods match identically declared methods in NSButtonCell. Aside from dispatching the action message, NSButton's unique role is to set the font of the key equivalent, and to manage the highlighting or depiction of the NSButton's current state.

The Icon Position and Pixels Inset controls as well as the Sound and Icon fields are described in detail in "Associating Sounds and Images with Buttons" on page 3-75. For more information on the Tag field, see "Using Tags" on page 3-107.

You might think of storing specially configured buttons on a dynamic palette. See "Adding Custom Palettes, Inspectors, and Editors" on page 3-169.

Titles and Icons

The text in the Title field is what is displayed in most buttons; this is the text you can select by double-clicking inside the button. The name in Icon identifies an image stored in the nib file (Images display of the nib file window) that is displayed within the button. The alternate title (Alt. Text) and the alternate icon (Alt. Icon) appear when the user clicks on a button of type Momentary Change or Toggle.

Key Equivalent

The Key field identifies a keyboard alternative to clicking the button. Possible values are: \b (Backspace), \d (Delete), \e (Escape), \t (Tab), and \r (Return).

Button Type

A button can be of any of the types listed in Table 3-3.

Table 3-3

Type	Button Behavior When Clicked
Momentary Push	Button is highlighted, appears to be pressed.
Momentary Change	Alternate button title and icon appear (as long as mouse button held down).
Momentary Light	Button is highlighted, but no illusion of being pressed.
Push On/Push Off	Click once and button is highlighted with illusion of being pushed in; click again and it returns to normal.
On/Off	Click once and button is highlighted; click again and it returns to normal.
Toggle	Alternate button title and icon appear; click again for main title and icon.

Button Options

You can select any of the button options listed in Table 3-4.

Table 3-4

Option	Description
Bordered	A line is drawn around the button's border.
Transparent	The button has no border, text, icon, or background color.
Continuous	The button sends its action message continuously when pressed.
Disabled	Prevents activation of the button; text is in gray.
Selected	The button, when initialized, is to be selected (switch and radio buttons).

Associating Sounds and Images with Buttons

To associate a sound or image with a button, do one of the following:

• Drag the icon representing a sound or image from the nib file window (see Figure 3-64) or the Workspace (see Figure 3-65 on page 3-76) and drop it over a button.
• Enter the file name of the sound or image in the appropriate field of the button's Attribute's display.

You associate a sound or image with a button by dragging the icon representing the resource and dropping it over the button.

Figure 3-64

When you click on a button that has a sound associated with it, it plays the sound. Images appear in buttons with or without text. They can play more than an iconic or decorative role; when you drag the NSReturnSign image onto a button, for instance, the carriage return key-equivalent is associated with the button ("\r" in the Key field).

You can drag sounds and images from the Workspace Manager's File Viewer too, as shown in Figure 3-65.

Figure 3-65

The sound or image automatically is added to the Sound or Image section of the nib file window.

Several fields and controls in the Inspector's Attributes display for buttons relate to images and sounds (see Figure 3-66 on page 3-77).

Figure 3-66 NSButton

Note that the name of a sound or image in this display is the file name (blat.snd and NSReturnsign.tiff, for example) minus the extension. Instead of dragging and dropping sound and image icons, you can type their file names (minus the extension) in the appropriate field. However, you should insert the resource into the nib file or the project before typing its name in the Attributes display.

---

Note - For most situations, the recommended course of action is to add sounds and images to your project. If you add resources only to a nib file, those resources might not be available to an application unless the nib file has been loaded.

---

The six buttons in the Icon Position group position the button title and icon relative to each other. Thus you can have the title above, below, to the left, or to the right of the icon, or show only the title, or show only the icon. The Pixels Inset pull-down menu gives several pixel distances for adjusting the spacing between the icon and the nearest edge of the button.

---

Note - If you want to import images into your interface for decorative purposes, drop the image on a button (if smaller than the image, the button will resize to contain it). Position the button, then deselect the Bordered option and select the Transparent and Disabled options.

---

Managing Sounds and Images

You can manage sounds and images in your interface in the following ways:

• Add an image or file by dragging the file icon representing the resource from the File Viewer and dropping it over the nib file window.
• Examine the sound or image in the Inspector's Attributes display.

As shown in "Associating Sounds and Images with Buttons" on page 3-75, you can add sounds and images to a nib file as a side effect of associating those resources with a button. You can also insert sounds and images into a nib file by dragging them from the File Viewer and dropping them over the nib file window, as shown in Figure 3-67.

Figure 3-67

You can drop a sound or image over the nib file window no matter what display is showing. The sound or image file will be correctly added to the appropriate display.

Although the association of sounds and images with buttons is an important reason for putting them into a nib file, there are other reasons. When you play a sound or composite an image in your code, the search path (if you supply no path) starts with the application's executable (already loaded resources), the main bundle, and the main bundle's .lproj directories. Then the following paths are searched:

• the appropriate subdirectory of the user's ~/openstep/Library directory
• the appropriate directory in /usr/local/openstep/Library
• the Application Kit

If you do not want to risk a sound or image not being in one of these standard directories, then you should store it in the a nib file or in the project.

Sounds and images have their own Attributes displays. If the Inspector panel is not visible, access it as you do for palette objects: choose the Inspector command from the Tools menu or press Command-1.

Figure 3-68 explains the Attributes display for sounds.

Figure 3-68

If your system has a microphone or some other input source connected, you can record new sounds. Click on OK to save new sounds.

For images, the Attributes display (see Figure 3-69) is mostly useful for images that are too large to show in the Images display of the nib file window.

Figure 3-69

Customizing Titles, Text Fields, and Scroll Views

For NSTitles, NSTextFields, and NSScrollViews, you can set background and text color, text alignment, border style, tag, and options affecting access to text.

OpenStep gives you several ways to display, format, and control access to text. The Attributes displays for NSTitles, NSTextFields, and NSScrollViews have controls for initializing those objects with various characteristics. A title is a specially configured text field: non-selectable with transparent backgrounds and no borders.

To see what certain effects look like, drag an NSTextField onto a window and click on the buttons on the display shown in Figure 3-70 on page 3-82.

Figure 3-70 NSTextField

An NSScrollView object is a compound object consisting of one or two NSScroller objects and a NSClipView object, which has as its document view (subview) an NSText object in Interface Builder. The document view is what is scrolled. The NSScrollView object has a slightly different Attributes display (see Figure 3-71): no text alignment buttons and a different set of options, which are listed in Table 3-5.

Figure 3-71 NSScrollView

Table 3-5

Option	Description
Editable	Set to permit the user to edit text.
Selectable	Set to permit the user to select text.
Scrollable	Set to enable typing beyond the borders of the field (text scrolls to the left--NSTextField only).
Multiple fonts allowed	Set to put text in RTF format. (NSScrollView only).
Graphics allowed	Set to put text in RTFD format (graphics can be inserted--NSScrollView only).

---

Note - A tag is an internal identifier of an object that you can use in your code. See "Using Tags" on page 3-107 for more information.

---

---

Note - For more information on the NSTextField, NSScrollView, NSScroller, NSText, and NSClipView classes, see the appropriate specification in OpenStep Programming Reference.

---

Setting Textual Attributes

You can set the following textual attributes:

• The font characteristics of selected text
• The alignment of selected text within its boundaries

NSTextFields and NSScrollViews (with NSText objects as document views) are not the only palette objects that can contain text. Almost all palette objects--from buttons to browsers--can display text. You can set the font and alignment attributes of this text as shown in Figure 3-72.

Figure 3-72

The Text submenu of the Format menu also has commands that affect selected text; it offers options for aligning text and for displaying, copying, and pasting the ruler in an NSText object. With rulers you can set tabs and indentation. Note that rulers can only appear in NSText objects (for instance, inside a scroll view).

If you choose Font Panel from the menu (or press Command-t), the Font Panel (shown in Figure 3-73) is displayed.

Figure 3-73

You can use the standard menus for setting font and alignment attributes for any text in your interface. See Using the OpenStep Desktop and online help for complete information.

Setting Box (Group) Attributes

You can set title position, border style, and horizontal and vertical offsets for an NSBox object.

When you group a selection of objects, a box encloses that object. The box (actually the box's content view) becomes the superview of the enclosed objects. If you select the box in Interface Builder, you can move, copy, paste, and delete the group of objects as one.

The box has several attributes that you can set, as shown in Figure 3-74.

Figure 3-74

You can also create a box object in your interface by dragging the NSBox object from the Views palette. To group objects within this box, double-click on the box when it is on the interface. Then drag objects from a palette and drop them within the box. Double-click on the box again when you are finished.

You can drag a box onto your interface and then programmatically replace its content view (blank by default) with another NSView object, or programmatically add subviews to the content view. You can also manipulate this box to make decorative rectangles and lines.

---

Note - To make a line in an interface, such as a divider line between sections of a panel, drag a box onto the interface, Then switch off the title and make the box as narrow as possible in the required dimension (vertically or horizontally). Finally, set the offset (vertical or horizontal, whichever is applicable) to zero.

---

Customizing Browsers

You can select the browsing controls (see Figure 3-75) and browser options (see Table 3-6) for NSBrowser objects.

Browsers display lists of data and allow users to select items from the list. They can hold one-dimensional lists or hierarchically organized lists of data such as directory paths. Browsers display these hierarchical levels in columns, which users can navigate using buttons or scrollers. An entry in a column can be either a leaf node or a branch node. Leaf nodes terminate a path; branch nodes, which have a right-arrow icon, lead into the next level in the hierarchy.

Browsers have attributes affecting their navigation controls, methods of selection, and appearance, as shown in Figure 3-75.

Figure 3-75 NSBrowser

The Horizontal Scrolling buttons determine whether the browser uses a scroller for navigating levels. Click on these radio buttons to see what the scrolling controls look like.

A browser automatically uses a scroller for vertical navigation of lists.

Table 3-6

Option	Description
Allow multiple selection	Permits the selection of more than one node at a time.
Allow empty selection	Makes it possible to have no cells selected; otherwise, first cell in column is selected by default.

Table 3-6

Option	Description
Allow branch selection	Permits the selection of branch nodes (such as directories).
Separate columns	Separate columns by a bezeled bar (if not set, a black line is displayed).
Display titles	Titles are above columns and column divider is bezeled bar.

Setting Attributes of Menu Cells and Pop-up Buttons

You can set whether the list is a pop-up or pull-down type (not applicable to menu cells). You can set whether the cell is initially disabled. And you can assign a tag to the cell.

Menus, pop-up lists, and pull-down lists are compound objects that contain NSMenuCell objects. The Attributes displays for menu cells and pop-up/pull-down lists are almost identical. Figure 3-76 shows the display for pop-up/pull-down lists.

Figure 3-76 NSPopUpButton

If you disable a menu cell in Interface Builder, its text is gray when the application is launched. When the user clicks the cell, no action message is sent. If conditions change to make the cell's function relevant, your code must re-enable the cell.

Pop-Up Lists and Pull-Down Lists

The object Item1 on Interface Builder's Views palette is actually a trigger button (see Figure 3-77) whose target is an NSPopUpButton object. When you double-click on the trigger button on your interface, three menu cells appear; you can initialize their titles or (in the Attributes display) disable them and assign them tags. In a running application, the NSPopUpButton object, once triggered, tracks the mouse until the user releases it, at which time it sends the selected action message to its target and disappears.

Figure 3-77

A pop-up list's trigger button always displays the item that was last selected.

In a pull-down list the trigger button's title is fixed. This type of list is effective for selecting actions in a very specific context, like the Operations pull-down list in Interface Builder's Classes display.

---

Note - Once you expose a pop-up list's menu cells, you can add more menu cells to it from the Menus palette (see "Creating Menus" on page 3-60).

---

---

Note - A tag is an internal identifier of an object that you can use in your code. See "Using Tags" on page 3-107 for more information.

---

Compound Objects

Most of the objects you can drag from the standard Interface Builder palettes are actually compound objects. They consist of two or more objects that work together in specific ways.

NSControl and NSActionCell

An NSControl (an instance of an NSControl subclass) functions as an event translator. It translates a user event like a mouse click into a action message and directs that message to another object in the application (the target).

NSControls supply the mechanism but not the content of the target/action paradigm. They need NSActionCell objects (or instances of NSActionCell subclasses) to hold this information:

• target - the object receiving the action message
• action - the method that specifies what the target is to do

At least one of these cells occupies the same area as its NSControl. Because it descends from NSCell, a cell also has content (text or image), which it draws upon request from its NSControl.

This division of responsibility makes for greater efficiency. This is especially true because an NSControl can have multiple cells and send a different action message to a different target for each of those NSCells. Since NSCells are lightweight objects, it is more efficient in some contexts to associate one NSControl with many NSCells.

Matrices

Instances of NSButton, NSSlider, and NSTextField are NSControl objects each of which are bound to a single NSCell. An NSMatrix (an instance of the NSMatrix class) is also an NSControl, but it manages more than one NSCell. It organizes its NSCells in rows and columns. The NSCells must be of the same size and usually are of the same class (although an NSMatrix can have instances of different subclasses of the NSCell class).

An NSMatrix allows each of its NSCells to have its own action and target. An NSMatrix also has its own action and target. If an NSCell does not have an action, the NSMatrix sends its own action to its own target. If an NSCell does not have a target, the NSMatrix sends the NSCell's action to its own target.

In Interface Builder you can convert a single-celled NSControl object into a NSMatrix by Alt-dragging a resize handle of that NSControl. The associated NSCell object, whether it is an NSButtonCell, NSSliderCell, or NSTextFieldCell, is duplicated for each row and column of the NSMatrix.

NSForms are a special type of matrix (NSForm inherits from NSMatrix). They have special NSCells (instances of NSFormCell) that compose both the form entry fields and the titles of those fields. An NSMenu, though actually a descendent of NSWindow, depends for its behavior on the NSMatrix object in its content area, which is filled with NSMenuCells.

Special Compound Objects

Some objects on Interface Builder's standard palettes are of a more complex composition.

NSScrollView
The NSScrollView object (see Figure 3-78) coordinates the interaction
between NSScroller objects and an NSClipView object to scroll a document.
It consists of one or two NSScrollers, an NSClipView object, and the
document view, which is generally an NSText object.

Figure 3-78 NSScrollView

NSBrowser

The NSBrowser object (see Figure 3-79) has scroll bars or buttons for controls, and columns to show hierarchically organized data. Each column is a NSMatrix of NSBrowserCell objects.

Figure 3-79 NSBrowser

Figure 3-80 NSPopUpButton

Setting Matrix Attributes

The Attributes display for matrices, shown in Figure 3-81, allows you to determine how a matrix and its cells look and behave.

Figure 3-81 NSMatrix

Matrix Selection Mode

You can set one of four selection modes to specify how cells behave when a user is dragging a mouse within a matrix. These modes also determine if selections in a matrix--a column of switch buttons, for example--are exclusive (only one allowed) or inclusive (multiple selections allowed).

• Track: The cells track the mouse when it is within their bounds but do not highlight themselves. This mode would be suitable for a "graphic equalizer" matrix of sliders. Moving the mouse around causes the sliders to move under the mouse.
• Radio: Only one cell in the matrix can be selected at a time, as is the typical case with a matrix of radio buttons.
• Highlight: Each cell is highlighted while it tracks the mouse, then is unhighlighted when it is done tracking. This mode allows multiple selections within a matrix. A matrix of switch buttons commonly has this mode.
• List: Cells are highlighted as the mouse is dragged across them, but they do not track the mouse. In this mode, a matrix supports multiple selection, enabling a user, for instance, to select a range of text.

Cell Prototype

When an NSMatrix object creates its cells, it typically makes them by copying a prototype cell stored as an instance variable. (It can also instantiate its cells from the cell's class.)

You can examine and alter the attributes of this prototype cell through the Attributes display. Click on the Inspect button to see the cell-prototype inspector shown in Figure 3-82.

Figure 3-82

If you change the prototype, be sure to apply the changes to existing matrices by selecting them, bringing up the Attributes display, and clicking on the Match Prototype button.

Table 3-7

Option	Description
Autosize	If set, the cells resize themselves whenever the matrix is resized, keeping the space between cells constant. If not selected, the space between cells changes.
Selection by rect	Set to allow users to select entire rows or columns of cells by dragging the mouse.
Set Return Sign	Click to have the carriage-return equivalent set in the last button cell of a matrix. This cell has both the carriage-return icon and control key associated with it.
Match Prototype	If you have changed the cell prototype, click on this button to apply the new prototype to the selected matrix.
Tags = Position	Click on this button to resequence the tags of the cells. When you create a matrix in Interface Builder, cells are assigned tag integers starting from zero. For two dimensional matrices, the progression is from left to right (row), then down column). If you later add new cells to a matrix by Alt-dragging it to the right or down, the new cells have tag numbers of zero.

---

Note - A tag is an internal identifier of an object that you can use in your code. See "Using Tags" on page 3-107 for more information.

---

Automatically Resizing Objects

When you resize a window, the View objects in the window must often adjust their size or the distances between themselves and other objects. The Size display of the Inspector panel, shown in Figure 3-83, lets you tell a selected object how to resize itself. To set the resizing behavior of an object, do the following:

1. Select an object.

2. Choose the Size display of the Inspector panel.

3. In the Autosizing view of the display, click on lines to make them springs or click on springs to make them lines.

Figure 3-83

The lines inside and outside the box affect different aspects of resizing behavior, as shown in Figure 3-84.

Figure 3-84

---

Note - For examples of the effects of these autosizing characteristics on views within a resized window, see "Some Effects of Automatic Resizing" on page 3-102.

---

If you do not make a view resize itself when its superview or window resizes, some ugly behavior could result. For instance, if the user makes a window small, objects that do not resize themselves could become truncated by the resized window's borders.

One recourse to this unwanted outcome is to specify a minimum size for the window, as shown in Figure 3-85.

Figure 3-85

You might need to make several iterations in Interface Builder--setting resizing characteristics in objects and shrinking the window in test mode--to determine what the ideal minimum size should be.

When There Are Conflicts

You can create an impossible resizing relationship, such as specifying as fixed the object's dimensions and its distance from the window's edges. In cases of conflict, an object's fixed dimension takes precedence over its fixed distance from a border. If all dimensions are made resizable, adjustments to the window or superview's changed dimensions are made equally to the object and its distance from a border.

---

Note - Interface Builder includes a test mode that simulates the actual operation of the inteface. In test mode, you can test the resizing behavior of your windows and views, see how connected objects communicate, play sounds associated with buttons, and do similar operations. Test mode does not test your custom objects or the connections custom objects have with the standard palette objects. See "Testing the Interface" on page 3-136 for more information.

---

Some Effects of Automatic Resizing

The window in Figure 3-86 has two identical scroll view objects. Different autosizing springs are set in each, and then the window is resized in test mode. Figure 3-87 and Figure 3-88 show you the results.

Figure 3-86

In Figure 3-87, one object resizes vertically while the other does not (distances to borders are absolute for both). The result: the object that does not resize itself is truncated when the window is vertically shortened.

Figure 3-87

In Figure 3-88, both objects resize themselves, but Object B maintains its distance to surrounding objects. This causes Object B to be more severely resized than Object A.

Figure 3-88

To learn more about the effects of resizing, try some experiments on your own using different combinations of objects and autosizing attributes.

Automatic Resizing: An Example

The example interface shown in Figure 3-89 incorporates autosizing attributes in such a combination that the window can shrink to a very small size and still be usable.

Figure 3-89

The window's minimum size is set to a dimension just large enough for the main view to show content and for the slider and button to be manipulated (see Figure 3-90).

Figure 3-90

The resizing behavior set for the box containing the slider (see Figure 3-91) ensures that the box keeps the same distance from the window's adjacent edges, but resizes the gaps between itself and the other views. It resizes itself horizontally, but not vertically.

Figure 3-91

The button's autosizing attributes (see Figure 3-92) complement the box's attributes. It keeps the same distance from the window's adjacent edges, but resizes all other distances. It also resizes itself horizontally, but not vertically.

Figure 3-92

The main view of the interface (a custom view) maintains a constant distance from the window's edges, but is itself resizable in all directions (see Figure 3-93).

Figure 3-93

Using Tags

Tags are integers that you use in your code to identify objects. They offer a convenient alternative to such methods of object identification as fetching an object's title. (What if the object't title changes while the application is running, or the object has no title?) Tag integers can also carry useful information associated with an object, and thus make it easier to integrate that information into a program. Tags are commonly assigned to matrices and to the cells contained by matrices.

You can specify tag integers in the Tag fields of most Attributes displays, as shown in Figure 3-94. To use tag integers for objects in your interface, do the following:

1. In Interface Builder, specify the tag integers for objects.

2. If the integers are not intrinsically meaningful, define constants for them in your source code.

3. Send the tag message to a tagged object to get the integer.

4. Evaluate the integer and act upon it.

Figure 3-94

You can also set tag integers programmatically in most NSView objects by sending those objects the setTag: message.

The integers that you assign could have some intrinsic value; for instance, they could be numbers that are multiplication factors for a document-zoom feature, or numbers that correspond to the number of a keypad in a calculator application. If the tag numbers are not instrinsically meaningful (that is, they are arbitrary), it is prudent to define constants to express them.

 typedef enum {
    LEFT = 1,
    RIGHT,
    BOTTOM,
    TOP,
    HORIZONTAL_CENTERS,
    VERTICAL_CENTERS,
    BASELINES
} AlignmentType;

When you need to identify a tagged objects in your code, use the tag method.

- align:sender
{
    [self alignBy:(AlignmentType)[[sender selectedCell] tag]];
    return self;
}

Making and Managing Connections

Once you build an interface with objects, you connect those objects so they can communicate with each other. You make connections between objects in Interface Builder by Control-dragging a line between them and then selecting a name for the connection.

Communicating With Other Objects: Outlets and Actions

Outlets

An outlet is an instance variable that points to another object. Objects use outlets to communicate with other objects; they simply send messages to the object identified by the outlet.

Figure 3-95

Using Interface Builder, you can declare and set outlets for the custom objects in your application. You can also set ready-made outlets in many Application Kit objects, such as browsers. .Once initialized, the connection information for the outlet is stored in the nib file. At run time, the nib file is unarchived and the outlet is reinitialized with the connection information.

The Application Kit defines two types of outlets that you can use to establish specialized connections with other objects: delegates and targets.

Delegates

A delegate is an object that acts on behalf of another object. Many kit classes define delegate outlets as an alternative to subclassing. All your object must do is register itself as a delegate of the kit object. At important junctures in its life

cycle, the kit object sends messages to its delegate, giving it an opportunity to participate in processing and sometimes even the chance to veto some behavior.

As examples, browsers request their delegates to supply the cells for browser columns; applications inform their delegates when they (the application) are initialized, hidden, and activated.

Targets

Targets are a special kind of outlet. They identify objects that can respond to action messages. When a user activates an NSControl object (for instance, clicking a button or moving a slider), that object sends an action message to the target. The action message gives application-specific meaning to the original mouse or key event.

Like a delegate, a target must implement methods to respond to the messages it is sent. But unlike a delegate, which receives messages chosen from a limited set defined by a kit, a target responds to action messages defined by the programmer.

You can also make one object a target of a second object programmatically by sending that second object setTarget:.

Actions

NSControl objects translate the event messages they receive when users manipulate them into messages meaningful within the application. They then send these messages to other objects. These application-specific messages initiated by an NSControl object are called action messages, and the method they invoke are called action methods. An NSControl object is simply a user-interface device that permits the user to give instructions to the application, a device that mediates between the user and the object that will ultimately respond to the user's event.

Figure 3-96

NSControl, an abstract class, defines for its many subclasses (such as NSButton, NSScroller, NSTextField, and NSForm) a paradigm for inter-object communication--action messages. But NSControl objects do not act alone: they always contain one or more objects of NSActionCell or its subclasses. The NSActionCell superclass defines instance variables for the two elements essential to an action message:

• Target: the object that is responsible for responding to the user's action on the NSControl
• Action: the method that specifies what the target is to do

Action methods take a single argument, the id of the NSControl object that sends the message. This argument enables the receiver to ask the control for more information, if it's needed.

An NSControl can send a different action message to a different target for each NSActionCell it contains. NSControls dispatch action messages differently; for instance, an NSButton generally sends action messages on a mouse-up event, but an NSSlider usually sends action messages continuously, as long as the mouse button is pressed.

Connecting Objects

In an object-oriented application, isolated objects have little value; they need to send messages to each other to get the work of the application done. Interface Builder gives you a way to establish connections between objects.

To connect two objects, do the following:

1. Select an object.

2. Control-drag a connection to another object.

3. In the Inspector panel's Connections display, select an outlet or action.

4. Click the Connect button.

   I

   ol-dragging a

connection line from one object to another object. Almost any object will do. Usually you Control-drag a line between an object in the interface and an object in the Instances display.

Figure 3-97

When you release the mouse button, the Inspector panel becomes the key window (see Figure 3-98 on page 3-115). Its Connections display shows the current and potential connections for the destination object.

Outlet Connections

In the example in Figure 3-97, the connection is made from a controller object--a custom object that manages the application--to a text field. The controller object (SimpleCalcInstance) declares several outlets--identifiers of destination objects-- as instance variables.

When you make a connection between objects, the first column of the Connections display shows the source object's outlets ("source" meaning the object from which a connection line is drawn).

Figure 3-98

You can make outlet connections between objects in the Instances display, as shown in Figure 3-99 on page 3-116.

Figure 3-99

Action Connections

When you make a connection by dragging a line from an NSControl object in the interface--a button, slider, text field, menu command, pop-up list, or matrix--odds are that the destination object is a target, and that you can complete the connection by selecting an action method, as shown in Figure 3-100 on page 3-117.

Figure 3-100

The destination object in an action connection is frequently a custom object that manages the application or a particular window (controller object).

When you make a connection from an NSControl object, the Inspector panel becomes key and shows the Connections display for the destination object.

Figure 3-101

When the user manipulates the NSControl object, such as clicking on a button or moving a slider, the action message is sent to the destination object (the target).

Connections Within the Interface

Sometimes you can connect two objects on an interface. These connections can involve both outlets and actions. Often one of the objects is a custom NSView object, as in Figure 3-102 on page 3-119.

Figure 3-102

Connections within an interface can also involve two Application Kit objects. Two examples are interconnecting text fields (so the user can tab from field to field), and connecting a menu command such as Print to an NSText object.

---

Note - To enable printing of an NSText object, drag a connection line from the Print menu command (or other NSControl object that initiates printing) and select the printPSCode: action in the Connections display.

---

Outlets are destination objects specified as instance variables. Actions are methods that NSControl objects (such as buttons) invoke in another object. See "Communicating With Other Objects: Outlets and Actions" on page 3-109 for more information.

"Creating a Class" on page 3-137 describes connecting the outlets and actions of custom objects in the context of creating a class.

See "Communicating With Other Objects: Outlets and Actions" on page 3-109 for more information on targets and actions.

See "Compound Objects" on page 3-91 for descriptions of the interaction between NSControl objects and NSCell objects, and of the role NSMatrix objects play.

You can connect text fields and form fields so that when the user presses the Tab key, the pointer moves to another field. See "Enabling Inter-Field Tabbing" on page 3-128 for information on this procedure.

Making Connections in Outline Mode

You can make connections between objects in the outline mode of the Instances display as well as its icon mode. The connections can be between an object in the outline and an object in the interface (see Figure 3-103) or between two objects listed in the outline (see Figure 3-105 on page 3-122). To connect objects in outline mode, do the following:

1. Select an object.

2. Control-drag a connection to another object.

3. Specify an outlet or action in the Connections display for the destination object.

Before you make a connection involving an object in outline mode, make sure that the objects is visible in the display. (You might have to expand the object's "parents" in outline mode to do this.)

Figure 3-103

The Connections display of the destination object's Inspector lists the possible connections, as shown in Figure 3-104 on page 3-121.

Figure 3-104

The outline mode offers the useful capability for making connections without leaving the nib file window. In this example, the same connection is made as in Figure 3-103 on page 3-120.

Figure 3-105

When the destination object is outlined, its Connections display lists the possible connections. Complete the connection as described above.

Examining Connections

• In the interface: Select an object and look at the Connections display of the Inspector panel.
• In the Instances display: Select an object and look at the Connections display of the Inspector panel.
• In the Connections display: Click a dimpled outlet to see the connection line drawn.
• In outline mode: Click a triangle button in the column to the right of an object.

Interface Builder gives you many ways to examine and verify connections between objects. It makes it easy, for example, to discover what outlets and actions might be associated with an object in the interface (see Figure 3-106).

Figure 3-106

You can also select an object in the Instances display (in both icon and outline modes) and examine the Inspector panel as described above to find out what object it is connected to.

You can also examine object connections going in the other direction, from the Connections display to the interface and the Instances display (see Figure 3-107 on page 3-124).

Figure 3-107

The Connections display allows you to see one connection at a time. The outline mode of the Instances display (see Figure 3-108 on page 3-125) shows you all connections an object has, both connections into the object and connections from that object to other objects.

Figure 3-108

When you click a three-dimensional triangle, lines appear to show the connections between objects, as shown in Figure 3-109 on page 3-126. The name and class of each connected object is highlighted in bold. Each connection is labelled with the name of an outlet or action.

Figure 3-109

To see connections into an object, as shown in Figure 3-110, click on a three-dimensional triangle that points to the left (that is, a triangle on the right side of the connections column).

Figure 3-110

An object may have multiple connections with another object, both in and out, both outlets and actions. In these cases, the outline mode lets you toggle between the connections.

To make the connection lines disappear, click the three-dimensional triangle button that is highlighted.

Identifying Objects in Outline Mode

• To see a representation of an object, Alt-click on it in outline mode of the Instances display.
• To have an arrow point at the interface object, Control-Shift-click on the object in outline mode.

In the outline mode of the Instances display you might want to verify what an object is before connecting it to another object. You have two graphical ways to identify an interface object. One method displays an image representing a selected object, as shown in Figure 3-111.

Figure 3-111

When you Alt-click on non-NSView objects in outline mode, the images that represent them in icon mode are displayed (cubes for custom objects, mini-windows for panels and windows). Menus, First Responder, and File's Owner do not display icons.

The other technique locates an object in the interface with a large arrow, as shown in Figure 3-112.

Figure 3-112

Control-Shift-Clicking on Menu, File's Owner, and First Responder has no effect.

See "Outline Mode of Instances Display" on page 3-12 for an introduction to outline mode.

Enabling Inter-Field Tabbing

Sometimes when users press the Tab or Return key in a window with multiple fields, you want the pointer to jump from the current text or form field to the next field. When users press Shift-Tab, you want the pointer to go the previous field. An NSForm object (a matrix) automatically moves the pointer between its fields. But between text fields, between NSForms, or between an NSForm and a text field, you must specify this behavior.

To specifying inter-field tabbing, do the following:

1. Make a connection line between forms or fields.

2. Select nextText in the object's Connections display.

3. Click the Connect button.

The NSMatrix class (of which NSForm is a subclass) and the NSTextField class define an instance variable, nextText, as an outlet. This is what you connect (see Figure 3-113).

Figure 3-113

Next, make the connection in the Inspector panel as shown in Figure 3-114 on page 3-130.

Figure 3-114

Note the textDelegate outlet in this example's Inspector. This is the object that receives delegation messages from the NSText class on behalf of a text-editable field.

Disconnecting Objects

Interface Builder gives you two ways to break the connections between objects. The first method uses the Inspector panel, as shown in Figure 3-115 on page 3-131, through the following steps.

1. Select an object.

2. In the Connections display, select a connection.

3. Click Disconnect.

Figure 3-115

You can also initiate this procedure by selecting objects in icon mode of the Instances display, and then disconnecting them in the Inspector panel as above.

The alternative method for disconnecting objects is somewhat easier because you can complete the operation in one place: in outline mode of the Instances display. First show connections for an object by clicking a three-dimensional triangle button, as shown in Figure 3-116 on page 3-132.

Figure 3-116

To make the scissors pointer appear over a connection line, you must press the Control key over a line on the right side of the column divider (nearest the connection-out and connection-in triangle buttons). You Control-click on the left side of the column divider to begin connection operations. See "Examining Connections" on page 3-122 to learn how to use outline mode to display the connections between objects.

Attaching Help to Objects

The Help Builder panel makes it easy to associate help text with any object in your application's user interface. (To learn about the design of the OpenStep help system, see the NSHelpPanel class specification in OpenStep Programmng Reference.)

The Help Builder panel is a slightly modified version of the standard Help panel.

Figure 3-117

Attaching help to an object involves selecting an object in your application, displaying the help text in the Help Builder panel, optionally selecting a help marker within the text, and clicking on the AttachFile to Selection button. Thereafter, when the application runs and the user Help-clicks on the object (that is, holds down the Help key and clicks on the object), the specified help text is displayed in the application's Help panel. However, before you begin attaching help text to your application's objects, you must provide your application with two components: a Help menu item and a Help directory.

Interface Builder's Menu palette supplies an Info menu item that, when dragged to your application's main menu, reveals a submenu containing a Help menu item. This menu item is preconfigured to open the Help panel. (If you inspect the Help item's connections, you will see that it sends a showHelpPanel: message to the First Responder object.)

Project Builder can provide your application with the required Help directory. Choose the Add Help Directory command in Project Builder's Project menu to create this directory. Project Builder creates the directory within the .lproj directory of your chosen development language (for example, English.lproj/Help). It copies into this directory generic table-of-contents and index files.

The next step is to customize these files and to add content files of your own. The generic help text that is accessed through the supplied table-of-contents and index files gives help on basic operations, such as using the mouse and choosing commands. You will want to add files that describe the operations that are unique to your application. You can also override or eliminate any of the generic help text that is not applicable to your application.

You create help files using Edit. (Make sure that Edit is in Developer Mode so that the Help commands can be accessed from the Format menu.) Perhaps the easiest way to ensure that the files you add agree in style and formatting with the generic help files is to display a generic file, copy its contents, and paste it into a new Edit document. Be sure to resize the new document's window to the same width as the original so that the text wraps to the same margins. You can then modify the contents of the new help document and save it in the Help directory. If you think you will want to associate objects with specific passages within the file, rather than to the file in general, you can place help markers within the document.

Each file you add should be represented by a new entry in the table-of-contents file. (However, see the NSHelpPanel class specification for an exception to this rule.) After adding content files, you will also probably have to update the index.

Once the table-of-contents, content, and index files for your help system are finished, you can begin attaching help to your application's user-interface objects. Display the Help Builder panel by choosing the Help Builder command from Interface Builder's Tools menu or by clicking on the Help Builder button in the Help display of the Inspector panel. Select an object in your application's user interface, locate the relevant help text in the Help Builder panel, and click on the Attach... button. If the Help inspector is open, it displays this new association in its Help Attachments list.

The Help Builder panel offers several ways to locate specific portions of help text. First, you can use the table-of-contents or index displays to locate a file. In addition, the pop-up list below the Find field lets you search for help files by name, for marker names within the help files, or for any string.

Reviewing Help Attachments

The Help display, shown in Figure 3-118, lets you review attachments between objects in your application and help text. It also gives you access to Interface Builder's Help Builder panel.

Figure 3-118

The Help display is used in conjunction with the Help Builder panel. See "Attaching Help to Objects" on page 3-132 for information on associating help text with objects in your application.

Assuming you have attached help to objects in your application, the Help display of the Inspector panel will list those attachments. Each entry in the list has two parts. The left half of the entry identifies the object, and the right half displays the file name for the attached help. Below the Help Attachments list are two text fields. The Marker field names the marker that the object is attached to within the help file. If the object is not attached to any marker in the file, the Marker field is blank. The File field displays the path of the help file relative to the application's Help directory. If the entire path is not visible, scroll the text field horizontally to reveal the hidden portion.

You can remove an attachment by selecting it in the list and clicking on the Detach button.

Testing the Interface

After you create an interface, Interface Builder lets you see how it works from the user's perspective. Just choose the Test Interface command from the Document menu.

1. Choose the Test Interface menu command.

2. Check the functioning of kit objects.

3. Choose Quit from the application menu or double-click the switch icon in the application dock.

Interface Builder's menu, windows, and panels disappear, leaving only the actual interface and (if you are testing the application's main nib file) the main menu. Give your interface a test ride. Here are some of the things you might try:

• Verify that the pointer moves from field to field when you press Tab and Return.
• Verify that you can copy, cut, and paste text (First Responder actions).
• See if you can print (the Print menu item must be connected to an appropriate NSView object's printPSCode: action method).

---

Note - When you test your interface, the behavior provided by your custom classes is not called into play (with the exception of static, compiled palette objects). You can only test the behavior that kit and static palette objects exhibit in themselves and when they send messages to each other. To test all components of your application, you must compile and run it.

---

When you are finished testing the interface, exit from test mode.

Figure 3-119

Creating a Class

Creating a class, or adding an existing class, is not a set of discrete, modular tasks, but a process consisting of many interdependent tasks. The order of these tasks is significant,: with some exceptions, you need only follow the tasks in the sections that follow sequentially, from first task to last task, and you will create a useful class.

However, the exceptions are significant, so flowcharts are provided to point the way. Figure 3-120 on page 3-139 guides you through the tasks required to define and implement a subclass of a root class or the NSView class. Figure 3-120 on page 3-139 identifies the tasks you must complete to integrate an existing class into an application. Table 3-8 on page 3-138 explains the symbols used in the flow charts.

Table 3-8

Symbol	Meaning
	Main Flow Decision Point
	Optional Flow
	Section in this chapter that describes a task you perform

---

Note - Interface Builder's role in subclass creation is to help you locate the class in the hierarchy. name it, coneect an instance of it with other objects in an application, and generate template source files. When Interface Builder's role is finished, you then must make the most important contribution: the source code that gives your class its distinctive behavior.

---

Figure 3-120

NSView

Figure 3-121

Naming a New Class

When you create an application in OpenStep, you must create at least one subclass to do anything meaningful. The Application Kit, Foundation Kit, and other OpenStep kits are powerful frameworks that do much of the work for you, but you must always supply one or more subclasses, the distinctive and logical flow of your application. To create a subclass, do the following:

1. Choose the Classes display of the nib file window.

2. Select the class from which you want your subclass to inherit.

3. Choose Subclass from the nib file window's Operations menu.

4. Type the name of your class over the highlighted default name.

When you create a class, the first thing you must do is select your class's superclass. Make your selection in the Classes display of the nib file window, as shown in Figure 3-122.

Figure 3-122

---

Note - Pressing the Return key when a class is selected is equivalent to choosing the Subclass command.

---

The new class is listed under its superclass with a default name: the superclass name prefixed with "My", such as MyNSObject. Replace this default name with the new name, as shown in Figure 3-123.

Figure 3-123

Later, if you want to rename the class, first re-select the class name by double-clicking on it. Then type the new name, replacing the selected text.

A Perspective on Class Hierarchy

The Classes display of the nib file window (see Figure 3-124 on page 3-143) shows the classes of which the current nib file is aware. The display lets you browse through both OpenStep classes and custom classes. It also depicts, by indentation, class inheritance relationships, and reveals the names of each class's outlets and actions.

Figure 3-124

You can move up and down the list of classes by pressing the up arrow key and down arrow key on your keyboard. When a class is highlighted, you can show its subclasses by pressing the right arrow key, and collapse an indented list by selecting the superclass and pressing the left arrow key. If the nib file window is active, incremental search is active; just type the first few letters of a class name until it is highlighted.

Specifying Outlets and Actions

An object isolated from other objects is of little use. Interface Builder provides two ways for you to specify how objects of your class communicate with the outlets and actions of other objects: outlets and actions. To specify an outlet or action for your class, do the following:

1. Click on the outlet button or the action button for the class.

2. Select Outlets or Actions and press the Return key.

3. Enter the name of the new outlet or action in place of the default name that is displayed.

Before you begin this task, take a moment to consider what other objects you want instances of your class to send messages to, and what kinds of requests instances of your class are likely to receive from other objects.

---

Note - For background information on outlets and actions, see "Communicating With Other Objects: Outlets and Actions" on page 3-109.

---

Adding Outlets

Outlets are instance variables that identify other objects. In the Classes display, you access the outlets of a class by clicking on the electrical outlet buttons, as shown in Figure 3-125.

Figure 3-125

When you press the Return key or choose the Add outlet command from the Operations menu, a new outlet is displayed under Outlets, as shown in Figure 3-126 on page 3-145. Type the name of the outlet in place of the default name and press the Return key.

Figure 3-126

When you press the Return key, the outlet is renamed and Interface Builder highlights the new outlet. To add another outlet, press the Return key again.

---

Note - To display a class's outlets and actions (with Outlets highlighted), you can choose the Edit class command from the nib file window's Operations menu instead of clicking on the outlet button.

---

Adding Actions

Actions are methods invoked as a direct consequence of the manipulation of NSControl objects in your application's interface, such as when users click on a button. In the Classes display, you access the actions of a class by clicking on the cross-hairs button, as shown in Figure 3-127 on page 3-146.

Figure 3-127

When you press the Return key or choose the Add action command from the Operations menu, a new action is displayed under Actions, as shown in Figure 3-128. Type the name of the action in place of the default name and press the Return key.

Figure 3-128

When you press the Return key, the action is renamed and Interface Builder highlights the new action. If you did not specify a colon (:) after the action name, Interface Builder appends it for you. To add another action, press the Return key again.

When you have finished adding outlets and actions, click on the class name to collapse the list of outlets and actions.

Creating an Instance of Your Class

You cannot connect classes to other classes. Only instances of classes--objects--can really communicate with each other. Interface Builder requires a real instance of your class to enable the connection of your object to other objects.

The procedure for generating instances of non-NSView classes in Interface Builder is simple (see Figure 3-129). The following steps apply only to classes that do not inherit from the NSView class.

1. Select your class in the Classes display.

2. Choose Instantiate from the Operations pull-down menu.

Figure 3-129

When the new instance is displayed in the Instances display (see Figure 3-130 on page 3-149), it takes the same name as the class. Rename it, if you want, to something more indicative of an object. Double-click on the text to select it, then type the new name. For example, AppController could become AppControllerObject. Be aware, however, that this name is merely a convenient way to identify the object in Interface Builder; it does not create an identifier that you can reference in code.

Figure 3-130

Connecting Your Class's Outlets

An outlet is an instance variable that identifies another object. You initialize an outlet in Interface Builder by making a connection from your instance to another object, as shown in Figure 3-131 on page 3-150. To do so, perform the following steps:

1. Control-drag a connection line from the instance to another object.

2. In the Connections display, select the outlet that identifies the destination object.

3. Click on the Connect button.

Figure 3-131

When you establish the line connection, the Inspector panel for the destination object becomes the key window. Specify the outlet identifier for this object as shown in Figure 3-132 on page 3-151.

Figure 3-132

---

Note - This task and the next one, "Connecting Your Class's Actions," summarize information presented more fully in "Making and Managing Connections" on page 3-109.

---

Connecting Your Class's Actions

An action is a method that an NSControl object invokes in your instance--the target object--when a user activates the NSControl (for example, clicks on a button). you make an action connection in Interface Builder by drawing a connection line form the NSControl object to the instance of your class, as shown in Figure 3-133 on page 3-152.

To make an action connection, do the following:

1. Control-drag a connection line from an NSControl object to your class's instance.

2. In the Connections display, select the appropriate action.

3. Click on the Connect button.

Figure 3-133 NSControl

When the line is set between objects, the second column of the Connections display shows the action methods that the target object (your instance) has declared. Select the action for this NSControl object, as shown in Figure 3-134 on page 3-153.

Figure 3-134

---

Note - You can make connections between objects entirely within the outline mode of the Instances display. For more information on the outline mode, see "Making and Managing Connections" on page 3-109.

---

Generating Source Code Files

Before you begin specifying the behavior of your class in code, you typically generate template source code files for your class from the information contained in the nib file. The header file MyClass.h created by Interface Builder declares the outlets you specified as instance variables of type id and

declares the actions as instance methods of the form methodName.sender. The implementation file MyClass.m contains emply function blocks for each of these methods.

To generate source code files for your class, do the following:

1. Select your class in the Classes display.

2. Choose Unparse from the Operations pull-down menu.

3. Click on Yes in the subsequent attention panels.

Interface Builder generates template code files by unparsing the nib file (see Figure 3-135 on page 3-154).

Figure 3-135

Interface Builder then displays an attention panel to confirm creation of the files (see Figure 3-136 on page 3-155).

Figure 3-136

If you confirm creation and the nib file is assocated with a project, another attention panel subsequently asks if you want to add the template code files to the project. Click on Yes to add the files to the project.

Implementing a Subclass of NSObject

This task summarizes the steps you must complete--and can optionally complete--to implement a subclass of NSObject. With this kind of subclass, the subtleties arising from inheritied behavior are simplified. Still, the interaction of your class with the root class is very important, and applies to all subclases.

In this task you write code, and so there is a temporary departure from interface Builder. The task assumes you have complete the following prerequisites in Interface Builder, presented earlier in this chapter:

• Naming a class and positioning it in the class hierarchy
• Specifying outlets and actions for the class
• Creating an instance of the class
• Connecting the instance to other objects through the outlets and actions
• Generating code files by unparsing the nib file

When you have generated code files in Interface Builder, switch over to Project Builder and open your project. Open your class's header file (ClassName.h) and implementation file (ClassName.m) in Edit windows.

1. Import header files

2. Declare new instance variables.

3. Implement accessor methods.

4. Define target/action behavior.

5. Define initialization and cleanup behavior.

6. Define how objects are copied.

7. Define how objects are compared.

8. Implement archiving and unarchiving.

9. Define special behavior for your class.

Making Your Class a Delegate

Several OpenStep classes allow you to register their object as a delegate. As certain events occur, the kit objects send messages to their delegates, giving them the opportunity to participate in processing. In Interface Builder, you can easily designate your class's instance as a delegate, as shown in Figure 3-137 on page 3-157. To do so, perform the following steps:

1. Connect your instance to an object that has delegates.

2. Select the delegate outlet in the Connections Inspector panel.

3. Click on Connect.

4. Implement the delegate methods.

Figure 3-137

Next implement the delegate methods to which you want your object to respond.

---

Note - Messages to delegates sometimes notify them of impending or just-transpired events, and sometimes request them to complete some work. Major classes with delegate methods are NSApplication, NSWindow, NSText, and NSBrowser. See OpenStep Programming Reference for details on delegate methods

---

Implementing an NSView Subclass

Making a subclass of the NSView class is a procedure that differs from making a subclass of the NSObject class. But it starts in the same way. In the Classes display of the nib file window, choose Subclass from the Operations pull-down menu while NSView is highlighted in the browser. Then name your class and add outlets and actions.

To implement an NSView subclass, do the following:

1. Identify the class and its outlets and actions.

2. Place and resize and NSCustomView object on a window or panel.

3. Assign your class as the class of the NSCustomView.

4. Connect the instance to other objects in the interface.

5. Generate code files.

6. Complete programming tasks necessary for any object.

7. Complete programming tasks specific to NSView objects.

Figure 3-138 NSView

---

Note - The steps in this task, insofar as they apply to NSView, also apply to creating classes that inherit from subclasses of NSView.

---

Place a proxy instance of your class in your interface, as shown in Figure 3-139 on page 3-160. Interface Builder provides a CustomView object to represent instances of NSView subclasses.

Figure 3-139 NSView

Position and resize the CustomView object, and while it is still selected, bring up the Attributes display of the Inspector panel (see Figure 3-140 on page 3-161). Assign a class name to the object; this creates an instance of your NSView subclass.

Figure 3-140 NSView

Now complete the following three tasks, which are the same tasks that follow the instantiation of an NSObject subclass:

• Connect the instance to other objects in the interface (see "Connecting Your Class's Outlets" on page 3-149 and "Connecting Your Class's Actions" on page 3-151). But now the instance is displayed as part of the interface, and not as an icon in the Instances display of the nib file window.
• Generate code files and have them inserted in your project (see "Generating Source Code Files" on page 3-153).
• Switch over to the project in Project Builder that contains the nib file. Open your class's code files in Edit and complete the programming tasks for your subclass.

Adding Existing Classes to Your Nib File

• Drag the header file from the File Viewer or Project Builder into the nib file window (see Figure 3-141).

or

• Copy a class in one nib file and paste it into another.

The easiest way to add a class to your nib file is to drag the header file for an existing custom class from the Workspace Manager's File Viewer into Interface Builder.

Figure 3-141

You can also add a class definition to a nib file by dragging a header or implementation file from Project Builder into a nib file window.

The new class is displayed in the Classes display under its subclass and with its outlets and actions defined. After adding the class, you must still connect it to other objects through its outlets and actions. To do so, complete the following steps:

1. Make an instance of the class (for NSView subclasses, that means assigning your class name to the NSCustomView object).

2. Connect the instance's outlets and actions to other objects in the nib file.

---

Note - Instead of defining a class in Interface Builder, you can write a header file and drag it into a nib file window as described above. When writing your header file, be sure to declare outlets as instance variables of type id. Declare actions as methods with a single argument: sender.

---

Updating a Class Definition

If you later add outlets and actions to the header file, or delete them from it, Interface Builder allows you to update the nib file with this new information (see Figure 3-142).

• Choose the Parse command and select a header file in the Open panel.

Figure 3-142

Interface Builder brings up an Open panel for you to confirm (or select) the class definition to update (see Figure 3-143 on page 3-164).

Figure 3-143

If there are any new outlets and actions, remember to connects these outlets and actions to other objects in the nib file.

---

Note - You can also use the Parse command to add an existing class to a nib file (see "Adding Existing Classes to Your Nib File" on page 3-162), or you can create a header file and read it into a nib file through the Parse command.

---

Adding IDL Template Objects to Your Interface

The IDL display of the File window shows the IDL types that are available to your application. You can parse IDL files into your application and instantiate IDL template objects using the Actions pull-down list.

The Parse IDL button (see Figure 3-144) displays an Open panel that lets you specify the IDL type file you want Interface Builder to parse. Interface Builder parses the type from the file and then displays the names of the IDL types in the IDL display.

Figure 3-144

You can instantiate an IDL template object from any of the IDL interfaces shown in the IDL display.

The Make Template Object button (see Figure 3-145) creates an IDL template object and places an icon representing that object in the Instances display of the File window. The template object does not make a connection with its NEO system until the nib file is loaded into your application at run time. Therefore, the NEO system does not have to be running when you create interfaces with IDL template objects.

Figure 3-145

The name of the object is derived from the name of the IDL type from which it is instantiated. You must change its name in your application to the name by which it is known to the NEO Naming Service. If you have access to the NamingContext (that is, the server that implements the object is running and is part of your NEO workgroup), you can determine this name by using neoadmin. (For an overview of the NEO Naming Service and information on using neoadmin, see NEO System Management.) If you do not have access to the NamingContext, you may need to get the correct name for the object from the developer who developed its server. You change the name by bringing up an Attributes inspector for the IDL template object and typing in the new name.

Connecting IDL Template Objects

Connections cannot be dragged from IDL template objects because IDL template objects have no outlets or actions to which connections can be made. Connections can be dragged from NSCustomObjects or NSCustomViews to IDL objects because the outlets in NSCustomObjects and NSCustomViews that you add can have their types changed (see "Outlet Autotyping" below).

After you click on the Connect button, the button's title changes to Disconnect, allowing you to remove the connection. If you cut or copy a connected object and then paste it, its connections are severed.

---

Note - You can connect IDL template objects only to NSCustomObjects or NSCustomViews subclassed from Application Kit objects. You must use outlets that you have added to the custom objects. See "Outlet Autotyping" below for information on how outlets are autotyped when connected to IDL template objects.

---

Outlet Autotyping

The OpenStep programmatic interface encourages developers to add types to variables wherever possible, but does not require types. Interface Builder supports types by autotyping outlets in NSCustomObjects and NSCustomViews.

When you connect an object to an outlet you have added to an NSCustomObject or NSCustomView, the outlet's type is automatically changed from id to the class of the object that is the source of the connection. If the source object is an IDL template object, the IDL type is used instead.

For Objective C objects, autotyping reduces the number of warning messages emitted by the compiler when compiling code generated by Interface Builder, and reduces the possibility of a run time type error (that is, an exception due to the object not supporting a method selector). For IDL template objects, autotyping removes the possibility of a compiler error, since IDL types are statically checked and the compiler does not compile a file unless the IDL types of objects and variables match.

If you later try to connect the same outlet to an object of a different class, the outlet type may be altered:

• If the source object's class is a subclass of the outlet type, then the connection succeeds and the outlet type is not changed for either IDL or Objective C.
• If the source object's class is a superclass of the outlet type, then the outlet's type is changed to the source object's class for both IDL and Objective C.

• If either the source object or outlet type is an Objective C class, and the other is an IDL type, you are prompted about whether you want to change the outlet type.removing all existing connections to other objects. If you answer YES, the outlet type is changed to the source object's type, and all connections to other objects having that outlet are removed.
• If no subclass/superclass relationship exists, then an outlet with an Objective C type is changed to id. You are prompted about whether you want to change the outlet type for an outlet with an IDL type, removing all existing connections to other objects. If you answer YES, the outlet type is changed to the source object's type, and all connections to other objects having that outlet are removed.

In addition, the outlet browser in the Connections display of the Inspector panel deactivates outlets and the Connect button if a connection is dragged to an object that cannot be connected to the outlet. For example, an IDL object cannot be connected to the target outlet in an NSButton object, because an NSButton object is created by the Application Kit and the types of Application Kit outlets cannot be changed (they are always id).

Setting Preferences

You open the Preferences panel by choosing the Preferences command in the Info menu. This panel has two displays; you use the pop-up list at the top of the panel to access these displays.

General Preferences

These preferences control which panels appear when Interface Builder is launched and also whether a backup file is created when the nib file is saved.

Figure 3-146

If the Save Option box is checked, Interface Builder creates a backup file whenever you save a nib file that has been modified. Assuming the box is checked, if you open a nib file named FindPanel.nib, make changes, and then save the modified file, Interface Builder renames the original file FindPanel.nib~ before saving the modified file as FindPanel.nib. Because of the safety of having a backup file, it is generally better to leave this box checked.

Palettes Preferences

This display of the Preferences panel shows you which palettes are available to Interface Builder and lets you control which palettes are installed in the Palettes window.

Figure 3-147

Each palette is represented by an icon. The palettes that are already installed in the Palettes window display their titles in gray; those that have not been installed display their titles in black. Double-clicking on the icon toggles the state of the palette: If it was installed, it is removed from the panel; if it was uninstalled, it is installed in the panel.

When Interface Builder begins running, it loads the standard palettes (those displayed in the top row of the illustration above). It also adds to the Preferences display any palettes the user has previously loaded using the Open... command on the Palettes menu.

Adding Custom Palettes, Inspectors, and Editors

Interface Builder's primary value as a development tool is that it lets you interact directly with the objects that will make up your application. In general, these objects are defined by the OpenStep system software. However, it is possible to extend Interface Builder's library of objects by creating custom palettes, thus letting you interact directly with objects that you or other developers have created.

A custom palette can contain objects of various sorts. Most commonly, a custom palette contains NSView objects, objects that the user instantiates by dragging into a standard window. It is also possible to create custom palettes that contain NSMenuCells (which are instantiated by being dragged into a menu), NSWindows (which are instantiated by being dragged into the workspace), and other non-NSView objects (which are instantiated by being dragged into the File window).

For any custom palette object, you can provide one or more inspectors. A custom object's inspector is displayed in the Inspector panel when the user selects the object. Most custom objects require an Attributes inspector. For example, the fictitious RepeatButton class mentioned earlier would probably require an Attributes inspector to let the user set the repeat rate for a given button. It could also supply its own Connections, Size, and Help inspectors, although the standard versions of these inspectors are generally adequate for most uses.

Finally, a more complex custom object may require its own editor. An editor controls how a user can interact with a selected object. Interface Builder itself supplies editors for the objects it knows about. For example, when you double-click on a window icon in the File window, Interface Builder's window editor is invoked and brings the actual window to the front. Or, when you double-click on an NSForm object in an application window, Interface Builder's matrix editor is invoked, letting you drag cells to new positions.

An editor that you provide must open its own window when the user double-clicks on the custom object. Since each custom object can have its own editor window, editors make copy and paste or drag and drop operations between editor windows possible.

Creating custom palettes, inspectors, and editors involves working with Interface Builder's application programming interface (API). This API is described in detail in Appendix B, "Interface Builder Application Programming Interface," Appendix C, "Interface Builder API Classes," Appendix D, "Interface Builder API Protocols," and Appendix E, "Interface Builder API Types and Constants."

Interface Builder Command Reference

The remainder of this chapter gives short descriptions of Interface Builder's commands. Only those commands that are unique to Interface Builder are listed; for information on commands that are common to all OpenStep applications see Using the OpenStep Desktop.

Commands in the Document Menu

These commands act to open, create, save, or test an Interface Builder document. (Interface Builder documents are generally referred to as "nib files," since that is how they are stored on disk. However, until a document is saved, no file exists, so referring to the document as a "nib file" is not strictly correct. Even so, for simplicity, Interface Builder documents are referred to as nib files throughout, unless to do so would cause confusion.)

Table 3-9

Command	Description
Open	Opens an existing nib file.
New Application	Creates a new Interface Builder nib file containing the basic components of an application: a main menu, a standard window, and other resources. You rarely use this command since it is generally more convenient to have Project Builder create the nib file for a new application. See the description of Project Builder's New command in "Commands in the Project Menu" on page 2-33 for more information.
New Module	Opens the New Module submenu, which offers commands for creating various sorts of Interface Builder nib files other than the type used for an application's main nib file. See "Commands in the New Module Submenu" on page 3-172 for more information.
Save	Saves the current nib file. You can edit more than one Interface Builder nib file at a time. Each open nib file is represented by a File window. The File window that has main or key window status identifies the current nib file.
Save As	Saves the current nib file under a different file name.

Table 3-9 (Continued)

Command	Description
Save All	Saves all open nib files.
Revert to Saved	Restores the current nib document to the state represented in the nib file. All changes made since the file was last saved are lost.
Test Interface	Puts Interface Builder in test mode. When you choose this command, Interface Builder's supporting windows disappear, leaving only those windows that belong to your application. You can then test the operation of the objects in your application. See ""Testing the Interface" on page 3-136 for more information.

Commands in the New Module Submenu

These commands let you create auxiliary nib files of various sorts. (The main nib file is generally created by Project Builder.)

Table 3-10

Command	Description
New Empty	Creates the simplest sort of nib file, one that includes references only to a File's Owner object and a First Responder object.
New Info Panel	Creates an auxiliary nib file containing a panel that is preconfigured as a standard Info panel.
New Attention Panel	Creates an auxiliary nib file containing a panel that is preconfigured as a standard Attention panel.
New Inspector	Creates an auxiliary nib file containing the components you need when creating an inspector for a custom palette project.
New Palette	Creates an auxiliary nib file containing the components you need for a custom palette project. You rarely issue this command directly, since Project Builder provides this nib for you when you create a new palette project.

Commands in the Edit Menu

Except for the Set Name command, this menu contains the standard editing commands: Cut, Copy, Paste, Delete, and Select All. These commands work in the expected ways.

Table 3-11

Command	Description
Enter selection	Highlights te name of the selected object in the outline mode of the nib file window's Instances display. To use this command, select an object in the interface, then choose Enter Selection. The appropriate object line in the outline mode is highlighted. This command is useful when you are using outline mode and you want to know which line in the outline mode represents a particular object in the interface.
Set Name	Displays a panel that lets you set the name of the selected object. With this name, and the NSGetNamedObject() function, you can access objects by name within your application. However, it is generally a better idea to access objects through the use of outlets, since outlets can be connected and disconnected in Interface Builder, eliminating the need to alter your application's code.

Commands in the Format Menu

This menu lets you set the font and formatting attributes of the selected object. It also gives you access to the Group submenu, the Align submenu, the Sixe submenu, and the Page Layout panel.

Table 3-12

Command	Description
Font	Opens the Font submenu. Interface Builder's use of the Font submenu is entirely standard. By setting the font of an NSTextField or the NSText object within the NSScrollView (for example), you are determining which font the user will use in those objects when the application runs.
Text	Opens the Text submenu. Interface Builder's use of the Text submenu is entirely standard. By setting the text alignment or tab settings of an object in Interface Builder, you are determining the alignment and tab settings for those objects at run time. Note that the ruler commands work only with a Text object that is the document view of an NSScrollView.
Bring To Front	Establishes the selected object as the frontmost object in the window. If the selected object intersects other objects, the selected one is drawn over the others. If more than one object is selected when you choose this command, the entire group of objects is brought in front of all other objects in the window.
Send To Back	Puts the selected object or objects behind all other objects in the window.
Group	Opens the Group submenu, which is described in "Commands in the Group Submenu" on page 3-175.
Align	Opens the Align submenu, which is described in "Commands in the Align Submenu" on page 3-175
Size	Opens the Size submenu, which is described in "Commands in the Size Submenu" on page 3-177
Page Layout	Opens the standard Page Layout panel. This panel lets you specify how the window you print using Interface Builder's Print command will appear on paper. Since a screen pixel is approximately 75 percent of the size of a printer pixel, the image of a window looks larger on paper than it does on the screen. To compensate, set the scaling factor to 75 percent in the Page Layout panel's Scale field.

Commands in the Group Submenu

This menu offers commands that help you group the selected object or objects.

Table 3-13

Command	Description
Group	Puts the selected object or objects behind all other objects in the window.
Group in ScrollView	Groups the selected object or objects in an NSScrollView. The NSScrollView is sized so that it just accommodates the objects in the group. The grouped objects are made subviews of the NSScrollView.
Group in SplitView	Groups the selected objects within an NSSplitView object. The objects become subviews of
Ungroup	Removes the grouping established by the Group or Group in NSScrollView commands.

Commands in the Align Submenu

This menu provides commands that let you position objects accurately within a window.

Table 3-14

Command	Description
Set Grid On / Off	Enables and disables the alignment grid in all windows of all open nib files. When the grid is enabled, View objects dragged into a window are constrained in their location and dimensions to the units defined by the grid. By default, the intersections of the grid are aligned, both vertically and horizontally, on every eighth pixel in a window. Also by default, an object's lower left corner is the reference point for alignment with the grid. (The grid spacing and the object's reference point can be changed using the Alignment panel.) By default, the intersections of the grid are aligned, both vertically and horizontally, on every eighth pixel in a window. Also by default, an object's lower left corner is the reference point for alignment with the grid. (The grid spacing and the object's reference point can be changed using the Alignment panel.)
Show Grid / Hide Grid	Displays and hides the alignment grid in all windows of all open nib files. The grid is displayed as a rectangular array of dark gray dots.
Align To Grid	Aligns the selected objects to the nearest grid mark. To use this command, first select one or more objects by dragging around them or by Shift-clicking on them..

Table 3-14

Command	Description
Make Row	Aligns the selected objects horizontally. The row extends to the right of the selected object that is nearest the top left corner of the window. The spacing between objects is determined by the original spacing between the two objects nearest the window's top left corner. If these objects originally overlapped, the objects in the resulting row abut each other.
Make Column	Aligns the selected objects vertically. The column forms below the object that is nearest the top left corner of the window. The spacing between objects is determined by the original vertical spacing between the two objects nearest the window's top left corner. If these objects originally overlapped, the objects in the resulting column abut each other.
Alignment	Opens the Alignment panel, which is described in the "Using the Alignment Panel" on page 3-45.

Commands in the Size Submenu

This menu's commands allow you to resize an object.

Table 3-15

Command	Description
Size to Fit	Resizes the selected object to the minimum size required to display its contents. If more than one object is selected, each is resized to its own minimum size. For an object of a given class, minimum size may depend on the font used to display the title, the alignment and location of the title, and the distance the content area is offset from other areas of the object.
Same Size	Forces one or more selected objects to assume the dimensions of another selected object. The first object you select establishes the dimensions that the other selected objects will assume.

Commands in the Tools Menu

This menu's commands open or bring to the front the named panel

.

Table 3-16

Command	Description
Colors	Displays the Colors panel.
Inspector	Displays the Inspector panel.
Palettes	Opens the Palettes submenu, which is described in "Commands on the Palettes Submenu" below.
Help Builder	Displays the Help Builder panel. This panel will be empty unless your application is part of a project containing a Help directory. See "Attaching Help to Objects" on page 3-132 for information on using the Help Builder panel.

Commands on the Palettes Submenu

This menu provides commands that let you open, create, save, and close palettes

Table 3-17

Command	Description
Open...	Presents an Open panel, enabling you to load additional palettes into Interface Builder's Palette window. See "Adding Custom Palettes, Inspectors, and Editors" on page 3-71 for more information.
New	Creates a dynamic palette. The Plette window will display a blank palette, to which you can add objects from your interface. Dynamic palettes do not have a palette project associated with them, and they do not have to be compiled.
Palettes...	Displays the Palette window. You can always access the four standard palettes using the palette window. You can also load nonstandard palettes into the window using the Open command on the Palettes menu.