Name

DwtListBox, DwtListBoxCreate − Creates a list box widget for the application to display large numbers of item choices or entries in a list format. 

Syntax

Widget DwtListBox(parent_widget, name, x, y,
                  items, item_count, visible_items_count,
                  callback, help_callback, resize, horiz)
     Widget parent_widget;
     char *name;
     Position x, y;
     DwtCompString *items;
     int item_count, visible_items_count;
     DwtCallbackPtr callback, help_callback;
     Boolean resize;
     Boolean horiz;

Widget DwtListBoxCreate (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. 

itemsSpecifies the list of items to be displayed by the list box widget.  The list of items must be unique.  This argument sets the DwtNitems attribute associated with DwtListBoxCreate. 

item_countSpecifies the total number of items in the list.  This argument sets the DwtNitemsCount associated with DwtListBoxCreate. 

visible_items_count
Specifies the maximum number of visible items contained in the list box. For example, if DwtNitemsCount is 20, but DwtNvisibleItemsCount is 5, only 5 items are visible at any one time.  This argument sets the DwtNvisibleItemsCount attribute associated with DwtListBoxCreate. 

callbackSpecifies the callback function or functions called when single callback, single confirm callback, extend callback, and extend confirm callback functions are activated.  This argument sets the DwtNsingleCallback, DwtNsingleConfirmCallback, DwtNextendCallback, and DwtNextendConfirmCallback attributes associated with DwtListBoxCreate. 

help_callbackSpecifies the callback function or functions called when a help request is made.  This argument sets the DwtNhelpCallback common widget attribute. 

resizeSpecifies a boolean value that, when True, indicates the list box increases its width to accommodate items too wide to fit inside the box.  If False, the width remains constant unless the caller changes the width by calling XtSetValues.  If you set DwtNresize to False, it is recommended that you set DwtNhorizontal to True.  This argument sets the DwtNresize attribute associated with DwtListBoxCreate. 

horizSpecifies a boolean value that, when True, indicates the list box contains a horizontal scroll bar.  If False, the list box does not contain a horizontal scroll bar.  A horizontal scroll bar cannot be deleted or added to a list box after the list box is created.  This argument sets the DwtNscrollHorizontal attribute associated with DwtListBoxCreate. 

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 DwtListBox and DwtListBoxCreate functions create an instance of a list box widget and return its associated widget ID.  The list box widget is a composite widget that consists of a list box, a menu with gadgets, and scroll bars. 

Inherited Attributes

Widget-Specific Attributes

DwtNmarginWidth
Specifies the number of pixels between the border of the widget window and the items. This attribute sets the list box menu margin width.

DwtNmarginHeight
Specifies the number of pixels between characters of each pair of consecutive items. This attribute sets the list box menu margin height.

DwtNspacingSpecifies in pixels the spacing between list box entries. 

DwtNitemsSpecifies the list of items to be displayed by the list box widget.  The list of items must be unique.  When modifying DwtNitems, always update DwtNitemsCount and DwtNselectedItemsCount.  When DwtNitems is NULL, DwtNitemsCount and DwtNselectedItemsCount must be zero. 

DwtNitemsCountSpecifies the total number of items in the list.  When DwtNitemsCount is zero, DwtNitems does not have to be NULL.  The list box widget uses DwtNitemsCount and DwtNselectedItemsCount, not DwtNitems, to determine if the list contains any items.  Therefore, you must specify DwtNitemsCount whenever you modify DwtNitems. 

DwtNselectedItems
Specifies the list of items that are selected in the list box. The last selected item is visible in the list box.

DwtNselectedItemsCount
Specifies the number of items selected in the list box. When DwtNselectedItemsCount is zero, DwtNselectedItems does not have to be NULL.  The list box uses DwtNselectedItemsCount not DwtNselectedItems to determine if the list contains any selected items.  Therefore, you must specify DwtNselectedItemsCount whenever you modify DwtNselectedItems. 

DwtNvisibleItemsCount
Specifies the maximum number of visible items contained in the list box. For example, if DwtNitemsCount is 20, but DwtNvisibleItemsCount is 5, only 5 items are visible at any one time. 

The list box widget is designed so that its height is based on DwtNvisibleItemsCount.  Therefore, it is preferable to control the list box height by using DwtNvisibleItemsCount rather than DwtNheight. 

Applications that control list box height through the core attribute DwtNheight are responsible for handling font changes. 

DwtNsingleSelection
Specifies a boolean value that, when True, indicates only one item can be selected at a time. 

DwtNresizeSpecifies a boolean value that, when True, indicates the list box increases its width to accommodate items too wide to fit inside the box.  If False, the width remains constant unless the caller changes the width by calling XtSetValues.  If you set DwtNresize to False, it is recommended that you set DwtNhorizontal to True. 

DwtNhorizontalSpecifies a boolean value that, when True, indicates the list box contains a horizontal scroll bar.  If False, the list box does not contain a horizontal scroll bar.  A horizontal scroll bar cannot be deleted or added to a list box after the list box is created. 

DwtNsingleCallback
Specifies the callback function or functions called when the user selects a single item by clicking MB1 on a single item. For this callback, the reason is DwtCRSingle. 

DwtNsingleConfirmCallback
Specifies the callback function or functions called when the user double clicked MB1 on an item. For this callback, the reason is DwtCRSingleConfirm. 

DwtNextendCallback
Specifies the callback function or functions called when the user single clicks MB1 while depressing the Shift key when more than one item is selected (multiple selection callback). See the DwtNsingleSelection attribute.  For this callback, the reason is DwtCRExtend. 

DwtNextendConfirmCallback
Specifies the callback function or functions called when the user double clicks MB1 while depressing the Shift key when more than one item is selected (multiple selection callback). See the DwtNsingleSelection attribute.  For this callback, the reason is DwtCRExtend. 

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 item;
int item_length;
int item_number;
} DwtListBoxCallbackStruct;

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 item member is set to the last item selected when the callback occurred.  Note that only the last item, not all selected items, is returned.  The item_length member is set to the selected item’s length when the callback occurred.  The item_number member is set to the item’s position in the list box when the callback occurred.  The first position is one, not zero. 

See Also

Guide to the XUI Toolkit: C Language Binding
Guide to the XUI Toolkit Intrinsics: C Language Binding