DwtDialogBox(3Dwt) DwtDialogBox(3Dwt)
Name
DwtDialogBox, DwtDialogBoxCreate, DwtDialogBoxPopupCreate - Creates a dialog box widget to contain other subwidgets.
Syntax
Widget DwtDialogBox(parent_widget, name, default_position,
x, y, title, style,
map_callback, help_callback)
Widget parent_widget;
char *name;
Boolean default_position;
Position x, y;
DwtCompString title;
unsigned char style;
DwtCallbackPtr map_callback, help_callback;
Widget DwtDialogBoxCreate (parent_widget, name,
override_arglist, override_argcount)
Widget parent_widget;
char *name;
ArgList override_arglist;
int override_argcount;
Widget DwtDialogBoxPopupCreate (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.
name Specifies 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 posi-
tion the widget.
If the dialog box is displayed partially off the screen as a result of being centered in the parent window, the centering rule is
violated. When this occurs, the parent window is repositioned so that the entire dialog box is displayed on the screen.
The pop-up dialog box is recentered every time it is popped up. Consequently, if the parent moves in between invocations of the
dialog box, the box pops up centered in the parent window's new location. However, the dialog box does not dynamically follow
its parent while it is displayed. If the parent is moved, the dialog box will not move until the next time it is popped up.
If the user moves the dialog box with the window manager, the toolkit turns off DwtNdefaultPosition. This results in the dialog
box popping up in the location specified by the user on each subsequent invocation. This argument sets the DwtNdefaultPosition
attribute associated with DwtDialogBoxCreate.
x Specifies 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.
y Specifies, 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.
title Specifies the compound-string label. The label is given to the window manager for the title bar if DwtNstyle is DwtModeless.
This argument sets the DwtNtitle attribute associated with DwtDialogBoxPopupCreate.
style Specifies the style of the dialog box widget. You can pass DwtModal, DwtModeless, or DwtWorkarea. You cannot change DwtNstyle
after the widget is created. This argument sets the DwtNstyle attribute associated with DwtDialogBoxCreate or DwtDialogBoxPop-
upCreate.
map_callback
Specifies the callback function or functions called when the window is about to be mapped. For this callback, the reason is
DwtCRMap. Note that map_callback is supported only if style is DwtModal or DwtModeless. If style is DwtWorkarea, map_callback
is ignored.
This argument sets the DwtNmapCallback attribute associated with DwtDialogBoxPopupCreate.
help_callback
Specifies 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
Depending on the constant you pass to DwtNstyle, the DwtDialogBox function creates a dialog box or a pop-up dialog box widget. The DwtDi-
alogBoxCreate function creates a dialog box widget, and DwtDialogBoxPopupCreate creates a pop-up dialog box widget. Upon completion, these
functions return the associated widget ID. When calling DwtDialogBox, you set the dialog box widget attributes presented in the formal
parameter list. For DwtDialogBoxCreate and DwtDialogBoxPopupCreate, however, you specify a list of attribute name/value pairs that repre-
sent all the possible dialog box widget attributes.
The dialog box widget is a composite widget that contains other subwidgets. Each subwidget displays information or requests and/or handles
input from the user.
The dialog box widget functions as a container only, and provides no input semantics over and above the expressions of the widgets it con-
tains.
Subwidgets can be positioned within the dialog box in two ways: by font units and by pixel units. By default, subwidgets are positioned in
terms of font units (that is, DwtNunits is DwtFontUnits). The X font units are defined to be one-fourth the width of whatever font is sup-
plied for the common attribute DwtNfont. The Y font units are defined to be one-eighth the width of whatever font is supplied for DwtN-
font. (Width is taken from the QUAD_WIDTH property of the font.) Subwidgets can also be positioned in terms of pixel units (that is, Dwt-
Nunits is DwtPixelUnits).
Note that when changing DwtNtextMergeTranslations, the existing widgets are not affected. The new value for DwtNtextMergeTranslations acts
only on widgets that are added after the pop-up dialog box is created.
Pop-up dialog box widgets create their own shells as parents. Therefore, to set the colormap of a pop-up dialog box, you must set the col-
ormap of its parent shell. (To find the parent shell, use XtParent.) For nonpop-up widgets, the shell widget ID is returned from XtIni-
tialize. You need only set the colormap once on the returned shell widget.
Inherited Attributes
------------------------------------------------------------------
Attribute Name Data Type Default
------------------------------------------------------------------
Core Attributes
DwtNx Position Determined by the geome-
try manager
DwtNy Position Determined by the geome-
try manager
DwtNwidth Dimension Set as large as neces-
sary to hold all child
widgets
DwtNheight Dimension Set as large as neces-
sary to hold all child
widgets
DwtNborderWidth Dimension One pixel
DwtNborder Pixel Default foreground color
DwtNborderPixmap Pixmap NULL
DwtNbackground Pixel Default background color
DwtNbackgroundPixmap Pixmap NULL
DwtNcolormap Colormap Default color map
DwtNsensitive Boolean True
DwtNancestorSensitive Boolean The bitwise AND of the
parent widget's DwtNsen-
sitive and DwtNances-
torSensitive attributes
DwtNaccelerators XtTranslations NULL
DwtNdepth int Depth of the parent win-
dow
DwtNtranslations XtTranslations NULL
DwtNmappedWhenManaged Boolean True
DwtNscreen Screen * The parent screen
DwtNdestroyCallback DwtCallbackPtr NULL
------------------------------------------------------------------
Widget-Specific Attributes
----------------------------------------------------------------------
Attribute Name Data Type Default
----------------------------------------------------------------------
DwtNforeground Pixel Default foreground color
DwtNhighlight Pixel Default foreground color
DwtNhighlightPixmap Pixmap NULL
DwtNuserData Opaque * NULL
DwtNfont DwtFontList The default XUI Toolkit
font
DwtNhelpCallback DwtCallbackPtr NULL
DwtNdirectionRToL unsigned char DwtDirectionRightDown
DwtNunits unsigned char DwtFontUnits
DwtNstyle unsigned char For DwtDialogBoxCreate,
the default is Dwt-
Workarea.
For DwtDialogBoxPop-
upCreate, the default is
DwtModeless.
DwtNfocusCallback DwtCallbackPtr NULL
DwtNtextMergeTranslations XtTranslations NULL
DwtNmarginWidth Dimension For DwtDialogBoxCreate,
the default is One
pixel.
For DwtDialogBoxPop-
upCreate, the default is
3 pixels.
DwtNmarginHeight Dimension For DwtDialogBoxCreate,
the default is One
pixel.
For DwtDialogBoxPop-
upCreate, the default is
3 pixels.
DwtNdefaultPosition Boolean False
DwtNchildOverlap Boolean True
DwtNresize unsigned char DwtResizeGrowOnly
DwtNgrabKeySyms KeySym The default array con-
tains the Tab key sym-
bol.
DwtNgrabMergeTranslations XtTranslations The default syntax is:
"~Shift<KeyPress>0xff09:
DWTDIMOVEFOCUS-
NEXT()\n.br Shift<Key-
Press>0xff09: DWTDI-
MOVEFOCUSPREV()";
----------------------------------------------------------------------
The following table lists the widget-specific attributes for the pop-up dialog box widget.
-----------------------------------------------------
Attribute Name Data Type Default
-----------------------------------------------------
DwtNtitle DwtCompString When DwtNstyle
is DwtModal,
the default is
NULL
When DwtNstyle
is DwtModeless,
the default is
the widget name
DwtNmapCallback DwtCallbackPtr NULL
DwtNunmapCallback DwtCallbackPtr NULL
DwtNtakeFocus Boolean True for modal
dialog box
False for mode-
less dialog box
DwtNnoResize Boolean True (that is,
no window man-
ager resize
button)
DwtNautoUnmanage Boolean True
DwtNdefaultButton Widget NULL
DwtNcancelButton Widget NULL
DwtNautoUnrealize Boolean False
-----------------------------------------------------
DwtNforeground Specifies the color of foreground gadget children in the widget window.
DwtNhighlight Specifies the color used for highlighting gadget children.
DwtNhighlightPixmap
Specifies the pattern and color used for highlighting gadget children.
DwtNuserData Specifies any user private data to be associated with the widget. The XUI Toolkit does not interpret this data.
DwtNdirectionRToL
Specifies the direction in which the text is drawn and wraps. You can pass DwtDirectionLeftDown (text is drawn from left to
right and wraps down); DwtDirectionRightUp (text is drawn from left to right and wraps up); DwtDirectionLeftDown (text is
drawn from right to left and wraps down); or DwtDirectionLeftUp (text is drawn from right to left and wraps up).
DwtNfont Specifies the font of the text used in gadget children.
DwtNhelpCallback
Specifies the callback function or functions called when a help request is made.
DwtNunits Specifies the type of units for the DwtNx and DwtNy attributes. You use these when adding child widgets to the dialog box.
The DwtNunits attribute cannot be changed after the widget is created. You can pass DwtPixelUnits or DwtFontUnits.
DwtNstyle Specifies the style of the dialog box widget. For DwtDialogBoxPopupCreate you can pass DwtModal or DwtModeless. For DwtDi-
alogBoxCreate you can pass DwtWorkarea. You cannot change DwtNstyle after the widget is created.
DwtNfocusCallback
Specifies the callback function or functions called when the dialog box accepted the input focus. For this callback, the
reason is DwtCRFocus.
DwtNtextMergeTranslations
Specifies the translation manager syntax that will be merged with each text widget.
DwtNmarginWidth
Specifies the number of pixels between the maximum right border of a child widget window and the dialog box.
DwtNmarginHeight
Specifies the number of pixels between the maximum bottom border of a child widget window and the dialog box.
DwtNdefaultPosition
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.
If the dialog box is displayed partially off the screen as a result of being centered in the parent window, the centering
rule is violated. When this occurs, the parent window is repositioned so that the entire dialog box is displayed on the
screen.
The pop-up dialog box is recentered every time it is popped up. Consequently, if the parent moves in between invocations of
the dialog box, the box pops up centered in the parent window's new location. However, the dialog box does not dynamically
follow its parent while it is displayed. If the parent is moved, the dialog box will not move until the next time it is
popped up.
If the user moves the dialog box with the window manager, the toolkit turns off DwtNdefaultPosition. This results in the
dialog box popping up in the location specified by the user on each subsequent invocation.
DwtNchildOverlap
Specifies a boolean value that, when True, indicates that the dialog box approves geometry requests from its children that
result in one child overlapping other children. If False, the dialog box disapproves these geometry requests.
DwtNresize Specifies how the dialog box resizes when its children are managed and unmanaged and when geometry requests occur. You can
pass DwtResizeFixed, DwtResizeGrowOnly, or DwtResizeShrinkWrap.
DwtResizeFixed indicates that the dialog box does not change its size when children are added or deleted, or on geometry
requests from its children.
DwtResizeGrowOnly indicates that the dialog box always attempts to grow as necessary when children are added or deleted, or
on geometry requests from its children.
DwtResizeShrinkWrap indicates that the dialog box always attempts to grow or shrink to fit its current set of managed chil-
dren as children are added or deleted, or on geometry requests from its children.
DwtNgrabKeySyms
Specifies a NULL-terminated array of keysyms. The dialog box calls the Xlib function XGrabKey for each keysym. XGrabKey
specifies AnyModifier for modifiers, GrabModeAsync for pointer_mode, and GrabModeSync for keyboard_mode. The dialog box
uses the XGrabKey function in conjunction with the value of DwtNgrabMergeTranslations to implement moving the focus among
its children in a synchronous manner. You cannot change this attribute after the widget is created.
DwtNgrabMergeTranslations
Specifies the parsed translation syntax to merge into the dialog box syntax to handle the key events. The syntax is merged
when the dialog box is first realized. Any change made to this attribute after the dialog box is realized will not have any
effect.
DwtNtitle Specifies the compound-string label. The label is given to the window manager for the title bar if DwtNstyle is DwtMode-
less.
DwtNmapCallback
Specifies the callback function or functions called when the window is about to be mapped. For this callback, the reason is
DwtCRMap.
DwtNunmapCallback
Specifies the callback function or functions called when the window was unmapped. For this callback, the reason is DwtCRUn-
map.
DwtNtakeFocus Specifies a boolean value that, when True, indicates that the dialog box takes the input focus when managed.
DwtNnoResize Specifies a boolean value that, when True, indicates that a modal or modeless dialog box does not have a window manager
resize button. When False, the dialog box has a window manager resize button.
DwtNautoUnmanage
Specifies a boolean value that, when True, indicates that the dialog box unmanages itself when any push button is activated.
This attribute cannot be changed after widget creation.
DwtNdefaultButton
Specifies the ID of the push button widget that is activated when the user presses the RETURN or ENTER key.
DwtNcancelButton
Specifies the ID of the push button widget that is activated when the user presses the Shift and Return keys simultaneously.
DwtNautoUnrealize
Specifies a boolean value that, when False, indicates that the dialog box creates the window(s) for itself and its children
when it is first managed, and never destroys them. If True, the dialog box re-creates the window(s) every time it is man-
aged, and destroys them when it is unmanaged.
The setting of this attribute is a performance tradeoff between the client cpu load (highest when set to True), and the
server window load (highest when set to False).
The following constraint attributes are passed on to any widget that is made a child of a dialog box widget. These constraint values are
used only for dialog boxes that have the DwtNunits attribute set to DwtFontUnits.
DwtNfontX Specifies the placement of the left hand side of the widget window in font units. The default is the value of DwtNx.
DwtNfontY Specifies the placement of the top of the widget window in font units. The default is the value of DwtNy.
Return Values
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 the callbacks associated with DwtDi-
alogBoxCreate, the reason member can be set to:
DwtCRFocus The dialog box has
received the input focus.
DwtCRHelpRequested The user has selected
Help.
For the callbacks associated with DwtDialogBoxPopupCreate, the reason member can be set to:
DwtCRMap The dialog box is about
to be mapped.
DwtCRUnmap The dialog box is about
to be unmapped.
DwtCRFocus The dialog box has
received the input focus.
DwtCRHelpRequested The user has selected
Help.
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
DwtDialogBox(3Dwt)