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
ListType Struct
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
List Constants
List Constants
Purpose
Declared In
List.h
Constants
List Events
lstEnterEvent
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
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
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
lstSelectEvent
Purpose
Sent when the stylus had previously entered the bounds of the list and is now lifted within 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 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
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
LstDrawList Function
Purpose
Makes the list visible and draws the list.
Declared In
List.h
Prototype
void LstDrawList (
ListType *listP
)
Parameters
Returns
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
Purpose
Declared In
List.h
Prototype
void LstEraseList (
ListType *listP
)
Parameters
Returns
See Also
FrmGetObjectPtr()
, LstDrawList()
LstGetFont Function
Purpose
Gets the font used to draw a list's text strings.
Declared In
List.h
Prototype
FontID LstGetFont (
const ListType *listP
)
Parameters
Returns
The ID of the font used to draw all list text strings.
See Also
LstGetItemsText Function
Purpose
Gets the text strings that represent the items in a list.
Declared In
List.h
Prototype
char **LstGetItemsText (
const ListType *listP
)
Parameters
Returns
A pointer to an array of pointers to the text of the list choices.
See Also
LstGetSelectionText()
, LstSetListChoices()
LstGetNumberOfItems Function
Purpose
Returns the number of items in a list.
Declared In
List.h
Prototype
int16_t LstGetNumberOfItems (
const ListType *listP
)
Parameters
Returns
The number of items in a list.
See Also
FrmGetObjectPtr()
, LstSetListChoices()
LstGetSelection Function
Purpose
Returns the currently selected choice in the list.
Declared In
List.h
Prototype
int16_t LstGetSelection (
const ListType *listP
)
Parameters
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
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_titemNum
)
Parameters
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
LstGetTopItem Function
Purpose
Returns the topmost visible item.
Declared In
List.h
Prototype
int16_t LstGetTopItem (
const ListType *listP
)
Parameters
Returns
The item number of the top item that is visible.
See Also
LstGetSelection()
, LstSetTopItem()
LstGetVisibleItems Function
Purpose
Returns the number of visible items.
Declared In
List.h
Prototype
int16_t LstGetVisibleItems (
const ListType *listP
)
Parameters
Returns
LstHandleEvent Function
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 thelstEnterEvent
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 alstSelectEvent
. Otherwise, it enqueues alstExitEvent
. - 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
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_titemNum
)
Parameters
-
→ listP
- Pointer to a list.
-
→ itemNum
- Item to select. Items are numbered from 0 to
LstGetNumberOfItems()
–1.
Returns
Comments
Does not visually update the list.
See Also
FrmGetObjectPtr()
, LstSetSelection()
, LstSetTopItem()
, LstDrawList()
LstNewList Function
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_tid
, Coordx
, Coordy
, Coordwidth
, Coordheight
, FontIDfont
, int16_tvisibleItems
, int16_ttriggerId
)
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 newformPP
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 fortriggerId
.
Returns
See Also
LstDrawList()
, FrmRemoveObject()
LstPopupList Function
Purpose
Displays a modal window that contains the items in the list.
Declared In
List.h
Prototype
int16_t LstPopupList (
ListType *listP
)
Parameters
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
LstScrollList Function
Purpose
Scrolls the list up or down a number of times.
Declared In
List.h
Prototype
Boolean LstScrollList ( ListType*listP
, WinDirectionTypedirection
, int16_titemCount
)
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
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
, ListDrawDataFuncPtrfunc
)
Parameters
-
→ listP
- Pointer to a list.
-
→ func
- Pointer to a function that draws items. See
ListDrawDataFuncType()
.
Returns
See Also
FrmGetObjectPtr()
, LstSetListChoices()
, ListDrawDataFuncType()
LstSetFont Function
Purpose
Specifies the font to be used to draw a list's text strings.
Declared In
List.h
Prototype
void LstSetFont ( ListType*listP
, FontIDfontID
)
Parameters
Returns
See Also
LstSetHeight Function
Purpose
Sets the number of items visible in a list.
Declared In
List.h
Prototype
void LstSetHeight ( ListType*listP
, int16_tvisibleItems
)
Parameters
Returns
Comments
This function doesn't redraw the list if it's already visible.
See Also
LstSetIncrementalSearch Function
Purpose
Enables or disables incremental search for a sorted pop-up list.
Declared In
List.h
Prototype
void LstSetIncrementalSearch ( ListType*listP
, BooleanincrementalSearch
)
Parameters
-
→ listP
- Pointer to a list.
-
→ incrementalSearch
- Set to
true
to enable incremental search,false
to disable it.
Returns
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
toLstSetListChoices()
).
LstSetListChoices Function
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_tnumItems
)
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
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
Purpose
Declared In
List.h
Prototype
void LstSetPosition ( ListType*listP
, const Coordx
, const Coordy
)
Parameters
Returns
Comments
The list is not redrawn. Don't call this function when the list is visible.
LstSetSelection Function
Purpose
Sets the selection for a list.
Declared In
List.h
Prototype
void LstSetSelection ( ListType*listP
, int16_titemNum
)
Parameters
-
→ listP
- Pointer to a list.
-
→ itemNum
- Item to select. Items are numbered from 0 to
LstGetNumberOfItems()
–1. SpecifynoListSelection
if you want to deselect all list items.
Returns
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
Purpose
Enables or disables the drawing of the list's scroll arrows.
Declared In
List.h
Prototype
void LstSetScrollArrows ( ListType *listP
, Booleanvisible
)
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 istrue
.
Returns
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
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_titemNum
)
Parameters
-
→ listP
- Pointer to a list.
-
→ itemNum
- Item to select. Items are numbered from 0 to
LstGetNumberOfItems()
–1.
Returns
Comments
See Also
FrmGetObjectPtr()
, LstSetSelection()
, LstGetTopItem()
, LstMakeItemVisible()
, LstDrawList()
, LstEraseList()
Application-Defined Functions
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
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_titemNum
, 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
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()