Categories
 

 < Home   < Developers   < Development Support   < Documentation

5 Categories


 Table of Contents  |  < Previous  |  Next >  |  Index
   
   

Title -
Palm OS® Programmer's API Reference

Part I: User Interface

5 Categories

Category Data Structures

AppInfoPtr

AppInfoType

Category Constants

Category Functions

CategoryCreateList

CategoryCreateListV10

CategoryEdit

CategoryEditV20

CategoryEditV10

CategoryFind

CategoryFreeList

CategoryFreeListV10

CategoryGetName

CategoryGetNext

CategoryInitialize

CategorySelect

CategorySelectV10

CategorySetName

CategorySetTriggerLabel

CategoryTruncateName

       

This chapter describes the category API as declared in the header file Category.h. It discusses the following topics:

Category Data Structures

Category Constants

Category Functions

For more information on categories, see the section "Categories" in the Palm OS Programmer's Companion, vol. I.

Category Data Structures

AppInfoPtr

The AppInfoPtr defines a pointer to an AppInfoType structure.

typedef AppInfoType *AppInfoPtr; 

AppInfoType

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.

typedef struct { 
  UInt16   renamedCategories; 
  Char    categoryLabels [dmRecNumCategories]
            [dmCategoryLength]; 
  UInt8    categoryUniqIDs[dmRecNumCategories]; 
  UInt8    lastUniqID; 
  UInt8    padding; 
} AppInfoType; 

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.

Field Descriptions

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 is dmCategoryLength. Both of these constants are defined in DataMgr.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.

Category Constants

The following category constants are defined:

Constant
Value
Description
categoryHideEditCategory
10000
Used to suppress the "Edit Categories" item.
categoryDefaultEditCategoryString
10001
Used to show the default "Edit Categories" item.

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

Purpose

Populate a popup list with a database's categories.

Prototype

void CategoryCreateList (DmOpenRef db, ListType *listP, UInt16 currentCategory, Boolean showAll, Boolean showUneditables, UInt8 numUneditableCategories, UInt32 editingStrID, Boolean resizeList)

Parameters

-> dbOpen database containing the category information you want to read.
<- listPPointer to the ListType structure that should display the categories.
-> currentCategoryIndex of the category to select. The index is the index into the categoryLabels array. The default is to have the "Unfiled" category selected.
-> showAlltrue to include an "All" list item.
-> showUneditables true to show uneditable categories.
-> numUneditableCategoriesThe 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.
-> editingStrIDThe resource ID of a tSTR resource to use as the Edit Categories list item. To use the default string ("Edit Categories") pass the constant categoryDefaultEditCategoryString.
If you don't want users to edit categories, pass the categoryHideEditCategory constant.
-> resizeListtrue to resize the list to the number of categories. Set to true for popups, false otherwise.

Result

Returns nothing.

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

CategoryCreateListV10

Purpose

Read a database's categories and set the category list.

Prototype

void CategoryCreateListV10 (DmOpenRef db, ListType *lst, UInt16 currentCategory, Boolean showAll)

Parameters

-> dbOpen database containing the category information you want to read.
<- lstPointer to the ListType that should display the categories.
-> currentCategoryIndex of the category to select. The index is the index into the categoryLabels array. The default is to have the "Unfiled" category selected.
-> showAlltrue to include an "All" list item.

Result

Returns nothing.

Compatibility

This function corresponds to the Palm OS® 1.0 version of CategoryCreateList. It is obsolete.

CategoryEdit

Purpose

Event handler for the Edit Categories dialog.

Prototype

Boolean CategoryEdit (DmOpenRef db, UInt16 *category, UInt32 titleStrID, UInt8 numUneditableCategories)

Parameters

-> dbOpen database containing the categories to be edited.
<- categoryUpon return, the index of the last category selected before the dialog was closed.
-> titleStrIDThe resource ID of a tSTR resource to use as the dialog's title. To use the default string ("Edit Categories"), pass the constant categoryDefaultEditCategoryString.
-> numUneditableCategoriesThe 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.

Result

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

Purpose

Event handler for the Edit Categories dialog.

Prototype

Boolean CategoryEditV20 (DmOpenRef db, UInt16 *category, UInt32 titleStrID)

Parameters

-> dbDatabase containing the categories to be edited.
<- categoryUpon return, the last category selected before the dialog was closed.
-> titleStrIDThe resource ID of a tSTR resource to use as the dialog's title.

Result

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

Purpose

Event handler for the Edit Categories dialog.

Prototype

Boolean CategoryEditV10 (DmOpenRef db, UInt16 *category)

Parameters

-> dbOpen database containing the categories to be edited.
<- categoryUpon return, the last category selected before the dialog was closed.

Result

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

Purpose

Return the index of a category given its name.

Prototype

UInt16 CategoryFind (DmOpenRef db, const Char *name)

Parameters

-> dbOpen database to search.
-> nameCategory name. Pass the empty string to find the first unused category.

Result

Returns the index of the category's entry in the categoryLabels array (see AppInfoType). Returns dmAllCategories if the category does not exist.

CategoryFreeList

Purpose

Unlock or free memory locked or allocated by CategoryCreateList.

Prototype

void CategoryFreeList (DmOpenRef db, ListType *listP, Boolean showAll, UInt32 editingStrID)

Parameters

-> dbOpen database containing the categories.
-> listPPointer to the category list. (See ListType.)
-> showAlltrue if the list was created with an "All" category.
-> editingStrIDThe resource ID that you passed as the editingStrID parameter to CategoryCreateList. This function unlocks the resource.

Result

Returns nothing.

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

CategoryFreeListV10

Purpose

Unlock or free memory locked or allocated by CategoryCreateListV10.

Prototype

void CategoryFreeListV10 (DmOpenRef db, ListType *lst)

Parameters

-> dbOpen database containing the categories.
-> listPPointer to the category list. (See ListType.)

Result

Returns nothing.

Compatibility

This function corresponds to the Palm OS 1.0 version of CategoryFreeList. It is obsolete.

See Also

CategoryFreeList

CategoryGetName

Purpose

Return the name of the specified category.

Prototype

void CategoryGetName (DmOpenRef db, UInt16 index, Char *name)

Parameters

-> dbDatabase that contains the categories.
-> indexCategory index. This is the index into the categoryLabels array in the AppInfoType structure. You can retrieve this index from a database record's attribute word.
<- nameBuffer to hold category name. Buffer should be dmCategoryLength in size.

Result

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

CategorySetName

CategoryGetNext

Purpose

Return the index of the next category after a given category.

Prototype

UInt16 CategoryGetNext (DmOpenRef db, UInt16 index)

Parameters

-> dbOpen database containing the categories.
-> indexCategory index.

Result

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

Purpose

Initialize the category names, IDs, and flags.

Prototype

void CategoryInitialize (AppInfoPtr appInfoP, UInt16 localizedAppInfoStrID)

Parameters

->appInfoPPointer to the locked application info block. See AppInfoType.
->localizedAppInfoStrIDResource ID of the localized category names. This must be a resource of the type appInfoStringsRsc ('tAIS').

Result

Returns nothing.

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

Purpose

Process the selection and editing of categories.

Prototype

Boolean CategorySelect (DmOpenRef db, const FormType *frm, UInt16 ctlID, UInt16 lstID, Boolean title, UInt16 *categoryP, Char *categoryName, UInt8 numUneditableCategories, UInt32 editingStrID)

Parameters

-> dbOpen database containing the categories.
-> frmForm that contains the category popup list.
-> ctlIDID of the popup trigger.
-> lstIDID of the popup list.
-> titletrue 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.)
<-> categoryPIndex of the selected category. The index is the index into the categoryLabels array.
<-> categoryNameName of the selected category.
-> numUneditableCategoriesThe 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.
-> editingStrIDThe resource ID of a tSTR resource to use as the Edit Categories list item. To use the default string ("Edit Categories"), pass the constant categoryDefaultEditCategoryString.
If you don't want users to edit categories, pass the categoryHideEditCategory constant.

Result

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

CategorySelectV10

Purpose

Process the selection and editing of categories.

Prototype

Boolean CategorySelectV10 (DmOpenRef db, const FormType *frm, UInt16 ctlID, UInt16 lstID, Boolean title, UInt16 *categoryP, Char *categoryName)

Parameters

-> dbOpen database containing the categories.
-> frmForm that contains the category popup list.
-> ctlIDID of the popup trigger.
-> lstIDID of the popup list.
-> titletrue 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.)
<-> categoryPIndex of the selected category. The index is the index into the categoryLabels array.
<-> categoryNameName of the selected category.

Result

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

Purpose

Change the category name in the AppInfoType structure, or delete a category.

Prototype

void CategorySetName (DmOpenRef db, UInt16 index, const Char *nameP)

Parameters

-> dbOpen database containing the category to change.
-> indexIndex of category to rename.
-> namePThe new category name (null-terminated), or NULL to delete the category.

Result

Returns nothing.

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

Purpose

Set the label displayed by the category popup trigger.

Prototype

void CategorySetTriggerLabel (ControlType *ctl, Char *name)

Parameters

<-> ctlPointer to control object (popup trigger) to relabel.
<-> namePointer to the name of the new category.

Result

Returns nothing.

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. (The resource maxCategoryWidthID contains this value. You can check the value of this resource using ResLoadConstant.)


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

CtlSetLabel

CategoryTruncateName

Purpose

Truncate a category name so that it's short enough to display. The category name is truncated if it's longer than maxWidth.

Prototype

void CategoryTruncateName (Char *name, UInt16 maxWidth)

Parameters

<-> nameCategory name to truncate. Upon return, contains the truncated name.
-> maxWidthMaximum size, in pixels, of truncated category (including ellipsis).

Result

Returns nothing.