[Previous] [Contents] [Index] [Next]

PtGenList

Generic superclass for list and tree widgets

Class hierarchy:

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

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

PhAB icon:

None - not normally instantiated.

Public header:

<photon/PtGenList.h>

Description:

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 PtDivider widget. Some child classes of PtGenList, such as PtList and PtTree, use Tab characters as column separators.

Using scrollbars

The PtGenList widget creates 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 is displayed only when necessary. This behavior is controlled by the Pt_LIST_SCROLLBAR_ALWAYS and (the default) Pt_LIST_SCROLLBAR_AS_REQUIRED bits in the Pt_ARG_LIST_FLAGS resource.

Mouse actions

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

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

New resources:

Resource C type Pt type Default
Pt_ARG_BALLOON_COLOR PgColor_t Scalar Pg_BLACK
Pt_ARG_BALLOON_FILL_COLOR PgColor_t Scalar See below
Pt_ARG_LIST_COLUMN_ATTR PtListColumnAttributes_t *, short Array NULL
Pt_ARG_LIST_COLUMN_POS PtListColumn_t *, short Array NULL
Pt_ARG_LIST_FLAGS unsigned short Flag See below
Pt_ARG_LIST_FONT char * String "helv12"
Pt_ARG_LIST_ITEM_COUNT unsigned short Scalar 0 (read-only)
Pt_ARG_LIST_SB_RES PtArg_t, int Array
Pt_ARG_LIST_SCROLL_RATE short 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 Pg_BLUE
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

Pt_ARG_BALLOON_COLOR

C type Pt type Default
PgColor_t Scalar Pg_BLACK

The balloon's text color.

Pt_ARG_BALLOON_FILL_COLOR

C type Pt type Default
PgColor_t Scalar Pg_BALLOONCOLOR

The balloon's fill color.

Pt_ARG_LIST_COLUMN_ATTR

C type Pt type Default
PtListColumnAttributes_t *, short Array NULL

An array of PtListColumnAttributes_t structures, each containing at least the following:

short flags;
The flags define the alignment of the text. The possible values are:

The Pt_LIST_COLUMN_DAMAGE_ALWAYS flag tells the widget to redraw the column when the column's position or size changes, even if it doesn't seem necessary. 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. The flag can be set 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.

Pt_ARG_LIST_COLUMN_POS

C type Pt type Default
PtListColumn_t *, short Array NULL

An array of PtListColumn_t column structures. The structure contains at least the following:

short from, to;
They define the positions of the left and right edges of the column (relative to the left edge of widget's canvas).

Pt_ARG_LIST_FLAGS

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:

Pt_LIST_SHOW_BALLOON
Show list balloons.
Pt_LIST_BALLOON_AS_REQUIRED
Show a balloon if the contents of the list are clipped.
Pt_LIST_BALLOONS_IN_COLUMNS (on by default)
Display balloons for individual columns, not the entire row.
Pt_LIST_BOUNDARY_KEY_EVENTS
If this flag is clear (the default), cursor key events (/\, \/, Pg Up, Pg Down, Home, and End) are always consumed by the widget.

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 won't be consumed if the first item in the list is already the current item.

Pt_LIST_HEADER_AUTORESIZE
When the scrollbar is realized or unrealized, adjust the width of the PtDivider widget (if there is one).
Pt_LIST_INACTIVE
Make the list inactive.
Pt_LIST_NOBLIT
Don't blit when the Pt_ARG_TOP_ITEM_POS resource is changed.
Pt_LIST_NON_SELECT
Make the list read-only.
Pt_LIST_SCROLLBAR_ALWAYS
Always display a scrollbar.
Pt_LIST_SCROLLBAR_AS_REQUIRED (on by default)
Display a scrollbar only if required.
Pt_LIST_SCROLLBAR_AUTORESIZE
Resize the scrollbar automatically when the size of the header changes.
Pt_LIST_SCROLLBAR_GETS_FOCUS
Let the scrollbar get focus.
Pt_LIST_SNAP
Make the list snap to fit the number of items. Note that the Pt_LIST_SNAP flag is cleared automatically if the items in the list don't have equal heights.

Pt_ARG_LIST_FONT

C type Pt type Default
char * String "helv12"

The font used for the items in the list.

Pt_ARG_LIST_ITEM_COUNT (read-only)

C type Pt type Default
unsigned short Scalar 0

The number of items.

Pt_ARG_LIST_SB_RES

C type Pt type Default
PtArg_t Array

An array of PtArg_t records that are passed to the scrollbar. Note that only a selected set of resources can be modified: the PtGenList widget won'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, the application must supply a buffer and pass its address and length to the PtSetArg() macro.

An equivalent of:

PtGetResources( scrollbar, N, args );
      

would be:

PtArg_t tmp;
PtSetArg( &tmp, Pt_ARG_LIST_SB_RES, args, N );
PtGetResources( list, 1, &tmp );
      

Pt_ARG_LIST_SCROLL_RATE

C type Pt type Default
short 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.

Pt_ARG_LIST_SEL_COUNT (read-only)

C type Pt type Default
unsigned short Scalar 0

The number of selected items.

Pt_ARG_LIST_TOTAL_HEIGHT (read-only)

C type Pt type Default
unsigned Scalar 0

The total height (in pixels) of all items.

Pt_ARG_SCROLLBAR_WIDTH

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.

Pt_ARG_SELECTION_FILL_COLOR

C type Pt type Default
PgColor_t Scalar Pg_BLUE

The fill color for selected items.

Pt_ARG_SELECTION_MODE

C type Pt type Default
unsigned short Scalar See below

The selection mode. PtGenList supports the selection of items using the mouse or the keyboard. The descriptions below assume the user will be using a mouse. If a mouse isn't available, the /\ and \/ keys on the numeric pad can be used to highlight items in a list. The current selection is accepted by the widget when Enter is pressed.

Pt_BROWSE_MODE (default)
To select an item using the mouse, the user either clicks on an item or drags the the pointer down the list and releases the mouse button when the correct item is highlighted. The user can select only one item. If the user drags the mouse, the list can be scrolled.
Pt_MULTIPLE_MODE
To select multiple items using the mouse, the user clicks on more than one item. When the user clicks on a selected item, the item is released.
Pt_EXTENDED_MODE
Click-Shift-click/drag and Ctrl-click combinations are supported to select 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.
Pt_SINGLE_MODE
To select an item the user points to the item, then clicks the mouse button. The user can select only one item. If the user selects a second item, the first is released.
Pt_RANGE_MODE
To select a range of items the user points to the first item, drags to the last item in the range, then releases the mouse button. When the user is dragging the mouse, the list can be scrolled.

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:

Pt_SELECTION_MODE_SINGLE
Select up to one item.
Pt_SELECTION_MODE_NONE
Callback functions will take care of selecting items.
Pt_SELECTION_MODE_MULTIPLE
Each item can be selected independently.
Pt_SELECTION_MODE_RANGE
A range 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:

Pt_SELECTION_MODE_NOMOVE
Don't move the current item when the user drags the mouse.
Pt_SELECTION_MODE_NOSCROLL
Don't scroll the widget if the user drags the mouse above or below the widget.
Pt_SELECTION_MODE_NOREST
Don't restore the previous state if the mouse is released outside the widget.
Pt_SELECTION_MODE_NOCLEAR
If the user clicks on an item, don't clear the previous selection (use with Pt_SELECTION_MODE_MULTIPLE mode only).
Pt_SELECTION_MODE_AUTO
Keyboard automatically selects the current item (unless Ctrl is used).
Pt_SELECTION_MODE_NOFOCUS
If the Pt_SELECTION_MODE_AUTO flag is set, don't select the current item automatically when the widget gets focus.
Pt_SELECTION_MODE_TOGGLE
Item can be deselected by clicking on it (Pt_SELECTION_MODE_SINGLE and Pt_SELECTION_MODE_MULTIPLE modes only).

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:

For Pt_BROWSE_MODE:
Pt_SELECTION_MODE_SINGLE | Pt_SELECTION_MODE_AUTO
For Pt_MULTIPLE_MODE:
Pt_SELECTION_MODE_MULTIPLE | Pt_SELECTION_MODE_NOMOVE | Pt_SELECTION_MODE_NOCLEAR | Pt_SELECTION_MODE_TOGGLE | Pt_SELECTION_MODE_NOSCROLL
For Pt_EXTENDED_MODE:
Pt_SELECTION_MODE_MULTIPLE | Pt_SELECTION_MODE_AUTO | Pt_SELECTION_MODE_NOMOVE | Pt_SELECTION_MODE_NOFOCUS
For Pt_SINGLE_MODE:
Pt_SELECTION_MODE_SINGLE | Pt_SELECTION_MODE_NOCLEAR
For Pt_RANGE_MODE:
Pt_SELECTION_MODE_RANGE | Pt_SELECTION_MODE_AUTO | Pt_SELECTION_MODE_NOFOCUS

Pt_ARG_SELECTION_TEXT_COLOR

C type Pt type Default
PgColor_t Scalar Pg_WHITE

The text color for selected items.

Pt_ARG_TOP_ITEM_POS

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.) Note that unless the widget has been held (using PtContainerHold()), setting the Pt_ARG_TOP_ITEM_POS resource will cause the widget to draw if damaged and possibly blit afterwards. The widget doesn't blit when its fill color is set to Pg_TRANSPARENT.

Pt_ARG_VISIBLE_COUNT (read-only)

C type Pt type Default
unsigned short Scalar 0

The number of items currently visible.

Pt_CB_SCROLL_MOVE

C type Pt type Default
PtCallback_t * Link NULL

The list of 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, this callback is also invoked when the top item position (Pt_ARG_TOP_ITEM_POS) is changed by a call to PtSetResources().

Each callback is passed a PtCallbackInfo_t structure that contains at least the following members:

reason
The name of the callback resource (Pt_CB_SCROLL_MOVE) that caused this callback to be invoked.
reason_subtype
Defines the source of the position change:
Pt_LIST_SCROLL_SCROLLBAR
The scrollbar was used.
Pt_LIST_SCROLL_LIST
The list was used directly.
cbdata
A pointer to a PtScrollbarCallback_t structure that contains at least the following members:
unsigned action;
A value indicating what happened - see below.
int position;
A value corresponding to the handle's location.

The action field can be one of the following:

Pt_SCROLL_DECREMENT
The scrollbar handle position has been decreased by one increment.
Pt_SCROLL_INCREMENT
The handle position has been increased by one increment.
Pt_SCROLL_PAGE_INCREMENT
The handle position has been increased by one page.
Pt_SCROLL_PAGE_DECREMENT
The handle position has been decreased by one page.
Pt_SCROLL_TO_MAX
The handle has been moved to the maximum value.
Pt_SCROLL_TO_MIN
The handle has been moved to the minimum value.
Pt_SCROLL_DRAGGED
The handle is being dragged.
Pt_SCROLL_RELEASED
The handle has been released after having been dragged.
Pt_SCROLL_SET
The change of position is the result of a call to PtSetResources() and the widget has the Pt_CALLBACKS_ACTIVE bit set in its Pt_ARG_FLAGS resource.

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.

Resource Inherited from Default override
Pt_ARG_ANCHOR_FLAGS PtContainer
Pt_ARG_ANCHOR_OFFSETS PtContainer
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BORDER_WIDTH PtWidget 2
Pt_ARG_BOT_BORDER_COLOR PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTAINER_FLAGS PtContainer
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget Pt_CONSUME_EVENTS
Pt_ARG_FILL_COLOR PtBasic
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget |= Pt_HIGHLIGHTED |
Pt_ETCH_HIGHLIGHT |
Pt_SET |
Pt_GETS_FOCUS |
Pt_FOCUS_RENDER
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_MARGIN_HEIGHT PtBasic 0
Pt_ARG_MARGIN_WIDTH PtBasic 0
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget 0
Pt_ARG_TOP_BORDER_COLOR PtBasic
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BALLOONS PtContainer
Pt_CB_BLOCKED PtWidget
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_FILTER PtContainer
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_RESIZE PtContainer
Pt_CB_UNREALIZED PtWidget

Convenience functions:

Most of PtGenList's convenience functions are useful only if you're creating a custom list widget; they're described in the Creating a List Widget chapter of the Building Custom Widget manual.

The following convenience functions and data structure are useful when working with descendants of PtGenList:

PtGenListCreateTextBalloon()
Create a popup balloon for an item in the list.
PtGenListItem_t
PtGenList item structure
PtGenListSetColumnBalloon()
Adjust the balloon text to correspond to a given column.

[Previous] [Contents] [Index] [Next]