PtRawList

A raw list

Class hierarchy:

PtWidgetPtBasicPtContainerPtCompoundPtGenListPtRawList

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

PhAB icon:

PtRawList button in PhAB

Public header:

<photon/PtRawList.h>

Description:

PtRawList is a list that gives you more control than PtList over the appearance and behavior of its items. You can supply various functions to draw items, react to events, and so on. If these functions aren't given, the widget uses the default functions defined for PtGenList.

Use PtGenListAddItems() to add items to the raw list.

New resources:

Resource C type Pt type Default
Pt_ARG_RAWLIST_BACKGROUND_F See below Pointer NULL
Pt_ARG_RAWLIST_DRAW_F See below Pointer NULL
Pt_ARG_RAWLIST_GFLAGS unsigned short Flag 0
Pt_ARG_RAWLIST_INFLATE_F See below Pointer NULL
Pt_ARG_RAWLIST_KEY_F See below Pointer NULL
Pt_ARG_RAWLIST_MOUSE_F See below Pointer NULL
Pt_ARG_RAWLIST_SELECT_F See below Pointer NULL

Pt_ARG_RAWLIST_BACKGROUND_F

C type Pt type Default
See below Pointer NULL

A function that draws the background of the list. If this resource is NULL, the widget uses the default function defined for PtGenList.

This function is of type PtRawListDrawBackgroundF_t; the prototype is:

void drawbackground( PtWidget_t *widget,
                     PhRect_t const *canvas,
                     PhRect_t const *empty );

The arguments are:

widget
A pointer to the raw-list widget.
canvas
A pointer to a PhRect_t structure (see the Photon Library Reference) that defines the widget's canvas.
empty
A pointer to a PhRect_t structure that defines the empty area between the last item and the bottom margin, if any.

Pt_ARG_RAWLIST_DRAW_F

C type Pt type Default
See below Pointer NULL

A function that draws the widget. If this resource is NULL, the widget uses the default function defined for PtGenList.

This function is of type PtRawListDrawF_t; the prototype is:

void drawf( PtWidget_t *widget,
            PtGenListItem_t *item,
            unsigned index,
            unsigned nitems,
            PhRect_t *where );

The arguments are:

widget
A pointer to the raw-list widget.
item
A pointer to the PtGenListItem_t structure for the first item that needs to be redrawn.
index
The index of the item to be redrawn. The first item in the list has an index of 1.
nitems
The number of items the function should look at.
where
A pointer to a PhRect_t structure (see the Photon Library Reference) that defines the extent of the items. The function can modify the structure pointed to by where, if needed.

Pt_ARG_RAWLIST_GFLAGS

C type Pt type Default
unsigned short Flag 0

Flags that affect the behavior of the widget. The bits include:

Pt_GEN_LIST_NO_BACKGROUND
If set, the Draw function doesn't draw the background (under the items) or margins.
Pt_GEN_LIST_ITEM_BACKGROUND
If this bit is set but the Pt_GEN_LIST_NO_BACKGROUND bit is clear, the Draw function draws the background beneath each item and calls the List Draw method once for each item that needs to be drawn.
Pt_GEN_LIST_NO_CLIPPING
If this bit is clear, the Draw method sets clipping to the widget's canvas before calling the List Draw method. The clipping isn't set if no items are wider than the canvas.
Pt_GEN_LIST_SHOW_DAMAGED
If this flag is set, the Draw method scans the damage list and sets the Pt_LIST_ITEM_DAMAGE flag in the items that need to be drawn. The List Draw method isn't called at all if no items are damaged.
Pt_GEN_LIST_FULL_WIDTH
If this flag is set, the space to the right of an item is considered part of the item — the width stored in the item is treated as a suggested minimum. If that space is damaged, the item is marked as damaged. If this flag isn't set, the space to the right of an item is treated like the margin. Mouse clicks on that space are ignored.
Pt_GEN_LIST_NO_AUTOFOCUS
If this flag is clear, giving focus to the widget when there's no current item (see Current item in the description of PtGenList) in that widget automatically sets the current item to the first displayed item.
Pt_LIST_BALLOONS_IN_COLUMNS
If this flag is set and the widget has columns, the widget destroys and recreates the balloon when the mouse pointer crosses column boundaries.

Pt_ARG_RAWLIST_INFLATE_F

C type Pt type Default
See below Pointer NULL

A function that's called when a balloon widget needs to be created. It should create a balloon and returns its widget pointer. If this resource is NULL, the widget uses the default function defined for PtGenList.

This function is of type PtRawListInflateF_t The prototype is:

PtWidget_t *inflatef( PtWidget_t *widget,
                      PtWidget_t *parent,
                      PtGenListItem_t *item,
                      unsigned index,
                      int column,
                      PhArea_t *area );

The arguments are:

widget
A pointer to the raw-list widget.
parent
A pointer to the balloon's parent.
item
A pointer to the PtGenListItem_t structure for the item under the mouse pointer.
index
The index of the list item. The first item in the list has an index of 1.
column
The index of the column under the mouse pointer, or -1 if the pointer isn't on a column or the list has no columns.
area
A pointer to a PhArea_t structure (see the Photon Library Reference) that contains the area, relative to the parent widget, corresponding to the entire item, Use PtGenListSetColumnBalloon() to adjust the area to the specified column if you're not using PtGenListCreateTextBalloon().

Pt_ARG_RAWLIST_KEY_F

C type Pt type Default
See below Pointer NULL

A function that's called for key events. If this resource is NULL, the widget uses the default function defined for PtGenList.

This function is of type PtRawListKeyF_t; the prototype is:

int keyf( PtWidget_t *widget,
         PhEvent_t *ev,
         PhKeyEvent_t *kev,
         PtGenListItem_t *newcur,
         unsigned newpos );

The arguments are:

widget
A pointer to the raw-list widget.
ev
A pointer to the PhEvent_t structure (see the Photon Library Reference) that describes the event.
kev
A pointer a PhKeyEvent_t structure that describes the event data, which the function can modify.
newcur
A pointer to the PtGenListItem_t structure for the new current item (see Current item in the description of PtGenList) in the list, if the event is processed normally.
newpos
The index of the new current item. The first item in the list has an index of 1.

This function must return one of the following values:

Pt_CONTINUE
The PtGenList class processes the data contained in the PhKeyEvent_t structure (see the Photon Library Reference). Note that the class's raw callbacks can modify the contents of this structure.
Pt_END
The widget ignores the event and the class's raw callbacks return Pt_CONTINUE immediately.
Pt_HALT
The event is consumed by the widget, but PtGenList itself doesn't take any further action. The class's raw callbacks return Pt_END immediately.

Pt_ARG_RAWLIST_MOUSE_F

C type Pt type Default
See below Pointer NULL

A function that's called to handle mouse events if the mouse points to an item. If this resource is NULL, the widget uses the default function defined for PtGenList.

This function is of type PtRawListMouseF_t, and the prototype is:

int mousef( PtWidget_t *widget,
            PtGenListItem_t *item,
            unsigned index,
            PhPoint_t *where,
            int column,
            PhEvent_t *event );

The arguments are:

widget
A pointer to the raw-list widget.
item
A pointer to the PtGenListItem_t structure for the item under the mouse cursor.
index
The index of that item. The first item in the list has an index of 1.
where
A pointer to a PhPoint_t structure that gives the mouse position relative to the item. The function can modify the structure pointed to by where.
column
The column number.
event
A pointer to the PhEvent_t structure (see the Photon Library Reference) that describes the event.

This function must return one of the following values:

Pt_CONTINUE
The PtGenList class processes the data contained in the PhKeyEvent_t structure (see the Photon Library Reference). Note that the class's raw callbacks can modify the contents of this structure.
Pt_END
The widget ignores the event and the class's raw callbacks return Pt_CONTINUE immediately.
Pt_HALT
The event is consumed by the widget, but PtGenList itself doesn't take any further action. The class's raw callbacks return Pt_END immediately.

Pt_ARG_RAWLIST_SELECT_F

C type Pt type Default
See below Pointer NULL

A function that's called when an item is selected or unselected. If this resource is NULL, the widget uses the default function defined for PtGenList.

This function is of type PtRawListSelectF_t, with a prototype of:

void selectf( PtWidget_t *widget,
              PtGenListItem_t *item,
              int pos,
              int column,
              int nitems,
              int subtype,
              PhEvent_t *ev );

The arguments are:

widget
A pointer to the raw-list widget.
item
A pointer to a PtGenListItem_t structure. In Pt_SELECTION_MODE_RANGE selection mode, it's a pointer to the first selected item. In other modes, it's a pointer to the item that's been selected or unselected.
pos
The index of that item. The first item on the list has an index of 1.
column
The column number.
nitems
The current number of selected items (the same as list->sel_count).
subtype
The selection subtype.
event
A pointer to the PhEvent_t structure (see the Photon Library Reference) that describes the event.

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 PtWidget
Pt_ARG_ANCHOR_OFFSETS PtWidget
Pt_ARG_AREA PtWidget
Pt_ARG_BANDWIDTH_THRESHOLD PtBasic Not used by this class.
Pt_ARG_BASIC_FLAGS PtBasic
Pt_ARG_BEVEL_WIDTH PtWidget
Pt_ARG_BITMAP_CURSOR PtWidget
Pt_ARG_BEVEL_COLOR PtBasic
Pt_ARG_BEVEL_CONTRAST PtBasic
Pt_ARG_COLOR PtBasic
Pt_ARG_CONTAINER_FLAGS PtContainer
Pt_ARG_CONTRAST PtBasic
Pt_ARG_CURSOR_COLOR PtWidget
Pt_ARG_CURSOR_OVERRIDE PtContainer
Pt_ARG_CURSOR_TYPE PtWidget
Pt_ARG_DARK_BEVEL_COLOR PtBasic
Pt_ARG_DARK_FILL_COLOR PtBasic
Pt_ARG_DATA PtWidget
Pt_ARG_DIM PtWidget
Pt_ARG_EFLAGS PtWidget
Pt_ARG_EXTENT PtWidget
Pt_ARG_FILL_COLOR PtBasic
Pt_ARG_FILL_PATTERN PtBasic
Pt_ARG_FLAGS PtWidget
Pt_ARG_GRID_LAYOUT_DATA PtWidget
Pt_ARG_HEIGHT PtWidget
Pt_ARG_HELP_TOPIC PtWidget
Pt_ARG_HIGHLIGHT_ROUNDNESS PtBasic
Pt_ARG_INLINE_COLOR PtBasic
Pt_ARG_LAYOUT_DATA PtWidget
Pt_ARG_LIGHT_BEVEL_COLOR PtBasic
Pt_ARG_LIGHT_FILL_COLOR PtBasic
Pt_ARG_LIST_COLUMN_ATTR PtGenList
Pt_ARG_LIST_COLUMN_POS PtGenList
Pt_ARG_LIST_DNDSEL_COLOR PtGenList
Pt_ARG_LIST_FLAGS PtGenList
Pt_ARG_LIST_FONT PtGenList
Pt_ARG_LIST_ITEM_COUNT PtGenList
Pt_ARG_LIST_SB_RES PtGenList
Pt_ARG_LIST_SCROLL_RATE PtGenList
Pt_ARG_LIST_SEL_COUNT PtGenList
Pt_ARG_LIST_TOTAL_HEIGHT PtGenList
Pt_ARG_MARGIN_HEIGHT PtBasic
Pt_ARG_MARGIN_WIDTH PtBasic
Pt_ARG_MAXIMUM_DIM PtWidget
Pt_ARG_MINIMUM_DIM PtWidget
Pt_ARG_OUTLINE_COLOR PtBasic
Pt_ARG_POINTER PtWidget
Pt_ARG_POS PtWidget
Pt_ARG_RESIZE_FLAGS PtWidget
Pt_ARG_ROW_LAYOUT_DATA PtWidget
Pt_ARG_SCROLLBAR_WIDTH PtGenList
Pt_ARG_SELECTION_FILL_COLOR PtGenList
Pt_ARG_SELECTION_MODE PtGenList
Pt_ARG_SELECTION_TEXT_COLOR PtGenList
Pt_ARG_STYLE PtBasic
Pt_ARG_TITLE PtContainer
Pt_ARG_TITLE_FONT PtContainer
Pt_ARG_TOP_ITEM_POS PtGenList
Pt_ARG_TRANS_PATTERN PtBasic
Pt_ARG_USER_DATA PtWidget
Pt_ARG_VISIBLE_COUNT PtGenList
Pt_ARG_WIDTH PtWidget
Pt_CB_ACTIVATE PtBasic
Pt_CB_ARM PtBasic
Pt_CB_BALLOONS PtContainer Not used by this class.
Pt_CB_BLOCKED PtWidget
Pt_CB_CHILD_ADDED_REMOVED PtContainer
Pt_CB_DESTROYED PtWidget
Pt_CB_DISARM PtBasic
Pt_CB_DND PtWidget See below.
Pt_CB_FILTER PtWidget
Pt_CB_GOT_FOCUS PtBasic
Pt_CB_HOTKEY PtWidget
Pt_CB_IS_DESTROYED PtWidget
Pt_CB_LOST_FOCUS PtBasic
Pt_CB_MENU PtBasic
Pt_CB_OUTBOUND PtWidget
Pt_CB_RAW PtWidget
Pt_CB_REALIZED PtWidget
Pt_CB_REPEAT PtBasic
Pt_CB_RESIZE PtContainer
Pt_CB_SCROLL_MOVE PtGenList
Pt_CB_UNREALIZED PtWidget

Pt_CB_DND

For Pt_CB_DND callbacks for a PtRawList, the cbinfo->cbdata is a pointer to a PtGenListDndCallback_t structure, containing at least the following members:

PtDndCallbackInfo_t dnd_info
See the description of Pt_CB_DND for PtWidget.
PtGenListItem_t *item
The target item involved in the drag-and-drop operation.
int item_pos
The index of that item.
unsigned long flags
Possible values:
int action
This member is initially set to Pt_LIST_ITEM_DNDSELECTED_UP | Pt_LIST_ITEM_DNDSELECTED_DOWN | Pt_LIST_ITEM_DNDSELECTED_IN. You can unset some of these values to indicate that the drag-and-drop isn't accepted in that case. For example, if you unset Pt_LIST_ITEM_DNDSELECTED_IN, the drag-and-drop can't occur inside the item, only above or below.

Convenience functions:

You can use any of the convenience functions defined for PtGenList when working with a PtRawList.