PtList

A scrolling list of text items

Class hierarchy:

PtWidget --> PtBasic --> PtContainer --> PtCompound --> PtGenList --> PtList

For more information, see the diagram of the widget hierarchy.

PhAB icon:

Public header:

<photon/PtList.h>

Description:

The PtList class displays a scrolling list of text items. You can select one or more items, depending on the selection policy.

A PtList containing text items.

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.

Lists have a few limitations:

• They display only text. If you want to display an image to the left of each item, use a PtTree instead.
• All items are in the same font.
• All unselected items are the same color
• All selected items are the same color.

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.

To display items in columns, you can:

• Create a PtDivider widget as a child of the PtList. Put it at the top of the list, and create (for example) PtButton widgets as children of the divider, one for each column. The width of each button is the width of the column.

  Or

• Use the inherited Pt_ARG_LIST_COLUMN_POS resource.

With both methods, the Tab character is used in the item strings as a column separator.

Even if you use columns, each line in the list remains a single item. When you select any part of the line, the entire line is selected - having columns doesn't make the list into a spreadsheet.

The selection policy for the widget determines how the user will select choices from the list. Lists support the following selection policies:

Single selection

Only one item from the list may be selected at once. The user may change the currently selected item by pressing the pointer button when the pointer is over a different item. The application is then notified that the selection has been changed.

Browse selection

As with single selection, only one item may be selected and the current selection is changed by pressing the pointer button when the pointer is over an item. The user may drag the pointer with the button down, and the item under the pointer will be selected.

Multiple selection

Multiple selection allows several items to be selected at once. Apart from this, selection occurs in the same way as single selection.

Extended selection

Extended selection supports Click-Shift-click/drag and Ctrl-click combinations for selecting multiple items. To select all items between and including two items in a list, the user clicks on the first item, presses the Shift key, then clicks on or drags to any other item in the list. To select multiple disjoint items, the user holds down the Ctrl while clicking on selected items.

Range selection

Range selection allows multiple items to be selected in a range. Pressing the pointer button over an item defines the start of a range. Dragging the pointer extends the range of selections forward or backward to encompass the items the pointer passes over. Releasing the pointer button completes the range selection. The new range may replace the set of currently selected items, or extend it to contiguous items, depending on the state of the modifier keys when the pointer button was pressed.

A callback function notifies the application of selections. The callback function behaves in a different manner for each of the selection policies. See "Selection notification."

Creating lists

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]);

Controlling number of items displayed

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 scroll bar so the user can scroll through the whole list.

The Pt_ARG_VISIBLE_COUNT resource is inherited from PtGenList but is used differently. For PtGenList, Pt_ARG_VISIBLE_COUNT is a read-only resource that tells you the number of visible items. For PtList, it's the number of items you want to display.

If specified, the number of visible items will be used to calculate the dimensions of the list (if no explicit dimensions were given). If you give explicit dimensions of the widget, the number of visible items will be calculated based on those dimensions and the font metrics for the list font.

Using scrolled lists

As we saw previously, the list widget will create a scroll bar if the list's area isn't large enough to display all the items in the list. By default, the scroll bar will be displayed only when necessary. This behavior is controlled by the Pt_LIST_SCROLLBAR_ALWAYS and (the default) Pt_LIST_SCROLLBAR_AS_REQUIRED flags in the Pt_ARG_LIST_FLAGS resource.

Selection notification

The list widget uses the Pt_CB_SELECTION callback to notify your application whenever the user has made a new selection. This cbdata passed to the callback always contains a pointer to a PtListCallback_t structure. The selection policy in effect on the widget at the time of the callback determines which members of the structure are valid.

The mode member of the callback data structure contains the selection mode that caused the callback to be invoked. This member should be consulted to determine how to handle the callback.

Handling single selections

Single selection and browse selection modes allow only a single selection to be made. In browse mode, the selection isn't made until the user releases the pointer button after having dragged the pointer over the list items.

In either case, the selection callback is invoked when the selection is made. The single selected item is identified in the call data.

Three members of the callback data structure identify the item that was selected:

• item - the textual label for the selected item
• item_len - the size of the item's label, in bytes.
• item_pos - the index of the selected item in the array of items maintained by the Pt_ARG_ITEMS resource.

Handling multiple selections

Multiple selection modes, including extended selection, allow several items to be selected at once. When the selection callback is invoked, more than one item may have been added to the set of selected items. The call data passed to the callback function includes the complete set of selected items.

The set of selected items is provided by these members:

• sel_item_count - the number of currently selected items
• sel_array - an array of indices for each currently selected item.

Each index in the array refers to the original array of items maintained by the Pt_ARG_ITEMS resource.

Mouse actions

Mouse actions depend on the current selection mode.

Keyboard actions

Keyboard actions depend on the current selection mode.

New resources:

Pt_ARG_ITEMS

An array of pointers to text items to be displayed in the list.

Pt_ARG_LIST_BALLOON

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 parameters are as follows:

• widget-the PtList widget
• parent-its parent window
• area-a PhArea_t structure that covers the item. The area->pos member is relative to the parent window.
• col-the position of the column the pointer is on
• coln-the index of the column the pointer is on
• item-the item the pointer is on
• index-the index of item
• font-the widget's Pt_ARG_LIST_FONT resource

The default function does this:

return
    PtGenListCreateTextBalloon(
      widget, parent, 
      PtGenListSetColumnBalloon ( area, col ),
      item, coln, font);
      

Pt_ARG_LIST_SPACING

The spacing between the items in the list.

Pt_ARG_MODIFY_ITEMS

Used internally by the convenience functions.

Pt_ARG_SELECTION_INDEXES

An array of indexes indicating which list items given by the Pt_ARG_ITEMS array are currently selected.

Pt_CB_LIST_INPUT

A list of 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:

reason

The name of the callback resource (Pt_CB_LIST_INPUT) that caused this callback to be invoked.

reason_subtype

The event type (same as event->type). For more info, see the event types described for the PhEvent_t structure in the Photon Library Reference.

cbdata

A pointer to a PtListInput_t structure that contains at least the following members:

PhPoint_t pos;

Mouse position relative to the item (valid only for mouse events).

char * item;

For mouse events, the item under the cursor. For key events, the item that will be the current item after the event is processed normally.

unsigned index;

The index of that item (the first item on the list has an index of 1).

int consumed;

Initially set to Pt_CONTINUE. The callback function can suppress normal handling of the event by setting this field to another value. In the case of key events, a value of Pt_END causes the event to be consumed, while Pt_HALT passes the event to the parent widget. Mouse events are always consumed.

These callbacks should return Pt_CONTINUE.

Pt_CB_SELECTION

A list of callbacks that the widget invokes whenever the user selects an item from the list. Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason

The name of the callback resource (Pt_CB_SELECTION) that caused this callback to be invoked.

reason_subtype

This value depends on the value of Pt_ARG_SELECTION_MODE. In general, the value of reason_subtype will be:

• Pt_LIST_SELECTION_FINAL when the mouse button is released inside the widget or the Enter is pressed (selection is accepted).
• Pt_LIST_SELECTION_CANCEL when the mouse button is released outside the widget (previous state restored).
• Pt_LIST_SELECTION_BROWSE when the mouse button is held down, the space bar is used to select an item, or arrow keys are being used to scroll through the list (a selection is in the process of being made).

cbdata

A pointer to a PtListCallback_t structure that contains at least the following members:

unsigned mode;

The selection mode.

char *item;

The selected item.

int item_len;

The length of the selected item, in bytes.

int item_pos;

The position of the item in the array.

char ** sel_items;

The list of selected items.

ushort_t * sel_array;

An array of the selected positions within the list.

int sel_item_count;

The number of items in the sel_items list and the sel_array list.

These callbacks should return Pt_CONTINUE.

Inherited resources:

If the widget modifies an inherited resource, the "Default override" column indicates the new value. This modification affects any subclasses of the widget.

Pt_ARG_VISIBLE_COUNT

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's the 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.

Convenience functions:

The PtList widget defines several convenience functions that make it easier to use the list once it's been created. Here's a brief overview:

PtListAddItems()

Add one or more items to the list at a specified position.

PtListDeleteAllItems()

Remove all the items from the list.

PtListDeleteItemPos()

Delete a range of items by position.

PtListDeleteItems()

Delete items in the list by name.

PtListGotoPos()

Make the item at the specified position the current item and display it.

PtListItemExists()

Determine whether or not an item exists within the list.

PtListItemPos()

Determine the position of an item within the list.

PtListRemovePositions()

Remove the items at the specified positions.

PtListReplaceItemPos()

Replace items by position number.

PtListReplaceItems()

Replace items by item text.

PtListSelectPos()

Select the item at the specified position.

PtListShowPos()

Display the item at the specified position.

PtListUnselectPos()

Unselect the item at the specified position.