Volume 6A: Motif Programming Manual

A List widget is typically a child of a ScrolledWindow, so that the List is displayed with ScrollBars attached to it. The

selection mechanism for the List does not change, so the user can still select items as before, but the user can now use

the ScrollBars to adjust the items in the list that are visible.

The List widget supports four different selection policies:

In single selection mode, selecting an item toggles its selection state and deselects any other selected item.

Single selection Lists should be used when only one of many choices may be selected at a time, although

under this policy there may also be no items selected. Some possible uses for a single selection List include

choosing a font family or style for text input and choosing a color for a bitmap editor.

•

In browse selection mode, selecting a new item deselects any other selected item, but there can never be a

state where no items are selected. From the user's perspective, browse selection is similar to single selection,

except that there is an initial selected item. There are also differences with respect to callback routines. This

issue is addressed in Section #slistcb.

•

In multiple selection mode, any number of items can be selected at one time. When an item is selected, the

selection state of the item is toggled; the selection states of the rest of the items are not changed. The List can

be in a state where none of the items are selected or all of the items are selected. Multiple selection mode is

advantageous in situations where an action may be taken on more than one item at a time, such as in an

electronic mail application, where the user might choose to delete, save, or print multiple messages

simultaneously.

•

In extended selection mode, the user can select discontiguous ranges of items. This selection policy is an

extension of the multiple selection policy that provides more flexibility.

•

13.1 Creating a List Widget

Using List widgets is fairly straightforward. An application that uses the List widget must include the header file

<Xm/List.h>. This header file declares the types of the public List functions and the widget class name

xmListWidgetClass. A List widget can be created as shown in the following code fragment:

Widget list;

list = XtVaCreateManagedWidget ("name",

xmListWidgetClass, parent,

resource−value−list,

NULL);

the source code shows a program that creates a simple List widget. XtSetLanguageProc() is only available in

X11R5; there is no corresponding function in X11R4. XmStringCreateLocalized() is only available in Motif

1.2; XmStringCreateSimple() is the corresponding function in Motif 1.1.

/* simple_list.c −− introduce the List widget. Lists present

* a number of comound strings as choices. Therefore, strings

* must be converted before set in lists. Also, the number of

* visible items must be set or the List defaults to 1 item.

*/

#include <Xm/List.h>

char *months[] = {

"January", "February", "March", "April", "May", "June", "July",

"August", "September", "October", "November", "December"

};

main(argc, argv)

int argc;

13 The List Widget 13.1 Creating a List Widget

342

char *argv[];

{

Widget toplevel;

XtAppContext app;

int i, n = XtNumber (months);

XmStringTable str_list;

XtSetLanguageProc (NULL, NULL, NULL);

toplevel = XtVaAppInitialize (&app, "Demos", NULL, 0,

&argc, argv, NULL, NULL);

str_list = (XmStringTable) XtMalloc (n * sizeof (XmString));

for (i = 0; i < n; i++)

str_list[i] = XmStringCreateLocalized (months[i]);

XtVaCreateManagedWidget ("Hello",

xmListWidgetClass, toplevel,

XmNvisibleItemCount, n,

XmNitemCount, n,

XmNitems, str_list,

NULL);

for (i = 0; i < n; i++)

XmStringFree (str_list[i]);

XtFree (str_list);

XtRealizeWidget (toplevel);

XtAppMainLoop (app);

}

The program simply creates a List widget as the child of the toplevel widget. The List contains the names of the

months as its choices. The output of the program is shown in the figure.

Output of simple_list.c

13 The List Widget 13.1 Creating a List Widget

343

The selection policy of the List is controlled by the XmNselectionPolicy resource. The possible values for this

resource are:

XmSINGLE_SELECT

XmBROWSE_SELECT

XmMULTIPLE_SELECT

XmEXTENDED_SELECT

XmBROWSE_SELECT is the default selection policy for the List widget. Since this policy is the one that we want to

use, we do not need to set the XmNselectionPolicy resource. You should be aware that the user could change

this policy with a resource specification. If you want to enforce this selection policy, you can program defensively and

hard−code the value for XmNselectionPolicy, despite its default.

The program demonstrates the use of three basic elements of the List widget: the list of items, the number of items in

the list, and the number of visible items. Because the items in a List must be compound strings, each of the choices

must be converted from a C string to a compound string. The application allocates an array of XmStrings, creates a

compound string for each month name, and stores the string in the str_list. The List widget is created with

str_list as the value for the XmNitems resource and XmNitemCount is set to n.

Just like other widgets that use compound strings, the List widget copies the entire table of compound strings into its

own internal storage. As a result, the list of strings needs to be freed after you have used it to set the XmNitems

resource. When you set the items using this resource, you also need to set the XmNitemCount resource to specify

the number of items in the list. If this resource is not set, the List does not know how many items to copy. The value

of XmNitemCount should never be larger than the number of items in XmN-items. If the value for

XmNitemCount is less than the number of items, the additional items are not put in the list.

To retrieve the list of items, you can call XtVaGetValues() on these resources, as shown in the following code

fragment:

extern Widget list;

XmStringTable choices;

int n_choices;

XtVaGetValues (list,

XmNitems, &choices,

XmNitemCount, &n_choices,

NULL);

Since the items that the area returned are compound strings, you must convert them to C−style strings if you need to

use any of the standard C library functions to view or manipulate the strings. You can also use any of the compound

string functions described in Chapter 19, Compound Strings, for this purpose. Since we used XtVaGetValues()

to obtain the values for the resources, the returned data should, as always, be considered read−only. You should not

change any of the items in the list or attempt to free them (or the pointer to them) when you are done examining their

values.

the source code also makes use of the XmNvisibleItemCount resource, which sets the height of the list to match

the number of items that should be visible. If you want all the items to be visible, you simply set the value to the total

number of items in the list. Setting the visible item count to a higher value is acceptable, assuming that the list is

expected to grow to at least that size. If you want to set the number of visible items to be less than the number of items

actually in the list, you should use a ScrolledList as described in the next section.

13 The List Widget 13.1 Creating a List Widget

344