Documentation  |   Table of Contents   |  < Previous   |  Next >   |  Index

14    Lists

Palm OS® Programmer's API Reference

Palm OS® 68K SDK

     

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

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, vol. I.

List Data Structures ^TOP^

ListAttrType Struct ^TOP^

Purpose

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

Prototype

typedef struct {
UInt16usable:1;
UInt16enabled:1;
UInt16visible:1;
UInt16poppedUp:1;
UInt16hasScrollBar:1.
UInt16search:1;
UInt16reserved:2;
} ListAttrType;

Fields

usable
Set to make the list usable.
If not set, the list is not considered part of the current interface of the application, and does not appear on screen.
enabled
Not used.
visible
Set when the list object is drawn, and cleared when the list object is erased.
This attribute is set and cleared internally.
poppedUp
Set to indicate that the choices are displayed in a popup window.
This attribute is set and cleared internally.
hasScrollBar
Set to indicate that the list has a scroll bar.
search
Set to enable incremental search. If incremental search is enabled, when the list is displayed the user can navigate the list by entering up to five characters. The list will scroll to present the first list item that matches the entered characters. This feature only works for popup lists, and only works if the list is sorted and the list items are available to the List Manager (that is, you don't pass NULL to LstSetListChoices()).
reserved
Reserved for system use.

ListType Struct ^TOP^

Purpose

The ListType structure is defined below.


WARNING! PalmSource, Inc. does not support or provide backward compatibility for the ListType structure. Never access its structure members directly, or your code may break in future versions. Use the information below for debugging purposes only.

Prototype

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;

Fields

id
The ID value, specified by the application developer. This ID value is part of the event data of lstEnterEvent and lstSelectEvent.
bounds
The bounds of the list, relative to the window. For example, to access the bounds of an object in a form whose ID is kObjectID:
{
RectangleType rect;
FormPtr formP = FrmGetActiveForm();
FrmGetObjectBounds(formP,
FrmGetObjectIndex(formP, kObjectID),
&rect);
}
attr
The list attributes. See ListAttrType.
itemsText
A pointer to an array of pointers to the text of the choices. Access with LstGetSelectionText().
For example, to access the string specified by itemNum in the list whose ID is kChoiceList use the following:
{
Char *string;
Int16 itemNum;
...
string = LstGetSelectionText(GetObjectPtr(kChoicesList), itemNum);
}
where GetObjectPtr is the following:
static void *GetObjectPtr(UInt16 rsrcID){
FormPtr formP;
formP = FrmGetActiveForm();
return FrmGetObjectPtr(formP, FrmGetObjectIndex(formP, rsrcID));
}
If you use a callback routine to draw the list items, note that the itemsText pointer you supply to LstSetListChoices() is passed to your callback routine. See the comments under ListDrawDataFuncType() for tips on using itemsText with a callback routine.
numItems
The number of choices in the list. Access with LstGetNumberOfItems().
currentItem
The currently-selected list choice (0 = first choice). Access with LstGetSelection().
topItem
The first choice displayed in the list. Set this field with LstSetTopItem().
font
The ID of the font used to draw all list text strings.
reserved
Reserved for future use.
popupWin
The handle of the window created when a list is displayed by calling LstPopupList().
drawItemCallback
Function used to draw an item in the list. If NULL, the default drawing routine is used instead. Set this field with LstSetDrawFunction(). See Application-Defined Function.

List Resources ^TOP^

The List Resource (tLST), and Popup Trigger Resource (tPUT) are used together to represent an active list. See Palm OS User Interface Guidelines for more information.

List Functions ^TOP^

LstDrawList Function ^TOP^

Purpose

Sets the visible attribute of the list object to true, and draws the list object if it is usable.

Declared In

List.h

Prototype

void LstDrawList (
   ListType*listP
)

Parameters

listP
Pointer to a list object (ListType).

Returns

Returns nothing.

Comments

If there are more choices than can be displayed, this function ensures that the current selection is visible. The current selection is highlighted. Note that this function does not ensure the current selection is visible; if you need to do this, call the LstMakeItemVisible() function.

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 Function ^TOP^

Purpose

Erase a list object.

Declared In

List.h

Prototype

void LstEraseList (
   ListType*listP
)

Parameters

listP
Pointer to a list object (ListType).

Returns

Returns nothing.

Comments

The visible attribute is set to false by this function.

See Also

FrmGetObjectPtr(), LstDrawList()

LstGetNumberOfItems Function ^TOP^

Purpose

Return the number of items in a list.

Declared In

List.h

Prototype

Int16 LstGetNumberOfItems (
   constListType*listP
)

Parameters

listP
Pointer to a list object (ListType).

Returns

Returns the number of items in a list.

See Also

FrmGetObjectPtr(), LstSetListChoices()

LstGetSelection Function ^TOP^

Purpose

Return the currently selected choice in the list.

Declared In

List.h

Prototype

Int16 LstGetSelection (
   constListType*listP
)

Parameters

listP
Pointer to a list object.

Returns

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 Function ^TOP^

Purpose

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

Declared In

List.h

Prototype

Char *LstGetSelectionText (
   constListType*listP,
   Int16itemNum
)

Parameters

listP
Pointer to a list object.
itemNum
Item to select (0 = first item in list).

Returns

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. This function is only usable if you supplied an array of strings and a count to LstSetListChoices(); if your application uses a callback function that dynamically generates the list text, this function returns NULL.

See Also

FrmGetObjectPtr()

LstGetTopItem Function ^TOP^

Purpose

Returns the topmost visible item.

Declared In

List.h

Prototype

Int16 LstGetTopItem (
   constListType*listP
)

Parameters

listP
Pointer to a list object.

Returns

Returns the item number of the top item visible.

Compatibility

Implemented only if 4.0 New Feature Set is present.

See Also

LstGetSelection(), LstSetTopItem()

LstGetVisibleItems Function ^TOP^

Purpose

Return the number of visible items.

Declared In

List.h

Prototype

Int16 LstGetVisibleItems (
   constListType*listP
)

Parameters

listP
Pointer to a list object.

Returns

The number of items visible.

Compatibility

Implemented only if 2.0 New Feature Set is present.

LstHandleEvent Function ^TOP^

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.

Declared In

List.h

Prototype

Boolean LstHandleEvent (
   ListType*listP,
   constEventType*eventP
)

Parameters

listP
Pointer to a list object (ListType).
eventP
Pointer to an EventType structure.

Returns

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 Function ^TOP^

Purpose

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

Declared In

List.h

Prototype

void LstMakeItemVisible (
   ListType*listP,
   Int16itemNum
)

Parameters

listP
Pointer to a list object (ListType).
itemNum
Item to select (0 = first item in list).

Returns

Returns nothing.

Comments

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

See Also

FrmGetObjectPtr(), LstSetSelection(), LstSetTopItem(), LstDrawList()

LstNewList Function ^TOP^

Purpose

Create a new list object dynamically and install it in the specified form. This function can be used to create a new popup trigger and its associated list.

Declared In

List.h

Prototype

Err LstNewList (
   void**formPP,
   UInt16id,
   Coordx,
   Coordy,
   Coordwidth,
   Coordheight,
   FontIDfont,
   Int16visibleItems,
   Int16triggerId
)

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). A nonzero value for triggerID causes this function to create both the list and its associated popup trigger. If the list isn't a popup list, pass 0 for triggerId.

Returns

Returns 0 if no error.

Compatibility

Implemented only if 3.0 New Feature Set is present.

See Also

LstDrawList(), FrmRemoveObject()

LstPopupList Function ^TOP^

Purpose

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

Declared In

List.h

Prototype

Int16 LstPopupList (
   ListType*listP
)

Parameters

listP
Pointer to a list object.

Returns

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 Function ^TOP^

Purpose

Scroll the list up or down a number of times.

Declared In

List.h

Prototype

Boolean LstScrollList (
   ListType*listP,
   WinDirectionTypedirection,
   Int16itemCount
)

Parameters

listP
Pointer to a list object.
direction
Direction to scroll.
itemCount
Items to scroll in direction.

Returns

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 Function ^TOP^

Purpose

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

Declared In

List.h

Prototype

void LstSetDrawFunction (
   ListType*listP,
   ListDrawDataFuncPtrfunc
)

Parameters

listP
Pointer to a list object.
func
Pointer to a function that draws items.

Returns

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(), LstGlueGetDrawFunction(), LstSetListChoices(), ListDrawDataFuncType()

LstSetHeight Function ^TOP^

Purpose

Set the number of items visible in a list.

Declared In

List.h

Prototype

void LstSetHeight (
   ListType*listP,
   Int16visibleItems
)

Parameters

listP
Pointer to a list object.
visibleItems
Number of choices visible at once.

Returns

Returns nothing.

Comments

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

See Also

FrmGetObjectPtr()

LstSetListChoices Function ^TOP^

Purpose

Set the items of a list to the array of text string pointers passed to this function. This functions erases the old list items.

Declared In

List.h

Prototype

void LstSetListChoices (
   ListType*listP,
   Char**itemsText,
   Int16numItems
)

Parameters

listP
Pointer to a list object.
itemsText
Pointer to an array of text strings. See SysFormPointerArrayToStrings() for one way to create this array of strings.
numItems
Number of choices in the list.

Returns

Returns nothing.

Comments

You need to call the LstDrawList function to update the list if it is displayed when you call this function.


NOTE: This function does not copy the strings in the itemsText array, which means that you need to ensure that the array is not moved or deallocated until after you are done with the list.

If you use a callback routine to draw the items in your list, the itemsText pointer is simply passed to that callback routine and is not otherwise used by the List Manager code. See the comments under ListDrawDataFuncType() for tips on using the itemsText parameter with a callback routine.

See Also

FrmGetObjectPtr(), LstGlueGetItemsText(), LstSetSelection(), LstSetTopItem(), LstDrawList(), LstSetHeight(), LstSetDrawFunction()

LstSetPosition Function ^TOP^

Purpose

Set the position of a list.

Declared In

List.h

Prototype

void LstSetPosition (
   ListType*listP,
   Coordx,
   Coordy
)

Parameters

listP
Pointer to a list object
x
Left bound.
y
Top bound.

Returns

Returns nothing.

Comments

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

See Also

FrmGetObjectPtr()

LstSetSelection Function ^TOP^

Purpose

Set the selection for a list.

Declared In

List.h

Prototype

void LstSetSelection (
   ListType*listP,
   Int16itemNum
)

Parameters

listP
Pointer to a list object.
itemNum
Item to select (0 = first item in list, noListSelection = none).

Returns

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, as long as the list object is both visible and usable.

See Also

FrmGetObjectPtr() , LstSetTopItem()

LstSetTopItem Function ^TOP^

Purpose

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

Declared In

List.h

Prototype

void LstSetTopItem (
   ListType*listP,
   Int16itemNum
)

Parameters

listP
Pointer to a list object.
itemNum
Item to select (0 = first item in list). This must be a valid item number.

Returns

Returns nothing.

Comments

Does not update the display.


NOTE: The value you specify for itemNum must be in the range 0 to max-number-of-items.

See Also

FrmGetObjectPtr(), LstGlueGetTopItem, LstSetSelection(), LstGetTopItem(), LstMakeItemVisible(), LstDrawList(), LstEraseList()

Application-Defined Function ^TOP^

If you need to perform special drawing for items in the list, call LstSetDrawFunction() to set the list drawing callback function. The ListDrawDataFuncType() section documents the prototype for the callback function you provide for drawing list items.

ListDrawDataFuncType Function ^TOP^

Purpose

Callback function that you provide for drawing items in a list. This function is called whenever the Palm OS needs to draw an element in the list. Your callback function declaration must match the prototype shown here.

Declared In

List.h

Prototype

void ListDrawDataFuncType(
   Int16itemNum,
   RectangleType*bounds,
   Char**itemsText
)

Parameters

itemNum
The number of the item to draw.
bounds
The bounds of the list, relative to the window.
itemsText
A pointer to an array of pointers to the text of the list items. This is the pointer that you supplied when calling LstSetListChoices().

Returns

Returns nothing.

Comments

You can call LstSetDrawFunction() to register your callback function for the list, which means that your function will be called to draw the list items, rather than using the built-in draw functionality, which displays each item's text string.

Your callback function is called whenever an item in the list needs to be drawn. When it is called, the value of the itemNum parameter specifies which item the function is to draw. The itemsText parameter, which is what was supplied to LstSetListChoices, doesn't actually need to point to a list of strings: you can pass NULL, or you can pass a pointer to anything that will be useful to your drawing function. Note, however, that if you pass anything other than a pointer to a list of strings when you call LstSetListChoices, you must ensure that LstGetSelectionText() is never called since it assumes that this pointer indicates an array of text items. In particular, if your list is associated with a pop-up trigger you must handle the popSelectEvent yourself before FrmHandleEvent() gets a chance at it since FrmHandleEvent calls LstGetSelectionText.


WARNING! If the list is a popup list, the form that owns the list is not active while the list is in a window. This means that you cannot call the FrmGetActiveForm() function. Instead, use itemsText pointer to access any information that you need for drawing. If you must access the form, use the FrmGetFormPtr() function.

Note that the list object manages which colors are used to draw the items and how to draw selected versus unselected items. In almost all circumstances, your drawing function does not have to be concerned with these details.

However, if you do need to determine if the item is selected, you can rely on the fact that the system has set the pen color to one of two colors prior to calling your draw function:

  • If the item is selected, the foreground color is UIObjectSelectedForeground.
  • If the item is not selected, the foreground color is UIObjectForeground.

You can determine the foreground color that is in effect for the list item by calling the WinSetForeColor() function, which returns the previous value of the foreground color. Remember to call WinSetForeColor again to reset the foreground color to what it was. For example:


itemColor = WinSetForeColor(myColor) 
WinSetForeColor(itemColor) 
selectColor = UiColorGetTableEntryIndex(
UIObjectSelectedForeground) 
if itemColor == selectColor 
... 

See Also

LstSetDrawFunction(), UIColorGetTableEntryIndex(), WinSetForeColor()