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

22    List Reference

User Interface

Exploring Palm OS®

This chapter provides information about lists by discussing these topics:

List Structures and Types
List Constants
List Events
List Functions and Macros
Application-Defined Functions

The header file List.h declares the API that this chapter describes. For more information on lists, see the section "Lists."

List Structures and Types ^TOP^

ListType Struct ^TOP^

Purpose

Internal structure that defines the list. A ListPtr is a pointer to a ListType structure.

Declared In

List.h

Prototype

typedef struct ListType ListType;
typedef ListType *ListPtr

Fields

None.

List Constants ^TOP^

List Constants ^TOP^

Purpose

Constants defined in List.h.

Declared In

List.h

Constants

#define noListSelection ((int16_t)(-1))
Used to denote that no item is selected.

List Events ^TOP^

lstEnterEvent ^TOP^

Purpose

Sent when penDownEvent occurs within the bounds of a list.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct lstEnter {
   struct ListType *pList;
   uint16_t listID;
   int16_t selection;
} lstEnter 

Fields

pList
Pointer to a list structure.
listID
Resource ID of the list.
selection
Unused.

Comments

In most cases, you should wait for a lstSelectEvent or popSelectEvent before taking the intended action of the list. When the application receives the lstEnterEvent, it is not guaranteed that a list item will become selected.

lstExitEvent ^TOP^

Purpose

Sent when the stylus had previously entered the bounds of the list but is lifted outside of the bounds of the list.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct lstExit {
   struct ListType *pList;
   uint16_t listID;
   _BA32_PADDING_16(1)
} lstExit 

Fields

pList
Pointer to a list structure.
listID
Resource ID of the list.

lstSelectEvent ^TOP^

Purpose

Sent when the stylus had previously entered the bounds of the list and is now lifted within the bounds of the list.


TIP: Pop-up lists don't generate a lstSelectEvent. Instead, they generate a popSelectEvent.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct lstSelect {
   struct ListType *pList;
   uint16_t listID;
   int16_t selection;
} lstSelect 

Fields

pList
Pointer to a list structure.
listID
Resource ID of the list.
selection
Item number (zero-based) of the new selection.

Comments

Applications should respond to this event if they need to respond to the list selection in some way. Most applications simply use LstGetSelection() or LstGetSelectionText() to obtain the list selection when it is needed.

popSelectEvent ^TOP^

Purpose

Sent when the user selects an item in a pop-up list.

For this event, the EventType data field contains the structure shown in the Prototype section, below.

Declared In

Event.h

Prototype

struct popSelect {
   uint16_t controlID;
   uint16_t listID;
   struct ControlType *controlP;
   struct ListType *listP;
   int16_t selection;
   int16_t priorSelection;
} popSelect 

Fields

controlID
Resource ID of the pop-up trigger.
listID
Resource ID of the list.
controlP
Pointer to the pop-up trigger ControlType structure.
listP
Pointer to the list's structure.
selection
Item number (zero-based) of the new list selection.
priorSelection
Item number (zero-based) of the prior list selection.

Comments

Applications should respond to this event to perform whatever action is necessary for this list. Return false from the event handler to have the form set the pop-up trigger's label to the selected list item's text.

Palm OS® can only set the pop-up trigger label if the list items are statically defined. If you are custom drawing the list items, you must respond to this event and set the selected text in the pop-up trigger yourself.

List Functions and Macros ^TOP^

LstDrawList Function ^TOP^

Purpose

Makes the list visible and draws the list.

Declared In

List.h

Prototype

void LstDrawList (
   ListType *listP
)

Parameters

listP
Pointer to a list.

Returns

Nothing.

Comments

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

Erases a list.

Declared In

List.h

Prototype

void LstEraseList (
   ListType *listP
)

Parameters

listP
Pointer to a list.

Returns

Nothing.

See Also

FrmGetObjectPtr(), LstDrawList()

LstGetFont Function ^TOP^

Purpose

Gets the font used to draw a list's text strings.

Declared In

List.h

Prototype

FontID LstGetFont (
   const ListType *listP
)

Parameters

listP
Pointer to the list.

Returns

The ID of the font used to draw all list text strings.

See Also

LstSetFont()

LstGetItemsText Function ^TOP^

Purpose

Gets the text strings that represent the items in a list.

Declared In

List.h

Prototype

char **LstGetItemsText (
   const ListType *listP
)

Parameters

listP
Pointer to the list.

Returns

A pointer to an array of pointers to the text of the list choices.

See Also

LstGetSelectionText(), LstSetListChoices()

LstGetNumberOfItems Function ^TOP^

Purpose

Returns the number of items in a list.

Declared In

List.h

Prototype

int16_t LstGetNumberOfItems (
   const ListType *listP
)

Parameters

listP
Pointer to a list.

Returns

The number of items in a list.

See Also

FrmGetObjectPtr(), LstSetListChoices()

LstGetSelection Function ^TOP^

Purpose

Returns the currently selected choice in the list.

Declared In

List.h

Prototype

int16_t LstGetSelection (
   const ListType *listP
)

Parameters

listP
Pointer to a list.

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

Returns 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 (
   const ListType *listP,
   const int16_t itemNum
)

Parameters

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

Returns

A pointer to the text of the current selection, or NULL if no such item exists.

Comments

The returned string is not a copy of the currently selected list item; it is a pointer to a field within the ListType structure. This function is only usable if you supplied an array of strings and a count to LstSetListChoices() or if you statically defined the list in the resource database; 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_t LstGetTopItem (
   const ListType *listP
)

Parameters

listP
Pointer to a list.

Returns

The item number of the top item that is visible.

See Also

LstGetSelection(), LstSetTopItem()

LstGetVisibleItems Function ^TOP^

Purpose

Returns the number of visible items.

Declared In

List.h

Prototype

int16_t LstGetVisibleItems (
   const ListType *listP
)

Parameters

listP
Pointer to a list.

Returns

The number of items visible.

LstHandleEvent Function ^TOP^

Purpose

Handles event in the specified list.

Declared In

List.h

Prototype

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

Parameters

listP
Pointer to a list.
eventP
Pointer to an EventType structure.

Returns

true if the event was handled.

Comments

The following cases will result in a return value of true:

  • A penDownEvent within the bounds of the list. The list begins tracking the pen, but it does not block. Adds the lstEnterEvent to the event queue.
  • A penMoveEvent. This function tracks the pen, updates the current selection. If the pen moves outside of the bounds of the list but is not lifted, this function scrolls the list in the direction indicated. That is, if the pen is dragged to the bottom of the list, the list scrolls down. If the pen is dragged to the top of the list, the list scrolls up.
  • A penUpEvent. If the pen is up within the bounds of the list, it enqueues a lstSelectEvent. Otherwise, it enqueues a lstExitEvent.
  • A lstEnterEvent with a list ID value that matches the list ID in the list data structure. If the list is a pop-up list, this function displays the pop-up lists window.

LstMakeItemVisible Function ^TOP^

Purpose

Makes 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,
   const int16_t itemNum
)

Parameters

listP
Pointer to a list.
itemNum
Item to select. Items are numbered from 0 to LstGetNumberOfItems()–1.

Returns

Nothing.

Comments

Does not visually update the list.

See Also

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

LstNewList Function ^TOP^

Purpose

Creates a new list dynamically and installs it in the specified form. This function can be used to create a new pop-up trigger and its associated list.

Declared In

List.h

Prototype

status_t LstNewList (
   void **formPP,
   uint16_t id,
   Coord x,
   Coord y,
   Coord width,
   Coord height,
   FontID font,
   int16_t visibleItems,
   int16_t 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 standard coordinates. Valid values are 1 – 160.
height
Height of the list, expressed in standard coordinates.Valid values are 1 – 160.
visibleItems
Number of list items that can be viewed together.
triggerId
Symbolic ID of the pop-up 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 pop-up trigger. If the list isn't a pop-up list, pass 0 for triggerId.

Returns

errNone if no error.

See Also

LstDrawList(), FrmRemoveObject()

LstPopupList Function ^TOP^

Purpose

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

Declared In

List.h

Prototype

int16_t LstPopupList (
   ListType *listP
)

Parameters

listP
Pointer to a list.

Returns

The list item selected, or noListSelection if no item was selected.

Comments

Saves the previously active window. Creates and deletes the new pop-up window.

Typical applications do not call this function. Palm OS pops up the list for you when the user holds the pen down on the pop-up trigger that is associated with the list.

See Also

FrmGetObjectPtr()

LstScrollList Function ^TOP^

Purpose

Scrolls the list up or down a number of times.

Declared In

List.h

Prototype

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

Parameters

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

Returns

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

Comments

List scrolling is fully handled within Palm OS. Applications do not have to handle any aspect of list scrolling. If you suppress the list scroll arrows, however, and attach a separate scroll bar to the list, you might need to call this function.

LstSetDrawFunction Function ^TOP^

Purpose

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

Declared In

List.h

Prototype

void LstSetDrawFunction (
   ListType *listP,
   ListDrawDataFuncPtr func
)

Parameters

listP
Pointer to a list.
func
Pointer to a function that draws items. See ListDrawDataFuncType().

Returns

Nothing.

See Also

FrmGetObjectPtr(), LstSetListChoices(), ListDrawDataFuncType()

LstSetFont Function ^TOP^

Purpose

Specifies the font to be used to draw a list's text strings.

Declared In

List.h

Prototype

void LstSetFont (
   ListType *listP,
   FontID fontID
)

Parameters

listP
Pointer to a list.
fontID
ID of the font to be used to draw all list text strings.

Returns

Nothing.

See Also

LstGetFont()

LstSetHeight Function ^TOP^

Purpose

Sets the number of items visible in a list.

Declared In

List.h

Prototype

void LstSetHeight (
   ListType *listP,
   int16_t visibleItems
)

Parameters

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

Returns

Nothing.

Comments

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

See Also

FrmGetObjectPtr()

LstSetIncrementalSearch Function ^TOP^

Purpose

Enables or disables incremental search for a sorted pop-up list.

Declared In

List.h

Prototype

void LstSetIncrementalSearch (
   ListType *listP,
   Boolean incrementalSearch
)

Parameters

listP
Pointer to a list.
incrementalSearch
Set to true to enable incremental search, false to disable it.

Returns

Nothing.

Comments

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 if the following are true:

  • The list is a pop-up list.
  • The items in the list are sorted alphabetically.
  • The list items are visible to the List Manager (that is, you don't pass NULL to LstSetListChoices()).

LstSetListChoices Function ^TOP^

Purpose

Sets the items of a list to the array of text string pointers passed to this function. This functions overwrites the previous set of list items.

Declared In

List.h

Prototype

void LstSetListChoices (
   ListType *listP,
   char **itemsText,
   int16_t numItems
)

Parameters

listP
Pointer to a list.
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

Nothing.

Comments

You need to call the LstDrawList() function to update the list if it is displayed when you call this function. LstSetListChoices() ensures that the selected item is within the range of the items you supply and that the top item is within the range of possible top items.


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(), LstGetItemsText(), LstSetSelection(), LstSetTopItem(), LstDrawList(), LstSetHeight(), LstSetDrawFunction()

LstSetPosition Function ^TOP^

Purpose

Sets the position of a list.

Declared In

List.h

Prototype

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

Parameters

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

Returns

Nothing.

Comments

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

LstSetSelection Function ^TOP^

Purpose

Sets the selection for a list.

Declared In

List.h

Prototype

void LstSetSelection (
   ListType *listP,
   int16_t itemNum
)

Parameters

listP
Pointer to a list.
itemNum
Item to select. Items are numbered from 0 to LstGetNumberOfItems()–1. Specify noListSelection if you want to deselect all list items.

Returns

Nothing.

Comments

The old selection, if any, is deselected. 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 is both visible and usable.

See Also

FrmGetObjectPtr(), LstSetTopItem()

LstSetScrollArrows Function ^TOP^

Purpose

Enables or disables the drawing of the list's scroll arrows.

Declared In

List.h

Prototype

void LstSetScrollArrows (
   ListType *listP,
   Boolean visible
)

Parameters

listP
Pointer to a list.
visible
true to have the scroll arrows visible if the list needs scrolling. false to suppress the drawing of scroll arrows. The default is true.

Returns

Nothing.

Comments

You might use this function to suppress the drawing the list's scroll indicators if you want the list to look and behave like a table does or if you have a very large list and want to use a scroll bar rather than the built-in scroll arrows. If you suppress the list's scroll indicators, you are responsible for handling scrolling the list.

LstSetTopItem Function ^TOP^

Purpose

Sets the item to be the top item visible in the list. The item cannot become the top item if it's on the last page.

Declared In

List.h

Prototype

void LstSetTopItem (
   ListType *listP,
   const int16_t itemNum
)

Parameters

listP
Pointer to a list.
itemNum
Item to select. Items are numbered from 0 to LstGetNumberOfItems()–1.

Returns

Nothing.

Comments

Does not update the display.

See Also

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

Application-Defined Functions ^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 (
   int16_t itemNum,
   RectangleType *bounds,
   char **itemsText,
   struct ListType *listP
)

Parameters

itemNum
The number of the item to draw.
bounds
The bounds of the item relative to either the list's window (for a pop-up list) or the form's window (for a regular list). See RectangleType.
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().
listP
A pointer to the list in which the item is to be drawn.

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 and return true. If you don't, FrmHandleEvent() will call LstGetSelectionText() in response to that event.

Note that the list 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.

See Also

LstSetDrawFunction(), UIColorGetTableEntryIndex(), WinSetForeColor()