PtRawList

`PtRawList`

A raw list

Class hierarchy:

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

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

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 .

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.

Museum

PtRawList

`PtRawList`

Class hierarchy:

PhAB icon:

Public header:

Description:

New resources:

Pt_ARG_RAWLIST_BACKGROUND_F

Pt_ARG_RAWLIST_DRAW_F

Pt_ARG_RAWLIST_GFLAGS

Pt_ARG_RAWLIST_INFLATE_F

Pt_ARG_RAWLIST_KEY_F

Pt_ARG_RAWLIST_MOUSE_F

Pt_ARG_RAWLIST_SELECT_F

Inherited resources:

Pt_CB_DND

Convenience functions: