This chapter describes the category API as declared in the header file Category.h
. It discusses the following topics:
For more information on categories, see the section "Categories" in the Palm OS Programmer's Companion, vol. I.
Category Data Structures
AppInfoPtr Typedef
Purpose
The AppInfoPtr
defines a pointer to an AppInfoType
structure.
Prototype
typedef AppInfoType *AppInfoPtr;
AppInfoType Struct
Purpose
The AppInfoType
structure shown below maps category names to category indexes and unique IDs. To use the category API described in this chapter, a database's application info block must either be an AppInfoType
structure, or it must have an AppInfoType
structure as its first field.
Prototype
typedef struct { UInt16 renamedCategories; Char categoryLabels [dmRecNumCategories] [dmCategoryLength]; UInt8 categoryUniqIDs[dmRecNumCategories]; UInt8 lastUniqID; UInt8 padding; } AppInfoType;
Fields
-
renamedCategories
- Used by
CategorySetName()
as a bit field indicating which categories have been renamed. Usually cleared by a conduit. -
categoryLabels
- An array of strings containing the category names. The maximum size of the array is
dmRecNumCategories
, and the maximum length of each string in the array isdmCategoryLength
. Both of these constants are defined inDataMgr.h
. -
categoryUniqIDs
- Category IDs used for synchronization with the desktop database. Unique IDs generated by the device are between 0 and 127. Unique IDs generated by the desktop computer are between 128 and 255.
-
lastUniqID
- Used for sorting and assigning unique IDs.
Comments
Allocate the application info block in the storage heap and use the DmSetDatabaseInfo()
function to set the database's application info ID to the local ID of this structure. Then, use the CategoryInitialize()
function to initialize it with a localized list of strings containing the category names.
Category Constants
The following category constants are defined:
NOTE: These constants look like system resource IDs, but they are not. To use a non-default string for the "Edit Categories" item you pass a resource ID of a string containing your title. If you want to use the default or hide the item, you pass one of these constants. They are within the system resource ID range (that is, they are greater than 10000) so that they don't conflict with any other possible value for that parameter.
Compatibility
Both categoryHideEditCategory
and categoryDefaultEditCategoryString
are defined only if the 3.5 New Feature Set is present.
Category Functions
CategoryCreateList Function
Purpose
Populate a popup list with a database's categories.
Declared In
Category.h
Prototype
void CategoryCreateList ( DmOpenRef db, ListType *listP, UInt16 currentCategory, Boolean showAll, Boolean showUneditables, UInt8 numUneditableCategories, UInt32 editingStrID, Boolean resizeList )
Parameters
-
→
db
- Open database containing the category information you want to read.
-
←
listP
- Pointer to the
ListType
structure that should display the categories. -
→
currentCategory
- Index of the category to select. The index is the index into the
categoryLabels
array. The default is to have the "Unfiled" category selected. -
→
showAll
-
true
to include an "All" list item. -
→
showUneditables
-
true
to show uneditable categories. -
→
numUneditableCategories
- The number of categories that the user cannot edit. You should store uneditable categories at the beginning of the
categoryLabels
array. For example, it's common to have an "Unfiled" category at position zero that is not editable. This function displays the uneditable categories at the end of the popup list. -
→
editingStrID
- The resource ID of a
tSTR
resource to use as the Edit Categories list item. To use the default string ("Edit Categories") pass the constantcategoryDefaultEditCategoryString
. - If you don't want users to edit categories, pass the
categoryHideEditCategory
constant. -
→
resizeList
-
true
to resize the list to the number of categories. Set totrue
for popups,false
otherwise.
Returns
Comments
The "All" item is first in the list (if the showAll
parameter is true
), followed by the editable categories in the database and then the categories that cannot be edited. The option to edit categories is last in the list and can be suppressed if desired.
You rarely call this function directly. Instead, most applications use CategorySelect()
, which calls this function and fully manages the user's selection of a category in the popup list. Use CategoryCreateList
only if you want more control over the category popup list.
This function obtains the db
parameter's appInfoID
, reads the AppInfoType
structure at that location, and uses the information in it to initialize the listP
's items array with the names of the database's categories. You must have already allocated the structure pointed to by listP
. CategoryCreateList
does not display the list; use LstPopupList()
or LstDrawList()
to do so.
You must balance a call to CategoryCreateList
with a call to CategoryFreeList()
. The CategoryCreateList
function locks the resources for the category names. It also allocates the listP
items array. CategoryFreeList
unlocks all resources locked by CategoryCreateList
and frees all memory allocated by CategoryCreateList
.
Compatibility
Implemented only if 2.0 New Feature Set is present.
The constants categoryDefaultEditCategoryString
and categoryHideEditCategory
are defined only if 3.5 New Feature Set is present. In earlier versions, you can suppress the Edit Categories string by passing 0 for the editingStrID
parameter, or include the item by passing categoryEditStrID
.
See Also
CategoryCreateListV10 Function
Purpose
Read a database's categories and set the category list.
Declared In
Category.h
Prototype
void CategoryCreateListV10 ( DmOpenRef db, ListType *lst, UInt16 currentCategory, Boolean showAll )
Parameters
-
→
db
- Open database containing the category information you want to read.
-
←
lst
- Pointer to the
ListType
that should display the categories. -
→
currentCategory
- Index of the category to select. The index is the index into the
categoryLabels
array. The default is to have the "Unfiled" category selected. -
→
showAll
-
true
to include an "All" list item.
Returns
Compatibility
This function corresponds to the Palm OS® 1.0 version of CategoryCreateList()
. It is obsolete.
CategoryEdit Function
Purpose
Event handler for the Edit Categories dialog.
Declared In
Category.h
Prototype
Boolean CategoryEdit ( DmOpenRef db, UInt16 *category, UInt32 titleStrID, UInt8 numUneditableCategories )
Parameters
-
→
db
- Open database containing the categories to be edited.
-
←
category
- Upon return, the index of the last category selected before the dialog was closed.
-
→
titleStrID
- The resource ID of a
tSTR
resource to use as the dialog's title. To use the default string ("Edit Categories"), pass the constantcategoryDefaultEditCategoryString
. -
→
numUneditableCategories
- The number of categories that the user cannot edit. You should store uneditable categories at the beginning of the
categoryLabels
array. For example, it's common to have an "Unfiled" category at position zero that is not editable.
Returns
Returns true
if any of the following conditions are true
:
- The current category is renamed.
- The current category is deleted.
- The current category is merged with another category.
Comments
You rarely call this function directly. The CategorySelect()
function calls it when the user chooses the Edit Category list item.
This function both displays the Edit Categories dialog and handles the result of the user actions. It updates the AppInfoType
structure's list of categories and reassigns database records to new categories as needed. If a user deletes a category, CategoryEdit
moves all of the records belonging to that category to the Unfiled category. If a category is renamed to be the same as an existing category, this function moves all of the old category's records to the new category.
Compatibility
Implemented only if 3.0 New Feature Set is present.
See Also
CategoryEditV20()
, CategoryEditV10()
, DmMoveCategory()
CategoryEditV20 Function
Purpose
Event handler for the Edit Categories dialog.
Declared In
Category.h
Prototype
Boolean CategoryEditV20 ( DmOpenRef db, UInt16 *category, UInt32 titleStrID )
Parameters
-
→
db
- Database containing the categories to be edited.
-
←
category
- Upon return, the last category selected before the dialog was closed.
-
→
titleStrID
- The resource ID of a
tSTR
resource to use as the dialog's title.
Returns
Returns true
if any of the following conditions are true
:
- The current category is renamed.
- The current category is deleted.
- The current category is merged with another category.
Compatibility
This function corresponds to the Palm OS 2.0 version of CategoryEdit
. Implemented only if 2.0 New Feature Set is present. This function is obsolete.
See Also
CategoryEdit()
, CategoryEditV10()
CategoryEditV10 Function
Purpose
Event handler for the Edit Categories dialog.
Declared In
Category.h
Prototype
Boolean CategoryEditV10 ( DmOpenRef db, UInt16 *category )
Parameters
-
→
db
- Open database containing the categories to be edited.
-
←
category
- Upon return, the last category selected before the dialog was closed.
Returns
Returns true
if any of the following conditions are true:
- The current category is renamed.
- The current category is deleted.
- The current category is merged with another category.
Compatibility
This function corresponds to the Palm OS 1.0 version of CategoryEdit
. It is obsolete.
See Also
CategoryEdit()
, CategoryEditV20()
CategoryFind Function
Purpose
Return the index of a category given its name.
Declared In
Category.h
Prototype
UInt16 CategoryFind ( DmOpenRef db, const Char *name )
Parameters
-
→
db
- Open database to search.
-
→
name
- Category name. Pass the empty string to find the first unused category.
Returns
Returns the index of the category's entry in the categoryLabels
array (see AppInfoType
). Returns dmAllCategories
if the category does not exist.
CategoryFreeList Function
Purpose
Unlock or free memory locked or allocated by CategoryCreateList()
.
Declared In
Category.h
Prototype
void CategoryFreeList ( DmOpenRef db, ListType *listP, Boolean showAll, UInt32 editingStrID )
Parameters
-
→
db
- Open database containing the categories.
-
→
listP
- Pointer to the category list. (See
ListType
.) -
→
showAll
-
true
if the list was created with an "All" category. -
→
editingStrID
- The resource ID that you passed as the
editingStrID
parameter toCategoryCreateList()
. This function unlocks the resource.
Returns
Comments
You only need to call this function if you explicitly call CategoryCreateList()
. Typical applications call CategorySelect
, which handles both the creation and deletion of the list.
This function frees the items in the popup list listP
's items array and it unlocks other resources that CategoryCreateList
may have locked.
This function does not remove the categories from the passed database, and it does not free the ListType
structure pointed to by listP
. (Typically, a list is freed when its form is freed.)
Compatibility
Implemented only if 2.0 New Feature Set is present.
See Also
CategoryFreeListV10 Function
Purpose
Unlock or free memory locked or allocated by CategoryCreateListV10()
.
Declared In
Category.h
Prototype
void CategoryFreeListV10 ( DmOpenRef db, ListType *lst )
Parameters
-
→
db
- Open database containing the categories.
-
→
listP
- Pointer to the category list. (See
ListType
.)
Returns
Compatibility
This function corresponds to the Palm OS 1.0 version of CategoryFreeList
. It is obsolete.
See Also
CategoryGetName Function
Purpose
Return the name of the specified category.
Declared In
Category.h
Prototype
void CategoryGetName ( DmOpenRef db, UInt16 index, Char *name )
Parameters
-
→
db
- Database that contains the categories.
-
→
index
- Category index. This is the index into the
categoryLabels
array in theAppInfoType
structure. You can retrieve this index from a database record's attribute word. -
←
name
- Buffer to hold category name. Buffer should be
dmCategoryLength
in size.
Returns
Stores the category name in the name
buffer passed.
May display a fatal error message if the index is out of range.
Comments
You can use this function to find out the name of a given database record's category. Use the DmRecordInfo()
call to obtain the category index from the given record. For example:
DmOpenRef myDB; UInt16 record, attr, category; Char *name; DmRecordInfo(myDB, record, &attr, NULL, NULL); category = attr & dmRecAttrCategoryMask; CategoryGetName(myDB, category, name);
The category's name is copied into the variable you pass for the name
parameter.
See Also
CategoryGetNext Function
Purpose
Return the index of the next category after a given category.
Declared In
Category.h
Prototype
UInt16 CategoryGetNext ( DmOpenRef db, UInt16 index )
Parameters
Returns
Category index of next category.
Comments
The intended use of this function is to allow your users to cycle through categories. For example, the built-in applications cycle through categories when the user presses the corresponding hard-key button. (See the ListViewNextCategory
function in the Address Book sample application for an example.) Note that categories are not displayed in the same order as they are stored.
Do not use this function for searching for a particular category or iterating through a category list.
Compatibility
In Palm OS 1.0, the system chose Unfiled
as one category.
In Palm OS 2.0 and later, the system skips both Unfiled
and categories with empty records.
CategoryInitialize Function
Purpose
Initialize the category names, IDs, and flags.
Declared In
Category.h
Prototype
void CategoryInitialize ( AppInfoPtr appInfoP, UInt16 localizedAppInfoStrID )
Parameters
-
→
appInfoP
- Pointer to the locked application info block. See
AppInfoType
. -
→
localizedAppInfoStrID
- Resource ID of the localized category names. This must be a resource of the type
appInfoStringsRsc
('tAIS'
).
Returns
Comments
Call this function at database creation time to initialize the database's categories from a list of localized strings.
CategoryInitialize
initializes the AppInfoType
structure that is associated with your database. It does not create the structure. To create the structure, you must allocate it in the storage heap (using DmNewHandle()
) and associate it with your database using DmSetDatabaseInfo()
.
Compatibility
Implemented only if 2.0 New Feature Set is present.
CategorySelect Function
Purpose
Process the selection and editing of categories.
Declared In
Category.h
Prototype
Boolean CategorySelect ( DmOpenRef db, const FormType *frm, UInt16 ctlID, UInt16 lstID, Boolean title, UInt16 *categoryP, Char *categoryName, UInt8 numUneditableCategories, UInt32 editingStrID )
Parameters
-
→
db
- Open database containing the categories.
-
→
frm
- Form that contains the category popup list.
-
→
ctlID
- ID of the popup trigger.
-
→
lstID
- ID of the popup list.
-
→
title
-
true
to have an "All" list item. (In general, if the trigger is in the form's title bar, it should have an "All" item. If the trigger is elsewhere in the form, it should not.) -
↔
categoryP
- Index of the selected category. The index is the index into the
categoryLabels
array. -
↔
categoryName
- Name of the selected category.
-
→
numUneditableCategories
- The number of categories that the user cannot edit. You should store uneditable categories at the beginning of the
categoryLabels
array. For example, it's common to have an "Unfiled" category at position zero that is not editable. This function displays the uneditable categories at the end of the popup list. -
→
editingStrID
- The resource ID of a
tSTR
resource to use as the Edit Categories list item. To use the default string ("Edit Categories"), pass the constantcategoryDefaultEditCategoryString
. - If you don't want users to edit categories, pass the
categoryHideEditCategory
constant.
Returns
Returns true
if any of the following conditions are true:
- The current category is renamed.
- The current category is deleted.
- The current category is merged with another category.
Comments
Call this function when the user taps the category popup trigger. This function handles all aspects of displaying the popup list and managing the user selection—It creates the popup list using CategoryCreateList()
, displays the popup list, calls CategoryEdit()
if the user selects the Edit Categories item, uses CategorySetTriggerLabel()
to set the trigger label to the item the user selected, and then calls CategoryFreeList()
to free the list items array. Your application is responsible for checking the value of categoryP
upon return and updating the display or changing the record's category to the new selection.
Compatibility
Implemented only if 2.0 New Feature Set is present.
The constants categoryDefaultEditCategoryString
and categoryHideEditCategory
are defined only if 3.5 New Feature Set is present. In earlier versions, you can suppress the Edit Categories string by passing 0 for the editingStrID
parameter, or include the item by passing categoryEditStrID
.
See Also
CategorySelectV10 Function
Purpose
Process the selection and editing of categories.
Declared In
Category.h
Prototype
Boolean CategorySelectV10 ( DmOpenRef db, const FormType *frm, UInt16 ctlID, UInt16 lstID, Boolean title, UInt16 *categoryP, Char *categoryName )
Parameters
-
→
db
- Open database containing the categories.
-
→
frm
- Form that contains the category popup list.
-
→
ctlID
- ID of the popup trigger.
-
→
lstID
- ID of the popup list.
-
→
title
-
true
to have an "All" list item. (In general, if the trigger is in the form's title bar, it should have an "All" item. If the trigger is elsewhere in the form, it should not.) -
↔
categoryP
- Index of the selected category. The index is the index into the
categoryLabels
array. -
↔
categoryName
- Name of the selected category.
Returns
Returns true
if any of the following conditions are true:
- The current category is renamed.
- The current category is deleted.
- The current category is merged with another category.
Compatibility
This function corresponds to the Palm OS 1.0 version of CategorySelect()
. It is obsolete.
CategorySetName Function
Purpose
Change the category name in the AppInfoType
structure, or delete a category.
Declared In
Category.h
Prototype
void CategorySetName ( DmOpenRef db, UInt16 index, const Char *nameP )
Parameters
-
→
db
- Open database containing the category to change.
-
→
index
- Index of category to rename.
-
→
nameP
- The new category name (null-terminated), or
NULL
to delete the category.
Returns
Comments
The CategoryEdit()
function calls this function when a user creates a new category or renames an existing category in the Edit Categories dialog. Your application does not have to call it directly.
Compatibility
Implemented only if 2.0 New Feature Set is present.
CategorySetTriggerLabel Function
Purpose
Set the label displayed by the category popup trigger.
Declared In
Category.h
Prototype
void CategorySetTriggerLabel ( ControlType *ctl, Char *name )
Parameters
-
↔
ctl
- Pointer to control object (popup trigger) to relabel.
-
↔
name
- Pointer to the name of the new category.
Returns
Comments
The CategorySetTriggerLabel
function calls the CategoryTruncateName()
function to truncate the category name to the maximum length. The maximum length varies, depending upon which ROM is installed in the device.
NOTE: This function passes the
name
parameter to the CategoryTruncateName
function, which means that the name
value must be modifiable. CategorySetTriggerLabel
does not make a copy of the string passed, so you must ensure that the string remains valid until the form is closed.
See Also
CategoryTruncateName Function
Purpose
Truncate a category name so that it's short enough to display. The category name is truncated if it's longer than maxWidth
.
Declared In
Category.h
Prototype
void CategoryTruncateName ( Char *name, UInt16 maxWidth )
Parameters
-
↔
name
- Category name to truncate. Upon return, contains the truncated name.
-
→
maxWidth
- Maximum size, in pixels, of truncated category (including ellipsis).