The List Widget
Author: Roland Krause 2002, roland_krause@freenet.de
Description: Documentation to XawPlus

### _________________________________________________________XawPlus

### The List Widget

Application Header file Class Header file Class Class Name Superclass | <X11/XawPlus/List.h> <X11/XawPlus/ListP.h> ListWidgetClass List Simple

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:

Name | Class | Type | Default Value
OBJECT: |  |  |
destroyCallback | Callback | Pointer | NULL
RECTANGLE: |  |  |
borderWidth height sensitive width x y | BorderWidth Height Sensitive Width Position Position | Dimension Dimension Boolean Dimension Position Position | 0 12 True 12 0 0
CORE: |  |  |
border background mappedWhenManaged | BorderColor Background MappedWhenManaged | Pixel Pixel Boolean | XtDefaultForeground grey75 True
SIMPLE: |  |  |
cursor cursorName pointerColor pointerColorBackground insensitiveBorder international highlightColor shadowColor buttonBorderWidth | Cursor Cursor Foreground Background Insensitive International Background Background Width | Cursor String Pixel Pixel Pixmap Boolean Pixel Pixel Dimension | None NULL XtDefaultForeground XtDefaultBackground NULL False grey90 grey40 2
LIST: |  |  |
callback pasteBuffer foreground font fontSet internalHeight internalWidth defaultColumns columnSpacing rowSpacing forceColumns verticalList list iconList longest numberStrings iconHeight iconWidth iconDepth | Callback Boolean Foreground Font FontSet Height Width Columns Spacing Spacing Columns Boolean List List Longest NumberStrings Height Width Depth | XtCallbackList Boolean Pixel XFontStruct * FontSet Dimension Dimension int Dimension Dimension Boolean Boolean String * XawIconList[] int int Dimension Dimension Dimension | NULL False XtDefaultForeground XtDefaultFont XtDefaultFontSet 2 4 2 6 4 False False NULL NULL 0 0 0 0 1

callback | All functions on this list are called whenever the notify action is invoked. The call_data argument contains information about the element selected and is described in detail in the List Callbacks section.
pasteBuffer | If this resource is set to True then the name of the currently selected list element will be put into CUT_BUFFER_0.
foreground | A pixel value which indexes the widget's colormap to derive the color used to paint the text of the list elements.
font | With this resource it is possible to set any available font to display the list text.
fontset | A set of fonts which will be used, if the international resource is set.
internalHeight, internalWidth | The margin, in pixels, between the edges of the list and the corresponding edge of the List widget's window.
defaultColumns | The default number of columns. This value is used when neither the width nor the height of the List widget is specified or when forceColumns is True.
columnSpacing rowSpacing | The amount of space, in pixels, between each of the rows and columns in the list.
forceColumns | Forces the default number of columns to be used regardless of the List widget's current size.
verticalList | If this resource is set to True then the list elements will be presented in column major order.
list | An array of text strings displayed in the List widget, if there is no iconList defined. If it exists, the iconlist is used with a higher priority. If numberStrings is zero (the default) then the list must be NULL terminated. If a value is not specified for the list, then numberStrings is set to 1, and the name of the widget is used as the list, and longest is set to the length of the name of the widget. The list is used in place, and must be available to the List widget for the lifetime of this widget, or until it is changed with XtSetValues() or XawListChange(). Note that XtSetValues() only works well, if the memory location of the list structure changes. It is a good idea to use always XawListChange(). This function also overrides the higher priority of the iconList resource, if you want to change from an icon list to a simple list while runtime.
iconList | An array of text strings and icons displayed in the List widget. If numberStrings is zero (the default) then the iconList must be NULL terminated. If a value is not specified for the iconList, then the list resource is used. The iconList must be available to the List widget for the lifetime of this widget, or until it is changed with XtSetValues() or better with XawIconListChange(). Note that XtSetValues() only works well, if the memory location of the list structure changes. It is a good idea to use always XawIconListChange().
longest | Specifies the width, in pixels, of the longest string in the current list. The List widget will compute this value if zero (the default) is specified. If this resource is not correctly specified, selection of list items may not work properly.
numberStrings | The number of strings in the current list. If a value of zero (the default) is specified, the List widget will compute it. When computing the number of strings the List widget assumes that the list is NULL terminated.
iconHeight, iconWidth | Set this resources to the width and height of your bitmap or pixmap icons. iconWidth and iconHeight are used to reserve enough space 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.

### 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:

Set() | Sets the list element that is currently under the pointer. To inform the user that this element is currently set, it is drawn with is foreground and background colors reversed. If this action is called when there is no list element under the cursor, the currently set element will be unset.
Unset() | Cancels the set state of the element under the pointer, and redraws it with normal foreground and background colors.
Notify() | Calls all callbacks on the List widget's callback list. Information about the currently selected list element is passed in the call_data argument (see List Callback below).

### 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_________________________________________________________