Creating a List Widget

This chapter covers the following topics:

• Overview
• Item structure
• Widget instance structure
• Methods
• Convenience functions

Overview

The Photon library provides the generic list widget class PtGenList for creating custom list widgets. The PtGenList class displays a vertical list of any number of items. A user can select one or more items from this list, depending on the selection policy.

The child class shouldn't override the Draw method or consume mouse or key events. Instead, it should define a List Draw method for drawing and may define a Mouse and/or Key Event method if additional handling of those event types is required. Usually, the child class will also define a Selection method that will be called by the PtGenList event handler.

Item structure

The PtGenList class never allocates or frees items. This is the responsibility of the child class. The PtGenList class expects each item to be represented by a PtGenListItem_t structure — see the Photon Widget Reference.

When you call a PtGenList*() convenience function, you give it a pointer to the PtGenListItem_t structure as an item. When PtGenList calls one of your methods, it provides a pointer to the PtGenListItem_t structure as an item.

Since a child class will most likely need additional data describing the item, it will usually define its item as a structure whose first member is PtGenListItem_t. This makes conversions to and from PtGenListItem_t easy.

The child class is responsible for allocating items and adding them to the widget. Before adding an item to the widget, the members of the item structure should be set to the required values. After adding the item to the widget, don't modify the PtGenListItem_t directly — use the convenience functions instead.

The PtGenListItem_t structure is defined as follows:

typedef struct Pt_genlist_item {
     unsigned flags;
     PhDim_t size;
     PtGenListItem_t *next, *prev;
     }
     PtGenListItem_t;

flags

The following flags describe the state of the item:

Pt_LIST_ITEM_SELECTED

This item is selected. Use PtGenListSelect() and PtGenListUnselect() to modify this flag.

Pt_LIST_ITEM_CURRENT

This item is the current item (see “Current item” in the description of PtGenList in the Widget Reference). Use PtGenListGoto() to modify this flag.

Pt_LIST_ITEM_DAMAGED

This item should be redrawn. Use PtGenListDamageItem() to force a redraw.

Pt_LIST_ITEM_ABOVE

This item is above the visible range of items. Use the Pt_ARG_TOP_ITEM_POS resource or PtGenListShow() to scroll the list.

Pt_LIST_ITEM_BELOW

This item is below the visible range of items. Use the Pt_ARG_TOP_ITEM_POS resource or PtGenListShow() to scroll the list.

The Pt_LIST_ITEM_USED_FLAGS macro defines the flags used by the PtGenList widget. The remaining bits are available for the child class.

size

A PhDim_t structure (see the Photon Library Reference) that defines the width and height of the item. If the child class needs to modify the size of an item after it has been added to the widget, it should use the PtGenListLockItem() and PtGenListUnlockItem() convenience functions. If the widget has columns, the widths of the items are ignored.

next, prev

The widget uses these links to find the next and previous items in the list. Don't modify these links after adding the item to the widget. The next link is used for linking items before they're added to a widget (see PtGenListAddItems()).

Widget instance structure

Some members of the PtGenListWidget_t structure may be used by the child class. In general, don't modify the structure members directly; use the provided resources and convenience functions instead.

---

For information on the correspondence between structure members and resources, see the “Resource definitions” section for PtGenList in the chapter on Using Widget Superclasses.

---

gflags

Flags that affect the behavior of the widget. The child class will probably set all or most of these flags to a fixed value; however, if a class has to modify gflags after the widget has been created, use PtGenListSetGflags().

Pt_GEN_LIST_NO_BACKGROUND

If set, the Draw method won't draw the background (under the items) or margins.

Pt_GEN_LIST_ITEM_BACKGROUND

If this flag is set but the Pt_GEN_LIST_NO_BACKGROUND flag is clear, the Draw method will draw the background beneath each item and call the List Draw method once for each item that needs to be drawn.

Pt_GEN_LIST_NO_CLIPPING

If this flag is clear, the Draw method will set clipping to the widget's canvas before calling the List Draw method. The clipping won't be set if no items are wider than the canvas.

Pt_GEN_LIST_SHOW_DAMAGED

If this flag is set, the Draw method will scan the damage list and set the Pt_LIST_ITEM_DAMAGE flag in the items that need to be drawn. The List Draw method won't be 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 will be 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 in that widget will automatically set the current item to the first displayed item (see “Current item” in the description of PtGenList in the Widget Reference).

Pt_LIST_BALLOONS_IN_COLUMNS

If this flag is set and the widget has columns, the widget will destroy and recreate the balloon when the mouse pointer crosses column boundaries.

sel_xmode and sel_xflags

The “decomposed” value of the current selection mode. The value of sel_xmode can be one of:

• Pt_SELECTION_MODE( Pt_SELECTION_MODE_NONE )
• Pt_SELECTION_MODE( Pt_SELECTION_MODE_SINGLE )
• Pt_SELECTION_MODE( Pt_SELECTION_MODE_MULTIPLE )
• Pt_SELECTION_MODE( Pt_SELECTION_MODE_RANGE )

The sel_xflags member contains the “flags” part of the current selection mode:

• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_NOSCROLL )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_NOMOVE )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_NOREST )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_AUTO )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_NOCLEAR )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_TOGGLE )
• Pt_SELECTION_FLAGS( Pt_SELECTION_MODE_NOFOCUS )

current_item

The pointer to the current item (see “Current item” in the description of PtGenList in the Widget Reference).

cur_ndx

The index of the current item (the first item on the list has an index of 1).

Methods

The methods described in this section are defined in the PtGenList class.

List Draw method

The Draw method calls the List Draw method with the following arguments:

PtGenListWidget_t *widget

The widget pointer.

PtGenListItem_t *items

A pointer to the PtGenListItem_t structure for the first item that needs to be redrawn.

unsigned index

The index of the item to be redrawn (the first item on the list has an index of 1).

unsigned nitems

The number of items the function should look at.

PhRect_t *where

A pointer to a PhRect_t structure (see the Photon Library Reference) that defines the extent of the items (the function is allowed to modify the PhRect_t structure pointed to by where).

List Mouse method

The list class's raw callbacks invoke the Mouse List method on every mouse event if the mouse points to an item. The function can return a value other than Pt_CONTINUE to suppress normal mouse handling.

The List Mouse method is called with the following arguments:

PtGenListWidget_t *widget

The widget pointer.

PtGenListItem_t *item

A pointer to the PtGenListItem_t structure for the item under the mouse cursor.

unsigned index

The index of that item (the first item on the list has an index of 1).

PhPoint_t *where

A pointer to a PhPoint_t structure (see the Photon Library Reference) that defines the mouse position, relative to the item. The function is allowed to modify the structure pointed to by where.

int column

The index of the column under the mouse pointer, or -1 if the pointer isn't on a column or the widget has no columns.

PhEvent_t const *event

A pointer to a PhEvent_t structure (see the Photon Library Reference) that describes the event.

List Key method

The list class's raw callbacks invoke the List Key method on every key event. This method should return one of the following values:

Pt_CONTINUE

The PtGenList class will normally process the data contained in the PhKeyEvent_t structure. Note that the class's raw callbacks are allowed to modify the contents of that structure.

Pt_END

The widget will ignore the event and the class's raw callbacks will return Pt_CONTINUE immediately.

Pt_HALT

The event will be consumed by the widget, but PtGenList itself won't take any further action. The class's raw callbacks return Pt_END immediately.

The List Key method is called with the following arguments:

PtGenListWidget_t *widget

The widget pointer.

PhEvent_t const *event

A pointer to a PhEvent_t structure (see the Photon Library Reference) that describes the event.

PhKeyEvent_t *kevent

A pointer to the event data (which the function can modify). See PhKeyEvent_t in the Photon Library Reference.

PtGenListItem_t *newcur

A pointer to the PtGenListItem_t structure for the new current item (if the event is processed normally).

int index

The index of that item (the first item on the list has an index of 1).

List Select method

The list class's raw callbacks invoke the List Select method when an item is selected or unselected. The arguments are:

PtGenListWidget_t *list

The widget pointer.

PtGenListItem_t *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 has been selected or unselected.

int index

The index of that item (the first item on the list has an index of 1).

int column

The index of the column under the mouse pointer, or -1 if the pointer isn't on a column or the widget has no columns.

int nitems

The current number of selected items (the same as list->sel_count).

int subtype

The selection subtype.

PhEvent_t const *event

A pointer to a PhEvent_t structure (see the Photon Library Reference) that describes the event.

List Inflate method

The List Inflate method is called whenever a balloon widget needs to be created. The List Inflate method should create a balloon and return its widget pointer.

The List Inflate method is called with the following arguments:

PtWidget_t *widget

The list widget.

PtWidget_t *parent

The parent widget for the balloon.

PtGenListItem_t *item

A pointer to the PtGenListItem_t structure for the item under the mouse pointer.

unsigned index

The index of that item (the first item on the list has an index of 1).

int column

The index of the column under the mouse pointer, or -1 if the pointer isn't on a column or the widget has no columns.

PhArea_t *area

A pointer to a PhArea_t structure (see the Photon Library Reference) that defines 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(). These functions are described in the Photon Widget Reference.

List Attributes method

The List Attributes is called from the widget's draw functions (PtGenListDrawString() and PtGenListDrawBackground()). It should return a pointer to a PtGenListItemAttrs_t attribute structure filled in with information about how to draw the item, and has the following arguments:

PtWidget_t *widget

The widget pointer.

PtGenListItem_t *item

A pointer to the item that's being drawn.

If the method returns NULL, the calling draw function uses the widget's resources. Also, if any of the colors in the attributes structure are set to Pg_TRANSPARENT, or the font is NULL, the corresponding widget-wide setting is used.

Convenience functions

The PtGenList class defines the following convenience functions (see the Photon Widget Reference):

PtGenListAddItems()

Add items to a list.

PtGenListAllItems()

Get pointers to all the items in a list.

PtGenListClearSelection()

Clear the selection.

PtGenListDamageItem()

Redraw an item when its data has been changed.

PtGenListDrawBackground()

Draw the background of a list.

PtGenListDrawString()

Draw a string.

PtGenListFirstItem()

Return a pointer to the first item in a list.

PtGenListGetCurrent()

Return a pointer to the current item in a list.

PtGenListGetSelIndexes()

Get the indexes of the selected items.

PtGenListGoto()

Set the current item so that the new current item is visible.

PtGenListHold()

Prevent visible repair of a list widget.

PtGenListItemIndex()

Find the index of an item.

PtGenListItemRealloc()

Reallocate memory for an item.

PtGenListLastItem()

Return a pointer to the last item in a list.

PtGenListLockItem()

Lock an item so it can be resized.

PtGenListRelease()

Release a hold on visible repairs of a list widget.

PtGenListRemoveItems()

Remove items from a list.

PtGenListResize()

Resize a list widget.

PtGenListSelect()

Select an item in a list.

PtGenListSelectedItems()

Get pointers to the selected items.

PtGenListSetGflags()

Modify the gflags field of the widget.

PtGenListSetSelIndexes()

Set the selection indexes.

PtGenListShow()

Set the current position so a given item is visible.

PtGenListUnlockItem()

Unlock an item so it can be updated.

PtGenListUnselect()

Unselect an item in a list.

PtSuperClassGenListDraw()

Invoke the Draw List method in a superclass.

PtSuperClassGenListInflate()

Invoke the List Inflate method in a superclass.

PtSuperClassGenListKey()

Invoke the List Key method in a superclass.

PtSuperClassGenListMouse()

Invoke the List Mouse method in a superclass.

PtSuperClassGenListSelect()

Invoke the List Select method in a superclass.