http://invisible-island.net/athena_widgets/XawPlus
| Application Header file Class Header file Class Class Name Superclass |
<X11/XawPlus/Dialog.h> <X11/XawPlus/DialogP.h> dialogWidgetClass Dialog Form |
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, which is simply a special case of the Form widget, 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.
Since release 2.1 of XawPlus Dialog has installed pixmap converters for the icon and a clip mask for nonrectangular color icons. A new resource clipMask is added.
When creating a Dialog widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:
| Name | Class | Type | Default Value |
| OBJECT: | |||
| destroyCallback | Callback | Pointer | NULL |
| RECTANGLE: | |||
| borderWidth height sensitive width x y |
BorderWidth Height Sensitive Width Position Position |
Dimension Dimension Boolean Dimension Position Position |
1 Space for all children True Space for all children 0 0 |
| CORE: | |||
| border background mappedWhenManaged |
BorderColor Background MappedWhenManaged |
Pixel Pixel Boolean |
XtDefaultForeground grey75 True |
| FORM: | |||
| defaultDistance | Thickness | int | 4 |
| DIALOG: | |||
| icon clipMask label value |
Pixmap Pixmap Label Value |
Bitmap ClipMask String String |
None None NULL NULL |
| icon | A pixmap image to be displayed immediately to the left of the Dialog widget's label. |
| label | A Latin1 string to be displayed at the top of the Dialog widget. |
| value | An initial value for the string field that the user will enter text into. 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). |
Each child of the Dialog widget may request special layout resources be applied to it. These constraint resources allow the Dialog widget's children to specify individual layout requirements.
| Name | Class | RepType | Default Value |
| bottom fromHoriz fromVert horizDistance left resizable right top vertDistance |
Edge Widget Widget Thickness Edge Boolean Edge Edge Thickness |
XtEdgeType Widget Widget int XtEdgeType Boolean XtEdgeType XtEdgeType int |
XtRubber (left edge of form) (top of form) defaultDistance XtRubber False XtRubber XtRubber defaultDistance |
| Edge Type | Resource Name | Description |
| XawChainBottom | ChainBottom | Edge remains a fixed distance from bottom of Dialog |
| XawChainLeft | ChainLeft | Edge remains a fixed distance from left of Dialog |
| XawChainRight | ChainRight | Edge remains a fixed distance from right of Dialog |
| XawChainTop | ChainTop | Edge remains a fixed distance from top of Dialog |
| XawRubber | Rubber | Edges will move a proportional distance |
If you wish to force the Dialog to never resize one or more of its children then set left and right to XawChainLeft and top and bottom to XawChainTop. This will cause the child to remain a fixed distance from the top and left edges of the Dialog, and to never resize.
The Dialog widget automatically sets the top and bottom resources for all Children that are subclasses of the Command widget, as well as the widget children that are used to contain the label, value, and icon. This policy allows the buttons at the bottom of the Dialog to interact correctly with the predefined children, and makes it possible for a client to simply create and manage a new Command button without having to specify its constraints.
The Dialog will also set fromLeft to the last button in the Dialog for each new button added to the Dialog widget.
The automatically added constraints cannot be overridden, as they are policy decisions of the Dialog widget. If a more flexible Dialog is desired, the application is free to use the Form widget to create its own Dialog policy.
The Dialog uses Label widgets to contain the label and icon. These widgets are named label and icon respectively. The Dialog value is contained in an AsciiText widget whose name is value. Using XtNameToWidget the application can change those resources associated with each of these widgets that are not available through the Dialog widget itself.
To return the character string in the text field, use XawDialogGetValueString():
String XawDialogGetValueString(w)
Widget w;
w Specifies the Dialog widget.
This function returns a copy of the value string of the Dialog widget. This string is allocated by the AsciiText widget and will remain valid and unchanged until another call to XawDialogGetValueString() or an XtGetValues() call on the value widget, when the string will be automatically freed, and a new string is returned. This string may be freed earlier by calling the function XawAsciiSourceFreeString().
To add a new button to the Dialog widget use XawDialogAddButton().
void XawDialogAddButton(w, name, func, client_data)
Widget w;
String name;
XtCallbackProc func;
XtPointer client_data;
w Specifies the Dialog widget. name Specifies the name of the new Command button to be added to the Dialog. func Specifies a callback function to be called when this button is activated. If NULL is specified then no callback is added. client_data Specifies the client_data to be passed to the func.
This function is merely a shorthand for the code sequence:
Widget button = XtCreateManagedWidget(name,
commandWidgetClass, w, NULL, ZERO);
XtAddCallback(button, XtNcallback, func, client_data);