Dialog widget

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.

Resources

Constraint Resources

Name	Class	Type	Notes	Default Value
bottom	Edge	XawEdgeType		XawRubber
fromHoriz	Widget	Widget		NULL (left edge of Dialog)
fromVert	Widget	Widget		NULL (top edge of Dialog)
horizDistance	Thickness	int		\fBdefaultDistance\fP resource
left	Edge	XawEdgeType		XawRubber
resizable	Boolean	Boolean		FALSE
right	Edge	XawEdgeType		XawRubber
top	Edge	XawEdgeType		XawRubber
vertDistance	Thickness	int		\fBdefaultDistance\fP resource

bottom left right top	What to do with this edge of the child when the parent is resized. This resource may be any edgeType. See Layout Semantics for details.
fromHoriz fromVert	Which widget this child should be placed underneath (or to the right of). If a value of NULL is specified then this widget will be positioned relative to the edge of the parent.
horizDistance vertDistance	The amount of space, in pixels, between this child and its left or upper neighbor.
resizable	If this resource is False then the parent widget will ignore all geometry request made by this child. The parent may still resize this child itself, however.

Layout Semantics

The first layout method uses the fromVert and fromHoriz resources to place the children of the Dialog. A single pass is made through the Dialog widget's children in the order that they were created. Each child is then placed in the Dialog widget below or to the right of the widget specified by the fromVert and fromHoriz resources. The distance the new child is placed from its left or upper neighbor is determined by the horizDistance and vertDistance resources. This implies some things about how the order of creation affects the possible placement of the children. The Dialog widget registers a string to widget converter which does not postpone conversion and does not cache conversion results.

The second layout method is used when the Dialog is resized. It does not matter what causes this resize, and it is possible for a resize to happen before the widget becomes visible (due to constraints imposed by the parent of the Dialog). This layout method uses the bottom, top, left, and right resources. These resources are used to determine what will happen to each edge of the child when the Dialog is resized. If a value of XawChain<something> is specified, the the edge of the child will remain a fixed distance from the chain edge of the Dialog. For example if XawChainLeft is specified for the right resource of a child then the right edge of that child will remain a fixed distance from the left edge of the Dialog widget. If a value of XawRubber is specified, that edge will grow by the same percentage that the Dialog grew. For instance if the Dialog grows by 50% the left edge of the child (if specified as XawRubber will be 50% farther from the left edge of the Dialog). One must be very careful when specifying these resources, for when they are specified incorrectly children may overlap or completely occlude other children when the Dialog widget is resized.

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

Example

Special Considerations

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 Dialog widget to create its own Dialog policy.

Automatically Created Children.

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.

Convenience routines

String XawDialogGetValueString(w)
	Widget w;

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;

This function is merely a shorthand for the code sequence:

{
  Widget button = XtCreateManagedWidget(name, commandWidgetClass, w, NULL, ZERO);
  XtAddCallback(button, XtNcallback, func, client_data);
}