How Panels Work

The panel is a type of window, and its most basic characteristics are those shared by all types of window. These are covered in Chapter 4, "Windows in the OpenStep Interface." Only the unique characteristics of panels are covered in this section.

Ordinary Panels

Ordinary panels look and behave very much like standard windows. They are typically in the same level as standard windows and compete with them for screen space. They have title bars, but do not usually have miniaturize buttons. Ordinary panels differ from standard windows:

• A panel can never become its application's main window.
• A panel should not become the key window unless it accepts typing from the keyboard.
• Panels are generally removed from the screen when the applications that own them are deactivated.
• You can make a panel into a "floating panel" by assigning it to the sixth level, which puts it above standard windows. See "Floating Panels" in this chapter for more about this.)
• Attention Panels

When an application opens an attention panel, it creates a mode that prevents the user from working in any of the other windows of the active application. The mode limits the user to rearranging. Nothing else in the application--title bar buttons, text entry, miniwindows, or controls in other panels--will work. The only menu commands that will work are those that can operate on the

attention panel itself. Cut, Copy, and Paste, for example, will work when an attention panel includes an editable text field. The mode remains in effect until the user responds to the attention panel and explicitly closes it.

While an attention panel is open, the user can activate another application and work in it. When the original application is reactivated, however, the attention panel is still displayed and the mode it created is still in effect.

Attention panels differ from ordinary panels in the following ways:

• An attention panel has an empty title bar.
• An attention panel is closed by one or more buttons in the content area, and does not have close buttons in their title bars.
• An attention panel stays on screen--even when its application is not active--until closed by the user.
• An open attention panel has key window status while the application that owns it is active.
• An attention panel is in the second level, above everything on the screen except spring-loaded windows such as pop-up lists.
• An attention panel is opened just above the center of the screen, so that users cannot overlook it. (Users can move attention panels.)

Because an attention panel creates a mode that disables the other functions of its application, it must have a distinctive appearance that immediately tells the user a mode is in effect. Some of the graphical features that create this distinctive appearance are illustrated in Figure 5-1.

Attention panels are closed when the user responds to the situation described by the panel. The buttons on the panel present the user with one or more possible responses. When the user chooses a button, the panel is closed and the mode ends.

Implementing Ordinary Panels

Because ordinary panels are used in many ways, you have considerable freedom when you design and implement them. This section covers guidelines for those aspects of ordinary panels that are different from standard windows.

Window Considerations

Title bar buttons and key-window status are handled differently than they are for standard windows. For more detailed information on the title bar buttons and on key windows, see "Implementing Windows" in Chapter 4.

Using the Resize Bar

If you decide that the ability to resize a panel might help your users, you should give it a resize bar. If necessary, you can set limits on the panel's dimensions that prevent users from making it too large or too small.

Using the Miniaturize Button

You can put a miniaturize button on an ordinary panel, but it is rarely needed. Since your users can use menu commands to close a panel or reopen it, the miniaturize button is generally redundant. You can make an exception if shrinking a panel to a miniwindow would be more convenient for users, or if a panel persists on screen when its application is not active. See "Persisting Panels" later in this chapter for more information.

Using the Close Button

Every ordinary panel should have a close button so the user can dismiss it when it is not needed. You don't need to break the close button, since panels do not display documents that users will be saving.

Panels That Become the Key Window

Panels that accept text entry and panels that are used independently of other windows should be allowed to get key window status. The Find panel, for example, becomes the key window because users can type in the word for which they are searching, and the standard Info panel becomes the key window because it displays information that is independent of the application's other windows and becomes the focus of the user's attention. On the other hand, the tool palette in a graphics application should never become the key window, because it is operated only by the mouse and is always used in conjunction with a document window.

Even if a panel accepts typing, you can delay giving it key window status until user action (such as clicking on a text field) indicates the user is ready to begin typing. Both of the following conditions must be true for you to implement this behavior:

• Text entry is not essential to using the panel.
• Users typically do not enter text when using the panel.

This is most often true for panels on which most of the control devices are not text fields, but are buttons, selection lists, and so on, and when there are alternatives to text entry. For example, the user can type an item or select it from a list. The Font panel is an example. This kind of panel should not show any selection until the user indicates a readiness to begin typing.

---

Note - Panels that need to avoid becoming the key window until the user indicates a readiness to begin typing can use the setBecomeKeyOnlyIfNeeded: method of the NSPanel class to do so. However, panels that should never become key--a tools palette, for example--must use a different way to avoid becoming the key window. Each panel must remove key-down and key-up events from its event mask.

---

Relinquishing Key-Window Status

After a panel becomes the key window, it should retain key window status only as long as necessary. If user actions on the panel affect the main window, key-window status should return to the main window when those actions are completed.

The Font panel, for example, gives up key-window status when the user clicks on the Set button on a Font panel and changes the font of the text currently selected in the main window. In all likelihood, the user is finished with the Font panel at this point and is ready to resume working in the main window. By managing key window status in this way, you allow the user to resume working in the main window immediately, without clicking on it just to make it the key window.

Exceptions to Ordinary Panel Characteristics

In general, ordinary panels are unobtrusive. They occupy the lowest level, and they disappear when their application is deactivated. In some situations that call for a more prominent panel, you can implement special features.

Persisting Panels

By default, an ordinary panel is removed from the screen when its application is deactivated. Users see only the panels that belong to the active application. This prevents confusion that could arise if similar panels from two different applications (two Find panels, for example) were on screen at the same time.

If one of your panels contains information that is relevant to the user's work in another application, you can override this default behavior and allow the panel to remain on screen after its application has been deactivated. This should be a rare occurrence.

An example is the Workspace Manager's Info panel, which contains system-level information, such as the amount of memory in the computer. Because the user might want to copy this information down--possibly into an e-mail message--this panel persists even when the user deactivates Workspace Manager and activates the mail application.

Floating Panels

By default, an ordinary panel is in the lowest level with standard windows. In some situations, however, it is useful for a panel to float above the standard windows and the other ordinary panels in the application. Typical of these situations is a small panel that contains a palette of drawing tools, which is most useful if it floats above the application's other windows. Figure 5-2 shows an example of a floating palette.

The following conditions should be true for you to implement a floating panel:

• The panel is oriented to the mouse rather than the keyboard. This means a panel you allow to become the key window should not be made a floating panel with one exception: It becomes the key window only when the user is ready to type (see "Becoming the Key Window" earlier in this chapter).
• It is important for the panel to remain visible while the user works in the application's standard windows. This is true when the user must frequently move between the standard window and the panel (as for a tool palette) or when the panel displays information that is relevant to the user's actions in the standard window (as in some inspector panels).
• It is small enough that it will not obscure much of what is behind it.
• It does not remain on screen when the application is deactivated.

Notice that panels float for some of the same reasons that menus do.

Panels With Variable Contents

Two types of ordinary panels--multiform panels and inspector panels--were designed for displaying specialized information in a limited amount of space. Both multiform and inspector panels can be used for many different purposes, even within the same application.

Multiform Panels

A multiform panel is a panel that can take a number of different forms. It has a pop-up list or a set of radio buttons at the top that which let the user choose which form it takes. Figure 5-3 shows a panel which lets the user choose among seven different forms.

Figure 5-3

Multiform panels conserve screen space by combining many related panels into a single panel. Since not all of a multiform panel's contents are visible at the same time, you should not use a multiform panel for an application's most basic functionality.

Inspector Panels

An inspector panel is a panel that displays information about the currently selected object. An inspector panel usually lets users set properties of the object, as well as view them. The Font panel (described in "Standard Panels" later in this chapter) is an inspector panel that displays font information for the current selection. Figure 5-4 shows the Workspace Manager Inspector panel, which lets users view and set information about the currently selected file or folder. Inspectors are often multiform panels, with each form displaying a different kind of information about the selected object.

Implementing Attention Panels

Because attention panels create modes that severely limit your users' freedom of action, you should use them only when they are really necessary. The guidelines for deciding when a panel should be implemented as an attention panel are:

• The panel gives the user information about the current context. The panel usually identifies an error, warns of potentially dangerous or unexpected results from the current course of action, or informs the user of a condition that makes it impossible to carry out the requested action. They may also supply information the user needs to proceed intelligently.
• It interrupts an action and gives the user an opportunity to take corrective steps--as does, for example, the panel that interrupts the Quit command to let the user save altered files before the application terminates.
• It clarifies or completes a user action--as does, for example, the panel that completes the Save As and Save To menu commands. In this case, the menu command must have three dots after its name--for example, "Save As...". This is discussed under "Commands That Open Panels" in Chapter 6.

Attention panels that interrupt or complete an action must have a Cancel button, which gives the user the option of cancelling the action. If Cancel is chosen, the application should return to its previous condition, as though the user had never initiated the action. When a panel informs or warns, it should, if possible, let the user choose what to do in response to the information it displays.

Naming an Attention Panel

Attention panels that open as the result of a command or a command-like action should be named for the action that brings them to the screen. The panel that appears after the user chooses Save, Save As, Save To, or Save All should be named Save. The panel that comes up when the user wants to close an edited but unsaved document should be named Close, whether it is invoked from the close button or through the Close or Close Window commands. The panel's name appears just to the right of the application icon, as shown in Figure 5-5.

Default Option in an Attention Panel

When a user action opens an attention panel that has more than one button, the button that allows the user to continue with the action should be the default button.

The default button should not perform any action that was not implied by the user request that brought up the panel. It should be the "safest" of the actions that are available to the user (for example, Open Copy rather than Open Anyway when the user tries to open a document that someone has already opened). It should not contradict what the user set out to do, which means you should not use Cancel as the default button.

The default button in an attention panel should be located in the lower right corner of the panel. In most cases, users should be able to operate it by pressing the Return key (when the panel is the key window), and you should mark it with the return symbol

to indicate this. When a default button has

dangerous side effects, it may be better to omit the return symbol and require that users click on the button.

Closing an Attention Panel

Each action that can close an attention panel is represented by a button. These buttons should be located along the right and lower edges of the panel, and the default button should be in the lower right corner. Only the default button should be operable by the Return key.

Naming the Buttons in an Attention Panel

Label each button clearly with a verb or verb phrase that describes its action. Users should be able to read the names of the buttons and choose the right one. They should not need to read other text on the panel. Avoid "generic" labels like Yes and No, because they are not clear and lead to user errors. Avoid using OK unless it is the only button in the attention panel.

Good names for attention panel buttons include:

Cancel Close Anyway Don't Close Don't Save

Explain Open

Open Copy Open Anyway Quit Anyway Replace

Revert Review Unsaved Save

Save All Set

Optional Explanations in an Attention Panel

An Explain button can offer users a way of getting more information before dismissing the panel. A typical example is shown in Figure 5-6.

Standard Panels

Some panels are used in many applications. The Info panel, which gives certain kinds of general information about the application, appears in every application. The Font panel, which lets the user set the font of the text selection, appears in every text processing application.

This section describes all the OpenStep standard panels. Some of them are provided by the App Kit; the others you build yourself, following the guidelines in this section. If there is a standard panel for a function you are using in an application, you should use it instead of designing a new panel.

If an Application Kit panel does not provide all of the features you want for your application, you can customize it by adding controls and information to what the App Kit already supplies. Figure 5-7 shows the standard Open panel on the right and a customized Open panel on the left. A check box (named Use Simple Mode) has been added to the customized panel.

Figure 5-7

---

Note - To customize a panel that is implemented by the Application Kit, construct an NSView that contains the information and controls you want to add. Add your NSView to the panel by sending it in a setAccessoryView: message.

---

Table 5-1 lists and describes the standard panels. The sections that follow the tables explain how to implement those panels that are not fully implemented by the App Kit.

Table 5-1

Panel	Description
Close	An attention panel that opens when a user tries to close a document with unsaved changes. For more information on this panel, see "Implementing the Close Panel" in this chapter.
Colors	An ordinary panel provided by the App Kit. It lets a user preview and specify colors in any of the following modes: color wheel, grayscale, red-green-blue (RGB), cyan-magenta-yellow-black (CMYK), hue-saturation-brightness (HSB), custom palette (which loads an image from which the user can choose colors), and custom color lists. A Colors panel sometimes works with color wells. See "Color Wells" in Chapter 7 for information on color wells. For information on the command that opens the Colors panel, see "Font Menu" in Chapter 6.
Find	An ordinary panel that lets the user enter a string for an application to search for. For more information on this panel, see "Implementing the Find Panel" later in this chapter.
Font	An ordinary panel provided by the Application Kit. It lets the user preview fonts and change the font of the currently selected text. For more information on the interface to fonts see "Font Menu" in Chapter 6.
Help	An ordinary panel provided by the Application Kit. Use this panel to display on-line help text. It can display text, graphics, and link buttons (which lead to other information). For more information on creating help, see "Using the Help Panel" later in this chapter.
Info	An ordinary panel that displays information about the active application. For more information on this panel, see "Implementing the Info Panel" later in this chapter.

Table 5-1 (Continued)

Panel	Description
Link Inspector	An ordinary panel provided by the App Kit. It lets a user get and set attributes of the currently selected linked information. If your application's documents can receive linked information, it should have this panel. For more information, see "Using the Link Inspector Panel" later in this chapter and "The Link Menu" in Chapter 6.
Open	An attention panel provided by the App Kit. It lets the user designate a file to open. For more information, see "Using the Open Panel" later in this chapter.
Page Layout	An Application Kit panel that prompts the user for information needed to display documents on screen, or print them. If your application has extensive page layout features, you can replace this panel with one that has information and controls for those features. For more information, see "The Format Menu" in Chapter 6.
Preferences	An ordinary panel that allows the user to determine some details of the application appearance and behavior. For more information, see "Implementing the Preferences Panel" later in this chapter.
Print	An attention panel provided by the Application Kit. This panel opens whenever the user prints a document or other data. It prompts the user for information needed to print, and displays the following options: send the output to a printer, save the output to a PostScript file, send the output to a fax modem, preview on screen, and cancel any of the preceding actions, even after they have started. For more information, see "The Main Menu" in Chapter 6.
Quit	An attention panel that should open when the user tries to quit an application that has some unsaved or incomplete work. For more information, see "Implementing the Quit Panel" later in this chapter.
Save	An attention panel provided by the Application Kit. It prompts the user for the name under which the file should be saved. For more information, see "Using the Save Panel" later in this chapter and "The Document Menu" in Chapter 6.
Spelling	An ordinary panel provided by the Application Kit to help the user check the spelling of text. See "Checking Spelling" in Chapter 6 for more information.

Implementing the Close Panel

When the user closes a document that has been edited but not saved, your application must open a Close panel and let the user choose among canceling the close operation, saving the document before closing, or closing without saving. This panel should have at least three buttons:

Cancel Don't Save

Save

Save is the default option, because many users do not think of closing a document and saving as separate operations--for many, closing implies saving.

If closing the document or window has consequences other than losing unsaved work, you must still use a Close panel to inform the user. When the user closes a terminal emulation window, for example, the emulator application should open a Close panel that tells the user closing will terminate the currently running command. In a situation like this, when there is no alternative to the "side effect" of the operation initiated by the user, the Close panel should have these buttons:

Cancel Close Anyway

---

Note - Do not open a Close panel unless there is work that will be lost.

---

Implementing the Find Panel

This panel, shown in Figure 5-8, should have at least two controls: a text field in which to enter a text string and a button that initiates a search for the next occurrence of the string. In most cases you should also have a button that will find the previous occurrence of the string.

---

Note - Although we recommended that you use verbs as button titles, it is not appropriate in this panel for two reasons. First, changing the titles to Find Previous and Find Next obscures the difference between the buttons--it is easy for users to miss the second word on a button. Second, the word "Find" is already used twice on the panel (and no other verb is), making it redundant in the button titles. For more information on naming buttons, see "Choosing the Button's Image or Label" in Chapter 7.

---

Find panels often have more controls than the panel in Figure 5-8. Typical additions are:

• Check box that lets users indicate whether capitalization matters in the search (by default, it should not)
• Check box that lets users indicate whether partial words should be considered matches (by default, they should)
• Second text field, named "Replace With" that allows the user to specify a second text string, which will replace the first when it is found
• Radio buttons that allow the user to indicate the range over which the search should be conducted (by default, the range should be global)
• Options that allow the user to specify objects other than text strings (such as paragraph characteristics) for the search

Although the Find panel usually stays open until the user explicitly closes it, there is one situation in which the application closes it for the user; see "When Mouse Operations and Keyboard Alternatives Differ" in Chapter 3.

This panel is opened by the Find Panel menu command, and the Find Next and Find Previous commands correspond to the buttons on the panel. For more information, see "The Find Menu" in Chapter 6.

Using the Help Panel

The App Kit's Help panel is part of the OpenStep help system. As supplied to you, the help system includes help text for basic interface tasks, such as using menus and scrollers, and skeletal help for menus and panels that are implemented in the App Kit. You write help text for application-specific objects and tasks, and link it to the basic text.

When users Help-click on a menu or panel implemented in the Application Kit, the supplied help text is displayed. For example, Help-clicking on the Print panel opens a Help panel with basic information on the panel's features.

You can add text for the objects in your application and the tasks associated with them. To do this, override the help files for Application Kit panels and commands with new files containing links to more task-oriented help. When you have added your own help text, you should modify the supplied index and table of contents so that they refer to your help text.

---

Programmer's Note - The Help panel is part of OpenStep's support for on-line help, which also includes:

• A question mark pointer which appears when the user presses the Help or F1 key (or on keyboards without a Help key, Alt-Control)
• Help text for basic user tasks (such as using menus and operating scrollers)
• An easy way to connect your interface objects to help text, so that Help-clicking on your objects will open Help panels with your help text

To add help text to your application, you first add a help folder using Project Builder. This help folder includes template files for the Help panel's index and table of contents. You can create and modify these and other help files, along with the help links in them, with the Edit application in developer mode. Both Interface Builder and the Application Kit have support for associating help with the user interface objects in your application.

For more information on implementing on-line help, see the discussion of NSHelpPanel in the OpenStep Programming Reference.

---

If your application uses the Help panel, you need to implement Help-clicking for each of its objects. (Otherwise, when the user Help-clicks on an object, the Help panel will open but will probably show inappropriate help.) Help-clicking on an object results in the panel automatically displaying the most specific help available. For example, when the user Help-clicks on a button, the help system first looks to see whether the button has help associated with it; if so, the Help panel displays it. If not, the help system looks for more general help, such as that associated with the window or even the application that the button is in.

---

Writing Note - You are encouraged to reuse the help text from OpenStep applications such as Edit, Mail, and Workspace Manager. After copying text from one of these applications' Help panels, you can paste it into a file in your application's help folder. You should then modify the text and update the help links it contains so that it suits your application. For example, Edit has help on working with documents, text, graphics, and color, as well as on printing. With a few changes, much of this help will be appropriate for other document-based applications.

You are also encouraged to use the design of OpenStep's help. Help in OpenStep applications is task-oriented, with Help-clicking serving as a way of discovering the tasks an object is used for. At the end of every help file is a list of related tasks, with links to the help for each task. The objects that have associated help are generally menu commands, standard windows, panels, and a few important buttons such as those in Mail's Compose window. If supplying this level of help is not practical, then you should at least ensure that Help-clicking on any object results in help on a relevant subject, even if the help is very general.

---

Implementing the Info Panel

Each application must have an Info panel (an example is shown in Figure 5-9), which displays a small amount of basic information about the application:

• Name of the application
• Application icon
• Copyright information
• Current version of the application
• Names of the authors (optional)

Figure 5-9

The Info panel should not offer help for using the application or give more information about it (such as its history or purpose).

Interface Builder includes a sample Info panel that you can use in your application. For information on the command that opens the Info panel, see "The Info Panel" in Chapter 6.

Using the Link Inspector Panel

When you use this App Kit panel, you should provide the following keyboard alternative for its Open Source button: hold down the Control key and double-click on a linked item. This should perform the same action as selecting an item and choosing the Open Source button.

Using the Open Panel

Whenever this panel is opened, it should list the contents of the folder with which the user was most recently working. To determine which folder this is, examine the window that is currently (or was most recently) the application's main window. The document displayed in this window will be the document most recently edited; the Open panel should list the contents of the folder that contains this document. If the application has not had a main window since it was started, the panel should show the user's home folder.

If your application can open only certain types of files, the Open panel should list only files of those types when it opens.

Implementing the Preferences Panel

Most applications have a Preferences panel, which is an ordinary panel that allows the user to determine some aspects of how the application looks and behaves. Figure 5-10 shows an Edit Preferences panel. Users typically use this panel infrequently. They should not need to open it during normal work with the application.

Figure 5-10

Preferences panels typically include controls for such things as:

• Default font size
• Format for displaying data
• Whether the application should make backup files
• Default size of the application's windows
• Options that make expert features available
• Application's keyboard alternatives

Do not use the Preferences panel for appearance or features the user might want to reset from time to time during a session.

The contents of the Preferences panel should be valid throughout the application; the appearance of the panel should not change depending on the window or data currently selected. The preferences should carry over from session to session; most will also affect the way the application works during the current session.

All of an application's options must be settable from within the application. It is not acceptable to have options that are settable only by using the dwrite command.

Preferences panels are often implemented as multiform panels, which reduces their dimensions and lets you organize the options. The Preferences panel is opened by the Preferences command in the Info menu. For more information, see Chapter 6, "Menus."

Implementing the Quit Panel

Whenever the user tries to quit an application that has unsaved or uncompleted work, the application should open a Quit panel. This should happen, for example, when the user has edited a document and not saved the changes, or when the application is still computing (a command is executing in a UNIX shell). Notice that in these situations, one or more of the application's windows should have a broken close button. For more information on breaking the close button, see "Using the Close Button" in chapter 4.

The Quit panel is an attention panel. In most cases it has three buttons, arranged as follows:

Cancel Quit Anyway

Review Unsaved

You could also add a Save All button that saves every unsaved document, exactly as the Save All command does. The buttons function as follows:

• Cancel cancels the Quit command and allows the user to take some alternative action.

---

Note - When your application opens a Quit panel because of a logout or a poweroff, the panel should not have a Cancel button, because the application cannot cancel the logout or poweroff.

---

• Quit Anyway continues the Quit operation, regardless of the consequences.
• Review Unsaved is the default button. If the user chooses this button, the application should cycle through its unsaved documents, opening a Review Unsaved panel for each one. The Review Unsaved panel functions like the Close panel, allowing the user to decide whether the document open for review should be saved, but its name reflects the different manner in which it is invoked.

  The user can cycle through all the unsaved documents, using the Review Unsaved panels to indicate which should be save. The user can also click on the Review Unsaved panel's Cancel button, which terminates the review process and returns the user to the Quit panel.

  You should only include a Review Unsaved button when the application is document-oriented.

---

Note - Do not open a Quit panel unless work is about to be lost.

---

Using the Save Panel

This Application Kit panel should come up showing the folder of the document being saved (the document in the main window). A document's folder is reflected in its window's title bar. For example, if the title bar shows

UNTITLED-1  --  /net/server/export/documents

the Save panel should come up showing /net/server/export/documents.