NAME

List widget − widget for managing row-column geometry. 

SYNOPSIS

Public Headers:<X11/StringDefs.h> <X11/Xaw/List.h>

Private Header:<X11/Xaw/ListP.h>

Class Name:List

Class Pointer:listWidgetClass

Instantiation:widget = XtCreateWidget(name, listWidgetClass, ...) 

CLASS HIERARCHY

Core → Simple → List

DESCRIPTION

The List widget is a rectangle that contains a list of strings formatted into rows and columns.  When one of the strings is selected, it is highlighted, and an application callback routine is invoked.  Only one string may be selected at a time. 

RESOURCES

When creating a List widget instance, the following resources are retrieved from the argument list or from the resource database:

The new resources associated with the List widget are:

XtNcallback
All functions on this list are called whenever the notify action is invoked. 

XtNrowSpacing

XtNcolumnSpacing
Specify the amount of space between each of the rows and columns in the list.

XtNdefaultColumns
Specifies the default number of columns, which is used when neither the width nor the height of the List widget is specified or when XtNforceColumns is True. 

XtNforceColumns
Specifies that the default number of columns is to be used no matter what the current size of the List widget is.

XtNfont
Specifies the font to be used to display the list.

XtNforeground
Specifies a pixel value that indexes the widget’s colormap in order to derive the color to be used to paint the text of the list elements.

XtNinternalHeight
Represents a margin, in pixels, between the top and bottom of the list and the edges of the List widget.

XtNinternalWidth
Represents a margin, in pixels, between the left and right edges of the list and the edges of the List widget.

XtNlist
Specifies the array of text strings that is to be displayed in the List widget. If the default for XtNnumberStrings is used, the list must be NULL-terminated.  If a value is not specified for the list, the number of strings is set to 1, and the name of the widget is used as the list. 

XtNlongest
Specifies the length, in pixels, of the longest string in the current list.  If the client knows the length, it should specify it; otherwise, the List widget computes a default length by searching through the list. If this resource is incorrectly specified, selection of list items may not work properly.

XtNnumberStrings
Specifies the number of strings in the current list. If a value is not specified, the list must be NULL-terminated. 

XtNpasteBuffer
If this is True, then the value of the string selected will be put into X cut buffer 0. 

XtNverticalList
If this is True, the elements in the list are arranged vertically; if False, the elements are arranged horizontally. 

TRANSLATIONS AND ACTIONS

The List widget has three predefined actions:  Set, Unset, and Notify.  Set and Unset allow switching the foreground and background colors for the current list item.  Notify allows processing application callbacks. 

The following is the default translation table used by the List widget: <Btn1Down>,<Btn1Up>: Set() Notify()

CALLBACK STRUCTURES

•The List widget supports two callback lists:

−XtNdestroyCallback

−XtNcallback

The notify action executes the callbacks on the XtNcallback list.  The call_data argument passed to callbacks on the XtNcallback list is a pointer to an XtListReturnStruct structure, defined in <X11/Xaw/List.h>: typedef struct _XtListReturnStruct {  String string; /∗ string shown in the list ∗/  int index; /∗ index of the item selected ∗/ } XtListReturnStruct;

PUBLIC FUNCTIONS

•To change the list of strings that is displayed, use: void XawListChange(w, list, nitems, longest, resize)
     Widget w;
     String ∗ list;
     int nitems, longest;
     Boolean resize; where:

wSpecifies the widget ID. 

listSpecifies the new list for the List widget to display. 

nitemsSpecifies the number of items in the list.  If a value less than 1 is specified, the list must be NULL-terminated, and the List widget calculates the number for you. 

longestSpecifies the length of the longest item in the list in pixels.  If a value less than 1 is specified, the List widget calculates the value for you. 

resizeSpecifies a Boolean value that indicates whether the List widget should try to resize itself (True) or not (False) after making the change.  Note that the constraints of the parent of the List widget are always enforced, regardless of the value specified. 

Note that XawListChange() will Unset all list elements that are currently Set before the list is actually changed, and will reset the XtNlongest resource.  The list is used in place, and it must remain usable either for the lifetime of the List widget or until the list has been changed again with this function or with XtSetValues(). 

•To highlight an item in the list, use: void XawListHighlight(w, item);
     Widget w;
     int item; where:

wSpecifies the widget ID. 

itemSpecifies the 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 immediately unhighlighted and the new item is highlighted. 

•To unhighlight the currently highlighted item in the list, use: void XawListUnhighlight(w);
     Widget w; where w specifies the widget ID. 

•To retrieve an item in the list, use: XtListReturnStruct ∗XtListShowCurrent(w);
     Widget w; where w specifies the widget ID. 

•The XawListShowCurrent() function returns a pointer to an XawListReturnStruct structure that contains the currently highlighted item.  If the value of the index member is XT_LIST_NONE, the string member is undefined, which indicates that no item is currently selected.