Qt API | Qtopia API | Qtopia Documentation | ![]() |
The Categories class is a database that groups categories and maps ids to names. More...
#include <qtopia/categories.h>
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 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.
Constructor for an empty Categories object. The standard parent and name
parameters are passed on.
Constructors a deep copy of copyFrom.
Empty destructor. Call save() before destruction if there are changes
that need to be saved.
See also addCategory().
Returns a map of application names to CategoryGroup. The CategoryGroup
class defines a map of ids to category labels and category labels to ids.
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
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
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
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.
Returns list of all global category labels
Returns the global CategoryGroup. The CategoryGroup
class defines a map of ids to category labels and category labels to ids.
Returns all ids associated with the application CategoryGroup app
and the passed in labels in that group.
Returns list of labels associated with the application app and catids.
Returns FALSE if there is error reading the file or TRUE on success.
Performs deep copy of c.
Returns FALSE if there is error writing the file or TRUE on success.
This file is part of the Qtopia ,
copyright © 1995-2002
Trolltech, all rights reserved.Member Type Documentation
Categories::DisplaySingle
Categories::ExtraLabels
Member Function Documentation
Categories::Categories ( QObject * parent = 0, const char * name = 0 )
Categories::Categories ( const Categories & copyFrom )
Categories::~Categories () [virtual]
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.
const QMap<QString, CategoryGroup> & Categories::appGroupMap () const
void Categories::categoryAdded ( const Categories & cats, const QString & appname, int uid ) [signal]
void Categories::categoryRemoved ( const Categories & cats, const QString & appname, int uid ) [signal]
void Categories::categoryRenamed ( const Categories & cats, const QString & appname, int uid ) [signal]
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.
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
const CategoryGroup & Categories::globalGroup () const
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
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
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.
Categories & Categories::operator= ( const Categories & 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.
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.
Copyright © 2001-2002 Trolltech Trademarks