The List widget allows selection from a variety of specified items. The List widget is actually one of the component widgets in the FileSelectionBox widget(Chapter 9).
The use of a List is similar to that of a Menu, but is a little more flexible:
An example of a List Widget is shown in Fig. 11.1.
Fig. 11.1 Output of list.c
To create a simple list use: XtVaCreateManagedWidget(), and specify
xmListWidgetClass as the widget type (or use
XmCreateList(). The header file <Xm/List.h>
must be included. We will
usually want to create a ScrolledList. To do this use:
XmCreateScrolledList().
There are a number of useful resources:
<Xm/List.h>
). Only one item may be selected.
As the name of this widget implies, the List is a dynamic structure that can grow or shrink as items are added or deleted.
To add an item to a list, use the function XmListAddItem() , which takes 3 arguments:
Another function XmListAddItemUnselected() has exactly the same syntax as XmListAddItem(), above. This function will guarantee that an item is not selected when it is added. This is not always the case with the XmListAddItem(), since selection will be dependent on the currently selected list index.
To remove a single named (XmString) item, str, from a
List widget, use the
XmListDeleteItem(Widget List, XmString
str) function.
To remove a number of named (XmString) items, use the
XmListDeleteItems(Widget List, XmString *del_items)
function where the second argument, del_items, is an array of
XmStrings that contain the names of items being deleted.
If you know the position of item(s) in a List, as opposed to their names, you can use the following functions:
To delete all items form a list, use XmListDeleteAllItems(Widget wid).
Two functions XmListSelectItem(Widget, XmString, Boolean) and
XmListSelectPos(Widget, int, Boolean) may be used to select an
item from within a program.
The Boolean value, if set to True, will call the callback function associated with the particular List.
To deselect items use XmListDeselectItem(Widget, XmString),
XmListDeselectPos(Widget, int) or XmListDeselectAllItems(Widget).
The operation of which is similar to corresponding delete functions.
Since the List is dynamic we may need to know how long the list is, and which items are currently selected etc.. Some of these values can be obtained from the callback structure of a list (see Section11.3 below). However, if no callback has been invoked the programmer may sometimes still need to access this information.
The List resources are updated automatically (by default callback resources) so all we need to do is to XtGetValues() (or something similar) for the resource we want. For example:
Obtain the value of the resource XmNitemCount.
Arg args[1]; /* Arg array */ int n = 1; /* number arguments */ int list_size; /* value to store XtGetValue() request */ ...... XtSetArg(args[0], XmNitemCount, &list_size); XtGetValues(list_wid, args, n); printf("The Size of the list = %d\n", list_size);
where list_wid is the List widget we request this information from.
Note: We pass the address of list_size to XtSetArg() since we need to specify a pointer to physical (program) memory in which to store the result. The value of list_size is available after the XtGetValues() call and is only accurate until the next user (or application) list addition/subtractions.
Obtain the value of the resource XmNselectedItemCount:
Arg args[1]; /* Arg array */ int n = 1; /* number arguments */ int select_count; /* value to store XtGetValue() request */ ...... XtSetArg(args[0], XmNselectedItemCount, &select_count); XtGetValues(list_wid, args, n); printf("The Numver of selected list items = %d\n", select_count);
Recall that the use of XtGetValue() is similar to that of
XtSetValue() (Chapter).
Default List callback functions facilitate common interaction with a List such as selection of an item (or multiple items) and addition or deletion of items. More importantly, related resource information is automatically updated ( e.g. the current List size, XmNitemCount). There is a List callback resource for each of the selection types (e.g. XmNsingleSelectionCallback ) and also a XmNdefaultActionCallback . The application programmer is free to add his own callback functions in the usual manner. In this case, the selection policy callback will be called first and then the default.
The Callback function has the usual form:
list_cbk(Widget w, XtPointer data, XmListCallbackStruct *cbk)
Elements of the XmListCallbackStruct include:
An example of the use of a List callback is given in the following list.c example program.
We create a simple list that shows a selection of colours. Selection of these
colours changes the background colour of the List widget.
#include <Xm/Xm.h> #include <Xm/List.h> /* Prototype Callback */ void list_cbk(Widget , XtPointer , XmListCallbackStruct *); String colours[] = { "Black", "Red", "Green", "Blue", "Grey"}; Display *display; /* xlib id of display */ Colormap cmap; main(int argc, char *argv[]) { Widget top_wid, list; XtAppContext app; int i, n = XtNumber(colours); XColor back, fore, spare; XmStringTable str_list; Arg args[4]; top_wid = XtVaAppInitialize(&app, "List_top", NULL, 0, &argc, argv, NULL, NULL); str_list = (XmStringTable) XtMalloc(n * sizeof (XmString *)); for (i = 0; i < n; i++) str_list[i] = XmStringCreateSimple(colours[i]); list = XtVaCreateManagedWidget("List", xmListWidgetClass, top_wid, XmNvisibleItemCount, n, XmNitemCount, n, XmNitems, str_list, XmNwidth, 300, XmNheight, 300, NULL); for (i = 0; i < n; i++) XmStringFree(str_list[i]); XtFree(str_list); /* background pixel to black foreground to white */ cmap = DefaultColormapOfScreen(XtScreen(list)); display = XtDisplay(list); XAllocNamedColor(display, cmap, colours[0], &back, &spare); XAllocNamedColor(display, cmap, "white", &fore, &spare); n = 0; XtSetArg(args[n],XmNbackground, back.pixel); ++n; XtSetArg(args[n],XmNforeground, fore.pixel); ++n; XtSetValues(list, args, n); XtAddCallback(list, XmNdefaultActionCallback, list_cbk, NULL); XtRealizeWidget(top_wid); XtAppMainLoop(app); } /* called from any of the "Colour" list items. Change the color of the list widget. Note: we have to use dynamic setting with XtSetValues().. */ void list_cbk(Widget w, XtPointer data, XmListCallbackStruct *list_cbs) { int n =0; Arg args[1]; String selection; XColor xcolour, spare; /* xlib color struct */ /* list->cbs holds XmString of selected list item */ /* map this to "ordinary" string */ XmStringGetLtoR(list_cbs->item, XmSTRING_DEFAULT_CHARSET, &selection); if (XAllocNamedColor(display, cmap, selection, &xcolour, &spare) == 0) return; XtSetArg(args[n],XmNbackground, xcolour.pixel); ++n; /* w id of list widget passed in */ XtSetValues(w, args, n); }
Needs SOME