Name

DwtWorkBox, DwtWorkBoxCreate − Creates a work-in-progress box widget for the application to display work in progress messages. 

Syntax

Widget DwtWorkBox(parent_widget, name, default_position,
                  x, y, style, label, cancel_label,
                  callback, help_callback)
     Widget parent_widget;
     char *name;
     Boolean default_position;
     Position x, y;
     int style;
     DwtCompString label, cancel_label;
     DwtCallbackPtr callback, help_callback;

Widget DwtWorkBoxCreate (parent_widget, name,
                         override_arglist, override_argcount)
     Widget parent_widget;
     char *name;
     ArgList override_arglist;
     int override_argcount;

Arguments

parent_widget
Specifies the parent widget ID.

nameSpecifies the name of the created widget. 

default_position
Specifies a boolean value that, when True, causes DwtNx and DwtNy to be ignored and forces the default widget position.  The default widget position is centered in the parent window.  If False, the specified DwtNx and DwtNy attributes are used to position the widget.  This argument sets the DwtNdefaultPosition attribute associated with DwtDialogBoxCreate. 

xSpecifies the placement, in pixels, of the left side of the widget window relative to the inner upper left corner of the parent window.  This argument sets the DwtNx core widget attribute. 

ySpecifies, in pixels, the placement of the upper left corner of the widget window relative to the inner upper left corner of the parent window.  This argument sets the DwtNy core widget attribute. 

styleSpecifies the style of the dialog box widget.  You can pass DwtModal (modal) or DwtModeless (modeless).  This argument sets the DwtNstyle attribute associated with DwtDialogBoxPopupCreate. 

labelSpecifies the text in the message line or lines.  This argument sets the DwtNlabel attribute associated with DwtWorkBoxCreate. 

cancel_labelSpecifies the label for the Cancel push button.  If the label is a NULL string, the button is not displayed.  This argument sets the DwtNcancelLabel attribute associated with DwtWorkBoxCreate. 

callbackSpecifies the callback function or functions called back when the Cancel button is activated.  This argument sets the DwtNcancelCallback attribute associated with DwtWorkBoxCreate. 

help_callbackSpecifies the callback function or functions called when a help request is made.  This argument sets the DwtNhelpCallback common widget attribute. 

override_arglist
Specifies the application override argument list.

override_argcount
Specifies the number of attributes in the application override argument list (override_arglist). 

Description

The DwtWorkBox and DwtWorkBoxCreate functions create an instance of a work-in-progress box widget and return its associated widget ID.  When calling DwtWorkBox, you set the work-in-progress box widget attributes presented in the formal parameter list.  For DwtWorkBoxCreate, however, you specify a list of attribute name/value pairs that represent all the possible work-in-progress box widget attributes.  The work-in-progress box widget is a dialog box that allows the application to display work in progress messages to the user.  When the application determines that an operation will take longer than five seconds, it is recommended that the application call this function to display a work-in-progress box with a message such as “Work in Progress./Please Wait.” The work-in-progress box may contain a push button labeled “Cancel Operation.” Do not include the push button if the operation cannot be canceled.  If the style is DwtModal when the user selects the Cancel push button, the widget is cleared from the screen, but not destroyed.  The widget can be redisplayed by calling XtManageChild. 

Inherited Attributes

Widget-Specific Attributes

DwtNlabelSpecifies the text in the message line or lines. 

DwtNcancelLabel
Specifies the label for the Cancel push button. If the label is a NULL string, the button is not displayed.

DwtNcancelCallback
Specifies the callback function or functions called when the user clicks on the Cancel button. For this callback, the reason is DwtCRCancel. 

Return Value

These functions return the ID of the created widget. 

Callback Information

The following structure is returned to your callback:

typedef struct {
int reason;
XEvent *event;
} DwtAnyCallbackStruct;

The reason member is set to a constant that represents the reason why this callback was invoked. For this callback, the reason member can be set to:

The event member is a pointer to the Xlib structure XEvent, which describes the event that generated this callback.  This structure is a union of the individual structures declared for each event type.  For information on XEvent and event processing, see the Guide to the Xlib Library: C Language Binding. 

See Also

Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding

Subroutines