NAME

XmtDisplayWorkingDialog(), XmtHideWorkingDialog() - display or hide a ``please wait'' dialog box.

SYNOPSIS

#include <Xmt/Dialogs.h>

Widget XmtDisplayWorkingDialog(Widget w, String dialog_name, String message_default, String scale_label_default, String button_label_default, int scale_min, int scale_max, Boolean show_scale, Boolean show_button)

void XmtHideWorkingDialog(Widget w)

ARGUMENTS

INPUTS

w: The shell widget over which the dialog will be popped up or popped down, or any descendant of that shell.
dialog_name: The name for this instantiation of the dialog. This name is used to look up the message and title resources for the dialog. NULL may be specified, but will result in a dialog that cannot be customized through the resource manager.
message_default: The default message to be used if no dialog_name is provided, or if no message is found under that name in the resource database.
scale_label_default: The string to display to the left of the XmScale widget if no overriding value is found in the resource database. Specify NULL for the default label.
button_label_default: The string to display in the single XmPushButton widget of the dialog if no overriding value is found in the resource database. Specify NULL for the default label.
scale_min: The minimum value to be displayed by the XmScale widget.
scale_max: The maximum value to be displayed by the XmScale widget.
show_scale: Whether the XmScale widget (and its associated text label) should be displayed in the dialog.
show_button: Whether the XmPushButton widget should be displayed in the dialog.

RETURNS

A pointer to the XmtWorkingBox widget which was popped up by the function.

DESCRIPTION

The XmtWorkingBox widget is designed to display ``Busy; please wait'' dialog boxes to the user. XmtDisplayWorkingDialog() and XmtHideWorkingDialog() provide a simplified interface for handling these dialogs-they automatically create the required dialog widget and cache it for subsequent reuse.

XmtDisplayWorkingDialog() displays a modal XmtWorkingBox dialog containing a message and a ``working'' icon. The dialog is intended to be posted while the application is performing some time consuming task during which it will not be responding to user input events. It optionally (depending on show_scale) contains an XmScale widget which can be used to provide feedback to the user about the progress of whatever task is underway. A label, ``% Complete:'' by default, appears to the left of the XmScale widget. The minimum and maximum bounds for the XmScale slider are specified by scale_min and scale_max. The working dialog also contains an optional (depending on show_button) XmPushButton widget which can be periodically polled to see if the user wants to abort the task. The default label for the button is Stop.

XmtDisplayWorkingDialog() returns the XmtWorkingBox widget of the dialog. This value can be used in subsequent calls to XmtWorkingBoxSetScaleValue() and XmtWorkingBoxHandleEvents() to update the XmScale slider value and to poll the XmPush Button widget of the dialog.

XmtDisplayWorkingDialog() calls XmtWaitUntilMapped() before returning to ensure that the dialog box is visible to the user before returning to the calling function which will generally perform some time consuming task without handling events.

XmtHideWorkingDialog() pops down any XmtWorkingBox dialog that was posted over the shell of w by XmtDisplayWorkingDialog(). Note that w is the same widget passed to XmtDisplayWorkingDialog() (or any other descendant of the shell); not the widget returned by XmtDisplayWorkingDialog().

WIDGETS

XmtDisplayWorkingDialog() creates a single XmtWorkingBox dialog for each screen it is called on, and caches that dialog for reuse by subsequent calls to the function. The name of the XmtWorkingBox is ``xmtWorkingDialog'', and the name of its XmDialogShell parent is ``xmtWorkingDialogShell''. If you set resources on these widgets note that, because of the dialog caching, they will affect all instantiations of the working dialog.

Customization

You can also customize individual instantiations of working dialogs by specifying the dialog_name argument to XmtDisplayWorkingDialog(). The resources are looked up as a subpart of the shell widget of w. The name of the subpart is given by dialog_name, and the class of the subpart is ``XmtWorkingDialog''. The table lists the resources that are looked up, their default values, and how they are used.

Name	Default	Purpose
message	message_default	the message to be displayed.
scaleLabel	scale_label_default or ”% Complete:“	the label for the scale widget.
buttonLabel	button_label_default or ”Stop“	the button label.
title	”Working“	text for the dialog titlebar.

NAME

SYNOPSIS

ARGUMENTS

DESCRIPTION

SEE ALSO