NAME
Dialog widget − dialog box widget.
SYNOPSIS
Public Headers:<X11/StringDefs.h> <X11/Xaw/Dialog.h>
Private Header:<X11/Xaw/DialogP.h>
Class Name:Dialog
Class Pointer:dialogWidgetClass
Instantiation:widget = XtCreateWidget(name, dialogWidgetClass, ...)
CLASS HIERARCHY
Core → Composite → Constraint → Form → Dialog
DESCRIPTION
The Dialog widget implements a commonly used interaction semantic to prompt for auxiliary input from a user. For example, you can use a Dialog widget when an application requires a small piece of information, such as a filename, from the user. A Dialog widget is simply a special case of the Form widget that provides a convenient way to create a preconfigured form.
The typical Dialog widget contains three areas. The first line contains a description of the function of the Dialog widget, for example, the string Filename:. The second line contains an area into which the user types input. The third line can contain buttons that let the user confirm or cancel the Dialog input. Any of these areas may be omitted by the application.
RESOURCES
When creating a Dialog widget instance, the following resources are retrieved from the argument list or from the resource database:
| Name (XtN...) | Type | Default | Description | |||
| XtNaccelerators | AcceleratorTable | NULL | List of event-to-action bindings to be executed by this widget, even though the event occurred in another widget. | |||
| XtNancestor− Sensitive |
Boolean | True | (D) Sensitivity state of the ancestors of this widget: a widget is insensitive if either it or any of its ancestors is insensitive. | |||
| XtNbackground | Pixel | XtDefault− Background |
Window background color. | |||
| XtNbackground− Pixmap |
Pixmap | XtUnspecified− Pixmap |
Window background pixmap. | |||
| XtNborderColor | Pixel | XtDefault− Foreground |
Window border color. | |||
| XtNborderPixmap | Pixmap | XtUnspecified− Pixmap |
Window border pixmap. | |||
| XtNborderWidth | Dimension | 1 | Width of border in pixels. | |||
| XtNchildren | WidgetList | NULL | (R) List of all this composite widget’s current children. | |||
| XtNcolormap | Colormap | Parent’s colormap. | Colormap that this widget will use. | |||
| XtNdefault− Distance |
int | 4 | Default value for XtNhorizDistance and XtNvertDistance. | |||
| XtNdepth | int | Parent’s depth. | (C) Depth of this widget’s window. | |||
| XtNdestroy− Callback |
XtCallbackList | NULL | Callbacks for XtDestroyWidget(). | |||
| XtNheight | Dimension | Computed at realize. |
(A) Height of dialog. | |||
| XtNicon | Pixmap | None | See below. | |||
| XtNlabel | String | "label" | See below. | |||
| XtNmappedWhen− Managed |
Boolean | TRUE | Whether XtMapWidget() is automatic. | |||
| XtNnumChildren | Cardinal | 0 | (R) Number of children in this composite widget. | |||
| XtNscreen | Screen | Parent’s screen. | (R) Screen on which this widget is displayed. | |||
| XtNsensitive | Boolean | TRUE | Whether widget receives input. | |||
| XtNtranslations | TranslationTable | NULL | Event-to-action translations. | |||
| XtNvalue | char∗ | NULL | Pointer to default string. | |||
| XtNwidth | Dimension | Computed at realize. |
(A) Width of dialog. | |||
| XtNx | Position | 0 | x coordinate in pixels. | |||
| XtNy | Position | 0 | y coordinate in pixels. | |||
The instance name of the label widget within the Dialog widget is label, and the instance name of the Dialog value widget is value.
The new resources (not inherited from superclasses) associated with the Dialog widget are:
XtNicon
A pixmap image to be displayed immediately to the left of the Dialog widget’s label.
XtNlabel
A Latin1 string to be displayed at the top of the Dialog widget.
XtNvalue
An initial value for the string field into which the user will enter text. By default, no text entry field is available to the user. Specifying an initial value for value activates the text entry field. If string input is desired but no initial value is to be specified, then set this resource to "" (empty string).
PUBLIC FUNCTIONS
•To add a child button to the Dialog box, use XtCreateWidget() and specify the widget ID of the previously created Dialog box as the parent of each child. When creating buttons, you do not have to specify form constraints. The Dialog widget will automatically add the constraints.
•To return the character string in the text field, use: char ∗XawDialogGetValueString(w) Widget w; where w specifies the widget ID of the Dialog box. If a string was specified in the XtNvalue resource, the Dialog widget will store the input directly into the string.
SEE ALSO
Command, Form, Text.