http://invisible-island.net/athena_widgets/XawPlus

_________________________________________________________XawPlus

The List Widget

The List widget contains a list of strings and/or bitmaps formatted into rows and columns. When one of the strings is selected, it is highlighted, and the List widget's Notify action is invoked, calling all routines on its callback list. Only one string may be selected at a time.

Differences between Xaw and XawPlus

Since the 3D extensions of Simple are inserted, the List widget has the additional resources highlightColor, shadowColor and buttonBorderWidth. The default background color is now grey75.

With Release 3.0 of XawPlus the List widget also has support for lists with an additional icon on the left side like the IconList widget in previous versions of XawPlus. To display icons and text in the list, the XawIconList structure is used, which contains pointer to strings and icons defined by the application programmer.

Resources

When creating a List widget instance, the following resources are retrieved from the argument list of XtSetValues() or XtVaSetValues() or from the resource database:

List Actions

The List widget supports the following actions:

• Highlighting and unhighlighting the list element under the pointer with Set and Unset.
• Processing application callbacks with Notify.

The following is the default translation table used by the List Widget:

<Btn1Down>,<Btn1Up>

Set(), Notify()

The full list of actions supported by List widget is:

List Callbacks

All procedures on the List widget's callback list will have a XawListReturnStruct passed to them as call_data. The structure is defined in the List widget's application header file.

typedef struct _XawListReturnStruct
{
        String string;  /* string shown in the list. */
        int list_index; /* index of the item selected. */

}
XawListReturnStruct;

The list_index item used to be called simply index. Unfortunately, this name collided with a global name defined on some operating systems, and had to be changed.

Changing the List

To change the list that is displayed, use XawListChange():

void XawListChange(w, list, nitems, longest, resize)
Widget w;
String * list;
int nitems, longest;
Boolean resize;

w	Specifies the List widget.
list	Specifies the new list for the List widget to display.
nitems	Specifies the number of items in the list. If a value less than 1 is specified, list must be NULL terminated, and the number of items will be calculated by the List widget.
longest	Specifies the length of the longest item in the list in pixels. If a value less than 1 is specified, the List widget will calculate the value.
resize	Specifies a Boolean value that if True indicates that the List widget should try to resize itself after making the change. The constraints of the List widget's parent are always enforced, regardless of the value specified here.

Changing the Icon List

To change the list that is displayed, use XawIconListChange():

void XawIconListChange(w, list, nitems, longest, resize)
Widget w;
XawIconList *list;
int nitems, longest;
int width, height, depth;
Boolean resize;

w	Specifies the List widget.
list	Specifies the new list for the List widget to display.
nitems	Specifies the number of items in the list. If a value less than 1 is specified, list must be NULL terminated, and the number of items will be calculated by the List widget.
longest	Specifies the length of the longest item in the list in pixels. If a value less than 1 is specified, the List widget will calculate the value.
width, height	Specifies the width and height of your bitmap or pixmap icons. These values are used to reserve enough space for the icons in the list entries.
iconDepth	Use the value of 1 for traditional XBM bitmap icons or the depth of your pixmaps for color icons like XPMs.
resize	Specifies a Boolean value that if True indicates that the IconList widget should try to resize itself after making the change. The constraints of the IconList widget's parent are always enforced, regardless of the value specified here.

The IconList has the following structure:

typedef struct _XawIconList
{
        Pixmap bitmap;          /* the icon, used as left bitmap */
        Pixmap clipMask;        /* drawing mask for the icon */
        String string;          /* text for the list entry */
}
XawIconList;

It is not required to set all entries of the structure. Unused entries of the type Pixmap has to be initialized with XtUnspecifiedPixmap and unused strings with NULL.

Highlighting an Item

To highlight an item in the list, use XawListHighlight():

void XawListHighlight(w, item)
Widget w;
int item;

w	Specifies the List widget.
item	Specifies an index into the current list that indicates the item to be highlighted.

Only one item can be highlighted at a time. If an item is already highlighted when XawListHighlight() is called, the highlighted item is unhighlighted before the new item is highlighted.

Unhighlighting an Item

To unhighlight the currently highlighted item in the list, use XawListUnhighlight():

void XawListUnhighlight(w)
Widget w;

w	Specifies the List widget.

Retrieving the Currently Selected Item

To retrieve the list element that is currently set, use XawListShowCurrent().

XawListReturnStruct *XawListShowCurrent(w)
Widget w;

w	Specifies the List widget.

XawListShowCurrent() returns a pointer to an XawListReturnStruct structure, containing the currently highlighted item. If the value of the index member is XAW_LIST_NONE, the string member is undefined, and no item is currently selected.

XawPlus_________________________________________________________