Categories Class Reference

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

#include <categories.h>

Inheritance diagram for Categories:

[legend]Collaboration diagram for Categories:


Public Types
enum	ExtraLabels { NoExtra, AllUnfiled, AllLabel, UnfiledLabel }
enum	DisplaySingle { ShowMulti, ShowAll, ShowFirst }
Signals
void	categoryAdded (const Categories &, const QString &, int)
	emitted if added a category; the second param is the application the category was added to or null if global the third param is the uid of the newly added category
void	categoryRemoved (const Categories &, const QString &, int)
	emitted if removed a category the second param is the application the category was removed from or null if global the third param is the uid of the removed category
void	categoryRenamed (const Categories &, const QString &, int)
	emitted if a category is renamed; the second param is the uid of the removed category
Public Member Functions
	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)
	Add the category name as long as it doesn't already exist locally or globally.
int	addCategory (const QString &appname, const QString &catname, int uid)
	Add the category name as long as it doesn't already exist locally or globally.
int	addGlobalCategory (const QString &catname)
	Add the global category just checking that it doesn't already exist globally.
int	addGlobalCategory (const QString &catname, int uid)
	Add the global category just checking that it doesn't already exist globally.
bool	removeCategory (const QString &appName, const QString &catName, bool checkGlobal=TRUE)
	Removes the category from the application; if it is not found in the application, then it removes it from the global list.
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
	Returns the id associated with the app.
QString	label (const QString &app, int id) const
	Returns the label associated with the id.
QStringList	labels (const QString &app, bool includeGlobal=TRUE, ExtraLabels extra=NoExtra) const
	Returns the sorted list of all categories that are associated with the app.
QStringList	labels (const QString &app, const QArray< int > &catids) const
QString	displaySingle (const QString &app, const QArray< int > &catids, DisplaySingle display) const
	Returns a single string associated with the cat ids for display in a combobox or any area that requires one string.
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 value)
bool	isGlobal (const QString &catname) const
bool	exists (const QString &catname) const
	Returns true if the catname is associated with any application.
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

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 PalmtopRecord subclass stores categories as an QArray<int> using PalmtopRecord::setCategories() and PalmtopRecord::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 between Qtopia 1.5 and Qtopia 3

See also:: CategoryGroup, CategoryMenu

Definition at line 89 of file categories.h.

Constructor & Destructor Documentation

Categories::Categories ( QObject * parent = 0,

const char * name = 0

) [inline]

Constructor for an empty Categories object.
Definition at line 93 of file categories.h.

Categories::Categories ( const Categories & copyFrom ) [inline]

Deep copy constructor
Definition at line 95 of file categories.h.

Categories::~Categories ( ) [inline, virtual]

Empty destructor. Call save() before destruction if there are changes that need to be saved.
Definition at line 98 of file categories.h.

Member Function Documentation

Categories & Categories::operator= ( const Categories & c ) [inline]

Performs deep copy.
Definition at line 100 of file categories.h.
References mAppCats, and mGlobalCats.

void Categories::clear ( )

Clear the categories in memory. Equivelent to creating an empty Categories object.
Definition at line 785 of file categories.cpp.
References QMap< QString, CategoryGroup >::clear(), and CategoryGroup::clear().
Referenced by load().

int Categories::addCategory ( const QString & appname,

const QString & catname

)

Add the category name as long as it doesn't already exist locally or globally.
Return UID if added, 0 if conflicts (error).
Definition at line 285 of file categories.cpp.
References CategoryGroup::add(), categoryAdded(), CategoryGroup::contains(), QMap< QString, CategoryGroup >::end(), QMap< QString, CategoryGroup >::find(), and QMap< QString, CategoryGroup >::insert().
Referenced by AppLnk::AppLnk(), and setGlobal().

int Categories::addCategory ( const QString & appname,

const QString & catname,

int uid

)

Add the category name as long as it doesn't already exist locally or globally.
Return UID if added, 0 if conflicts (error).
Definition at line 256 of file categories.cpp.
References CategoryGroup::add(), categoryAdded(), CategoryGroup::contains(), QMap< QString, CategoryGroup >::end(), QMap< QString, CategoryGroup >::find(), and QMap< QString, CategoryGroup >::insert().

int Categories::addGlobalCategory ( const QString & catname )

Add the global category just checking that it doesn't already exist globally.
Return UID if added, 0 if conflicts.
Definition at line 326 of file categories.cpp.
References CategoryGroup::add(), and categoryAdded().
Referenced by load(), and setGlobal().

int Categories::addGlobalCategory ( const QString & catname,

int uid

)

Add the global category just checking that it doesn't already exist globally.
Return UID if added, 0 if conflicts.
Definition at line 313 of file categories.cpp.
References CategoryGroup::add(), and categoryAdded().

bool Categories::removeCategory ( const QString & appname,

const QString & catname,

bool checkGlobal = TRUE

)

Removes the category from the application; if it is not found in the application, then it removes it from the global list.
Removes the catname from the application group. If it is not found in the application group and checkGlobal is TRUE, then it attempts to remove it from the global list
Definition at line 341 of file categories.cpp.
References categoryRemoved(), QMap< QString, CategoryGroup >::end(), QMap< QString, CategoryGroup >::find(), CategoryGroup::id(), CategoryGroup::remove(), and removeGlobalCategory().
Referenced by setGlobal().

bool Categories::removeCategory ( const QString & appname,

int uid

)

Removes the uid from the application group appname. Returns TRUE if success, FALSE if not found.
Definition at line 365 of file categories.cpp.
References categoryRemoved(), QMap< QString, CategoryGroup >::end(), QMap< QString, CategoryGroup >::find(), and CategoryGroup::remove().

bool Categories::removeGlobalCategory ( const QString & catname )

Removes the global category catname. Returns TRUE if success, FALSE if not found.
Definition at line 383 of file categories.cpp.
References categoryRemoved(), CategoryGroup::id(), and CategoryGroup::remove().
Referenced by removeCategory().

bool Categories::removeGlobalCategory ( int uid )

Removes the global category uid. Returns TRUE if success, FALSE if not found.
Definition at line 397 of file categories.cpp.
References categoryRemoved(), and CategoryGroup::remove().

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.
Definition at line 499 of file categories.cpp.
References QValueList::begin(), QValueList::end(), id(), QArray::resize(), and QArray::size().

int Categories::id ( const QString & app,

const QString & cat

) const

Returns the id associated with the app.
Returns the id associated with the 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.
Definition at line 521 of file categories.cpp.
References QString::contains(), CategoryGroup::id(), and QObject::tr().
Referenced by AppLnk::AppLnk(), ids(), load(), CategoryMenu::reload(), and renameCategory().

QString Categories::label ( const QString & app,

int id

) const

Returns the label associated with the id.
Returns the label associated with the id
Definition at line 446 of file categories.cpp.
References CategoryGroup::contains(), QMap< QString, CategoryGroup >::end(), QMap< QString, CategoryGroup >::find(), and CategoryGroup::label().

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 parameter is TRUE then the returned categories will include the global category items. If extra = NoExtra, then If extra = AllUnfiled, then All and Unfiled will be prepended to the list If extra = AllLabel, then All is prepended If extra = UnfiledLabel, then Unfiled is prepended
Definition at line 411 of file categories.cpp.
References QValueList::append(), QMap< QString, CategoryGroup >::end(), QMap< QString, CategoryGroup >::find(), CategoryGroup::labels(), QStringList::sort(), and QObject::tr().
Referenced by displaySingle(), and CategoryMenu::reload().

QString Categories::displaySingle ( const QString & app,

const QArray< int > & catids,

DisplaySingle display

) const

Returns a single string associated with the cat ids 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 /a display is set to ShowMulti then " (multi)" appended to the first string. If /a display is set to ShowAll, then a space seperated string is returned with all categories. If ShowFirst is returned, the just the first string is returned.
Definition at line 468 of file categories.cpp.
References QValueList::count(), QValueList::first(), QStringList::join(), labels(), QStringList::sort(), and QObject::tr().

QStringList Categories::globalCategories ( ) const [inline]

Returns list of all global category labels
Definition at line 172 of file categories.h.

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 in the CategoryGroup.
It will first search the CategoryGroup associated with appname and if not found it will try to replace in global CategoryGroup.
Definition at line 540 of file categories.cpp.
References categoryRenamed(), QMap< QString, CategoryGroup >::end(), QMap< QString, CategoryGroup >::find(), CategoryGroup::id(), id(), CategoryGroup::rename(), and renameGlobalCategory().

bool Categories::renameGlobalCategory ( 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 in the CategoryGroup. This function will only rename categories found in the global CategoryGroup.
Definition at line 564 of file categories.cpp.
References categoryRenamed(), CategoryGroup::id(), and CategoryGroup::rename().
Referenced by renameCategory().

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.
Definition at line 579 of file categories.cpp.
References addCategory(), addGlobalCategory(), CategoryGroup::contains(), CategoryGroup::remove(), and removeCategory().

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

Returns TRUE if the catname is in the global CategoryGroup, FALSE if not.
Definition at line 600 of file categories.cpp.
References CategoryGroup::contains().
Referenced by exists().

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

Returns true if the catname is associated with any application.
Returns true if the catname is associated with any CategoryGroup, including global.
Definition at line 610 of file categories.cpp.
References QMap< QString, CategoryGroup >::begin(), QMap< QString, CategoryGroup >::end(), and isGlobal().

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.
Definition at line 626 of file categories.cpp.
References QMap< QString, CategoryGroup >::end(), and QMap< QString, CategoryGroup >::find().

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.
Definition at line 644 of file categories.cpp.
References QMap::begin(), QMap< QString, CategoryGroup >::begin(), QMap< int, QString >::begin(), QFile::close(), QByteArray::data(), QMap::end(), QMap< QString, CategoryGroup >::end(), QMap< int, QString >::end(), CategoryGroup::idMap(), QString::latin1(), QCString::length(), QString::number(), QFile::open(), QFile::remove(), QString::utf8(), and QIODevice::writeBlock().
Referenced by load().

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.
Definition at line 706 of file categories.cpp.
References CategoryGroup::add(), addGlobalCategory(), clear(), QByteArray::data(), QString::find(), QString::fromUtf8(), id(), QString::isNull(), QString::latin1(), QString::length(), QFile::open(), QIODevice::readAll(), save(), QByteArray::size(), QObject::tr(), and QString::unicode().
Referenced by AppLnk::AppLnk(), FileSelector::FileSelector(), and CategoryMenu::reload().

void Categories::dump ( ) const

Dump the contents to standard out. Used for debugging only.
Definition at line 794 of file categories.cpp.
References QMap< QString, CategoryGroup >::begin(), QMap< QString, CategoryGroup >::end(), QStringList::join(), CategoryGroup::labels(), and QString::latin1().

const QMap< QString, CategoryGroup > & Categories::appGroupMap ( ) const [inline]

Returns a map of application names to CategoryGroup. The CategoryGroup class defines a map of ids to category labels and category labels to ids.
Definition at line 196 of file categories.h.

const CategoryGroup & Categories::globalGroup ( ) const [inline]

Returns the global CategoryGroup. The CategoryGroup class defines a map of ids to category labels and category labels to ids.
Definition at line 197 of file categories.h.

void Categories::categoryAdded ( const Categories & cats,

const QString & appname,

int uid

) [signal]

emitted if added a category; the second param is the application the category was added to or null if global the third param is the uid of the newly added category
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
Referenced by addCategory(), and addGlobalCategory().

void Categories::categoryRemoved ( const Categories & cats,

const QString & appname,

int uid

) [signal]

emitted if removed a category the second param is the application the category was removed from or null if global the third param is the uid of the removed 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
Referenced by removeCategory(), and removeGlobalCategory().

void Categories::categoryRenamed ( const Categories & cats,

const QString & appname,

int uid

) [signal]

emitted if a category is renamed; the second param is the uid of 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
Referenced by renameCategory(), and renameGlobalCategory().

The documentation for this class was generated from the following files:

Qtopia library API Documentation

Categories Class Reference

Public Types

Signals

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

Member Function Documentation