A scrolling list of text items
PtWidget → PtBasic → PtContainer → PtCompound → PtGenList → PtList
For more information, see the diagram of the widget hierarchy.
<photon/PtList.h>
The PtList class displays a scrolling list of text items. You can select one or more items, depending on the selection policy.
Lists are particularly useful for presenting a large or unknown number of textual items (e.g. a set of items changing over time). Lists have the added advantage of displaying the set of items currently selected, and allowing more than one item to be selected at once (see the Pt_ARG_SELECTION_MODE resource defined by PtGenList).
If the number of items is too large to display in the area allocated to the list, the widget can display a vertical scrollbar. You can use the inherited Pt_ARG_LIST_FLAGS resource to control when the scrollbar appears: always, never, or as required.
PtList widgets have a few limitations:
To display items in columns, you can:
Or
With both methods, use Tab characters in the item strings to separate the text for each column.
Even if you use columns, each line in the list remains a single item. When you click on any part of the line, the entire line is selected — having columns doesn't make the list into a spreadsheet. |
If you know the list of available choices when you create the list, you can specify it using the Pt_ARG_ITEMS resource. This resource takes an array of null-terminated strings.
You should establish the selection policy for the list when it's created. The resource that controls the selection policy is Pt_ARG_SEL_MODE.
The default selection policy is browse selection mode, which is the more user-friendly of the two selection modes that allow a single selection.
If the number of items in a widget is variable, or is known to be large, you should control the size of the widget by explicitly setting dimensions or limiting the number of items displayed.
If you ever need to get the items in a list, you can use some code like this:
PtArg_t args[1]; short *num, i; char **items = NULL; PtSetArg(&args[0], Pt_ARG_ITEMS, &items, &num); PtGetResources(list_wgt, 1, args); for (i = 0; i < *num; i++) printf("Item %d: %s\n", i, items[i]);
To control the number of visible items in the list widget, use the Pt_ARG_VISIBLE_COUNT resource. The number of visible items is the number of list items displayed in the list at any given time. If this number is less than the total number of items in the list, the list widget can add a vertical scrollbar so that you can scroll through the whole list.
If you specify it, the number of visible items is used to calculate the dimensions of the list (overriding any explicit dimensions specified in Pt_ARG_DIM).
The list widget uses the Pt_CB_SELECTION callback to notify your application whenever you make a new selection. The cbdata passed to the callback always contains a pointer to a PtListCallback_t structure. The selection policy in effect for the widget at the time of the callback determines which members of the structure are valid.
The mode member of the callback data structure indicates the selection mode that caused the callback to be invoked.
Single selection and browse selection modes let you select only a single item. In browse mode, the selection isn't made until you release the pointer button after dragging the pointer over the list items.
In either case, the selection callback is invoked when you make the selection. The following members of the callback data structure identify the item that you selected:
Multiple selection modes, including extended selection, let you select several items at once. When the selection callback is invoked, more than one item may have been added to the set of selected items.
The data passed to the callback function uses these members to identify the complete set of selected items:
Each index in the array refers to the original array of items maintained by the Pt_ARG_ITEMS resource.
Resource | C type | Pt type | Default |
---|---|---|---|
Pt_ARG_ITEMS | char *, short | Array | NULL |
Pt_ARG_LIST_BALLOON | PtListBalloonF_t * | Pointer | See below |
Pt_ARG_LIST_SPACING | short | Scalar | 0 |
Pt_ARG_MODIFY_ITEMS | PtListModifyItems_t | Struct | Write-only |
Pt_ARG_SELECTION_INDEXES | unsigned short, short | Array | NULL |
Pt_CB_LIST_INPUT | PtCallback_t * | Link | NULL |
Pt_CB_SELECTION | PtCallback_t * | Link | NULL |
C type | Pt type | Default |
---|---|---|
char *, short | Array | NULL |
An array of pointers to text items to be displayed in the list.
C type | Pt type | Default |
---|---|---|
PtListBalloonF_t * | Pointer | See below |
A function that inflates a balloon for the item the pointer is on. PtListBalloonF_t is a function type:
typedef PtWidget_t *PtListBalloonF_t( PtWidget_t *widget, PtWidget_t *parent, PhArea_t *area, PtListColumn_t const *col, int coln, const char *item, unsigned index, const char *font);
The arguments are as follows:
The default function does this:
return PtGenListCreateTextBalloon( widget, parent, PtGenListSetColumnBalloon ( area, col ), item, coln, font);
C type | Pt type | Default |
---|---|---|
short | Scalar | 0 |
The spacing, in pixels, between the items in the list.
C type | Pt type | Default |
---|---|---|
PtListModifyItems_t | Struct |
Used internally by the convenience functions.
C type | Pt type | Default |
---|---|---|
unsigned short, short | Array | NULL |
An array of indexes indicating which list items given by the Pt_ARG_ITEMS array are currently selected.
C type | Pt type | Default |
---|---|---|
PtCallback_t * | Link | NULL |
A list of PtCallback_t structures that define the callbacks that the widget invokes on each mouse and key event. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:
These callbacks should return Pt_CONTINUE.
C type | Pt type | Default |
---|---|---|
PtCallback_t * | Link | NULL |
A list of PtCallback_t structures that define the callbacks that the widget invokes whenever you select an item from the list. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:
The item member of the PtListCallback_t structure identifies the item that you just selected (or unselected in modes that let you unselect items by clicking on them). Depending on the selection mode used by the list, any previously selected items might or might not remain selected — check sel_items or sel_array. |
These callbacks should return Pt_CONTINUE.
If the widget modifies an inherited resource, the “Default override” column indicates the new value. This modification affects any subclasses of the widget.
Although this resource is inherited from PtGenList, it's used in a different way. For PtGenList, Pt_ARG_VISIBLE_COUNT is a read-only resource that tells you the number of visible items. For PtList, it can be set to number of items you want to display in the list. If it isn't specified, or is set to 0, the widget displays as many items as its specified dimensions allow.
For Pt_CB_DND callbacks for a PtList, the cbinfo->cbdata is a pointer to a PtListDndCallback_t structure, containing at least the following members:
If neither of these is set, the drop occurred inside the item.
The PtList widget defines the following convenience functions that make it easier to use the list once it's been created: