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

_____________________________________________________XawPlus

The IconList 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.

Since release 3.0 of XawPlus, this widget is only a IconList compatible mapping to the List widget. Programmers may use IconList as in previous versions for the future but a List widget will be created.

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:

IconList Actions

The IconList 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 IconList Widget:

<Btn1Down>,<Btn1Up>

Set(), Notify()

The full list of actions supported by IconList widget is:

IconList Callbacks

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

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

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 XawIconListChange():

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

w	Specifies the IconList widget.
list	Specifies the new list for the IconList 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 IconList widget.
longest	Specifies the length of the longest item in the list in pixels. If a value less than 1 is specified, the IconList 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.

An XawIconList entry 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;

Highlighting an Item

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

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

w	Specifies the IconList 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 XawIconListHighlight() 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 XawIconListUnhighlight():

void XawIconListUnhighlight(w)
Widget w;

w	Specifies the IconList widget.

Retrieving the Currently Selected Item

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

XawIconListReturnStruct *XawIconListShowCurrent(w)
Widget w;

w	Specifies the IconList widget.

XawIconListShowCurrent() returns a pointer to an XawIconListReturnStruct 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_____________________________________________________