4 Categories

This chapter describes the categories 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.

Category Data Structures

An AppInfo block can hold any data at all. The category APIs provide a way to implement categories and use the AppInfo block as the storage area. An application could implement the category popup on its own without this API and use the Data Manager category routines, and /or the AppInfo block, as it chooses.

This API requires that the AppInfo block be used like this:

AppInfoType

typedef struct {

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

typedef AppInfoType *AppInfoPtr;

Field Descriptions

Category Constants

Compatibility

The functionality of the constants categoryHideEditCategory and categoryDefaultEditCategoryString is present only if the 3.5 New Feature Set is present.

Category Functions

CategoryCreateList

Purpose

Read a database's categories and store them in a list.

Prototype

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

Parameters

->db

Opened database containing category info.

<-listP

A pointer to the list of category names. See ListType.

->currentCategory

Category to select.

->showAll

true to have an "All" category.

->showUneditables

true to show uneditable categories.

->numUneditableCategories

This is the number of categories, starting with the first one at zero, that may not have their names edited by the user. For example, it's common to have an "Unfiled" category at position zero which is not editable.

->editingStrID

The resource ID of a string to use with the "Edit Categories" list item.

->resizeList

true to resize the list to the number of categories. Set to true for pop-ups, false otherwise.

Result

A memory block is allocated containing the list of categories. The ListType in listP must be allocated outside this function. However, this function allocates some structs that are stored INSIDE the ListType, so CategoryFreeList must be called when you are done with the list to free the memory block.

Comments

You use this function to create a list of categories to display in your application's user interface, usually by calling LstDrawList or LstPopupList. The category list is obtained from the AppInfoType structure of the database specified by the db parameter.

If the showAll parameter is true, the "All" item is first in the list, 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. If the current selection is not in any category, it is marked "Unfiled".

Compatibility

Implemented only if 2.0 New Feature Set is present.

The functionality of the constants categoryDefaultEditCategoryString and categoryHideEditString is available 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.

This function is obsolete and should not be used.

Prototype

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

Parameters

->db

Database containing categories to extract.

<-lst

List object to load categories into.

->currentCategory

Set as the current selection in the resulting list.

->showAll

true if an "All" category should be included in the list.

Result

Returns nothing.

Compatibility

This function corresponds to the Palm OS^® 1.0 version of CategoryCreateList.

---

NOTE:  

Obsolete functions are provided ONLY for backward compatibility; for example, so a 1.0 application will work on 3.x OS releases. New code should not call these routines!

---

See Also

CategoryCreateList

CategoryEdit

Purpose

Event handler for the "Edit Categories" dialog. Called by CategorySelect if the user chooses the Edit Category line. (If the Edit Category line is present)

->db

Database containing the categories to be edited.

<-categoryP

Set to the category selected when the dialog is done.

->titleStrID

Title of the dialog bar.

->numUneditableCategories

This is the number of categories (starting with the first one at zero) that may not have their names edited by the user. For example, it's common to have an "Unfiled" category at position zero which 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.
  

Compatibility

This function was revised for Palm OS 2.0, and Palm OS 3.0. In Palm OS 3.0, the numUneditableCategories parameter was added.

---

NOTE:  

This enhancement is implemented only if 3.0 New Feature Set is present.

---

See Also

CategoryEditV20, CategoryEditV10

CategoryEditV20

Purpose

Event handler for the Edit Categories dialog.Called by CategorySelect if the user chooses the Edit Category line. (If the Edit Category line is present.)

This function is obsolete and should not be used.

Prototype

Boolean CategoryEdit (DmOpenRef db, UInt16 *categoryP, UInt32 titleStrID)

Parameters

->db

Database containing the categories to be edited.

<-categoryP

Set to the category selected when the dialog is done.

->titleStrID

Title of the dialog bar.

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 3.0 New Feature Set is present.

---

NOTE:  

Obsolete functions are provided ONLY for backward compatibility. For example, so a 1.0 application will work on 3.x OS releases. New code should not call these routines!

---

See Also

CategoryEdit, CategoryEditV10

CategoryEditV10

Purpose

Event handler for the Edit Categories dialog. Called by CategorySelect if the user chooses the "Edit Category" line. (If the Edit Category line is present.)

This function is obsolete and should not be used.

Prototype

Boolean CategoryEditV10 (DmOpenRef db, UInt16 *categoryP)

Parameters

->db

Database containing the categories to be edited.

<-categoryP

Current category (index into the database).

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.

---

NOTE:  

Obsolete functions are provided ONLY for backward compatibility; for example, so a 1.0 application will work on 3.x OS releases. New code should not call these routines!

---

See Also

CategoryEdit, CategoryEditV20

CategoryFind

Purpose

Return the unique ID of the category that matches the name passed.

Prototype

UIint16 CategoryFind (DmOpenRef db, const Char *name)

Parameters

->db

Database to search for the passed category.

->name

Category name.

Result

Returns the category index.

CategoryFreeList

Purpose

This routine unlocks or frees memory locked or allocated by CategoryCreateList.

Prototype

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

Parameters

->db

Categories database.

->listP

Pointer to the category list.

->showAll

true if the list was created with an "All" category.

->editingStrID

The editingStrID should be the same as that passed to CategoryCreateList. The function will unlock the resource.

Result

Returns nothing.

Comments

Calling this function doesn't remove the categories from the passed database. It frees the items in the list. The developer must manage the ListType structure.

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 which was attached to the passed list object.

This function is obsolete and should not be used.

Prototype

void CategoryFreeListV10 (DmOpenRef db, const ListType *lst)

Parameters

->db

Database containing the categories.

->1st

Pointer to the category list containing the memory to be freed.

Result

Returns nothing.

Compatibility

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

---

NOTE:  

Obsolete functions are provided ONLY for backward compatibility; for example, so a 1.0 application will work on 3.x OS releases. New code should not call these routines!

---

See Also

CategoryFreeList

CategoryGetName

Purpose

Return the name of the specified category.

Prototype

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

Parameters

->db

Database that contains the categories.

->index

Category index.

<-name

Buffer to hold category name. Buffer should be dmCategoryLength in size.

Result

Stores the category name in the name buffer passed.

CategoryGetNext

Purpose

Given a category index, this function returns the index of the next category. Note that categories are not stored sequentially.

Prototype

UInt16 CategoryGetNext (DmOpenRef db, UInt16 index)

Parameters

->db

Database that contains the categories.

->index

Category index.

Result

Category index of next category.

Comments

Don't use this function to search for a category. Instead, use it to allow your users to cycle through categories, for example, using the hard-button scroll bars on the device.

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 empty records. That is, if a category contains no records, then its index will not be returned by this function.

CategoryInitialize

Purpose

Initialize the category names, IDs, and flags.

Prototype

void CategoryInitialize (AppInfoPtr appInfoP, UInt16 localizedAppInfoStrID)

Parameters

->appInfoP

Application info pointer. See AppInfoType.

->localizedAppInfoStrID

Resource ID of the localized category names. This must be a resource of the type appInfoStringsRsc.

Result

Returns nothing.

Comments

Used to make sure the first field in your application info block is of type AppInfoType, and to initialize category names.

Compatibility

Implemented only if 2.0 New Feature Set is present.

CategorySelect

Purpose

Process the selection and editing of categories.Usually you call this when the user taps the category pop-up trigger.

Prototype

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

Parameters

->db

Database that contains the categories.

->frm

Form that contains the category popup list.

->ctlID

ID of the popup trigger.

->lstID

ID of the popup list.

->title

true if the popup trigger is on the title line, which means that an "All" choice should be added to the list. Pass false if the popup trigger appears in a form where a specific record is being modified or any where else the "All" choice should not appear.

<->categoryP

Current category (pointer into db structure).

<->categoryName

Name of the current category.

->numUneditableCategories

This is the number of categories, starting with the first one at zero, that may not have their names edited by the user. For example, it's common to have an "Unfiled" category at position zero which is not editable.

->editingStrID

The resource ID of a string to use with the "Edit Categories" list item.

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

This function calls CategoryEdit if the user selects the Edit Categories option in the list.

Compatibility

Implemented only if 2.0 New Feature Set is present.

See Also

CategorySelectV10

CategorySelectV10

Purpose

Process the selection and editing of categories.

This function is obsolete and should not be used.

Prototype

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

Parameters

->db

Database that contains the categories.

->frm

Form that contains the category popup list.

->ctlID

ID of the popup trigger.

->lstID

ID of the popup list.

->title

true if the popup trigger is on the title line.

<->categoryP

Current category (index into db structure).

<->categoryName

Name of the current 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.

---

NOTE:  

Obsolete functions are provided ONLY for backward compatibility; for example, so a 1.0 application will work on 3.x OS releases. New code should not call these routines!

---

CategorySetName

Purpose

Set the category name and rename bits. A NULL pointer removes the category name.

Prototype

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

Parameters

->db

Database containing the categories to change.

->index

Index of category to set.

->nameP

A category name (null-terminated) or NULL pointer to remove the category.

Result

Returns nothing.

Compatibility

Implemented only if 2.0 New Feature Set is present.

CategorySetTriggerLabel

Purpose

Set the label displayed by the category trigger. The category name is truncated if it is larger than the system default maximum width. CategorySetTrigger calls CategoryTruncateName, with a default (system-provided) width.

Prototype

void CategorySetTriggerLabel (ControlType *ctl, Char *name)

Parameters

->ctl

Pointer to control object to relabel.

->name

Pointer to the name of the new category.

Result

Does not copy the string. Ctl points to the passed string when done. See 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

->name

Category name to truncate.

->maxWidth

Maximum size, in pixels, of truncated category (including ellipsis).

Result

Returns nothing. Stores the changed category in name