13 Lists

This chapter provides information about list objects by discussing these topics:

• List Data Structures
  
  
• List Resources
  
  
• List Functions
  
  
• Application-Defined Function
  

The header file List.h declares the API that this chapter describes. For more information on lists, see the section "Lists" in the Palm OS Programmer's Companion.

List Data Structures

ListAttrType

The ListAttrType bit field defines the visible characteristics of the list.

typedef struct {

    UInt16 usable :1;
    UInt16 enabled :1;
    UInt16 visible :1;
    UInt16 poppedUp :1;
    UInt16 hasScrollBar :1.
    UInt16 search :1;
    UInt16 reserved :2;
} ListAttrType;

Field Descriptions

ListType

The ListType structure is defined as follows:

typedef struct {

    UInt16 id;
    RectangleType bounds;
    ListAttrType attr;
    Char ** itemsText;
    Int16 numItems;
    Int16 currentItem;
    Int16 topItem;
    FontID font;
    UInt8 reserved;
    WinHandle popupWin;
    ListDrawDataFuncPtr drawItemCallback;
} ListType;

Field Descriptions

List Resources

The List Resource (tLST), and Popup Trigger Resource (tPUT) are used together to represent an active list.

List Functions

LstDrawList

Purpose

Draw the list object if it's usable. Set its visible attribute to true.

Prototype

void LstDrawList (ListType *listP)

Parameters

listP

Pointer to list object (ListType).

Result

Returns nothing.

Comments

If there are more choices than can be displayed, this function ensures that the current selection is visible. If possible, the current selection is displayed at the top. The current selection is highlighted.

If the list is disabled, it's drawn grayed-out (strongly discouraged). If it's empty, nothing is drawn. If it's not usable, nothing is drawn.

See Also

FrmGetObjectPtr, LstPopupList, LstEraseList

LstEraseList

Purpose

Erase a list object.

Prototype

void LstEraseList (ListType *listP)

Parameters

listP

Pointer to a list object (ListType).

Result

Returns nothing.

Comments

The visible attribute is set to false by this function.

See Also

FrmGetObjectPtr, LstDrawList

LstGetNumberOfItems

Purpose

Return the number of items in a list.

Prototype

Int16 LstGetNumberOfItems (const ListType *listP)

Parameters

listP

Pointer to a list object (ListType).

Result

Returns the number of items in a list.

See Also

FrmGetObjectPtr, LstSetListChoices

LstGetSelection

Purpose

Return the currently selected choice in the list.

Prototype

Int16 LstGetSelection (const ListType *listP)

Parameters

listP

Pointer to list object.

Result

Returns the item number of the current list choice. The list choices are numbered sequentially, starting with 0; Returns noListSelection if none of the items are selected.

See Also

FrmGetObjectPtr, LstSetListChoices, LstSetSelection, LstGetSelectionText

LstGetSelectionText

Purpose

Return a pointer to the text of the specified item in the list, or NULL if no such item exists.

Prototype

Char * LstGetSelectionText (const ListType *listP, Int16 itemNum)

Parameters

listP

Pointer to list object.

itemNum

Item to select (0 = first item in list).

Result

Returns a pointer to the text of the current selection, or NULL if out of bounds.

Comments

This is a pointer within ListType, not a copy.

See Also

FrmGetObjectPtr, LstSetListChoices

LstGetVisibleItems

Purpose

Return the number of visible items.

Prototype

Int16 LstGetVisibleItems (const ListType *listP)

Parameters

listP

Pointer to list object.

Result

The number of items visible.

Compatibility

Implemented only if 2.0 New Feature Set is present.

LstHandleEvent

Purpose

Handle event in the specified list; the list object must have its usable and visible attribute set to true.This routine handles two type of events, penDownEvent and lstEnterEvent; see Comments.

Prototype

Boolean LstHandleEvent (ListType *listP, const EventType *eventP)

Parameters

listP

Pointer to a list object (ListType).

eventP

Pointer to an EventType structure.

Result

Return true if the event was handled. The following cases will result in a return value of true:

• A penDownEvent within the bounds of the list
  
  
• A lstEnterEvent with a list ID value that matches the list ID in the list data structure
  

Comments

When this routine receives a penDownEvent, it checks if the pen position is within the bounds of the list object. If it is, this routine tracks the pen until the pen comes up. If the pen comes up within the bounds of the list, a lstEnterEvent is added to the event queue, and the routine is exited.

When this routine receives a lstEnterEvent, it checks that the list ID in the event record matches the ID of the specified list. If there is a match, this routine creates and displays a popup window containing the list's choices and the routine is exited.

If a penDownEvent is received while the list's popup window is displayed and the pen position is outside the bounds of the popup window, the window is dismissed. If the pen position is within the bounds of the window, this routine tracks the pen until it comes up. If the pen comes up outside the list object, a lstEnterEvent is added to the event queue.

LstMakeItemVisible

Purpose

Make an item visible, preferably at the top. If the item is already visible, make no changes.

Prototype

void LstMakeItemVisible (ListType *listP, Int16 itemNum)

Parameters

listP

Pointer to a list object (ListType).

itemNum

Item to select (0 = first item in list).

Result

Returns nothing.

Comments

Does not visually update the list. You must call LstDrawList to update it.

See Also

FrmGetObjectPtr, LstSetSelection, LstSetTopItem, LstDrawList

LstNewList

Purpose

Create a new list object dynamically and install it in the specified form.

Prototype

Err LstNewList (void **formPP, UInt16 id, Coord x, Coord y, Coord width, Coord height, FontID font, Int16 visibleItems, Int16 triggerId)

Parameters

<--> formPP

Pointer to the pointer to the form in which the new list is installed. This value is not a handle; that is, the old formPP value is not necessarily valid after this function returns. In subsequent calls, always use the new formPP value returned by this function.

id

Symbolic ID of the list, specified by the developer. By convention, this ID should match the resource ID (not mandatory).

x

Horizontal coordinate of the upper-left corner of the list's boundaries, relative to the window in which it appears.

y

Vertical coordinate of the upper-left corner of the list's boundaries, relative to the window in which it appears.

width

Width of the list, expressed in pixels. Valid values are 1 - 160.

height

Height of the list, expressed in pixels.Valid values are 1 - 160.

visibleItems

Number of list items that can be viewed together.

triggerId

Symbolic ID of the popup trigger associated with the new list. This ID is specified by the developer; by convention, this ID should match the resource ID (not mandatory).

Result

Returns 0 if no error.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

LstDrawList, FrmRemoveObject

LstPopupList

Purpose

Display a modal window that contains the items in the list.

Prototype

Int16 LstPopupList (ListType *listP)

Parameters

listP

Pointer to list object.

Result

Returns the list item selected, or -1 if no item was selected.

Comments

Saves the previously active window. Creates and deletes the new popup window.

See Also

FrmGetObjectPtr

LstScrollList

Purpose

Scroll the list up or down a number of times.

Prototype

Boolean LstScrollList (ListType *listP, WinDirectionType direction, Int16 itemCount)

Parameters

listP

Pointer to list object.

direction

Direction to scroll.

itemCount

Items to scroll in direction.

Result

Returns true when the list is actually scrolled, false otherwise. May return false if a scroll past the end of the list is requested.

Compatibility

Implemented only if 2.0 New Feature Set is present.

LstSetDrawFunction

Purpose

Set a callback function to draw each item instead of drawing the item's text string.

Prototype

void LstSetDrawFunction (ListType *listP, ListDrawDataFuncPtr func)

Parameters

listP

Pointer to list object.

func

Pointer to function which draws items.

Result

Returns nothing.

Comments

This function also adjusts topItem to prevent a shrunken list from being scrolled down too far. Use this function for custom draw functionality.

See Also

FrmGetObjectPtr, LstSetListChoices

LstSetHeight

Purpose

Set the number of items visible in a list.

Prototype

void LstSetHeight (ListType *listP, Int16 visibleItems)

Parameters

listP

Pointer to list object.

visibleItems

Number of choices visible at once.

Result

Returns nothing.

Comments

This function doesn't redraw the list if it's already visible.

See Also

FrmGetObjectPtr

LstSetListChoices

Purpose

Set the items of a list to the array of text strings passed to this function. This function doesn't affect the display of the list. If the list is visible, erases the old list items.

Prototype

void LstSetListChoices (ListType *listP, Char **itemsText, UInt16 numItems)

Parameters

listP

Pointer to a list object.

itemsText

Pointer to an array of text strings.

numItems

Number of choices in the list.

Result

Returns nothing.

See Also

FrmGetObjectPtr, LstSetSelection, LstSetTopItem, LstDrawList, LstSetHeight, LstSetDrawFunction

LstSetPosition

Purpose

Set the position of a list.

Prototype

void LstSetPosition (ListType *listP, Coord x, Coord y)

Parameters

listP

Pointer to a list object

x, y

Left and top bound.

Result

Returns nothing.

Comments

List is not redrawn. Don't call this function when the list is visible.

See Also

FrmGetObjectPtr

LstSetSelection

Purpose

Set the selection for a list.

Prototype

void LstSetSelection (ListType *listP, Int16 itemNum)

Parameters

listP

Pointer to a list object.

itemNum

Item to select (0 = first item in list; -1 = none).

Result

Returns nothing.

Comments

The old selection, if any, is unselected. If the list is visible, the selected item is visually updated. The list is scrolled to the selection, if necessary.

See Also

FrmGetObjectPtr

LstSetTopItem

Purpose

Set the item visible. The item cannot become the top item if it's on the last page.

Prototype

void LstSetTopItem (ListType *listP, Int16 itemNum)

Parameters

listP

Pointer to list object.

itemNum

Item to select (0 = first item in list).

Result

Returns nothing.

Comments

Does not update the display.

See Also

FrmGetObjectPtr, LstSetSelection, LstMakeItemVisible, LstDrawList, LstEraseList

Application-Defined Function

If you need to perform special drawing for items in the list, call LstSetDrawFunction to set the list drawing callback function. The callback function's prototype is:

void ListDrawDataFuncType (Int16 itemNum,
RectangleType *bounds, Char **itemsText)