1 files changed, 52 insertions, 0 deletions

diff --git a/library/categorymenu.cpp b/library/categorymenu.cpp
index e733107..5d7adf7 100644
--- a/library/categorymenu.cpp
+++ b/library/categorymenu.cpp
@@ -24,6 +24,35 @@
 #include <qstring.h>
 #include <qmap.h>
 
+/*!
+  \class CategoryMenu
+  \brief The CategoryMenu widget aids in filtering records or files by Category.
+
+  The CategoryMenu widget provides a popup menu that will make filtering records
+  or files by category much easier.  The widget will lookup the available
+  categories for an application, populate the menu, and keep a track of which
+  categories are being filtered against.  A set of categories can be tested
+  by the isSelected() function to see if a record or file containing those
+  categories would be allowed through by the filter.
+
+  \warning Currently this class is not suitable for extending.
+
+  \ingroup qtopiaemb
+*/
+
+/*!
+  \fn void CategoryMenu::categoryChange()
+  This signal is emitted when the user selects a different category in the
+  menu, hence changing what records or files should be selected.
+*/
+
+/*!
+  Creates a new CategoryMenu with \a parent and \a name.  The menu will be
+  populated with the available categories for \a application.
+
+  If \a globals is TRUE then it will also poplulate the menu with the
+  global categories.
+*/
 CategoryMenu::CategoryMenu( const QString &n, bool ig = TRUE,
         QWidget *parent, const char *name ) : 
     QPopupMenu(parent, name),
@@ -35,10 +64,16 @@ CategoryMenu::CategoryMenu( const QString &n, bool ig = TRUE,
     connect(this, SIGNAL(activated(int)), this, SLOT(mapMenuId(int)));
 }
 
+/*!
+  Destroys a CategoryMenu.
+*/
 CategoryMenu::~CategoryMenu( ) 
 {
 }
 
+/*!
+  Repopulates the widget's list of available categories.
+*/
 void CategoryMenu::reload()
 {
     clear();
@@ -66,6 +101,9 @@ void CategoryMenu::reload()
     setItemChecked(currentMid, TRUE );
 }
 
+/*!
+  \internal
+*/
 void CategoryMenu::mapMenuId(int id) 
 {
     if (id == currentMid)
@@ -77,6 +115,11 @@ void CategoryMenu::mapMenuId(int id)
     emit categoryChange();
 }
 
+/*!
+  Returns TRUE if a record or file with the set of category ids \a cUids
+  is allowed by the current selection in the CategoryMenu.
+  Otherwise returns FALSE.
+*/
 bool CategoryMenu::isSelected(const QArray<int> &cUids) const
 {
     if (currentMid == 1)
@@ -91,6 +134,9 @@ bool CategoryMenu::isSelected(const QArray<int> &cUids) const
     return FALSE;
 }
 
+/*!
+  Sets the menu to have \a newCatUid as the currently selected Category.
+*/
 void CategoryMenu::setCurrentCategory( int newCatUid )
 {
     if (!idToMenu.contains(newCatUid)) 
@@ -99,11 +145,17 @@ void CategoryMenu::setCurrentCategory( int newCatUid )
     mapMenuId(idToMenu[newCatUid]);
 }
 
+/*!
+  Sets the menu to allow all category sets.
+*/
 void CategoryMenu::setCurrentCategoryAll( )
 {
     mapMenuId(1);
 }
 
+/*!
+  Sets the menu to allow only empty category sets.
+*/
 void CategoryMenu::setCurrentCategoryUnfiled( )
 {
     mapMenuId(2);