DwtListBox(3Dwt) DwtListBox(3Dwt)
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.
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.
items Specifies 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_count
Specifies 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 DwtNvisi-
bleItemsCount is 5, only 5 items are visible at any one time. This argument sets the DwtNvisibleItemsCount attribute associated
with DwtListBoxCreate.
callback Specifies 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, DwtNextendCall-
back, and DwtNextendConfirmCallback attributes associated with DwtListBoxCreate.
help_callback
Specifies the callback function or functions called when a help request is made. This argument sets the DwtNhelpCallback common
widget attribute.
resize Specifies 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.
horiz Specifies 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 cre-
ated. 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
-------------------------------------------------------------------------
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 the longest
item without exceeding
the size of its parent
DwtNheight Dimension Set as large as neces-
sary to hold the number
of items specified by
DwtNvisibleItemsCount,
without exceeding the
size of the parent wid-
get
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
Common Attributes
DwtNforeground Pixel Default foreground color
DwtNhighlight Pixel Default foreground color
DwtNhighlightPixmap Pixmap NULL
DwtNuserData Opaque * NULL
DwtNdirectionRToL unsigned char DwtDirectionRightDown
DwtNfont NOT SUPPORTED
DwtNhelpCallback NOT SUPPORTED
Scroll Window Attributes
DwtNhorizontalScrollBar Widget NULL
DwtNverticalScrollBar Widget NULL
DwtNworkWindow Widget NULL
DwtNshownValueAutomaticHoriz Boolean True
DwtNshownValueAutomaticVert Boolean False
-------------------------------------------------------------------------
Widget-Specific Attributes
--------------------------------------------------------------
Attribute Name Data Type Default
--------------------------------------------------------------
DwtNmarginWidth Dimension 10 pixels
DwtNmarginHeight Dimension 4 pixels
DwtNspacing Dimension 1 pixel
DwtNitems DwtCompString * NULL
DwtNitemsCount int Zero
DwtNselectedItems DwtCompString * NULL
DwtNselectedItemsCount int Zero
DwtNvisibleItemsCount int As many items
as can fit in
the core
attribute
DwtNheight.
The minimum is
1.
DwtNsingleSelection Boolean True
DwtNresize Boolean True
DwtNhorizontal Boolean False
DwtNsingleCallback DwtCallbackPtr NULL
DwtNsingleConfirmCallback DwtCallbackPtr NULL
DwtNextendCallback DwtCallbackPtr NULL
DwtNextendConfirmCallback DwtCallbackPtr NULL
--------------------------------------------------------------
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.
DwtNspacing Specifies in pixels the spacing between list box entries.
DwtNitems Specifies the list of items to be displayed by the list box widget. The list of items must be unique. When modifying Dwt-
Nitems, always update DwtNitemsCount and DwtNselectedItemsCount. When DwtNitems is NULL, DwtNitemsCount and DwtNselecte-
dItemsCount must be zero.
DwtNitemsCount Specifies 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 DwtNvis-
ibleItemsCount 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 con-
trol 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.
DwtNresize Specifies 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.
DwtNhorizontal Specifies 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:
DwtCRSingle The user selected a sin-
gle item in the list by
clicking MB1 on the item.
DwtCRSingleConfirm The user selected a sin-
gle item in the list and
confirmed another action
to be taken (by a call-
back) by double clicking
on an item. For example,
a double click on a file
in the file selection box
selects that file and
confirms another action
to be taken.
DwtCRExtend The user selected an item
(by clicking MB1 on a
single item while
depressing the shift key)
while there is at least
one other selected item.
The user clicked MB1 once
while pressing the Shift
key on an item when more
than one is selected
(multiple selection call-
back).
DwtCRExtendConfirm The user selected an item
and confirmed another
action to be taken (by
double clicking MB1 on a
single item while
depressing the Shift key)
while there is at least
one other selected item.
This reason applies only
if DwtNsingleSelection is
True.
DwtCRHelpRequested The user 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.
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
DwtListBox(3Dwt)