PtRawList

A raw list

Class hierarchy:

PtWidget → PtBasic → PtContainer → PtCompound → PtGenList → PtRawList

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

PhAB icon:

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:

Pt_ARG_RAWLIST_BACKGROUND_F

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

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

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

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

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

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

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.

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:

• Pt_LIST_ITEM_DNDSELECTED_UP — the drop occurred above the item.
• Pt_LIST_ITEM_DNDSELECTED_DOWN — the drop occurred below the item.
• Pt_LIST_ITEM_DNDSELECTED_IN — the drop occurred inside the item.

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.