Generic superclass for list and tree widgets
PtWidget → PtBasic → PtContainer → PtCompound → PtGenList
Immediate subclasses:
For more information, see the diagram of the widget hierarchy.
None — not normally instantiated.
<photon/PtGenList.h>
The PtGenList class is a superclass for creating list widgets. It's discussed in more detail in Building Custom Widgets.
PtGenList handles a vertical, left-aligned list of rectangular items that may have different sizes. You can select one or more items, depending on the selection policy (see Pt_ARG_SELECTION_MODE).
PtGenListItem_t is the data structure used for the items.
A PtGenList widget can have one child, provided it's a PtDivider widget. In this case, PtGenList attaches a callback to the child so that the columns are set automatically to match the children of PtDivider; the items are drawn below the divider. Some child classes of PtGenList, such as PtList and PtTree, use Tab characters as column separators.
PtGenList creates a scrollbar if the list's area isn't large enough to display all the items in the list. By default, the scrollbar is displayed only when necessary. You can control this behavior by setting the Pt_LIST_SCROLLBAR_ALWAYS or (the default) Pt_LIST_SCROLLBAR_AS_REQUIRED bits in Pt_ARG_LIST_FLAGS.
You can set or get a limited number of resources (mainly the colors) for the child PtScrollbar widget by using the list's Pt_ARG_LIST_SB_RES resource.
Most of the time, one of the items in a list widget is the current item. (On rare occasions, a list can have no current item but it can't have more than one.)
The concept of the current item is similar to the concept of widget focus; typically, the current item is drawn with a blue dotted line around it when its widget has focus. When you press Enter or Space, it's the current item that gets selected; depending on the widget's selection mode, this may also unselect any previously selected items and/or unselect the current item if it was already selected. For more information, see the description of Pt_ARG_SELECTION_MODE.
Cursor keys change the current item, scroll the list if necessary to make the new current item visible, and, depending on the widget's selection mode, may also select and unselect items. For instance, pressing the ↓ key makes the next item the current item, and may select the new current item and unselect any previously selected items. Clicking on an item also makes it the current item and also may select or unselect items.
Holding down the Ctrl key when you click or press cursor keys will prevent any changes to the selection if you just want to walk the list without changing the selection.
Mouse actions depend on the current selection mode.
Button action | Result |
---|---|
Press | Result depends on the value of Pt_ARG_SELECTION_MODE |
Release | Invokes callbacks. |
Keyboard actions depend on the current selection mode.
Key | Action |
---|---|
Enter | Result depends on value of Pt_ARG_SELECTION_MODE |
↑ | Previous item |
↓ | Next item |
Pg Up | Previous page |
Pg Dn | Next page |
Home | First item |
End | Last item |
Resource | C type | Pt type | Default |
---|---|---|---|
Pt_ARG_LIST_COLUMN_ATTR | See below | Array | NULL |
Pt_ARG_LIST_COLUMN_POS | PtListColumn_t *, short | Array | NULL |
Pt_ARG_LIST_DNDSEL_COLOR | PgColor_t | Scalar | PgRGB(216, 216, 216) |
Pt_ARG_LIST_FLAGS | unsigned short | Flag | See below |
Pt_ARG_LIST_FONT | char * | String | "TextFont09" |
Pt_ARG_LIST_ITEM_COUNT | unsigned short | Scalar | 0 (read-only) |
Pt_ARG_LIST_SB_RES | PtArg_t *, int | Array | None |
Pt_ARG_LIST_SCROLL_RATE | unsigned char | Scalar | 2 |
Pt_ARG_LIST_SEL_COUNT | unsigned short | Scalar | 0 (read-only) |
Pt_ARG_LIST_TOTAL_HEIGHT | unsigned | Scalar | 0 (read-only) |
Pt_ARG_SCROLLBAR_WIDTH | unsigned short | Scalar | 0 (see below) |
Pt_ARG_SELECTION_FILL_COLOR | PgColor_t | Scalar | PgRGB(142, 162, 155) |
Pt_ARG_SELECTION_MODE | unsigned short | Scalar | See below |
Pt_ARG_SELECTION_TEXT_COLOR | PgColor_t | Scalar | Pg_WHITE |
Pt_ARG_TOP_ITEM_POS | unsigned short | Scalar | 1 |
Pt_ARG_VISIBLE_COUNT | unsigned short | Scalar | 0 (read-only) |
Pt_CB_SCROLL_MOVE | PtCallback_t * | Link | NULL |
C type | Pt type | Default |
---|---|---|
PtListColumnAttributes_t *, short | Array | NULL |
An array of PtListColumnAttributes_t structures, each containing at least the following:
For example, if a right-aligned column is made narrower but its right edge doesn't move, there's no need to redraw the column. You can set the flag to force a redraw, which needs to be done if the column contains some elements that aren't right-aligned. This flag is usually set by the child class of PtGenList that knows what's drawn in the columns.
C type | Pt type | Default |
---|---|---|
PtListColumn_t *, short | Array | NULL |
An array of PtListColumn_t column structures. The structure contains at least the following:
C type | Pt type | Default |
---|---|---|
PgColor_t | Scalar | PgRGB(216, 216, 216) |
The selection color in a drag-and-drop operation. See PgColor_t in the Photon Library Reference.
C type | Pt type | Default |
---|---|---|
unsigned short | Flag | Pt_LIST_BALLOONS_IN_COLUMNS | Pt_LIST_SCROLLBAR_AS_REQUIRED |
Flags that control the appearance and behavior of the list. The possible values are:
If this flag is set, a cursor key event is consumed only if it actually changes the current item. For example, an ↑ or Home event isn't consumed if the first item in the list is already the current item.
C type | Pt type | Default |
---|---|---|
char * | String | "TextFont09" |
The font used for the items in the list.
C type | Pt type | Default |
---|---|---|
unsigned short | Scalar | 0 |
The number of items.
C type | Pt type | Default |
---|---|---|
PtArg_t * | Array | None |
An array of PtArg_t structures (see the Photon Library Reference) that are passed to the list's child PtScrollbar. Note that you can modify only a selected set of the scrollbar's resources:
The PtGenList widget doesn't let you modify resources that might affect the position or size of the scrollbar. The main purpose of this resource is to change the colors of the scrollbar.
To get the Pt_ARG_LIST_SB_RES resource, your application must supply a buffer and pass its address and length to the PtSetArg() macro. For example, this code for a PtScrollbar widget:
PtGetResources( scrollbar, N, args );
is equivalent to this when the scrollbar is part of a PtGenList:
PtArg_t tmp; PtSetArg( &tmp, Pt_ARG_LIST_SB_RES, args, N ); PtGetResources( list, 1, &tmp );
C type | Pt type | Default |
---|---|---|
unsigned char | Scalar | 2 |
If you drag in a list and move outside the widget, the list scrolls at a rate determined by the number of “button repeats”. This resource specifies the number of button repeats that must be received before scrolling occurs. The default value is 2. To make the scrolling faster, set this resource to 1; to make scrolling slower, set this resource to a larger number.
C type | Pt type | Default |
---|---|---|
unsigned short | Scalar | 0 |
The number of selected items.
C type | Pt type | Default |
---|---|---|
unsigned | Scalar | 0 |
The total height (in pixels) of all items.
C type | Pt type | Default |
---|---|---|
unsigned short | Scalar | 0 (see below) |
The width of the accompanying scrollbar, if displayed. The minimum width is 6 pixels. If you set this resource to 0, the default width of 15 is used.
C type | Pt type | Default |
---|---|---|
PgColor_t | Scalar | PgRGB(142, 162, 155) |
The fill color for selected items. See PgColor_t in the Photon Library Reference.
C type | Pt type | Default |
---|---|---|
unsigned short | Scalar | See below |
The selection mode. PtGenList lets you select items using the mouse or the keyboard. The descriptions below assume you're using a mouse. If a mouse isn't available, you can use the ↑ and ↓ keys on the numeric keypad to highlight items in a list. The widget accepts the current selection when you press Enter.
To select multiple disjoint items, hold down the Ctrl while clicking on selected items.
The PtGenList widget supports several “predefined” selection modes, but you can also set “compose selection modes” using special flag values. To define a compose mode, start with one of the following values, which describe what kind of sets of items can be selected:
You can OR one of these values with zero or more of the following flags, which describe how the mouse and keyboard should work:
Note that zero isn't a valid value for the selection mode; neither is a mixture of predefined and compose values.
The “predefined” selection modes are equivalent to the following compose modes:
C type | Pt type | Default |
---|---|---|
PgColor_t | Scalar | Pg_WHITE |
The text color for selected items. See PgColor_t in the Photon Library Reference.
C type | Pt type | Default |
---|---|---|
unsigned short | Scalar | 1 |
The item index that appears at the top of the list. (The first item is 1.)
C type | Pt type | Default |
---|---|---|
unsigned short | Scalar | 0 |
The number of items currently visible.
C type | Pt type | Default |
---|---|---|
PtCallback_t * | Link | NULL |
A list of PtCallback_t structures that define the callbacks that the widget invokes when the top item position changes.
If the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource, these callbacks are also invoked when your application changes the top item position (Pt_ARG_TOP_ITEM_POS) by calling PtSetResource() or PtSetResources().
Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:
The action field can be one of the following:
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.
For Pt_CB_DND callbacks for a PtGenList, 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 following convenience functions and data structure are useful when working with descendants of PtGenList:
In general, the subclass specifies which of the convenience functions you can use. For example, PtList and PtTree don't let you call any of the PtGenList convenience functions except the ones that are redefined as their own convenience functions. |
The following convenience functions are useful only if you're creating a custom list widget; they're described in the Creating a List Widget chapter of Building Custom Widget: