This section describes the various methods of posting dialogs and provides some simple examples.

Methods of Posting Dialogs

ViewKit offers four different functions for posting dialogs:

post()		Posts a non-blocking, non-modal dialog. The function immediately returns, and the application continues to process user input in all windows.
postModal()		Posts a non-blocking, full-application-modal dialog. The function immediately returns, but the user cannot interact with any application windows until after dismissing the dialog.
postBlocked()		Posts a blocking, full-application-modal dialog. The user cannot interact with any application windows until after dismissing the dialog. Furthermore, the function does not return until the user dismisses the dialog.
postAndWait()		Posts a blocking, full-application-modal dialog. The user cannot interact with any application windows until after dismissing the dialog. Furthermore, the function does not return until the user dismisses the dialog. postAndWait() is simpler to use than postBlocked(), but it does not allow as much programming flexibility.

post(), postModal(), and postBlocked() accept the same arguments. They are also overloaded identically to allow for almost any combination of arguments without resorting to using NULLs as placeholders. Consult the VkDialogManager(3x) reference page for a complete listing of the overloaded versions of the post(), postModal(), and postBlocked() functions. The following is the most general form of the post() function:

virtual Widget post ( const char *msg = NULL, XtCallbackProc  okCB = NULL, XtCallbackProc  cancelCB = NULL, XtCallbackProc  applyCB = NULL, XtPointer clientData = NULL, const char *helpString = NULL, Widget *parent = NULL)

The following are the arguments for these methods:

msg		The message to display in the dialog. This string is first treated as a resource name, which is looked up relative to the dialog widget. If it exists, the resource value is used as the message. If the resource does not exist, or if the string contains spaces or newline characters, the string itself is used as the message. Most dialogs are not useful if you do not provide a message argument: they display no text. VkFileDialog and VkPreferenceDialog are exceptions in that they provide their own complex interfaces.
okCB		An Xt-style callback function executed when the user clicks the OK button. (All dialogs except for the VkBusyDialog and VkInterruptDialog dialogs display an OK button by default.)
cancelCB		An Xt-style callback function executed when the user clicks the Cancel button. For many of the dialog classes, ViewKit does not display a Cancel button unless you provide this callback.
applyCB		An Xt-style callback function executed when the user clicks the Apply button. For many of the dialog classes, ViewKit does not display an Apply button unless you provide this callback.
clientData		Client data to pass to the button callback functions. Following ViewKit conventions as described in “Using Xt Callbacks With Components”, you should normally pass the this pointer as client data so that the callback functions can retrieve the pointer, cast it to the expected component type, and call a corresponding member function.
helpString		A help string to pass to the help system. See , “Using a Help System With ViewKit,” for information on the help system. If you provide a string, the dialog displays a Help button.
parent		The widget over which ViewKit should display the dialog. If you do not provide a widget, or if the given widget is hidden or iconified, ViewKit posts the dialog over the main window if it is managed and not iconified. (“Managing Top-Level Windows” describes how the main window is determined.) If both the widget you specify and the main window are hidden or iconified, ViewKit posts the dialog as a child of the hidden application shell created by the VkApp class. Also see the description of VkDialogManager::centerOnScreen() in “Dialog Access and Utility Functions”.

All versions of the post(), postModal(), and postBlocked() functions return the widget ID of the posted dialog. You should rarely need to use this value.

---

Note: The arguments that you provide apply only to the dialog posted by the current call to post(), postModal(), and postBlocked(); they have no effect on subsequent dialogs. For example, if you provide an apply callback function to a call to post(), it is used only for the dialog posted by that call. If you want to use that callback for subsequent dialogs, you must provide it as an argument every time you post a dialog.

---

postAndWait() provides a simpler method for posting blocking, application-modal dialogs than postBlocked(). The most general form of the postAndWait() function is as follows:

virtual VkDialogReason postAndWait ( const char *msg = NULL, Boolean ok = TRUE, Boolean cancel = TRUE, Boolean apply = FALSE, const char *helpString = NULL, Widget *parent = NULL)

msg is the message to display in the dialog. As with the other posting functions, postAndWait() first treats the string as a resource name, which it looks up relative to the dialog widget. If the resource exists, postAndWait() uses the resource value as the message. If postAndWait() finds no resource, or if the string contains spaces or newline characters, it uses the string itself as the message. The next three arguments determine which buttons the dialog should display. A TRUE value displays the button and a FALSE value hides the button. helpString and parent specify a help string and a parent window, just as with the other posting functions.

---

Note: The arguments that you provide apply only to the dialog posted by the current call to postAndWait(); they have no effect on subsequent dialogs.

---

When you call postAndWait(), ViewKit posts the dialog, enters a secondary event loop, and does not return until the user dismisses the dialog. Unlike postBlocked(), postAndWait() handles all callbacks internally and simply returns an enumerated value of type VkDialogReason, indicating which button the user chose. The possible return values are VkDialogManager::OK, VkDialogManager::CANCEL, or VkDialogManager::APPLY. postAndWait() is useful for cases in which it is necessary or convenient not to go on to the next line of code until the user dismisses the dialog. For example:

if ( theFileSectionDialog->postAndWait() == VkDialogManager::OK ) int fd = open( theFileSelectionDialog->fileName(), O_RDONLY);

---

Note: postAndWait() posts dialogs as full-application modal dialogs to minimize potential problems that can be caused by the secondary event loop, but you should be aware that the second event loop is used and be sure that no non-re-entrant code can be called.

---

As with the other functions for posting a dialog, postAndWait() is overloaded to allow for almost any combination of arguments without resorting to using NULLs as placeholders. Consult the VkDialogManager reference page for a complete listing of the overloaded versions of postAndWait().

---

Note: Under certain circumstances, using postAndWait() can cause some unexpected consequences. If you have your own custom dialog, and you delete a widget within it from an event handler such as prePost(), the widget will not be destroyed until the event handler returns. Therefore, widgets that you destroyed will still appear in the dialog. This is because the phase 2 destroy does not happen until the return from the XtDispatch. There are several workarounds you can try if this proves to be a problem:

---

• Do not use postAndWait(). Simply post the dialog, return from your event handler, then do whatever you need to do. This may result in flashing, since widgets may be momentarily posted before they are destroyed.

• Unmanage any widget that should not appear. The object will still be there, but will not be visible.

• Keep the dialog cleaned up as you go along. Set up the dialog initially with only permanent items. Then, whenever the dialog is posted, add whatever objects you need. Finally, whenever that dialog is taken down, return it to the original state. You can handle this by catching both OK and Cancel callbacks.

Posting Dialogs

The following line posts a simple non-modal, non-blocking information dialog over the application's main window:

theInfoDialog->post("You have new mail in your system mailbox");

Figure 7-2 shows the appearance of this dialog when posted. Because the call did not provide any callback for the OK button, when the user clicks the button, ViewKit simply dismisses the dialog.

Figure 7-2. Information Dialog

You could also specify the message as an X resource. In the above example, you could name the resource something such as newMailMessage and set it in a resource file with the following line:

*newMailMessage: You have new mail in your system mailbox

Then you could use this line to post the information dialog:

theInfoDialog->post("newMailMessage");

The following code displays a non-modal, non-blocking question dialog over the application's main window:

void MailWindow::newMail() { // ... theQuestionDialog->post("Read new mail?", &MailWindow::readMailCallback, (XtPointer) this); // ... }

Figure 7-3 shows the appearance of this dialog when posted. If the user clicks the OK button, the program dismisses the dialog and executes the MailWindow::readMailCallback() function. Following ViewKit conventions as described in “Using Xt Callbacks With Components”, the client data argument is set to the value of the this pointer so that MailWindow::readMailCallback() can retrieve the pointer, cast it to the expected component type, and call a corresponding member function.

Figure 7-3. Question Dialog

Because the call to post() did not provide any callback for the Cancel button, when the user clicks the button, ViewKit simply dismisses the dialog. If instead you needed to perform some type of cleanup operation when the user clicks the Cancel button, you would need to provide a callback for the Cancel button:

void MailWindow::newMail() { // ... theQuestionDialog->post("Read new mail?", &MailWindow::readMailCallback, &MailWindow::cleanupMailCallback, (XtPointer) this); // ... }

In general, you should try to encapsulate all dialog callbacks and related information in the subclass of the object with which they are associated. For example, for dialogs that are associated with a specific window, you include all the code related to those dialogs in the subclass definition for that window.

This technique is illustrated in Example 7-1, a simple program which uses the VkWarningDialog class to post a warning dialog.

Example 7-1. Posting a Dialog

#include <Vk/VkApp.h> #include <Vk/VkSimpleWindow.h> #include <Vk/VkWarningDialog.h> #include <Xm/PushB.h> class MyWindow: public VkSimpleWindow { protected: static void postCallback(Widget, XtPointer, XtPointer); public: MyWindow (const char *name); ~MyWindow ( ); virtual const char* className(); }; MyWindow::MyWindow (const char *name) : VkSimpleWindow (name) { Widget button = XmCreatePushButton (mainWindowWidget(), "Push Me", NULL, 0); XtAddCallback(button, XmNactivateCallback, &MyWindow::postCallback, (XtPointer) this); addView(button); } const char* MyWindow::className() { return "MyWindow"; } MyWindow::~MyWindow() { // Empty } void MyWindow::postCallback(Widget, XtPointer clientData, XtPointer) { theWarningDialog->post("Watch Out!!!", NULL, (MyWindow *) clientData); } void main ( int argc, char **argv ) { VkApp *app = new VkApp("Dialog", &argc, argv); MyWindow *win = new MyWindow("Dialog"); win->show(); app->run(); }

After posting a dialog, you might encounter situations in which you want to unpost it even though the user has not acknowledged and dismissed it. For example, your application might post an information dialog that the user doesn't bother to acknowledge. At some later point, the information presented in the dialog might no longer be valid, in which case the application should unpost the dialog. In situations such as these, you can use the VkDialogManager::unpost() function to remove the dialog:

void unpost()
void unpost(Widget w)

If you provide the widget ID of a specific dialog, unpost() dismisses that dialog. Otherwise, unpost() dismisses the most recent dialog of that class posted.

If you want to dismiss all dialogs of a given class, you can call the VkDialogManager::unpostAll() function:

void unpostAll()

For example, the following dismisses all information dialogs currently posted:

theInformationDialog->unpostAll();

By default, ViewKit sets the title of a dialog (displayed in the window manager title bar for the dialog) to the name of the application; however, you have the ability to set dialog titles on both a per-class and per-dialog basis.

If you want all dialogs of a certain class to have a title other than the default, you can specify the title with an X resource. For example, you could set the title of all warning dialogs in an application to “Warning” by including the following line in a resource file:

*warningDialog.dialogTitle: Warning

You can use the VkDialogManager::setTitle() function to set the title for the next dialog of that class that you post:

void setTitle(const char *nextTitle = NULL)

setTitle() accepts as an argument a character string. setTitle() first treats the string as a resource name which it looks up relative to the dialog widget. If the resource exists, setTitle() uses the resource value as the dialog title. If setTitle() finds no resource, or if the string contains spaces or newline characters, it uses the string itself as the dialog title.

setTitle() affects only the next dialog posted; subsequent dialogs revert to the default title for that class.

For example, imagine an editor that uses the question dialog to post two dialogs, one that asks “Do you really want to replace the current buffer?” and one that asks “Do you really want to exit?” If you want different titles for each dialog, you could define resources for each:

*replaceTitle: Dangerous Replacement Dialog
*exitTitle: Last Chance Before Exit Dialog

Then to post the question dialog for replacing the buffer, call the following:

theQuestionDialog->setTitle("replaceTitle");
theQuestionDialog->post("Do you really want to replace the current buffer?",
                         &EditWindow::replaceBufferCallback, 
                         XtPointer) this);

Figure 7-4 shows the resulting dialog.

Figure 7-4. Setting the Dialog Title

To post the exit question dialog as a modal dialog, call the following:

theQuestionDialog->setTitle("exitTitle");
theQuestionDialog->postModal("Do you really want to exit?",
                             &EditWindow::replaceBufferCallback,
                             (XtPointer) this);

Figure 7-5 shows the resulting dialog.

Figure 7-5. Another Example of Setting the Dialog Title

The button labels (the text that appears on the buttons) used for a dialog are controlled by the XmNokLabelString, XmNcancelLabelString, and XmNapplyLabelString resources. The default values of these resources are respectively “OK”, “Cancel”, and “Apply”.

You can use the VkDialogManager::setButtonLabels() function to set the button labels for the next dialog that you post:

void setButtonLabels(const char *ok = NULL,
                     const char *cancel = NULL,
                     const char *apply = NULL)

setButtonLabels() accepts as arguments up to three character strings: the first string controls the label for the OK button, the second the label for the Cancel button, and the third the label for the Apply button. If you pass NULL as an argument for any of these strings, the corresponding button uses the default label. setTitle() first treats each string as a resource name, which it looks up relative to the dialog widget. If the resource exists, setTitle() uses the resource value as the button label. If setTitle() finds no resource, or if the string contains spaces or newline characters, it uses the string itself as the button label.

setButtonLabels() affects only the next dialog posted; subsequent dialogs revert to the default button labels.

The VkDialogManager class also provides some access and utility functions to help manipulate dialogs.

VkDialogManager::centerOnScreen() controls the algorithm that ViewKit uses to determine where on the screen to post a dialog:

void centerOnScreen(Boolean flag)

If flag is TRUE, ViewKit uses the following algorithm:

If flag is FALSE, ViewKit uses the following algorithm, which is the default algorithm:

VkDialogManager::enableCancelButton() sets whether or not the default will be to provide a Cancel button in future dialogs, and allows the application to determine when a dialog was closed without using the cancel button, such as by a window manager action:

VkDialogManager::enableCancelButton (Boolean flag)

VkDialogManager::lastPosted() returns the widget ID of the last dialog posted of that class:

Widget lastPosted()

VkDialogManager::setVisual() sets visual resources:

void setVisual (VkVisual *v)

setVisual() overrides any visual arguments that may have been passed in using setArgs().

VkDialogManager::setArgs() allows you to pass in resources to be used when creating the first dialog:

void setArgs (ArgList list, Cardinal argCnt)

Whichever way you set them, dialog arguments should be set just once, before any dialog is created. Due to the way ViewKit caches dialogs, resetting the dialog creation arguments after the first dialog is created results in an undefined action.

The VkInfoDialog class supports standard Motif information dialogs. The global pointer to the information dialog manager, declared in <Vk/VkInfoDialog.h>, is theInfoDialog.

Use information dialogs to display useful information. Do not use information dialogs to display error messages, which should be handled by the VkErrorDialog, VkWarningDialog, or VkFatalErrorDialog class.

Because the message contained in an information dialog should not require any decision to be made by the user, information dialogs display only the OK button by default. If you need the user to make a selection, you should use another dialog class such as VkQuestionDialog.

VkInfoDialog does not provide any additional functions beyond those offered by the VkDialogManager.

Example 7-2 shows a simple example of posting an information dialog. Note that the window subclass that posts the dialog defines the dialog title and message as resource values.

#include <Vk/VkWindow.h>
#include <Vk/VkInfoDialog.h>
 
class MailWindow: public VkWindow {
  public:
    MailWindow(const char*);
    void newMail();
    // ...
 
  private:
    static String _defaultResources[];
    // ...
};
 
String MailWindow::_defaultResources[] = {
    "-*newMailMsg:     You have new mail in your system mailbox.",
    "-*newMailTitle:   New Mail",
    NULL
};
 
MailWindow::MailWindow(const char *name) : VkSimpleWindow (name)
{
    setDefaultResources( mainWindowWidget(), _defaultResources );
    // ...
}
void MailWindow::newMail()
{
    // ...
    theInfoDialog->setTitle("newMailTitle");
    theInfoDialog->post("newMailMsg");
    // ...
}

Figure 7-6 shows the appearance of the resulting dialog.

Figure 7-6. Information Dialog

The VkWarningDialog class supports standard Motif warning dialogs. The global pointer to the warning dialog manager, declared in <Vk/VkWarningDialog.h>, is theWarningDialog.

Use VkWarningDialog to warn the user of the consequences of an action. For example, VkWarningDialog is appropriate for warning the user that an action will irretrievably delete information.

By default, the dialogs posted by VkWarningDialog contain only an OK button; however, according to Open Software Foundation style guidelines, if you have posted a warning dialog to warn the user about an unrecoverable action, you must allow the user to cancel the destructive action. To add a Cancel button to your warning dialog, simply provide a cancel callback function when you post the dialog.

---

Tip: If you perform the action in the warning dialog's OK callback, you can simply define an empty function as a cancel callback. If the user clicks the warning dialog's OK, button, the ok callback performs the action; if the user clicks the Cancel button, ViewKit dismisses the dialog without performing any action.

---

VkWarningDialog does not provide any additional functions beyond those offered by the VkDialogManager.

The VkErrorDialog class supports standard Motif error dialogs. The global pointer to the error dialog manager, declared in <Vk/VkErrorDialog.h>, is theErrorDialog.

Use VkErrorDialog to inform the user of an invalid action (such as entering out-of-range data) or potentially dangerous condition (for example, the inability to create a backup file).

The messages contained in the error dialogs should not require any decision to be made by the user. Therefore, the error dialogs display only the OK button by default. If you need the user to make a selection, you should use another dialog class such as VkQuestionDialog.

VkErrorDialog does not provide any additional functions beyond those offered by the VkDialogManager.

The VkFatalErrorDialog class supports an error dialog that terminates the application when the user dismisses it. The global pointer to the fatal error dialog manager, declared in <Vk/VkFatalErrorDialog.h>, is theFatalErrorDialog.

Use VkFatalErrorDialog only for those errors from which your program cannot recover. For example, VkFatalErrorDialog is appropriate if an application terminates because it cannot open a necessary data file. When the user acknowledges the dialog posted by VkFatalErrorDialog, the application terminates by calling VkApp::terminate() with an error value of 1. “Quitting ViewKit Applications” describes the terminate() function.

The messages contained in a fatal error dialog should not require any decision to be made by the user. Therefore, the fatal error dialog displays only the OK button by default.

VkFatalErrorDialog does not provide any additional functions beyond those offered by the VkDialogManager.

The VkBusyDialog class supports a busy dialog (also called a working dialog in Motif) that is displayed when the application is busy. The global pointer to the busy dialog manager, declared in <Vk/VkBusyDialog.h>, is theBusyDialog.

Unlike most other dialog classes, you should not directly post and unpost the busy dialog. VkBusyDialog is used by the VkApp object to display a busy dialog when you place the application in a busy state. The busy dialog is displayed automatically when you call VkApp::busy(), and dismissed automatically when you make a corresponding call to VkApp::notBusy(). VkApp also allows you to use the VkApp::setBusyDialog() function to use a busy dialog other than that provided by VkBusyDialog. Consult “Supporting Busy States” for more information about how VkApp handles busy states.

Because the busy dialog is intended to lock out user input during a busy state, by default the busy dialog does not display any buttons. If you want to allow the user to interrupt the busy state, you should use the VkApp::setBusyDialog() function to substitute the VkInterruptDialog class object for the normal busy dialog.

VkBusyDialog does not provide any additional functions beyond those offered by the VkDialogManager.

The VkInterruptDialog class supports an interruptible busy dialog that you can substitute for the normal busy dialog. The dialog posted by the VkInterruptDialog class includes a Cancel button that the user can click to cancel the current action. The global pointer to the interruptible busy dialog manager, declared in <Vk/VkInterruptDialog.h>, is theInterruptDialog.

In addition to those functions offered by the VkDialogManager class, VkInterruptDialog provides the wasInterrupted() member function:

Boolean wasInterrupted()

Applications that use VkInterruptDialog must periodically call wasInterrupted() to determine whether the user has clicked the dialog's Cancel button since the last time the function was called. The period of time between checks is up to the application, which must weigh responsiveness against time spent checking.

Note that wasInterrupted() also calls VkApp::handlePendingEvents() to process any events that have occurred while the application was busy. Because checking for interrupts involves entering a secondary event loop for a short time, you should beware of any problems with re-entrant code in any callbacks that could be invoked.

Also note that you are responsible for performing any cleanup operations required by your application if the user interrupts a process before it is finished (that is, before you would normally call VkApp::notBusy() to end the busy state).

VkInterruptDialog also provides the ViewKit callback VkInterruptDialog::interruptedCallback. This callback allows objects to register a member function to be called when the user clicks the Cancel button of a VkInterruptDialog dialog. This callback can be called only if the application calls VkInterruptDialog::wasInterrupted().

Unlike most other dialog classes, you should not directly post and unpost the interruptible busy dialog. You can use the VkApp::setBusyDialog() function to instruct the VkApp object to use the interruptible busy dialog rather than the normal busy dialog provided by the VkBusyDialog class. The following line shows how you could do this in a program:

theApplication->setBusyDialog(theInterruptDialog);

The following line instructs the VkApp object to revert to the normal busy dialog:

theApplication->setBusyDialog(NULL);

If you instruct the VkApp object to use the interruptible busy dialog, it is displayed automatically when you call VkApp::busy(), and dismissed automatically when you make a corresponding call to VkApp::notBusy(). Consult “Supporting Busy States” for more information about how VkApp handles busy states.

The code fragment in Example 7-3 installs the interruptible busy dialog and performs a simulated lengthy task, checking for interrupts periodically. After completing the task, the code reinstalls the normal busy dialog.

int i;
 
// Install the interruptible dialog as the dialog
// to post when busy
 
theApplication->setBusyDialog(theInterruptDialog);
 
// Start being "busy"
 
theApplication->busy("Very Busy", (BusyWindow *) clientData);
 
for(i=0; i<10000; i++)
{
  // Every so often, see if the task was interrupted
 
  if( theInterruptDialog->wasInterupted() )
  {
    break; // kick out of current task if user interrupts
  }
  sleep(1);
}
 
// Task done, so we're not busy anymore
 
theApplication->notBusy(); 
 
// Restore the application's busy dialog as the default
 
theApplication->setBusyDialog(NULL);

The VkProgressDialog class supports applications that perform lengthy, interruptible tasks, and wish to display a progress report to the user. This class displays a bar graph showing what percentage of the job has been completed, and how much remains to be done. See Figure 7-7 for an example of a progress dialog.

The global pointer to the interruptible busy dialog manager, declared in <Vk/VkProgressDialog.h>, is theProgressDialog.

VkProgressDialog is used in nearly the same way as VkInterruptDialog. The only addition is the setPercentDone() method, which changes the dialog's graphical progress indicator.

The prototype for setPercentDone() is as follows:

void setPercentDone(int percentDone)

percentDone should be an integer between 0 and 100, where 100 represents completion.

By default, VkProgressDialog shows a Cancel button that permits the user to interrupt the current task. If you do not wish to allow users to interrupt your task, you can prevent the Cancel button from appearing by passing FALSE as the second parameter in the VKProgressDialog constructor.

Figure 7-7. Progress Dialog

Example 7-4 shows a code segment that installs the progress dialog and performs a simulated lengthy task, checking for interrupts periodically and updating the progress indicator.

int i;
 
// Install the progress dialog as the dialog to post when busy
 
theApplication->setBusyDialog(theProgressDialog);
 
// Start being “busy”
 
the application->busy(“Very Busy”, (BusyWindow *) clientData);
 
int percentDone = 0;
for (i = 0; i < 10000; i++)
{
    // Every so often see if the task was interrupted
 
    if (theProgressDialog->wasInterrupted())
    {
        break;   // kick out of current task if user interrupts
    }
 
    // Update the percent done indicator. Do this only if we've made
    // more than one percent increment in progress. This avoids 
    // updating the dialog more frequently than is really necessary.
 
    if ((i/100) > percentDone)
    {
        percentDone = i/100;
        theProgressDialog->setPercentDone(percentDone);
    }
 
    sleep(1);
}
//Task done, so we're not busy anymore
 
theApplication->notBusy();
 
// Restore the application's busy dialog as the default
 
theApplication->setBusyDialog(NULL);

The VkQuestionDialog class supports standard Motif question dialogs. These allow the user to select among simple choices by clicking pushbuttons. The global pointer to the question dialog manager, declared in <Vk/VkQuestionDialog.h>, is theQuestionDialog.

As described in “Posting Dialogs”, the post(), postModal(), and postBlocked() functions allow you to specify callback functions to be executed when the user clicks the OK, Cancel, or Apply button. These callbacks apply only to the dialog posted by the current function call; they do not affect any subsequent dialog postings. You can also provide client data that is passed to all of the callbacks. Following ViewKit conventions as described in “Using Xt Callbacks With Components”, you should normally pass the this pointer as client data so that the callback functions can retrieve the pointer, cast it to the expected component type, and call a corresponding member function.

For the postAndWait() function, instead of providing callbacks, you simply pass a Boolean value for each button specifying whether or not it is displayed. Unlike the other posting functions, the value returned by postAndWait() is an enumerated constant of type VkDialogReason (defined in VkDialogManager). This value is CANCEL, OK, or APPLY, corresponding to the button the user clicked.

By default, VkQuestionDialog displays only the OK and Cancel buttons. VkQuestionDialog displays the Apply button only if you provide a callback for that button.

VkQuestionDialog does not provide any additional functions beyond those offered by the VkDialogManager.

The VkPromptDialog supports standard Motif prompt dialogs that allow the user to enter a text string. The global pointer to the prompt dialog manager, declared in <Vk/VkPromptDialog.h>, is thePromptDialog.

You can use VkPromptDialog any time you need to prompt the user to enter a single piece of information. If you need the user to enter more than one value, you should consider whether it is more appropriate to create a preference dialog as described in Chapter 8, “Preference Dialogs.” Another option is to create your own custom dialog using VkGenericDialog as described in “Deriving New Dialog Classes Using the Generic Dialog”.

By default, VkPromptDialog displays only the OK and Cancel buttons. VkPromptDialog displays the Apply button only if you provide a callback for that button.

VkPromptDialog::setText() allows you to enter an initial text string in the prompt dialog's text field.

One method of obtaining the text string the user entered in the prompt dialog is to extract it and use it in the OK callback function (and the apply callback function if you provide one). Example 7-5 demonstrates this technique.

void MailWindow::okCallback(Widget w, XtPointer, clientData, XtPointer callData)
{
    MailWindow *obj = (MailWindow *) clientData;
    obj->ok(w, callData);
}
 
void MailWindow::ok(Widget dialog, XtPointer callData);
{
    char *_text;
    XmSelectionBoxCallbackStruct *cbs = (XmSelectionBoxCallbackStruct *)callData;
 
    XmStringGetLtoR(cbs->value,
                    XmFONTLIST_DEFAULT_TAG,
                    &_text );
    // ...
}

Another method of obtaining the text string is to call VkPromptDialog::text() after the user has dismissed the dialog:

const char *text()

If the user clicks the OK button, the dialog accepts the currently displayed text as input and uses that string as the return value of text(). If the user clicks the Cancel button, the dialog discards the currently displayed value and any previously-displayed string the dialog might have contain is returned as the value of text(). Do not attempt to free the string returned by text(). Typically, you should call text() only if you post the dialog using postAndWait() and postAndWait() returns a value of VkDialogManager::OK.

---

Caution: The following are two points that you should keep in mind when using VkPromptDialog:

---

The VkFileSelectionDialog class supports standard Motif file selection dialogs (an example of which is shown in Figure 7-8). These allow the user to interactively browse and select a file or directory. The global pointer to the file selection dialog manager, declared in <Vk/VkFileSelectionDialog.h>, is theFileSelectionDialog.

Figure 7-8. File Selection Dialog

You can set the initial directory displayed by the dialog using VkFileSelectionDialog::setDirectory():

void setDirectory(const char *directory)

If you do not explicitly set a directory, the dialog defaults to the current directory.

You can set the initial filter pattern used by the dialog, which determines the files displayed in the list box by using VkFileSelectionDialog::setFilterPattern():

void setFilterPattern(const char *pattern)

If you do not explicitly set a selection, the dialog displays all files in a directory.

You can set the initial selection used of the dialog using VkFileSelectionDialog::setSelection():

void setSelection(const char *selection)   

One method of obtaining the selection string of the file selection dialog is to extract it and use it in the OK callback function. Example 7-6 demonstrates this technique.

void MailWindow::okCallback(Widget w, XtPointer, clientData, XtPointer callData)
{
    MailWindow *obj = (MailWindow *) clientData;
    obj->ok(w, callData);
}
 
void MailWindow::ok(Widget dialog, XtPointer callData);
{
    char *_text;
    XmFileSelectionBoxCallbackStruct *cbs =
                                  (XmFileSelectionBoxCallbackStruct *) callData;
 
    XmStringGetLtoR(cbs->value,
                    XmFONTLIST_DEFAULT_TAG,
                    &_text );
    // ...
}

Another method of obtaining the selection string is to call VkFileSelectionDialog::fileName() after the user has dismissed the dialog:

const char* fileName()

If the user clicks the OK button, the dialog accepts the currently displayed text as input and uses that string as the return value of fileName(). If the user clicks the Cancel button, the dialog discards the currently displayed value, and any previously-displayed string the dialog might have contained is returned as the value of fileName(). Do not attempt to free the string returned by fileName(). Typically, you should call fileName() only if you post the dialog using postAndWait(), and postAndWait() returns a value of VkDialogManager::OK.

---

Caution: The following are two points that you should keep in mind when using VkFileSelectionDialog:

---

The following code fragment shows a simple example of using the VkFileSelectionDialog class:

#include <iostream.h>
#include <Vk/VkFileSelectionDialog.h>
 
// ...
 
theFileSelectionDialog->setDirectory(“/usr/tmp”);
 
if(theFileSelectionDialog->postAndWait( ) == VkDialogManager::OK)
  cout << "File name: " << theFileSelectionDialog->fileName()
       << '\n' << flush;   

The VkColorChooserDialog class displays an SgColorChooser dialog widget that provides a powerful user-friendly interface for selecting colors (see Figure 7-9). The color chooser provides a color hexagon, color sliders, and editable text fields. The color hexagon allows the user to pick a color by sight. The sliders and text fields let the user choose a color by hue, saturation, and value (HSV), or by the levels of red, green, and blue (RGB). The user has the option of displaying and manipulating different combinations of sliders: value only, value and RGB, and HSV and RGB. The color chooser dialog also allows the user to store one color for reference (the “stored color”) while selecting another one (the “current color”).

For more information about color chooser dialogs, see the VkColorChooserDialog(3x) and SgColorChooser(3X) reference pages. For a demonstration of the VkColorChooserDialog class, see the example program in /usr/share/src/ViewKit/Dialogs.

The global pointer to the color chooser dialog manager, declared in <Vk/VkColorChooserDialog.h>, is theColorChooserDialog.

Figure 7-9. Color Chooser Dialog

VkColorChooserDialog Access Functions

The VkColorChooserDialog class provides access functions to set and obtain the current and stored color selections. Each of these functions has two variations. One set uses true XColors, with color component values in the range of 0 to 64K. The other set uses colors suitable for non-X graphics, with component values in the range of 0 to 255.

You can obtain the current color by using one of the following functions:

You can set colors by using the following functions:

The VkGenericDialog class is an abstract subclass of VkDialogManager. It provides a convenient interface for creating custom dialogs that use the ViewKit interface. Custom dialogs that you derive from this class automatically support caching and all the other features supported by VkDialogManager. You can post and manipulate your custom dialogs using the functions provided by VkDialogManager.

Minimally, when you derive a new dialog class, you must override the VkGenericDialog::createDialog() function to create the dialog used by your class:

virtual Widget createDialog(Widget parent)

ViewKit passes to createDialog() the parent widget for the dialog, and createDialog() must return the dialog you create. Your overriding function must first call VkGenericDialog::createDialog(), which creates a MessageBox dialog template. By default, the dialog displays OK and Cancel buttons. Then, you simply add the interface to the MessageBox widget.

You can change the buttons displayed by default and other characteristics for your custom dialog by setting certain protected data members:

Also, by default ViewKit dismisses your dialog whenever the user clicks either the OK or Cancel button, and keeps the dialog posted whenever the user clicks the Apply button. You can change this behavior by overriding the functions VkDialogManager::ok(), VkDialogManager::cancel(), and VkDialogManager::apply(), respectively:

virtual void ok(Widget dialog, XtPointer callData)
virtual void cancel(Widget dialog, XtPointer callData)
virtual void apply(Widget dialog, XtPointer callData)

ViewKit calls these functions whenever the user clicks one of the buttons in the dialog. By default, ok() and cancel() unpost the dialog and apply() is empty. You can override these functions to change the unposting behavior or to perform any other actions you want.