Volume 6A: Motif Programming Manual

XmListDeleteItemsPos() deletes item_count items from the List starting at position.

XmListDeletePositions() deletes the item at each position specified in pos_list until item_count has

been reached. This routine is new in Motif 1.2.

You can delete all of the items in a List widget using XmListDeleteAllItems(). This routine takes the

following form:

void

XmListDeleteAllItems(list_w)

Widget list_w;

13.3.5 Selecting Items

Since the main purpose of the List widget is to allow a user to make a selection from a set of choices, one of the most

important tasks for the programmer is to determine which items have been selected by the user. In this section, we

present an overview of the resources and functions available to set or get the actual items that are selected in the List

widget. Later in Section #slistcb, we discuss how to determine the items that are selected by the user when they are

selected. The resources and functions used to set and get the selected items in the List widget are directly analogous to

those that set the actual items in the list. Just as XmNitems represents the entire list, the XmNselectedItems

resource represents the list of selected items. The XmNselectedItemCount resource specifies the number of

items that are selected.

There are convenience routines that allow you to modify the items that are selected in a List. The functions

XmSelectItem() and XmSelectPos() can be used to select individual items. These functions take the

following form:

void

XmListSelectItem(list_w, item, notify)

Widget list_w;

XmString item;

Boolean notify;

void

XmListSelectPos(list_w, position, notify)

Widget list_w;

int position;

Boolean notify;

These functions cause the specified item to be selected. If you know the position in the list of the item to be selected,

you should use XmListSelectPos() rather than XmListSelectItem(). The latter routine uses a linear search

to find the specified item. The search can take a long time in a large list, which can affect performance if you are

performing frequent list operations.

When the specified item is selected, any other items that have been previously selected are deselected, except when

XmNselectionPolicy is set to XmMULTIPLE_SELECT. In this case, the specified item is added to the list of

selected items. Even though the extended selection policy allows multiple items to be selected, the previous selection

is deselected when one of these routines is called. If you want to add an item to the list of selected items in an

extended selection list, you can set the selection policy to XmMULTIPLE_SELECT, use one of the routines, and then

set the selection policy back to XmEXTENDED_SELECT.

The notify parameter indicates whether or not the callback routine for the List widget should be called. If your

callback routine does special processing of list items, then you can avoid having redundant code by passing True. As

a result, the callback routine is called just as if the user had made the selection himself. If you are calling either of

13 The List Widget 13.3.5 Selecting Items

353

these functions from the callback routine, you probably want to pass False to avoid a possible infinite loop.

There are no functions available for selecting multiple items at the same time. To select multiple items, use

XtVaSetValues() and set the XmNselectedItems and XmN-selectedItemCount resources to the entire

list of selected items. Another alternative is to follow the suggestion made earlier and temporarily set

XmNselectionPolicy to XmMULTIPLE_SELECT. You can call the above routines repeatedly to select the

desired items individually and then set the selection policy back to XmEXTENDED_SELECT.

Items can be deselected in the same manner that they are selected using XmListDeselectItem() and

XmListDeselectPos(). These functions take the following form:

void

XmListDeselectItem(list_w, item)

Widget list_w;

XmString item;

void

XmListDeselectPos(list_w, position)

Widget list_w;

int position;

These routines modify the list of selected items, but they do not have a notify parameter, so they do not invoke the

callback routine for the List. You can deselect all items in the list by calling XmListDeselectAllItems(),

which takes the following form:

void

XmListDeselectAllItems(list_w)

Widget list_w;

There are also convenience routines that allow you to check on the selected items in a List. You can use

XmListPosSelected() to determine whether an item is selected. This routine in new in Motif 1.2; it takes the

following form:

Boolean

XmListPosSelected(list_w, position)

Widget list_w;

int position;

The routine returns True if the item at the specified position is selected and False otherwise. You can get the

positions of all of the selected items in a List using XmListGetSelectedPos(), which takes the following form:

Boolean

XmListGetSelectedPos(list_w, pos_list, pos_cnt)

Widget list_w;

int **pos_list;

int *pos_cnt;

The use of this function is identical to that of XmListGetMatchPos(). The pos_list parameter is allocated to

contain the array of positions of selected items and the number of items selected is returned in pos_cnt. When you

are done using pos_list, you should free it using XtFree(). The function returns False if there are no selected

items in the List or if memory cannot be allocated for pos_list. In these cases, pos_list does not point to

allocated space and should not be referenced or freed and the value of pos_cnt is not specified.

13 The List Widget 13.3.5 Selecting Items

354