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.

nameSpecifies the name of the created widget. 

xSpecifies 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. 

ySpecifies, 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. 

titleSpecifies the text that appears in the banner of the selection box.  This argument sets the DwtNtitle attribute associated with DwtDialogBoxCreate. 

valueSpecifies the text in the text edit field.  This argument sets the DwtNvalue attribute associated with DwtSelectionCreate. 

itemsSpecifies the items in the selection widget’s list box.  This argument sets the DwtNitems attribute associated with DwtSelectionCreate. 

item_countSpecifies the number of items in the selection widget’s list box.  This argument sets the DwtNitemsCount associated with DwtSelectionCreate. 

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. 

styleSpecifies 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 position the widget.  This argument sets the DwtNdefaultPosition attribute associated with DwtDialogBoxCreate. 

callbackSpecifies 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 associated with DwtSelectionCreate. 

help_callbackSpecifies 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

Widget-Specific Attributes

DwtNlabelSpecifies the label to appear above the list box containing the items. 

DwtNvalueSpecifies the text in the text edit field. 

DwtNselectionLabel
Specifies the label above the selection text entry field.

DwtNokLabelSpecifies 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 reason 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.

DwtNitemsSpecifies the items in the selection widget’s list box. 

DwtNitemsCountSpecifies the number of items in the selection widget’s list box. 

DwtNmustMatchSpecifies 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:

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