Main Page | Namespace List | Class Hierarchy | Alphabetical List | Class List | Directories | File List | Namespace Members | Class Members | File Members | Related Pages

Categories Class Reference

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

#include </home/clem/local/src/opie/library/backend/categories.h>

Collaboration diagram for Categories:

Collaboration graph
[legend]
List of all members.

Public Types

enum  ExtraLabels { NoExtra, AllUnfiled, AllLabel, UnfiledLabel }
enum  DisplaySingle { ShowMulti, ShowAll, ShowFirst }

Signals

void categoryAdded (const Categories &, const QString &, int)
void categoryRemoved (const Categories &, const QString &, int)
void categoryRenamed (const Categories &, const QString &, int)

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)
int addCategory (const QString &appname, const QString &catname, int uid)
int addGlobalCategory (const QString &catname)
int addGlobalCategory (const QString &catname, int uid)
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
QStringList labels (const QString &app, bool includeGlobal=TRUE, ExtraLabels extra=NoExtra) const
QStringList labels (const QString &app, const QArray< int > &catids) const
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 value)
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

Private Attributes

CategoryGroup mGlobalCats
QMap< QString, CategoryGroup > mAppCats

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.

Member Enumeration Documentation

enum Categories::DisplaySingle
 

Enumeration values:
ShowMulti 
ShowAll 
ShowFirst 

Definition at line 157 of file categories.h.

enum Categories::ExtraLabels
 

Enumeration values:
NoExtra 
AllUnfiled 
AllLabel 
UnfiledLabel 

Definition at line 139 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

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< Key, T >::end(), QMap< Key, T >::find(), QMap< Key, T >::insert(), mAppCats, and mGlobalCats.

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< Key, T >::end(), QMap< Key, T >::find(), QMap< Key, T >::insert(), mAppCats, and mGlobalCats.

Referenced by AppLnk::AppLnk(), AppLnkPrivate::ensureCatArray(), setGlobal(), and CategoryEdit::slotAdd().

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(), categoryAdded(), mGlobalCats, and QString::null.

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(), categoryAdded(), mGlobalCats, and QString::null.

Referenced by load(), and setGlobal().

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.

void Categories::categoryAdded (  const Categories &  ,
const QString &  ,
int 
)  [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

Referenced by addCategory(), and addGlobalCategory().

void Categories::categoryRemoved (  const Categories &  ,
const QString &  ,
int 
)  [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

Referenced by removeCategory(), and removeGlobalCategory().

void Categories::categoryRenamed (  const Categories &  ,
const QString &  ,
int 
)  [signal]
 

emitted if a category is renamed; the second param is the uid of the removed category

Referenced by renameCategory(), and renameGlobalCategory().

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< Key, T >::clear(), CategoryGroup::clear(), mAppCats, and mGlobalCats.

Referenced by load().

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< T >::count(), QValueList< T >::first(), QStringList::join(), labels(), ShowAll, ShowFirst, ShowMulti, QStringList::sort(), and tr.

void Categories::dump (   )  const
 

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

Definition at line 794 of file categories.cpp.

References app, QMap< Key, T >::begin(), QMap< Key, T >::end(), QStringList::join(), CategoryGroup::labels(), QString::latin1(), mAppCats, mGlobalCats, and qDebug().

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< Key, T >::end(), FALSE, QMap< Key, T >::find(), and mAppCats.

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

Returns true if the catname is associated with any application

Definition at line 610 of file categories.cpp.

References QMap< Key, T >::begin(), QMap< Key, T >::end(), FALSE, isGlobal(), mAppCats, and TRUE.

QStringList Categories::globalCategories (   )  const [inline]
 

Returns list of all global category labels

Definition at line 172 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.

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

Returns the id associated with the app

Definition at line 521 of file categories.cpp.

References QString::contains(), CategoryGroup::id(), mAppCats, mGlobalCats, and tr.

Referenced by AppLnk::AppLnk(), Todo::TodoManager::catId(), AppLnkPrivate::ensureCatArray(), ids(), load(), CategoryEdit::newCategories(), CategoryMenu::reload(), AbView::setShowByCategory(), and AbView::slotDoFind().

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< T >::begin(), QValueList< T >::end(), i, and id().

Referenced by CategoryCombo::initCombo(), CategoryCombo::initComboWithRefind(), and CategoryEdit::setCategories().

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(), and mGlobalCats.

Referenced by exists(), and CategoryEdit::setCategories().

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

Returns the label associated with the id

Definition at line 446 of file categories.cpp.

References CategoryGroup::contains(), QMap< Key, T >::end(), QMap< Key, T >::find(), CategoryGroup::label(), mAppCats, mGlobalCats, and QString::null.

Referenced by OPimRecord::categoryNames(), Opie::OPimRecord::categoryNames(), AbView::showCategory(), and AppLnkPrivate::updateCatListFromArray().

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

Definition at line 934 of file categories.cpp.

References CategoryGroup::labels(), mAppCats, and mGlobalCats.

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 AllLabel, AllUnfiled, QValueList< T >::append(), QMap< Key, T >::end(), QMap< Key, T >::find(), CategoryGroup::labels(), mAppCats, mGlobalCats, NoExtra, QStringList::sort(), tr, and UnfiledLabel.

Referenced by Todo::TodoManager::categories(), AbView::categories(), displaySingle(), CategoryCombo::initCombo(), CategoryCombo::initComboWithRefind(), CategoryMenu::reload(), Opie::OPimMainWindow::reloadCategories(), DocumentList::sendAllDocLinks(), and CategoryEdit::setCategories().

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(), app, clear(), data, FALSE, QString::find(), QString::fromUtf8(), i, id(), IO_ReadOnly, QString::isNull(), QString::latin1(), len, QString::length(), mAppCats, mGlobalCats, name, QString::null, QFile::open(), Qtopia::plainString(), qWarning(), QIODevice::readAll(), save(), Opie::Internal::string(), tr, TRUE, and QString::unicode().

Referenced by AbView::AbView(), OPimRecord::addCategoryName(), Opie::OPimRecord::addCategoryName(), AppLnk::AppLnk(), Todo::TodoManager::categories(), AbView::categories(), CategoryEditPrivate::CategoryEditPrivate(), OPimRecord::categoryNames(), Opie::OPimRecord::categoryNames(), AppLnkPrivate::ensureCatArray(), FileSelector::FileSelector(), CategoryCombo::initCombo(), CategoryCombo::initComboWithRefind(), CategoryMenu::reload(), Opie::OPimMainWindow::reloadCategories(), Todo::TodoManager::TodoManager(), AppLnkPrivate::updateCatListFromArray(), LauncherView::updateTools(), and Doc_DirLister::widget().

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

Performs deep copy.

Definition at line 100 of file categories.h.

References mAppCats, and mGlobalCats.

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< Key, T >::end(), FALSE, QMap< Key, T >::find(), mAppCats, CategoryGroup::remove(), and TRUE.

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

Definition at line 341 of file categories.cpp.

References categoryRemoved(), QMap< Key, T >::end(), FALSE, QMap< Key, T >::find(), CategoryGroup::id(), mAppCats, CategoryGroup::remove(), removeGlobalCategory(), and TRUE.

Referenced by setGlobal(), and CategoryEdit::slotRemove().

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(), FALSE, mGlobalCats, QString::null, CategoryGroup::remove(), and TRUE.

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(), FALSE, CategoryGroup::id(), mGlobalCats, QString::null, CategoryGroup::remove(), and TRUE.

Referenced by removeCategory().

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< Key, T >::end(), QMap< Key, T >::find(), CategoryGroup::id(), mAppCats, CategoryGroup::rename(), renameGlobalCategory(), and TRUE.

Referenced by CategoryEdit::slotTextChanged().

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(), FALSE, CategoryGroup::id(), mGlobalCats, QString::null, CategoryGroup::rename(), and TRUE.

Referenced by renameCategory(), and CategoryEdit::slotTextChanged().

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 app, QMap< Key, T >::begin(), QFile::close(), QMap< Key, T >::end(), Qtopia::escapeString(), f, FALSE, CategoryGroup::idMap(), IO_Raw, IO_WriteOnly, QString::latin1(), QCString::length(), mAppCats, mGlobalCats, QString::number(), QFile::open(), out, qWarning(), QFile::remove(), TRUE, QString::utf8(), and QFile::writeBlock().

Referenced by CategoryEdit::accept(), load(), and CategoryEdit::newCategories().

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(), FALSE, mGlobalCats, CategoryGroup::remove(), and removeCategory().

Referenced by CategoryEdit::slotSetGlobal().

Member Data Documentation

QMap< QString, CategoryGroup > Categories::mAppCats [private]
 

Definition at line 218 of file categories.h.

Referenced by addCategory(), clear(), dump(), exists(), id(), label(), labels(), load(), operator=(), removeCategory(), renameCategory(), and save().

CategoryGroup Categories::mGlobalCats [private]
 

Definition at line 217 of file categories.h.

Referenced by addCategory(), addGlobalCategory(), clear(), dump(), id(), isGlobal(), label(), labels(), load(), operator=(), removeGlobalCategory(), renameGlobalCategory(), save(), and setGlobal().

The documentation for this class was generated from the following files:
Generated on Sat Nov 5 17:28:06 2005 for OPIE by  doxygen 1.4.2