As its name implies, a Simple Window is the simplest top-level window. A Simple Window has no menu bar and can contain only one child element. If you want a menu bar for the window, create a VkWindow instead of a Simple Window. The child element that you place in a Simple Window is typically either a container widget or a complex component. You can use Simple Windows as main windows, but typically they're more appropriate as co-primary windows. See “Main Primary and Co-Primary Windows” for more information on main and co-primary windows.

When RapidApp generates code for a Simple Window, it creates it as a subclass of the IRIS ViewKit VkSimpleWindow class. (See Chapter 4, “ViewKit Windows,” in the IRIS ViewKit Programmer's Guide for more information on the VkSimpleWindow class.)

A VkWindow supports far more functionality than a Simple Window. Although it, like the Simple Window, can contain only one child element, a VkWindow includes a menu bar with many of the standard menu bar entries complete with keyboard accelerators (see Chapter 8, “Menus,” in the Indigo Magic User Interface Guidelines for information on standard menu bar entries). You typically use VkWindows as main windows, but you can use them as co-primary windows as well. See “Main Primary and Co-Primary Windows” for more information on main and co-primary windows.

Figure 6-2 shows the default configuration of the VkWindow component.

Figure 6-2. Default Configuration of VkWindow Component

When RapidApp generates code for a VkWindow, it creates it as a subclass of the IRIS ViewKit VkWindow class. (See Chapter 4, “ViewKit Windows,” in the IRIS ViewKit Programmer's Guide for more information on the VkWindow class.)

By default, for each menu item in the menu bar for which you've defined an activateCallback function, RapidApp adds a member function of the same name to the VkWindow's child component or generated class. You can then add the functional code to the functions to define behavior for the menu items. RapidApp doesn't add member functions to the child for those menu items for which you haven't defined an activateCallback function. You can disable this feature by setting the window's autoRouteCallbacks resource to “False.”

Furthermore, for the default items on the File and Edit menus, RapidApp implements some functionality automatically. For example, RapidApp generates code for the “Open” selection of the File menu to display a file selection dialog. You need only take the filename returned by the dialog and perform an open operation appropriate for your application. Table 6-1 summarizes the actions and the functions added for the default items on the File and Edit menus.

You can add, edit, and remove menu panes and menu items if you want. For more information on manipulating menus in RapidApp, see “Work With Menus”.

---

Note: Don't remove or edit the Help menu using RapidApp. The VkWindow class automatically creates a standard Help menu that interfaces with the Silicon Graphics help system; RapidApp ignores any changes that you make to the Help menu. For more information on the standard Help menu, see Chapter 5, “Creating Menus With ViewKit,” in the IRIS ViewKit Programmer's Guide.

---

If your application doesn't include online help, you can disable the Help menu by setting the window's hideHelpMenu resource to True.

Chapter 3, “Windows in the Indigo Magic Environment,” of the Indigo Magic User Interface Guidelines describes two types of primary windows recommended for use in Indigo Magic Desktop applications: main primary windows and co-primary windows:

RapidApp allows you to set the type of a Simple Window or a VkWindow with the coprimaryWindow resource, as shown in Figure 6-3.

Figure 6-3. Setting the Window Type

Chapter 3 of the Indigo Magic User Interface Guidelines recommends different entries in the window menu (that is, the menu in the title bar added by the window manager) based on the type of window. RapidApp automatically generates the necessary code to configure a window based on the value of the coprimaryWindow resource that you select.

RapidApp automatically instantiates and displays all main windows in main.C. However, it doesn't create instances of or display co-primary windows in your application. You need to instantiate co-primary windows explicitly and use the show() member function to display them when appropriate. For example, if you display a co-primary window based on an action in another component, you can declare the co-primary window as a protected data member of the component:

protected:
  CoprimaryMainWindow * _coprimary;

Then instantiate the co-primary window in the component's constructor:

_coprimary = new CoprimaryMainWindow("coPrimary");

When you need to display the co-primary window, call its show() member function:

_coprimary->show();

See Chapter 4, “ViewKit Windows,” in the IRIS ViewKit Programmer's Guide for more information on manipulating windows using the window class member functions.

The VkWindow user interface element provided on RapidApp's Windows palette is somewhat different from many other elements on RapidApp's palettes. The VkWindow (and VkSimpleWindow) elements are not individual widgets, and are not classes. They are simply templates, created as a collection of other widgets, that can be altered and extended to meet your needs. RapidApp treats these windows specially, so that they ultimately become a C++ class, derived from VkWindow or VkSimpleWindow, but at the beginning, these elements are simply a description of a particular combination of widgets.

The VkWindow template has been chosen to conform to the SGI user interface guidelines, and provides menu entries that are often useful. However, you may find that you have additional or simply different menu items that you would like to use repeatedly, and would like to avoid having to start with a VkWindow and make the same modifications each time you need a window.

RapidApp allows you to edit a VkWindow object once, and save the results as a template that can be used any time you want the same interface. To create and save a template, follow these steps:

The Bulletin Board widget (XmBulletinBoard) is the simplest IRIS IM container and the easiest to use. You simply “tack” elements to a particular position in the Bulletin Board and they stay there unless you explicitly move them. The Bulletin Board doesn't reposition or resize its children for any reason. Using a Bulletin Board container is the most like working with a drawing editor.

The limitation of a Bulletin Board is that all positions and sizes are fixed. For example, if you change the text or font of a label in a resource file, the label could grow or shrink, altering its alignment to other elements. Because of this limitation, the Bulletin Board is a poor choice for programs that you expect to internationalize or to allow users to customize the interface. Also, don't use a Bulletin Board if you want to allow the user to stretch or shrink the interface size. However, the Bulletin Board is a good choice for quickly prototyping interface designs because it is easy to use and provides the greatest flexibility for arranging elements within it.

---

Note: The Bulletin Board supports marginWidth and marginHeight resources that enforce minimum offsets from the edges of the container to its child elements. However, the Bulletin Board wasn't designed with an interactive builder in mind, so after initially placing an element you can move it closer to the edge of the Bulletin Board than allowed by the margin values. But when you run your application, the Bulletin Board overrides the children's positions and places them within the margins, resulting in a layout slightly different from what you specified in RapidApp. Therefore, either obey the margins when placing and moving elements, or change the marginWidth and marginHeight resources if you prefer smaller margins.

---

See the XmBulletinBoard(3Xm) reference page for more information on the XmBulletinBoard widget.

The Rubber Board widget (SgRubberBoard) is an IRIS IM extension to Motif. The Rubber Board is similar to a Bulletin Board and shares both its ease of use and some of its limitations. However, it has a unique ability to support resizable layouts simply and easily. This widget is also designed explicitly for use with an interface builder; it would be awkward to use programmatically.

To use the Rubber Board:

---

Note: The Rubber Board responds to changes in size initiated only by its parent (for example, its parent window); it doesn't respond to changes in the size of its children. Therefore, the Rubber Board continues to have the same limitations with respect to changing fonts, labels, or internationalization as the Bulletin Board.

---

The Rubber Board widget interpolates both size and position. In theory you can create bizarre dynamic behavior in which widgets move unexpectedly in response to resizing. For example, a widget on the right side of the Rubber Board when the container is small can move slowly to the left side as the Rubber Board grows larger. For obvious reasons, avoid using the Rubber Board in this manner.

You can nest Rubber Boards within one another. To do so, it's best to design the resize behavior of the inner containers first, and then place them in the larger Rubber Board.

---

Tip: The Rubber Board doesn't handle certain errors well, such as making the final size smaller than the initial size. Therefore, create the initial layout with the Rubber Board as small as possible, even if the size is unrealistic. Similarly, create the final size as large as possible.

---

Figure 6-5 through Figure 6-8 demonstrate the behavior of the Rubber Board widget. To begin, create an interface in a small container, such as in Figure 6-5. Once you've finished the layout, set the Rubber Board's setInitial resource to True.

Figure 6-5. Rubber Board: Initial Layout

Next, resize the Rubber Board to a much larger size, as in Figure 6-6. Notice that all widgets keep their original size and position.

Figure 6-6. Rubber Board: Preparing for Larger Layout

Then resize and reposition the elements to reflect their desired size and position for the larger container size, as shown in Figure 6-7.

Figure 6-7. Rubber Board: Final Layout

After setting the Rubber Board's setFinal and autoPosition resources, you can resize the Rubber Board to any shape and the children will maintain their relative positions and sizes, as demonstrated in Figure 6-8.

Figure 6-8. Effect of Resizing the Final Rubber Board Layout

The Spring Box widget (SgSpringBox) is an IRIS IM extension to Motif. At its simplest, the Spring Box simply enforces row or column behavior on its child elements. Figure 6-9 shows two simple layouts with buttons placed in vertical and horizontal Spring Boxes.

Figure 6-9. Vertical and Horizontal Spring Boxes

What you can't see from Figure 6-9 is that each child of the Spring Box has six springs associated with it. Each spring has an associated “spring constant” value, which combines with the other springs to determine the overall behavior of the spring system. You can control each spring individually.

By default, the value of the horizontal and vertical spring resources are set to 100, while the other springs are set to 0. This means the children of the Spring Box stretch to fill the size of the Spring Box.

You can change the values of the spring resources by selecting a child and changing its constraint resources, as shown in Figure 6-10.

Figure 6-10. Setting Spring Resources

For example, consider the behavior if you set up the spring values as shown in the following table:

Figure 6-11 shows the layout created by these values, both when the Spring Box is its natural size and when it is stretched.

Figure 6-11. Spring Box Behavior With Modified Values

To create complete layouts using the Spring Box, you usually need to nest Spring Boxes within Spring Boxes, mixing vertical and horizontal orientations.

As a convenience, the Spring Box container itself includes two resources, defaultHorizontalLayout and defaultVerticalLayout, to help you create common layouts. Settings these resource causes the Spring Box container to apply a collection of resource settings to all the children it currently contains. Each resource is independent and controls only the resources that apply vertically or horizontally. The meaning of these resources does not change with the value of the orientation resource (that is, vertical is always vertical). Possible layouts include:

The Spring Box container uses the creation order of its children to determine their positions. You can move a child to a different position by selecting it and then using the “Up/Left” (or the <Ctrl+u>, <Left arrow>, or <Up arrow> keyboard shortcut) and “Down/Right” (or the <Ctrl+d>, <Right arrow>, or <Down arrow> keyboard shortcut) selections from the Edit menu.

The Spring Box tends to wrap itself tightly around its children, so that you can't select or move it directly. To access the Spring Box, select a child of the Spring Box widget, then choose “Select Parent” from the Edit menu (or type the <Ctrl+p> keyboard shortcut) to select the Spring Box widget. You can then access the Spring Box's resources. To move or resize the Spring Box, hold down the <Ctrl> key while using the left mouse button as you normally would. The <Ctrl> key prevents RapidApp from selecting a new element so that you can easily manipulate the currently selected element.

The Form widget (XmForm) is the most common choice for resizable layouts. The Form widget positions its children based on attachments. For example, you can attach an element to a percentage position in the Form, to the side of another element, and so on. Forms can respond to resizes initiated by both its parent (for example, its parent window) and its children.

The traditional problem with Forms is that they are difficult to set up and use. Programmatically setting all the attachment resources for the Form's children is tedious, and it's difficult to envision the resulting appearance. RapidApp makes Forms easier to use by allowing you to interactively edit attachments and see the results.

---

Tip: Although you can create complex layouts within a Form widget, often it's simpler to create simple layouts with only a few widgets, define that collection as a component, and then group the component with other components in a parent Form.

---

The easiest way to understand how to manipulate elements within a Form is by example. Figure 6-12 shows what happens when you add a push button to a Form.

Note the symbols around the push button and the lines from the button to the edge of the Form. The symbols are called attachment icons; there is one for each side of a child in a Form. The lines represent attachments. In this case, the button is attached to the top and left sides of the Form and is unattached on the right and bottom. This is the default behavior for an interface element placed in a Form.

Figure 6-12. Push Button in a Form

The length of the line represents the offset from the point of attachment to the element. You can vary this offset in several ways. First, you can simply move the element. For example, moving the push button to the top of the window as shown in Figure 6-13 sets the top offset to zero.

Figure 6-13. Setting the Top Offset to Zero

You can also set the offset by holding down the <Shift> key and pressing the left mouse button over an attachment icon. RapidApp displays a menu showing the value of the offset. You can change this value by moving the mouse while continuing to hold down the <Shift> key and left mouse button. Figure 6-14 shows an example.

Figure 6-14. Using the Popup to Set an Offset

Alternatively, you can change the value of the offset in the appropriate field of the resource editor when the child element is selected.

You can change the type of an attachment by pressing the right mouse button over the attachment icon. RapidApp displays a menu showing the attachment type choices. For example, Figure 6-15 demonstrates pressing the right mouse button over the right attachment icon. Figure 6-16 shows the results of selecting XmATTACH_FORM.

Figure 6-15. Displaying the Attachment Menu

Figure 6-16. Push Button With a Right Attachment

Another way to create or edit an attachment is by dragging from an attachment icon to another interface element. For example, add a second push button to the Form, near the bottom of the container. Now press the left mouse button over the new button's top attachment icon and drag to the bottom edge of the original button, as shown in Figure 6-17.

Figure 6-17. Drawing an Attachment

The XmATTACH_POSITION attachment type allows you to set the position of the element within a Form relative to the size of the Form. For example, you can specify the position of an element so that its top is always one quarter of the way from the top of the Form no matter what size the Form takes. To do this, you must specify two resource values: a numerator (in the interface element) and a denominator (in the Form). The denominator is the fractionBase resource in the Form. You can set the numerator either interactively, in the same way that you set the offset, or by changing the appropriate position resource when the child element is selected.

---

Note: If you use position attachments, be sure to set the value of the fractionBase resource before setting the attachments of any children to XmATTACH_POSITION. A Form doesn't recompute the children's position attachments if you change the Form's fraction base.

---

See the XmForm(3Xm) reference page for more information on the XmForm widget.

The IRIS IM Paned Window widget (XmPanedWindow) places all its children in a column with each widget separated by a control, known as a sash, and an optional separator. The user can drag the sash to adjust the height of a section. The Paned Window widget adds constraint resources to each child that you can use to specify a minimum or maximum size. The Paned Window is suitable for interfaces that contain panels of information that the user might want to hide, reveal, or enlarge separately. See the XmPanedWindow(3Xm) reference page for more information on the XmPanedWindow widget.

The HPaned Window widget (SgHorzPanedWindow) is an IRIS IM extension to Motif. This widget is identical in functionality to the XmPanedWindow widget, but arranges its children in a horizontal row with separators and sashes between each child. Figure 6-18 shows an example of the HPaned Window.

Figure 6-18. HPaned Window Container

The Paned Window containers use the creation order of their children to determine their positions. You can move a child to a different position by selecting it and then using the “Up/Left” (or the <Ctrl+u>, <Left arrow>, or <Up arrow> keyboard shortcut) and “Down/Right” (or the <Ctrl+d>, <Right arrow>, or <Down arrow> keyboard shortcut) selections from the Edit menu.

Because these Paned Window containers weren't designed with an interactive builder in mind, they might exhibit some odd behaviors in RapidApp.

The primary purpose of the RowColumn widget (XmRowColumn) is to support menu panes and menu bars. It also has limited use for simple aligned rows, and can support multiple columns as well. However, the RowColumn container forces all of its children to have the same height, and it provides only limited ability to control how children are resized. If you want a layout like that shown in Figure 6-19, then the RowColumn widget is a good choice. Otherwise, you might want to choose another container.

Figure 6-19. Typical RowColumn Layout

The RowColumn container uses the creation order of its children to determine their positions. You can move a child to a different position by selecting it and then using the “Up/Left” (or the <Ctrl+u>, <Left arrow>, or <Up arrow> keyboard shortcut) and “Down/Right” (or the <Ctrl+d>, <Right arrow>, or <Down arrow> keyboard shortcut) selections from the Edit menu.

The RowColumn container tends to wrap itself tightly around it children, so that it cannot be selected or moved. To select the RowColumn container, select a child of the RowColumn widget, then choose “Select Parent” from the Edit menu (or use the <Ctrl+p> keyboard shortcut). You can then access the RowColumn's resources. To move or resize the widget, hold down the <Ctrl> key while using the left mouse button as you normally would. The <Ctrl> key prevents RapidApp from selecting a new element so that you can easily manipulate the currently selected one.

See the XmRowColumn(3Xm) reference page for more information on the XmRowColumn widget.

The Radio Box container is really a RowColumn container. It enforces radio behavior (one-of-many) on all toggle buttons it contains. The Radio Box is useful for small rows or columns of one-of-many radio buttons, as shown in Figure 6-20.

Figure 6-20. Radio Box With Toggle Button Children

When you create a Radio Box, RapidApp automatically creates two toggle buttons as children. In all other aspects, the Radio Box behaves the same as a RowColumn container (see “RowColumn” for more information).

The Frame widget (XmFrame) is a purely decorative container, drawing a frame around its contents. A Frame can contain two children. One is the work area child, the widget surrounded by the Frame. The other is an optional label widget. The Frame places the label at the top, in-line with the frame, as shown in Figure 6-21. You can change its position slightly by editing the label's constraint resources added by the Frame.

Figure 6-21. Frame Widget

---

Tip: It's easiest to add the title label widget first. RapidApp initially places the label in the middle of the Frame as the work area child. You need to change the label widget's childType constraint resource (added by the Frame) to XmFRAME_TITLE_CHILD. Once the title is in place, you can then add the work area widget for the Frame—typically, a container or a component.

---

See the XmFrame(3Xm) reference page for more information on the XmFrame widget.

The Scrolled Window widget (XmScrolledWindow) adds scroll bars to a child element. The Scrolled Window can contain only one child, typically a container or a component.

See the XmScrolledWindow(3Xm) reference page for more information on the XmScrolledWindow widget.

RapidApp provides three drawing area widgets: Drawing Area (XmDrawingArea), Visual Drawing (SgVisualDrawingArea), and GLDraw (GLwMDrawingArea). The Drawing Area and Visual Drawing widgets provide a canvas on which you can draw using Xlib library calls; the Visual Drawing widget is an IRIS IM extension to Motif; it allows the widget to use a visual different from the rest of the application.

---

Note: Although both the Drawing Area and Visual Drawing widgets can function as simple containers, similar to the Bulletin Board, use these widgets only for drawing rather than managing other widgets. Other containers are more appropriate for managing child widgets.

---

See the XmDrawingArea(3Xm) reference page for more information on the XmDrawingArea widget. See the SgVisualDrawingArea(3Xm) reference page for more information on the SgVisualDrawingArea widget. See the GLwMDrawingArea(3Xm) reference page for more information on the GLwMDrawingArea widget.

The Tabbed Deck component (VkTabbedDeck) is a special container that arranges any number of child elements in a “deck.” The Tabbed Deck component displays only one child at a time, but also displays a tab area, with one tab for each child. The user can click a tab to display the corresponding child. Figure 6-22 shows an example of a Tabbed Deck.

Figure 6-22. Tabbed Deck

You can add any number of child elements to the Tabbed Deck. Each element automatically fills the entire area of the Tabbed Deck except for the tab area.

---

Tip: After adding the first child element to a Tabbed Deck, add other elements by dropping them over the tab area.

---

The Tabbed Deck creates a tab for each element you add. You can display an element, even in Build Mode, by selecting its corresponding tab. To change the text of an element's tab, select the element and edit the tabLabel constraint resource added by the Tabbed Deck.

When RapidApp generates code for a Tabbed Deck, it creates it as a subclass of the IRIS ViewKit VkTabbedDeck class. Furthermore, for each child of the Tabbed Deck that isn't a component (that is, a C++ class), RapidApp automatically encapsulates that child and its contents within a subclass of VkComponent. (See Chapter 2, “Components,” in the IRIS ViewKit Programmer's Guide for more information on the VkComponent class.) The Tabbed Deck then simply creates an instance of that class.

---

Note: There is currently no way to reorder the children's positions within the Tabbed Deck. Be sure to add the children in the order in which you want them to appear in the tab area.

---

A menu bar consists of a collection of cascade buttons at the top of a window with pulldown menus (also referred to as menu panes) connected to them. This section describes how to create and edit menu bars using RapidApp. See “Menu Panes” for information on editing the contents of individual menu panes.

Creating a Menu Bar

The only way to create a menu bar on a main window in RapidApp is to create a VkWindow. You can't add a menu bar to a simple window after you create it.

---

Tip: If you build an interface in a simple window and later decide that you want a menu bar for the window, you can create a new VkWindow, cut or copy the top-level child (and thus everything it contains) of the existing simple window, and paste the interface into the new VkWindow.

---

When you create a VkWindow, RapidApp automatically includes a menu bar with many of the standard menu bar entries implemented complete with keyboard accelerators. See “VkWindows” for more information on the standard menu bar entries.

You can add a menu bar to a dialog if you want a custom dialog. To do so, select the Menu Bar element from the Menus palette and add it to the desired dialog as you would any other element. This menu bar doesn't contain the standard menu bar entries described in “VkWindows”; instead, it contains only two dummy menu panes with three dummy menu entries each. See “Creating and Using Custom Dialogs” for more information on creating custom dialogs.

Adding Panes to a Menu Bar

Add panes to a menu bar just as you add other elements to a container First, select the menu bar. Then click with the left mouse button on the icon on the menus palette of the type of pane you want to add, then click with the left mouse button within the menu bar to add the item. Alternatively, you can click the icon with the middle mouse button, drag the item to the menu bar, then release the mouse button.

You can add the following two items to a menu bar:

Pulldown menu		A regular menu pane. For your convenience, RapidApp automatically adds three initial menu entries to the pulldown menu. You can edit these items as described in “Menu Panes”.
Radio pulldown		A menu pane that enforces radio behavior (one-of-many) on all toggles that it contains. For your convenience, RapidApp automatically adds three dummy menu toggles to the pulldown menu. You can edit these items as described in “Menu Panes”.

---

Tip: A convenient way to add multiple panes to a menu bar is to select the menu bar and then toggle on “Keep Parent” on the RapidApp View menu. RapidApp grays out all inapplicable items on the Menus palette, leaving active only those items you can add to a menu bar. You can then left-click an icon and drop it anywhere on the screen; RapidApp still adds the item to the selected menu bar.

---

After adding a menu pane, you can use the RapidApp resource editor to change the menu's label and mnemonic.

This section describes how to build individual menus—that is, the contents of individual menu panes.

Adding Items to a Menu

You add items to a menu just as you add elements to a container (in fact, the menu pane container is simply a RowColumn widget). First, select the menu or any item in the menu. Then click with the left mouse button on the icon on the menus palette of the type of item you want to add, then click with the left mouse button within the menu to add the item. Alternatively, you can click the icon with the middle mouse button, drag the item to the menu, then release the mouse button.

You can add the following items to a menu:

Menu entry		A selectable action (implemented as a an XmPushButtonGadget)
Confirm first		A selectable entry that posts a confirmation dialog before executing the action. Confirm First menu items don't support an undoCallback resource.
Menu toggle		A selectable toggle entry. To enforce radio behavior on a group of toggles within a menu, put them within a Radio Pulldown menu.
Label		A non-selectable label.
Separator		A non-selectable separator.
Pulldown menu		A cascading, or pull-right, menu. For your convenience, RapidApp automatically adds three initial menu entries to the pulldown menu.
Radio pulldown		A cascading menu that enforces radio behavior (one-of-many) on all toggles that it contains. For your convenience, RapidApp automatically adds three initial menu toggles to the pulldown menu.

---

Tip: A convenient way to add multiple items to a menu is to select the menu (select any item in the menu, then choose “Select Parent” from the RapidApp Edit menu), then toggle on “Keep Parent” on the RapidApp View menu. RapidApp grays out all inapplicable items on the Menus palette, leaving active only those items you can add to a menu bar. You can then left-click an icon and drop it anywhere on the screen; RapidApp still adds the item to the selected menu.

---

After adding an item, you can use the RapidApp resource editor to change the item's label and mnemonic. For each item that invokes an action—Menu Entry, Confirm First, and Menu Toggle—you must define an activateCallback function that your application invokes when the user selects the item. For Menu Entry and Menu Toggle items, you can also define an undoCallback function that your application can invoke to undo the effects of the item's action.

For each menu item in a menu pane, RapidApp adds a member function of the same name to the VkWindow's child component. You can then add the functional code to the functions to implement the menu items.

An option menu is an interface element that allows the user to select one of several options using a menu. An option menu consists of a label and the equivalent of a cascading menu. When not displaying the cascading menu, an option menu displays the last item the user selected.

You create an option menu just as you do other interface elements. A newly created option menu has no label. To work with an option menu more easily, immediately edit the option menu's labelString resource to provide a label.

You can click anywhere on the option menu's label or cascade button to display its cascading menu pane. RapidApp automatically adds two dummy menu entries to the option menu when you create it. You can edit the option menu pane as described in “Menu Panes”.

IRIS ViewKit implements a complete dialog management system including:

The IRIS ViewKit dialog mechanism handles all standard dialog types including information, warning, error, busy, question, prompt, file selection, and preference dialogs. IRIS ViewKit encapsulates dialog management, including caching, in the abstract VkDialogManager class that serves as a base class for other, specific dialog classes. Each type of dialog in IRIS ViewKit has a separate class derived from VkDialogManager. Each class is responsible for managing its own type of dialog (for example, each class maintains its own dialog cache).

The header file for each dialog class provides a global pointer to the instance of that class's dialog manager. The name of the pointer consists of “the” followed by the dialog type. For example, the global pointer to the information dialog manager declared in <Vk/VkInfoDialog.h> is theInfoDialog, the global pointer to the error dialog manager declared in <Vk/VkErrorDialog.h> is theErrorDialog, and so forth. To access the dialog managers in your application, simply use these global pointers.

The VkDialogManager class offers four different functions for posting dialogs:

Each function accepts arguments for setting the dialog message, callback functions for each button on the dialog, and other parameters. The VkDialogManager class also offers functions for setting the dialog's title, setting the labels for its buttons, programmatically dismissing the dialog, and other actions. For more information on the IRIS ViewKit dialog mechanism, see Chapter 7, “Using Dialogs in ViewKit,” in the IRIS ViewKit Programmer's Guide. You can also consult the VkDialogManager(3Vk) reference page for more information on the functions provided by the VkDialogManager class.

Occasionally, you might need to create a custom dialog not implemented in IRIS ViewKit. You can use any of the dialogs on the Windows palette as the basis for a custom dialog. Any custom dialog that you create with RapidApp integrates with the IRIS ViewKit dialog mechanism; you post, dismiss, and otherwise interact with them in your application in the same way as the predefined IRIS ViewKit dialogs.

Selecting a Dialog to Customize

You can use any of the standard dialogs on the Windows palette as the basis for a custom dialog. If none of the predefined dialog types are appropriate, you can start with the Dialog Window element. Figure 6-24 shows the default configuration of a Dialog Window. The Dialog Window is ideal for implementing support windows, which are described in Chapter 3, “Windows in the Indigo Magic Environment,” in the Indigo Magic User Interface Guidelines.

Figure 6-24. Default Configuration of Dialog Window

Code Generation for Dialogs Customized From the Dialog Window

When RapidApp generates code for a dialog customized from the Dialog Window, it creates the dialog as a subclass of VkGenericDialog. See “Deriving New Dialog Classes Using the Generic Dialog” in Chapter 7 of the IRIS ViewKit Programmer's Guide for more information on the VkGenericDialog class.

For Dialog Windows, if the child element of the customized dialog isn't a component (that is, a C++ class), RapidApp automatically encapsulates that child and its contents within a subclass of VkComponent. (See Chapter 2, “Components,” in the IRIS ViewKit Programmer's Guide for more information on the VkComponent class.) The customized dialog then simply creates an instance of this class in its createDialog() member function.

---

Note: RapidApp generates both a UI and a functional subclass for the child of a Dialog Window. Typically, you should edit only the subclass.

---

RapidApp creates the VkComponent subclass in this case (rather than simply creating the child elements directly in the createDialog() member function as it does for customized standard dialogs) because Dialog Windows usually contain palettes or other complex controls typical of support windows. In these cases, it makes sense to follow the same encapsulation scheme used by the Simple Window and VkWindow components.

For customized Dialog Windows, RapidApp includes the callbacks associated with all menu items, pushbuttons, and other controls that you add to your customized dialog in the VkComponent subclass it generates to contain the child elements of the dialog.

How you specify the actions taken when the user clicks a standard dialog button (that is, the OK, Apply, and Cancel buttons) depends on the function you use to post the dialog. If you post the dialog using post(), postModal(), or postBlocked(), you provide a callback function for each button. If you post the dialog using postAndWait(), you test the enumerated value returned by the function and then perform an appropriate action. See “Posting Dialogs” in Chapter 7 of the IRIS ViewKit Programmer's Guide for more information on specifying actions to take when users click dialog buttons.

RapidApp also generates ok(), cancel(), and apply() functions in the dialog subclass. The default actions of these functions are to call their corresponding VkDialogManager functions, which dismiss your dialog whenever the user clicks on either the OK or Cancel button, and keeps the dialog posted whenever the user clicks on the Apply button. You can change this behavior by editing these functions in your dialog subclass. You can also include in them any other code needed to support your custom dialog (for example, storing the values of various controls in class data members that you can then retrieve using access functions that you provide for your class).

Example of a Custom Dialog

Figure 6-25 shows an example of a custom dialog created from the Dialog Window. In this case, when you generate code, the container widget containing the scale and label is encapsulated into a subclass of VkComponent. Alternatively, you could select the container widget and explicitly create a component, VolumeControl for example, before generating code.

Figure 6-25. Example of a Custom Dialog

When RapidApp generates the code for the dialog's child class, it adds three member functions to it: ok(), cancel(), and apply(). These functions are called when the user clicks the corresponding button. You can add code to these functions to perform whatever tasks you require. In the case of the custom dialog shown in Figure 6-25, the VolumeControl::ok() function can store the current value of the scale widget into a data member; the VolumeControl::cancel() function can restore the scale to the previously stored value.

Because a custom dialog is a subclass of VkGenericDialog, you post, dismiss, and set dialog titles and button labels the same way as for any other IRIS ViewKit dialog. For example, if the name of the dialog class for the dialog shown in Figure 6-25 is VolumeDialog, you create an instance of the dialog in your program with:

VolumeDialog _volumeDialog = new VolumeDialog();

Then you post this dialog with a call such as:

_volumeDialog->post();

See Chapter 7, “Using Dialogs in ViewKit,” in the IRIS ViewKit Programmer's Guide for more information on manipulating dialogs in IRIS ViewKit.

If you want to retrieve values set in the dialog or otherwise manipulate the dialog, create these access functions in both the dialog class and the child class. The dialog class should simply call the corresponding function in the child class. For example, assume that you want to be able to retrieve the last value of the scale in the dialog shown in Figure 6-25. Assume also that the dialog's child class, VolumeControl, stores the value in a private data member, _scaleValue. First, add the following function to the VolumeDialog class:

// _volumeControl contains a pointer to the child // VolumeControl object. int VolumeDialog::getValue() { return ( _volumeControl->getValue() ); }

Next, add the following function to the VolumeControl class:

int VolumeControl::getValue() { return ( _scaleValue ); }

Finally, retrieve the value from the dialog with:

currentValue = _volumeDialog->getValue();

It's easy to create components in RapidApp.

After creating the new class, RapidApp adds its representing icon to the User-Defined palette. (RapidApp creates the palette if it doesn't already exist.)

*VkComponent.headerFile: <Vk/VkComponent.h>
*VkComponent.library: -lvk

////////////////////
// MyComponent.h
class MyComponent : public VkComponent {

public:
MyComponent(const char *name);

void print();
};

*MyComponent.headerFile: <MyStuff/MyComponent.h>
*MyCSomponent.library: -lmyComponent

After creating a user-defined component, you can create instances of, select, move, and otherwise manipulate it just as you would any other interface element.

After creating a component, you can no longer simply click on one of its elements to edit it; RapidApp treats the component as a single interface element. However, you can still use RapidApp to edit the component.

To do so, toggle on “Edit Classes” in the Classes menu. RapidApp hides your current interface and displays all classes currently on the User-Defined palette. You can now select, edit, and manipulate the individual elements composing the classes. You can even add elements to and delete them from components. When you are finished editing classes, toggle off “Edit Classes.” RapidApp redisplays your current interface, reflecting the changes you made to your components.

Once you create a class, it remains on the User-Defined palette even if there are no instances of the class in your interface. When you save your interface, RapidApp saves the class along with the rest of the information about the interface. If you no longer want to keep a class on the palette, you can delete it in one of two ways: