Qt API | Qtopia API | Qtopia Documentation |

# Categories Class Reference

The Categories class is a database that groups categories and maps ids to names. More...

`#include <qtopia/categories.h>`

Inherits QObject.

List of all member functions.

## Public Members

- Categories ( QObject * parent = 0, const char * name = 0 )
- Categories ( const Categories & copyFrom )
- virtual ~Categories ()
- Categories & operator= ( const Categories & c )
- void clear ()
- int addCategory ( const QString & appname, const QString & catname )
- int addGlobalCategory ( const QString & catname )
- bool removeCategory ( const QString & appname, const QString & catname, bool checkGlobal = TRUE )
- bool removeCategory ( const QString & appname, int uid )
- bool removeGlobalCategory ( const QString & catname )
- bool removeGlobalCategory ( int uid )
- QArray<int> ids ( const QString & app, const QStringList & labels ) const
- int id ( const QString & app, const QString & cat ) const
- QString label ( const QString & app, int id ) const
- enum ExtraLabels { NoExtra, AllUnfiled, AllLabel, UnfiledLabel }
- QStringList labels ( const QString & app, bool includeGlobal = TRUE, ExtraLabels extra = NoExtra ) const
- QStringList labels ( const QString & app, const QArray<int> & catids ) const
- enum DisplaySingle { ShowMulti, ShowAll, ShowFirst }
- QString displaySingle ( const QString & app, const QArray<int> & catids, DisplaySingle display ) const
- QStringList globalCategories () const
- bool renameCategory ( const QString & appname, const QString & oldName, const QString & newName )
- bool renameGlobalCategory ( const QString & oldName, const QString & newName )
- void setGlobal ( const QString & appname, const QString & catname, bool global )
- bool isGlobal ( const QString & catname ) const
- bool exists ( const QString & catname ) const
- bool exists ( const QString & appname, const QString & catname ) const
- bool save ( const QString & fname ) const
- bool load ( const QString & fname )
- void dump () const
- const QMap<QString, CategoryGroup> & appGroupMap () const
- const CategoryGroup & globalGroup () const

## Signals

- void categoryAdded ( const Categories & cats, const QString & appname, int uid )
- void categoryRemoved ( const Categories & cats, const QString & appname, int uid )
- void categoryRenamed ( const Categories & cats, const QString & appname, int uid )

## Detailed Description

The Categories class is a database that groups categories and maps ids to names.

The Categories class is the low level Categories accessor class. To add a category menu and filter for your application, see CategoryMenu.

The Categories class allows the developer to add, remove, and rename categories. Categories can be created for an individual application such as Todo List or to be used for all applications. Categories that can be used by all applications are called global categories. Each PimRecord subclass stores categories as an QArray<int> using PimRecord::setCategories() and PimRecord::categories(). This allows each record to be assigned to multiple categories. This also allows the user to rename a category and for it to update automatically in all records.

This class provides several methods to convert between a category id and it's associated string such as id(), ids(), label() and labels(). A helper class called CategoryGroup is used to access categories of a single application group, such as Todo List. Global categories can also be accessed via CategoryGroup objects. See appGroupMap() and globalGroup() for the appropriate accessor methods.

Categories are stored in an xml file in the Settings directory (Categories.xml). A global function called categoryFileName() will return to appropriate QString file location to be passed to load() and save() for the master categories database.

Warning: Categories API will likely change after Qtopia 2.

See also CategoryGroup, CategoryMenu, PimRecord, Qtopia Desktop Classes and Qtopia Classes.

## Member Type Documentation

### Categories::DisplaySingle

- `Categories::ShowMulti`
- `Categories::ShowAll`
- `Categories::ShowFirst`

### Categories::ExtraLabels

- `Categories::NoExtra` - only the category labels
- `Categories::AllUnfiled` - add All and Unfiled labels
- `Categories::AllLabel` - add All label
- `Categories::UnfiledLabel` - add Unfiled label

## Member Function Documentation

### Categories::Categories ( QObject * parent = 0, const char * name = 0 )

Constructor for an empty Categories object. The standard parent and name parameters are passed on.

### Categories::Categories ( const Categories & copyFrom )

Constructors a deep copy of copyFrom.

### Categories::~Categories ()`[virtual]`

Empty destructor. Call save() before destruction if there are changes that need to be saved.

### int Categories::addCategory ( const QString & appname, const QString & catname )

Add the category name catname for the application appname. Return UID if added, 0 if the category already exists locally for any application or globally.

### int Categories::addGlobalCategory ( const QString & catname )

Add the global category catname while checking that it doesn't already exist globally. Return UID if added, 0 if conflicts.

See also addCategory().

### const QMap<QString, CategoryGroup> & Categories::appGroupMap () const

Returns a map of application names to CategoryGroup. The CategoryGroup class defines a map of ids to category labels and category labels to ids.

### void Categories::categoryAdded ( const Categories & cats, const QString & appname, int uid )`[signal]`

Emitted if a category is added.

cats is a const reference to this object appname is the CategoryGroup application name that the category was added to or QString::null if it was global uid is the unique identifier associated with the added category

### void Categories::categoryRemoved ( const Categories & cats, const QString & appname, int uid )`[signal]`

Emitted if removed category is removed.

cats is a const reference to this object appname is the CategoryGroup application name that the category was removed from or QString::null if it was the global CategoryGroup uid is the unique identifier associated with the removed category

### void Categories::categoryRenamed ( const Categories & cats, const QString & appname, int uid )`[signal]`

Emitted if uid in the appname CategoryGroup is renamed in cats object.

cats is a const reference to this object appname is the CategoryGroup application name that the category was renamed in or QString::null if it was the global CategoryGroup uid is the unique identifier associated with the renamed category

### void Categories::clear ()

Clear the categories in memory. Equivelent to creating an empty Categories object.

### QString Categories::displaySingle ( const QString & app, const QArray<int> & catids, DisplaySingle display ) const

Returns a single string associated with catids for applications app. The returned string is for display in a combobox or any area that requires one string. If catids are empty then "Unfiled" will be returned. If multiple categories are assigned then the behavior depends on the DisplaySingle type.

If display is set to ShowMulti then " (multi)" appended to the first string. If display is set to ShowAll, then a space seperated string is returned with all categories. If ShowFirst is set, the just the first string is returned.

### void Categories::dump () const

Dump the contents to standard out. Used for debugging only.

### bool Categories::exists ( const QString & catname ) const

Returns true if the catname is associated with any CategoryGroup, including global.

### bool Categories::exists ( const QString & appname, const QString & catname ) const

Returns TRUE if the catname is associated with the appname CategoryGroup, FALSE if not found.

### QStringList Categories::globalCategories () const

Returns list of all global category labels

### const CategoryGroup & Categories::globalGroup () const

Returns the global CategoryGroup. The CategoryGroup class defines a map of ids to category labels and category labels to ids.

### int Categories::id ( const QString & app, const QString & cat ) const

Returns the id associated with cat in application app. If the id is not found in the application CategoryGroup, then it searches the global CategoryGroup. If it is not found it either, 0 is returned.

### QArray<int> Categories::ids ( const QString & app, const QStringList & labels ) const

Returns all ids associated with the application CategoryGroup app and the passed in labels in that group.

### bool Categories::isGlobal ( const QString & catname ) const

Returns TRUE if the catname is in the global CategoryGroup, FALSE if not.

### QString Categories::label ( const QString & app, int id ) const

Returns the label associated with id in application app.

### QStringList Categories::labels ( const QString & app, bool includeGlobal = TRUE, ExtraLabels extra = NoExtra ) const

Returns the sorted list of all categories that are associated with the app. If includeGlobal is TRUE then the returned categories will include the global category items. extra specifies which extra labels should be added.

### QStringList Categories::labels ( const QString & app, const QArray<int> & catids ) const

Returns list of labels associated with the application app and catids.

### bool Categories::load ( const QString & fname )

Loads the Categories database using fname. See categoryFileName() for the default file name string used for the shared category database.

Returns FALSE if there is error reading the file or TRUE on success.

### Categories & Categories::operator= ( const Categories & c )

Performs deep copy of c.

### bool Categories::removeCategory ( const QString & appname, const QString & catname, bool checkGlobal = TRUE )

Removes the catname from the application group. If it is not found in the application group appname and checkGlobal is TRUE, then it attempts to remove it from the global list

### bool Categories::removeCategory ( const QString & appname, int uid )

Removes the uid from the application group appname. Returns TRUE if success, FALSE if not found.

### bool Categories::removeGlobalCategory ( const QString & catname )

Removes the global category catname. Returns TRUE if success, FALSE if not found.

### bool Categories::removeGlobalCategory ( int uid )

Removes the global category uid. Returns TRUE if success, FALSE if not found.

### bool Categories::renameCategory ( const QString & appname, const QString & oldName, const QString & newName )

Return TRUE if renaming succeeded; FALSE if appname or oldName is not found, or if newName conflicts with an existing category name in any CategoryGroup.

### bool Categories::renameGlobalCategory ( const QString & oldName, const QString & newName )

Return TRUE if renaming succeeded; FALSE if oldName or newName is not found, or if newName conflicts with an existing category in any CategoryGroup. This function will only rename categories found in the global CategoryGroup.

### bool Categories::save ( const QString & fname ) const

Saves the Categories database to the fname. See categoryFileName() for the default file name string used for the shared category database.

Returns FALSE if there is error writing the file or TRUE on success.

### void Categories::setGlobal ( const QString & appname, const QString & catname, bool global )

Changes the grouping of a category. If a category was global and global is set to TRUE, then the catname will be moved to the appname group.

This file is part of the Qtopia , copyright © 1995-2002 Trolltech, all rights reserved.