DwtSelection(3Dwt) DwtSelection(3Dwt)
Name
DwtSelection, DwtSelectionCreate - Creates a selection box widget.
Syntax
Widget DwtSelection(parent_widget, name, x, y,
title, value, items,
item_count, visible_items_count, style,
default_position, callback, help_callback)
Widget parent_widget;
char *name;
Position x, y;
DwtCompString title;
DwtCompString value;
DwtCompString *items;
int item_count, visible_items_count;
int style;
Boolean default_position;
DwtCallbackPtr callback, help_callback;
Widget DwtSelectionCreate (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.
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 text that appears in the banner of the selection box. This argument sets the DwtNtitle attribute associated with
DwtDialogBoxCreate.
value Specifies the text in the text edit field. This argument sets the DwtNvalue attribute associated with DwtSelectionCreate.
items Specifies the items in the selection widget's list box. This argument sets the DwtNitems attribute associated with DwtSelection-
Create.
item_count
Specifies the number of items in the selection widget's list box. This argument sets the DwtNitemsCount associated with DwtSe-
lectionCreate.
visible_items_count
Specifies the number of items displayed in the selection widget's list box. This argument sets the DwtNvisibleItemsCount
attribute associated with DwtSelectionCreate.
style Specifies the style of the pop-up dialog box widget. You can pass DwtModal (modal) or DwtModeless (modeless). This argument
sets the DwtNstyle attribute associated with DwtDialogBoxPopupCreate.
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. This argument sets the DwtNdefaultPosition attribute associated with DwtDialogBoxCreate.
callback Specifies the callback function or functions called when the user makes or cancels a selection, or there is no match for the item
selected by the user. This argument sets the DwtNactivateCallback, DwtNcancelCallback, and DwtNnoMatchCallback attributes asso-
ciated with DwtSelectionCreate.
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
The DwtSelection and DwtSelectionCreate functions create an instance of a selection box widget and return its associated widget ID.
When calling DwtSelection, you set the selection box widget attributes presented in the formal parameter list. For DwtSelectionCreate,
however, you specify a list of attribute name/value pairs that represent all the possible selection box widget attributes. The selection
widget is a pop-up dialog box containing a label widget, a text entry widget holding the current value, a list box displaying the current
item list, and Ok and Cancel push buttons.
When realized, the selection widget displays the item list passed by the caller. The current value is displayed in the text entry field.
Users make selections by clicking the mouse in the list box or by typing item names in the text entry field. The selection widget does not
do file searches. To perform file searches, use DwtFileSelectionCreate.
Inherited Attributes
----------------------------------------------------------------------
Attribute Name Data Type Default
----------------------------------------------------------------------
Core Attributes
DwtNx Position Centered in the parent
window
DwtNy Position Centered in the parent
window
DwtNwidth Dimension The width of the list
box, plus the width of
the push buttons, plus
three times DwtNmargin-
Width. The list box
will grow to accommodate
items wider than the
title.
DwtNheight Dimension The height of the list
box, plus the height of
the text edit field,
plus the height of the
label, plus three times
DwtNmarginHeight.
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
Dialog Pop-Up Attributes
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 DwtModal
DwtNfocusCallback DwtCallbackPtr NULL
DwtNtextMergeTranslations XtTranslations NULL
DwtNmarginWidth Dimension 5 pixels
DwtNmarginHeight Dimension 5 pixels
DwtNdefaultPosition Boolean False
DwtNchildOverlap Boolean True
DwtNresize unsigned char DwtResizeGrowOnly
DwtNnoResize Boolean True (that is, no window
manager resize button)
DwtNtitle DwtCompString "Open"
DwtNmapCallback DwtCallbackPtr NULL
DwtNunmapCallback DwtCallbackPtr NULL
DwtNtakeFocus Boolean True for modal dialog
box
False for modeless dia-
log box
DwtNautoUnmanage Boolean True
DwtNdefaultButton Widget NULL
DwtNcancelButton Widget NULL
----------------------------------------------------------------------
Widget-Specific Attributes
----------------------------------------------------------
Attribute Name Data Type Default
----------------------------------------------------------
DwtNlabel DwtCompString "Items"
DwtNvalue DwtCompString ""
DwtNokLabel DwtCompString "Ok"
DwtNcancelLabel DwtCompString "Cancel"
DwtNactivateCallback DwtCallbackPtr NULL
DwtNcancelCallback DwtCallbackPtr NULL
DwtNnoMatchCallback DwtCallbackPtr NULL
DwtNvisibleItemsCount int 8
DwtNitems DwtCompString * NULL
DwtNitemsCount int Zero
DwtNmustMatch Boolean False
DwtNselectionLabel DwtCompString "Selection"
----------------------------------------------------------
DwtNlabel Specifies the label to appear above the list box containing the items.
DwtNvalue Specifies the text in the text edit field.
DwtNselectionLabel
Specifies the label above the selection text entry field.
DwtNokLabel Specifies the label for the Ok push button. If the label is a NULL string, the button is not displayed.
DwtNcancelLabel
Specifies the label for the Cancel push button. If the label is a NULL string, the button is not displayed.
DwtNactivateCallback
Specifies the callback function or functions called when the user makes a selection. For this callback, the reason is
DwtCRActivate.
DwtNcancelCallback
Specifies the callback function or functions called when the user clicks on the Cancel button. For this callback, the rea-
son is DwtCRCancel.
DwtNnoMatchCallback
Specifies the callback function or functions called when the user's selection does not have an exact match with any items in
the list box. This callback is activated only if DwtNmustMatch is True. For this callback, the reason is DwtCRNoMatch.
DwtNvisibleItemsCount
Specifies the number of items displayed in the selection widget's list box.
DwtNitems Specifies the items in the selection widget's list box.
DwtNitemsCount Specifies the number of items in the selection widget's list box.
DwtNmustMatch Specifies a boolean value that, when True, indicates that the selection widget checks whether the user's selection has an
exact match in the list box. If the selection does not have an exact match, the DwtNnoMatchCallback is activated. If the
selection has an exact match, the DwtNactivateCallback is activated.
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;
DwtCompString value;
int value_len;
} DwtSelectionCallbackStruct;
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:
DwtCRActivate The user activated the Ok
push button or double
clicked on an item that
has an exact match in the
list box.
DwtCRNoMatch The user activated the Ok
push button or double
clicked on an item that
does not have an exact
match in the list box.
DwtCRCancel The user activated the
Cancel button.
DwtCRHelpRequested The user selected help
somewhere in the file
selection box.
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. The value member is set to the current selection when the callback occurred. The value_len member is set to
the length of the selection compound-string.
See Also
Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding
DwtSelection(3Dwt)