This chapter describes the category API as declared in the header file CatMgr.h
. It discusses the following topics:
Category Manager Structures and Types
Category Manager Constants
Category Manager Functions and Macros
For more information on categories, see the section "Category Controls".
Category Manager Structures and Types
AppInfoType Struct
Purpose
Maps category names to category indexes and unique IDs. The AppInfoPtr
defines a pointer to an AppInfoType
structure.
Declared In
CatMgr.h
Prototype
typedef struct AppInfoTag { uint16_t renamedCategories; char categoryLabels [dmRecNumCategories] [dmCategoryLength]; uint8_t categoryUniqIDs[dmRecNumCategories]; uint8_t lastUniqID; uint8_t padding; } AppInfoType;
typedef AppInfoType *AppInfoPtr
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.
-
padding
- Reserved for future use.
Comments
The AppInfoType
structure is used in non-schema databases. A non-schema database's application info block must either be an AppInfoType
structure, or it must have an AppInfoType
structure as its first field if you want to use the functions described in this chapter to manage the user interface elements associated with categories.
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 Manager Constants
Category ID Range Constants
Purpose
Specify the range of valid values for category IDs in schema databases.
Declared In
CatMgr.h
Constants
-
#define catCategoryIDNegativeLowerBound ((CategoryID)0x80000001)
- The lowest possible private category ID.
-
#define catCategoryIDNegativeUpperBound ((CategoryID)0xfffffffe)
- The highest possible private category ID.
-
#define catCategoryIDPositiveLowerBound ((CategoryID)0x00000010)
- The lowest possible public category ID.
-
#define catCategoryIDPositiveUpperBound ((CategoryID)0x7fffffff)
- The highest possible public category ID.
Error Code Constants
Purpose
Error codes returned by Category Manager functions.
Declared In
CatMgr.h
Constants
-
#define catmErrAISResourceNotFound (catmErrorClass | 9)
- The app info strings resource used to initialize the categories in the database cannot be found.
-
#define catmErrCantFind (catmErrorClass | 3)
- The specified category could not be found.
-
#define catmErrCategoryNotFound (catmErrorClass | 5)
- The specified category could not be found.
-
#define catmErrIndexOutOfRange (catmErrorClass | 4)
- An error occurred while iterating through a list of categories.
-
#define catmErrInvalidParam (catmErrorClass | 2)
- An invalid parameter was passed to a function.
-
#define catmErrInvalidStoragePtr (catmErrorClass | 7)
- The category information in the database cannot be accessed.
-
#define catmErrMaxCategoryLimit (catmErrorClass | 8)
- An attempt was made to add more categories to a database than is allowed.
-
#define catmErrMemError (catmErrorClass | 1)
- Not enough memory to perform the requested operation.
-
#define catmErrNameAlreadyExists (catmErrorClass | 6)
- An attempt was made to add a new category or rename a category, but a category with that name already exists.
-
#define catmErrNotSchemaDatabase (catmErrorClass | 10)
- A schema database Category Manager call was passed the handle to a non-schema database.
-
#define catmErrReadOnlyDatabase (catmErrorClass | 11)
- The schema database must be opened for write access for this function.
Non-schema Database Category Constants
Purpose
Constants used by the non-schema database Category Manager functions.
Declared In
CatMgr.h
Constants
-
#define categoryDefaultEditCategoryString 10001
- Used to show the default "Edit Categories" item.
-
#define categoryHideEditCategory 10000
- Used to suppress the "Edit Categories" item.
Comments
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.
Special Category ID Constants
Purpose
Represent items that a user might select in a category pop-up list but that are not actual categories. The CatMgrSelectEdit()
and CatMgrSelectFilter()
might return these IDs as the user selection.
Declared In
CatMgr.h
Constants
-
#define catIDAll ((CategoryID)0x01)
- The "All" list item. The record should belong to all categories, or all records should be displayed.
-
#define catIDMultiple ((CategoryID)0x02)
- The "Multiple" list item. Users select this list item to assign more than one category to a record.
-
#define catIDUnfiled ((CategoryID)0x00)
- The "Unfiled" list item. The name of this category is stored as category ID 0 in each schema database.
See Also
CatMgrGetAllItemLabel()
, CatMgrGetUnfiledItemLabel()
Miscellaneous Schema Database Category Constants
Purpose
Other constants defined in CatMgr.h
.
Declared In
CatMgr.h
Constants
-
#define catCategoryNameLength 0x20
- The size of a category name. Strings that hold the category name must be at least this size.
-
#define CategoryNameReserved 10021
- Resource ID of an alert displayed if the user attempts to rename uneditable categories.
-
#define catNumCategories 0xff
- The maximum number of categories allowed in a schema database.
Category Manager Functions and Macros
CategoryCreateList Function
Purpose
Populates a pop-up list with a non-schema database's categories.
Declared In
CatMgr.h
Prototype
void CategoryCreateList ( DmOpenRefdb
, ListType*listP
, uint16_tcurrentCategory
, BooleanshowAll
, BooleanshowUneditables
, uint8_tnumUneditableCategories
, DmOpenRefresDbRef
, uint32_teditingStrID
, BooleanresizeList
)
Parameters
-
→ db
- Open non-schema database containing the category information you want to read.
-
←
listP
- Pointer to the
ListType
that is populated with the database's 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 pop-up list. -
→ resDbRef
- Open resource database containing the string resource.
-
→ editingStrID
- The resource ID of a string resource to use as the Edit Categories list item. To use the default string for the current locale (such as "Edit Categories") pass the constant
categoryDefaultEditCategoryString
. - 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 pop-ups,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 pop-up list. Use CategoryCreateList()
only if you want more control over the category pop-up 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.
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()
.
CategoryEdit Function
Purpose
Event handler for the Edit Categories dialog for non-schema databases.
Declared In
CatMgr.h
Prototype
Boolean CategoryEdit ( DmOpenRefdb
, uint16_t*categoryP
, DmOpenRefresDbRef
, uint32_ttitleStrID
, uint8_tnumUneditableCategories
)
Parameters
-
→ db
- Open non-schema database containing the categories to be edited.
-
←
category
- Upon return, the index of the last category selected before the dialog was closed.
-
→ resDbRef
- Open resource database containing the string resource.
-
→ titleStrID
- The resource ID of a string resource to use as the dialog's title. To use the default string ("Edit Categories"), pass the constant
categoryDefaultEditCategoryString
. -
→ 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
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.
See Also
CategoryEdit()
, DmMoveCategory()
CategoryFind Function
Purpose
Returns the index of a category in a non-schema database given its name.
Declared In
CatMgr.h
Prototype
uint16_t CategoryFind ( DmOpenRefdb
, const char*name
)
Parameters
-
→ db
- Open non-schema database to search.
-
→
name
- Category name. Pass the empty string to find the first unused category.
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
Unlocks or frees memory locked or allocated by CategoryCreateList()
.
Declared In
CatMgr.h
Prototype
void CategoryFreeList ( DmOpenRefdb
, const ListType*listP
, BooleanshowAll
, uint32_teditingStrID
)
Parameters
-
→ db
- Open non-schema database containing the categories.
-
→
listP
- Pointer to the category list.
-
→
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 pop-up 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.)
CategoryGetName Function
Purpose
Returns the name of the specified category in a non-schema database.
Declared In
CatMgr.h
Prototype
void CategoryGetName ( DmOpenRefdb
, uint16_tindex
, char*name
)
Parameters
-
→ db
- Open non-schema 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
Nothing. May display a fatal error message if the index is out of range.
Example
You can use this function to find out the name of a given database record's category. Use the DmGetRecordCategory()
call to obtain the category index from the given record. For example:
DmOpenRef myDB; uint16_t category; Char *name; DmGetRecordCategory (AddrDB, CurrentRecord, &category); CategoryGetName(myDB, category, name);
See Also
CategoryGetNext Function
Purpose
Returns the index of the next category after a given category in a non-schema database.
Declared In
CatMgr.h
Prototype
uint16_t CategoryGetNext ( DmOpenRefdb
, uint16_tindex
)
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.
CategoryInitialize Function
Purpose
Initializes the category names, IDs, and flags for a non-schema database.
Declared In
CatMgr.h
Prototype
void CategoryInitialize ( AppInfoPtrappInfoP
, DmOpenRefresDbRef
, uint16_tlocalizedAppInfoStrID
)
Parameters
-
→ appInfoP
- Pointer to the locked application info block. See
AppInfoType
. -
→ resDbRef
- Open resource database containing the app info strings resource.
-
→ 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()
.
CategorySelect Function
Purpose
Processes the selection and editing of categories for a non-schema database.
Declared In
CatMgr.h
Prototype
Boolean CategorySelect ( DmOpenRefdb
, const FormType*frm
, uint16_tctlID
, uint16_tlstID
, BooleanshowAll
, uint16_t*categoryP
, char*categoryName
, uint8_tnumUneditableCategories
, DmOpenRefresDbRef
, uint32_teditingStrID
)
Parameters
-
→ db
- Open database containing the categories.
-
→
frm
- Form that contains the category pop-up list.
-
→ ctlID
- Resource ID of the pop-up trigger.
-
→ lstID
- Resource ID of the pop-up list.
-
→ showAll
-
true
to have an "All" list item. In general, if the form displays multiple records, it should have an "All" list item. If the form displays a single database record, 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 pop-up list. -
→ resDbRef
- Open resource database containing the string resource.
-
→ editingStrID
- The resource ID of a string 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.
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 pop-up trigger. This function handles all aspects of displaying the pop-up list and managing the user selection—It creates the pop-up list using CategoryCreateList()
, displays the pop-up 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.
CategorySetName Function
Purpose
Changes the category name in the AppInfoType
structure of a non-schema database, or deletes a category.
Declared In
CatMgr.h
Prototype
void CategorySetName ( DmOpenRefdb
, uint16_tindex
, const char*nameP
)
Parameters
-
→ db
- Open non-schema 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.
CategorySetTriggerLabel Function
Purpose
Sets the label displayed by the category pop-up trigger for a non-schema database.
Declared In
CatMgr.h
Prototype
void CategorySetTriggerLabel ( ControlType*ctl
, char*name
)
Parameters
-
↔
ctl
- Pointer to control (pop-up or selector 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
Truncates a category name from a non-schema database so that it's short enough to display. The category name is truncated if it's longer than maxWidth
.
Declared In
CatMgr.h
Prototype
void CategoryTruncateName ( char*name
, uint16_tmaxWidth
)
Parameters
-
↔
name
- Category name to truncate. Upon return, contains the truncated name.
-
→ maxWidth
- Maximum size, in standard coordinates, of truncated category (including ellipsis).
Returns
CatMgrAdd Function
Purpose
Creates a category and adds it to a schema database.
Declared In
CatMgr.h
Prototype
status_t CatMgrAdd ( DmOpenRefdbP
, const char*nameP
, CategoryID*catIDP
)
Parameters
-
→ dbP
- Open schema database.
-
→ nameP
- The name of the new category.
-
← catIDP
- The ID that this function assigned to the new category.
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
-
dbP
ornameP
isNULL
. -
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
catmErrMemError
- There is not enough memory to complete the operation.
-
catmErrMaxCategoryLimit
- The database already contains the maximum number of categories allowed.
-
catmErrNameAlreadyExists
-
nameP
is already used by another category.
Comments
Typical applications do not call this function. Instead, use CatMgrInitialize()
to initialize the database with default categories stored in an application's resource database, and use CatMgrSelectEdit()
and CatMgrSelectFilter()
to allow the user to edit the categories list. These functions add categories to the schema database as necessary.
Example
The following code shows how to create an uneditable category.
CategoryID catID; dbRef = DbOpenDatabase(dbID, dmModeReadWrite, dbShareNone); err = CatMgrAdd(dbRef, "category name", &catID); if (err == errNone) CatMgrSetEditable(dbref, catID, false);
See Also
CatMgrCreateList Function
Purpose
Populates a pop-up list with a schema database's categories.
Declared In
CatMgr.h
Prototype
status_t CatMgrCreateList ( DmOpenRefdbRef
, ListType*listP
, CategoryIDcurrentCategory
, BooleanshowAll
, BooleanshowMultiple
, BooleanshowUneditables
, BooleanresizeList
, BooleanshowEditingStr
, char*customEditingStrP
)
Parameters
-
→ dbRef
- Open schema database containing the category information you want to read.
-
← listP
- Pointer to the
ListType
structure that should display the categories. -
→ currentCategory
- ID of the category that should be selected when the list is initially displayed.
-
→ showAll
-
true
to include an "All" list item. In general, if the list is used to filter the display of database records, it should have an "All" list item. If the list is a list of categories that might be assigned to a single database record, it should not. -
→ showMultiple
-
true
to show a "Multiple" list item, which is used if multiple categories can be selected. In general, if the list is used to filter the display of database records, it should not have a "Multiple" list item. If the list is a list of categories that might be assigned to a single database record, it can have the list item if you like. -
→ showUneditables
-
true
to show uneditable categories. -
→ resizeList
-
true
to resize the list to the number of categories. Set totrue
for pop-up lists,false
otherwise. -
→ showEditingStr
-
true
to show an Edit Categories list item. -
→ customEditingStrP
- A string to use as the Edit Categories list item. To use the default string for the current locale, pass
NULL
for this parameter. This parameter is ignored ifshowEditingStr
isfalse
.
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access dbRef.
-
catmErrNotSchemaDatabase
- dbRef is not a schema database.
-
catmErrReadOnlyDatabase
- dbRef is not open for writing.
-
dmErrInvalidParam
- dbRef is an invalid database.
-
catmErrMemError
- There is not enough memory to complete the operation.
-
catmErrCategoryNotFound
- An error occurred while retrieving category information from the database.
-
catmErrIndexOutOfRange
- An error occurred while retrieving category information from the database.
-
catmErrCategoryNotFound
- Could not find the specified category.
-
memErrNotEnoughSpace
- An error occurred while attempting to resize the list.
-
memErrChunkLocked
- An error occurred while attempting to resize the list.
-
memErrInvalidParam
- An error occurred while attempting to resize the list.
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 CatMgrSelectEdit()
and CatMgrSelectFilter()
, which call this function and fully manage the user's selection of categories in the pop-up list. Use CatMgrCreateList()
only if you want more control over the category pop-up list.
This function obtains the dbRef
parameter's category information and uses 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
. CatMgrCreateList()
does not display the list.
You must balance a call to CatMgrCreateList()
with a call to CatMgrFreeList()
. The CatMgrCreateList()
function locks the resources for the category names. It also allocates the listP
items array. CatMgrFreeList()
unlocks all resources locked by CatMgrCreateList()
and frees all memory allocated by CatMgrCreateList()
.
CatMgrEdit Function
Purpose
Event handler for the Edit Categories dialog used for schema databases.
Declared In
CatMgr.h
Prototype
Boolean CatMgrEdit ( DmOpenRefdbRef
, CategoryID*inCurrentCategoriesP
, uint32_tnumInCurrentCategories
, CategoryID**outCurrentCategoriesPP
, uint32_t*numOutCurrentCategoriesP
, char*titleStrP
)
Parameters
-
→ dbRef
- Open schema database containing the categories to be edited.
-
→ inCurrentCategoriesP
- An array of category IDs representing the currently selected categories. If this parameter contains only one category, that category is initially selected when the dialog is opened. If it contains multiple categories, there is no initial selection.
-
→ numInCurrentCategories
- The number of categories listed in
inCurrentCategoriesP
. -
← outCurrentCategoriesPP
- An array of category IDs from
inCurrentCategoriesP
that the user has edited. Deleted categories do not appear in this list. -
← numOutCurrentCategoriesP
- The number of categories in
outCurrentCategoriesPP
. -
→ titleStrP
- A string to use as the dialog's title. This function makes a copy of the string, so you may free it at any time. To use the default string for the current locale, pass
NULL
for this parameter.
Returns
true
if any of the following conditions are true:
- One of the categories in
inCurrentCategoriesP
is renamed. - One of the categories in
inCurrentCategoriesP
is deleted. - One of the categories in
inCurrentCategoriesP
is merged with another category.
Comments
You rarely call this function directly. The CatMgrSelectFilter()
and CatMgrSelectEdit()
functions call 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 update's the schema database's list of categories and reassigns database records to new categories as needed. If the user deletes a category, CatMgrEdit()
removes it from the membership lists of all database records that belong to it. 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.
The inCurrentCategoriesP
and outCurrentCategoriesPP
parameters are used to manage the display of database records on the form containing the category user interface. Set inCurrentCategoriesP
to the categories currently being displayed. For example, if the form displays one database record and the currently displayed record belongs to three categories, inCurrentCategoriesP
should list the IDs of all three categories and numInCurrentCategories
should be set to three. If the user modifies any of these categories during the Edit Categories session, CatMgrEdit()
returns true
. Your application should then check outCurrentCategoriesPP
and, if necessary, update the user interface to reflect the change.
CatMgrFind Function
Purpose
Returns the ID of the category with the specified name.
Declared In
CatMgr.h
Prototype
status_t CatMgrFind ( DmOpenRefdbP
, const char*nameP
, CategoryID*catIDP
)
Parameters
-
→ dbP
- Open schema database.
-
→ nameP
- The name of the category that you want to find.
-
← catIDP
- The ID of the category with the specified name.
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access
dbP
. -
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
catmErrMemError
- There is not enough memory to complete the operation.
-
catmErrCategoryNotFound
- Could not find the specified category.
See Also
CatMgrGetName()
, CatMgrSetName()
CatMgrFreeList Function
Purpose
Unlocks or frees memory locked or allocated by CatMgrCreateList()
.
Declared In
CatMgr.h
Prototype
void CatMgrFreeList ( DmOpenRefdbRef
, ListType*listP
, BooleanshowAll
, BooleanshowMultiple
, BooleanshowEditingStr
)
Parameters
-
→ dbRef
- Open schema database.
-
→ listP
- Pointer to the category list.
-
→ showAll
-
true
if the list was created with an "All" item. -
→ showMultiple
-
true
if the list was created with a "Multiple" item. -
→ showEditingStr
-
true
if the list was created with an "Edit Categories" item.
Returns
Comments
You only need to call this function if you explicitly call CatMgrCreateList()
. Typical applications call CatMgrSelectEdit()
and CatMgrSelectFilter()
, both of which handle the creation and deletion of the list.
This function frees the items in the pop-up list listP
's items array and it unlocks other resources that CatMgrCreateList()
may have locked.
This function does not do the following:
- Remove the categories from the passed database.
- Free the
ListType
structure pointed to bylistP
. (Typically a list is freed when its form is freed.) - Free the string you pass as a custom name for the "Edit Categories" list item. You'll need to unlock the associated resource or free that string in your application's code.
CatMgrFreeSelectedCategories Function
Purpose
Frees the memory associated with the selected categories list, which is returned by some of the Category Manager functions.
Declared In
CatMgr.h
Prototype
void CatMgrFreeSelectedCategories ( DmOpenRefdbRef
, CategoryID**selectedCategoriesPP
)
Parameters
Returns
See Also
CatMgrSelectEdit()
, CatMgrSelectFilter()
CatMgrGetAllItemLabel Function
Purpose
Returns the text of the "All" list item used in the current locale.
Declared In
CatMgr.h
Prototype
status_t CatMgrGetAllItemLabel ( DmOpenRefdbP
, char*labelP
)
Parameters
-
→ dbP
- Open schema database.
-
← labelP
- A copy of the string used for the "All" item in a category pop-up list.
Returns
errNone
upon success or catmErrInvalidParam
if labelP
is NULL
.
Comments
The "All" item label is stored in the system resource database and is localized to all supported languages. In contrast, the "Unfiled" item label is specific to each schema database.
See Also
CatMgrGetEditable Function
Purpose
Returns whether the user can edit the specified category.
Declared In
CatMgr.h
Prototype
status_t CatMgrGetEditable ( DmOpenRefdbP
, CategoryIDcatID
, Boolean*editableP
)
Parameters
-
→ dbP
- Open schema database.
-
→ catID
- A category ID.
-
← editableP
-
true
if the category with the specified ID is editable, orfalse
otherwise.
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access
dbP
orcatID
is not a valid category ID number. -
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
catmErrMemError
- There is not enough memory to complete the operation.
-
catmErrCategoryNotFound
- Cannot find the category with ID
catID
.
See Also
CatMgrGetID Function
Purpose
Returns the ID of the category at the specified index.
Declared In
CatMgr.h
Prototype
status_t CatMgrGetID ( DmOpenRefdbP
, uint32_tindex
, CategoryID*catIDP
)
Parameters
-
→ dbP
- Open schema database.
-
→ index
- The index into the database's list of categories.
-
← catIDP
- The ID of the category at the specified index.
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access
dbP
. -
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
catmErrMemError
- There is not enough memory to complete the operation.
-
catmErrIndexOutOfRange
- The
index
parameter is invalid.
Comments
You might use this function in a loop to retrieve all category information stored in a schema database. To retrieve the ID of a specific category, use CatMgrFind()
.
This function only returns information about public categories. Schema databases might contain private categories. If so, CatMgrGetID()
ignores those categories.
See Also
CatMgrGetName()
, CatMgrNumCategories()
CatMgrGetName Function
Purpose
Returns the name of the specified category.
Declared In
CatMgr.h
Prototype
status_t CatMgrGetName ( DmOpenRefdbP
, CategoryIDcatID
, char*nameP
)
Parameters
-
→ dbP
- Open schema database.
-
→ catID
- The category ID.
-
← nameP
- The name of the category with the specified ID. This string is copied from the database, so you are responsible for freeing it.
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access
dbP
. -
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
catmErrMemError
- There is not enough memory to complete the operation.
-
catmErrCategoryNotFound
- Cannot find the category with ID
catID
.
See Also
CatMgrSetName()
, CatMgrFind()
, CatMgrGetID()
CatMgrGetNext Function
Purpose
Returns the next non-empty category after the specified category.
Declared In
CatMgr.h
Prototype
status_t CatMgrGetNext ( DmOpenRefdbP
, CategoryIDinCatID
, CategoryID*outCatIDP
)
Parameters
-
→ dbP
- Open schema database.
-
→ inCatID
- A category ID.
-
← outCatIDP
- The ID of the next category in the list.
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access
dbP
. -
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
catmErrMemError
- There is not enough memory to complete the operation.
-
catmErrCategoryNotFound
- Cannot find the category with ID
inCatID
. -
catmErrIndexOutOfRange
- An error occurred iterating through the list of categories.
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 on the device. 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 the category list.
See Also
CatMgrGetUnfiledItemLabel Function
Purpose
Returns the label used for the "Unfiled" item in a category list.
Declared In
CatMgr.h
Prototype
status_t CatMgrGetUnfiledItemLabel ( DmOpenRefdbP
, char*labelP
)
Parameters
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access
dbP
. -
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
catmErrMemError
- There is not enough memory to complete the operation.
-
catmErrCategoryNotFound
- Cannot find the category with ID catIDUnfiled.
Comments
The "Unfiled" item label is specific to each schema database. In contrast, the "All" item label is stored in the system resource database and is localized to all supported languages.
In schema databases, a database record never belongs to the Unfiled category the way that it does in a non-schema database. A schema database record with no category information can be said to be Unfiled.
See Also
CatMgrInitialize Function
Purpose
Initializes category information for a schema database. This function is typically called right after you create a schema database.
Declared In
CatMgr.h
Prototype
status_t CatMgrInitialize ( DmOpenRefdbRef
, MemHandlelocalizedCategoryNamesStrH
)
Parameters
-
→ dbRef
- Open schema database.
-
→ localizedCategoryNamesStrH
- A handle to a string list containing localized category names. This list is initialized from a resource of type
appInfoStringsRsc
('tAIS'
).
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access
dbP
orlocalizedCategoryNamesStrH.
-
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
catmErrMemError
- There is not enough memory to complete the operation.
-
catmErrMaxCategoryLimit
- The
localizedCategoryNamesStrH
contains more than the maximum number of categories allowed for a schema database. -
catmErrNameAlreadyExists
- The database has already been initialized with category information.
Comments
This function creates IDs for each initialized category. The IDs are assigned starting with zero for the first category in the list and incremented for each subsequent category in the list.
The localizedCategoryNamesStrH
parameter contains predefined categories that new users see when they start the application for the first time. Follow these guidelines when creating the resource:
- The string list may contain up to 255 entries. Typically you don't want to predefine 255 categories.
- Each category name has a maximum length defined by the catCategoryNameLength constant (currently 31+1 bytes).
- It's common to have at least one category named Unfiled as the first item in the list. No database records ever belong to this category, but it may be used to determine which records to display. Records that do not belong to any category are considered to be unfiled.
- Don't include strings for the "All" or "Edit Categories" items that you see in a categories pop-up list. When displaying the category list, the Category Manager will automatically generated list entries for these items.
See Also
CatMgrGetUnfiledItemLabel()
, CatMgrAdd()
CatMgrNumCategories Function
Purpose
Returns the number of categories in a schema database.
Declared In
CatMgr.h
Prototype
status_t CatMgrNumCategories ( DmOpenRefdbP
, uint32_t*numCategoriesP
)
Parameters
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access
dbP
. -
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
catmErrMemError
- There is not enough memory to complete the operation.
See Also
CatMgrGetID()
, CatMgrGetNext()
CatMgrRemove Function
Purpose
Removes a category from a schema database.
Declared In
CatMgr.h
Prototype
status_t CatMgrRemove ( DmOpenRefdbP
, CategoryIDcatID
)
Parameters
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access
dbP
orcatID
is an invalid ID. -
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
dmErrInvalidCategory
- The category could not be found in the database.
-
catmErrMemError
- There is not enough memory to complete the operation.
Comments
This function also removes the membership in this category from each database record that is a member of this category. If a record belongs only to this category, it becomes unfiled.
See Also
CatMgrSelectEdit Function
Purpose
Displays a pop-up list from which the user can choose category membership for an existing record.
Declared In
CatMgr.h
Prototype
Boolean CatMgrSelectEdit ( DmOpenRefdbRef
, const FormType *frm
, uint16_tctlID
, char *ctlLabelBuffer
, uint16_tlstID
, BooleanallowMultiple
, CategoryIDcurrentCategoriesP
[], uint32_tnumCurrentCategories
, CategoryID *selectedCategoriesPP
[], uint32_t *numSelectedCategoriesP
, BooleanshowEditingStr
, char *customEditingStrP
)
Parameters
-
→ dbRef
- Open schema database.
-
→ frm
- Pointer to the form that contains the category pop-up list.
-
→ ctlID
- Resource ID of the selector trigger.
-
↔ ctlLabelBuffer
- Stores the string displayed in the selector trigger. This string must have a minimum size of
catCategoryNameLength
, but it can be longer. It must exist for the life of the form. - Upon return, contains the updated string displayed in the selector trigger. This string is a comma-separated list of the currently selected categories, truncated to fit a particular space.
-
→ lstID
- Resource ID of the pop-up list.
-
→ allowMultiple
- If
true
, a "Multiple" item is added to the list so that the user can select multiple categories for the record. Iffalse
, the record can only belong to a single category. -
→ currentCategoriesP
- An array of the IDs of categories to which the record belongs.
-
→ numCurrentCategories
- The number of categories listed in
currentCategoriesP
. -
← selectedCategoriesPP
- Points to an array of the IDs of categories that the user has selected, or
NULL
if the selection has not changed. If this parameter is defined, your application should update the record so that it belongs to all categories listed in this parameter. This new list should overwrite the current category membership list. -
← numSelectedCategoriesP
- The number of categories listed in the
selectedCategoriesPP
array orNULL
ifselectedCategoriesPP
isNULL
. -
→ showEditingStr
-
true
if the list should display an Edit Categories list item, orfalse
not to display it. -
→ customEditingStrP
- A string to use as the Edit Categories list item. To use the default string for the current locale, pass
NULL
for this parameter. This parameter is ignored ifshowEditingStr
isfalse
.
Returns
true
if the user changes the selected categories or selects new categories to which the record should belong. Returns false
if the user does not change category membership for this record.
Comments
Use this function for forms that use a category selector trigger/pop-up list combination to allow the user to change a category or categories to which the displayed schema database record belongs. Call it when the user taps the category selector trigger. This function handles all aspects of displaying the pop-up list and managing the user selection—It creates the pop-up list using CatMgrCreateList()
, displays the pop-up list, calls CatMgrEdit()
if the user selects the Edit Categories item, uses CatMgrSetTriggerLabel()
to set the selector trigger label to the item the user selected, and then calls CatMgrFreeList()
to free the list items array.
Your application is responsible for checking the value of selectedCategoriesPP
upon return and changing the record's category memberships to the new selection. You must then free the selected categories list using the function CatMgrFreeSelectedCategories()
.
See Also
CatMgrSelectFilter()
, CatMgrTruncateName()
CatMgrSelectFilter Function
Purpose
Displays a category pop-up list from which the user selects a category whose records should be listed on the form.
Declared In
CatMgr.h
Prototype
Boolean CatMgrSelectFilter ( DmOpenRefdbRef
, const FormType*frm
, uint16_tctlID
, char*ctlLabelBuffer
, uint16_tlstID
, CategoryID*inCurrentCategoriesP
, uint32_tnumInCurrentCategories
, CategoryID**outCurrentCategoriesPP
, uint32_t*numOutCurrentCategoriesP
, BooleanshowEditingStr
, char*customEditingStrP
)
Parameters
-
→ dbRef
- Open schema database containing the categories to display.
-
→ frm
- Pointer to the form that contains the category pop-up list.
-
→ ctlID
- Resource ID of the pop-up trigger.
-
↔ ctlLabelBuffer
- Stores the string displayed in the pop-up trigger. This string must have a minimum size of
catCategoryNameLength
, but it can be longer. It must exist for the life of the form. - Upon return, contains the updated string displayed in the pop-up trigger. This string is a comma-separated list of the currently selected categories, truncated to fit a particular space.
-
→ lstID
- Resource ID of the pop-up list.
-
→ inCurrentCategoriesP
- An array of the IDs of categories that are currently displayed.
-
→ numInCurrentCategories
- The number of categories specified in
inCurrentCategoriesP
. -
← outCurrentCategoriesPP
- If the category selection changes, points to an array of the IDs of the newly selected categories. Typically, there is only one category.
NULL
if the selection did not change. -
← numOutCurrentCategoriesP
- The number of categories in
outCurrentCategoriesPP
orNULL
ifoutCurrentCategoriesPP
isNULL
. -
→ showEditingStr
-
true
if the list should display an Edit Categories list item, orfalse
not to display it. -
→ customEditingStrP
- A string to use as the Edit Categories list item. To use the default string for the current locale, pass
NULL
for this parameter. This parameter is ignored ifshowEditingStr
isfalse
.
Returns
true
if the user changes the selected categories, or false
otherwise.
Comments
Use this function for forms that use a category pop-up list to filter the display. Call it when the user taps the category pop-up trigger. This function handles all aspects of displaying the pop-up list and managing the user selection—It creates the pop-up list using CatMgrCreateList()
, displays the pop-up list, calls CatMgrEdit()
if the user selects the Edit Categories item, uses CatMgrSetTriggerLabel()
to set the trigger label to the item the user selected, and then calls CatMgrFreeList()
to free the list items array. Your application is responsible for checking the value of outCurentCategoriesPP
upon return and updating the display or changing the record's category to the new selection. You must then free the selected categories list using the function CatMgrFreeSelectedCategories()
.
The "All" list item is automatically added. The "Edit Categories" list item is only added if showEditingStr
is true
.
If this function returns true
, the application should update the display so that only the newly selected categories are displayed.
CatMgrSetEditable Function
Purpose
Enables or disables the ability to edit a specified category.
Declared In
CatMgr.h
Prototype
status_t CatMgrSetEditable ( DmOpenRefdbP
, CategoryIDcatID
, Booleaneditable
)
Parameters
-
→ dbP
- Open schema database.
-
→ catID
- A category ID.
-
→ editable
-
true
to allow the user to modify or delete the specified category;false
to disallow it.
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access
dbP
orcatID
is invalid. -
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
catmErrMemError
- There is not enough memory to complete the operation.
-
catmErrCategoryNotFound
- Cannot find the category with ID
catID
.
See Also
CatMgrSetName Function
Purpose
Sets the name of the specified category.
Declared In
CatMgr.h
Prototype
status_t CatMgrSetName ( DmOpenRefdbP
, CategoryIDcatID
, const char*nameP
)
Parameters
-
→ dbP
- Open schema database.
-
→ catID
- A category ID.
-
→ nameP
- A string containing the category's new name. This string is copied into the appropriate portion of the database.
Returns
errNone
upon success or one of the following:
-
catmErrInvalidParam
- Could not access
dbP
orcatID
is invalid. -
catmErrNotSchemaDatabase
-
dbP
is not a schema database. -
catmErrReadOnlyDatabase
-
dbP
is not open for writing. -
dmErrInvalidParam
-
dbP
is an invalid database. -
catmErrMemError
- There is not enough memory to complete the operation.
-
catmErrCategoryNotFound
- Cannot find the category with ID
catID
. -
catmErrNameAlreadyExists
- The database already contains a category with this name.
See Also
CatMgrSetTriggerLabel Function
Purpose
Sets the label displayed by the category pop-up trigger for a schema database.
Declared In
CatMgr.h
Prototype
void CatMgrSetTriggerLabel ( DmOpenRefdbRef
, CategoryIDcategoriesP[]
, uint32_tnumCategories
, ControlType*ctl
, char*nameP
)
Parameters
-
→ dbRef
- Open schema database.
-
→ categoriesP
- An array of the IDs of categories whose names should be displayed in the trigger.
-
→ numCategories
- The number of categories in the
categoriesP
array. -
→ ctl
- Pointer to the control (pop-up or selector trigger) to relabel.
-
↔ nameP
- Stores the string displayed in the trigger. This string must have a minimum size of
catCategoryNameLength
, but it can be longer. It must exist for the life of the form. - Upon return, contains the updated string displayed in the trigger. This string is a comma-separated list of the currently selected categories, truncated to fit a particular space.
Returns
Comments
The CatMgrSetTriggerLabel()
function looks up the names for the specified categories and then creates a comma-separated list of the category names. It calls the CatMgrTruncateName()
function to truncate this string to the maximum length. The maximum length varies, depending upon which ROM is installed in the device.
NOTE: This function passes the
nameP
parameter to the CatMgrTruncateName()
function, which means that the nameP
value must be modifiable. CatMgrSetTriggerLabel()
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
CatMgrTruncateName Function
Purpose
Truncates a list of categories from a schema database so that it's short enough to display. The string is truncated if it's longer than maxWidth
.
Declared In
CatMgr.h
Prototype
void CatMgrTruncateName ( DmOpenRefdbRef
, CategoryIDcategoriesP[]
, uint32_tnumCategories
, uint16_tmaxWidth
, char*nameP
)
Parameters
-
→ dbRef
- An open schema database.
-
→ categoriesP
- An array of the IDs of categories whose names should be displayed in the trigger.
-
→ numCategories
- The number of categories in the
categoriesP
array. -
→ maxWidth
- Maximum size, in standard coordinates, of the truncated category string (including ellipsis and commas).
-
↔
name
- Stores the string displayed in the pop-up or selector trigger. This string must have a minimum size of
catCategoryNameLength
, but it can be longer. It must exist for the life of the form. - Upon return, contains the updated string displayed in the trigger. This string is a comma-separated list of the currently selected categories, truncated to fit the space indicated by
maxWidth
.