Merged branches from BRANCH_1_0

1 files changed, 111 insertions, 3 deletions

diff --git a/library/categoryselect.cpp b/library/categoryselect.cpp
index 21b3f91..8473aeb 100644
--- a/library/categoryselect.cpp
+++ b/library/categoryselect.cpp
@@ -1,5 +1,6 @@
 /**********************************************************************
 ** Copyright (C) 2001 Trolltech AS.  All rights reserved.
+** Copyright (C) 2003 zecke introduce a needed symbol
 **
 ** This file is part of Qtopia Environment.
 **
@@ -31,6 +32,41 @@
 
 #include <stdlib.h>
 
+
+/*! \enum CategorySelect::SelectorWidget
+  Chooses a type of widget to use as the selection widget.
+
+  \value ComboBox
+  \value ListView
+*/
+
+/*!
+  \class CategorySelect
+  \brief The CategorySelect widget allows users to select Categories with a
+  combobox interface.
+
+  CategorySelect is useful to provide a QComboBox of Categories for
+  filtering (such as in the Contacts table view) or to allow the user
+  to select multiple Categories. The allCategories variable sets
+  whether the CategorySelect is in filtering or selecting mode.
+
+  In filtering mode, the All and Unfiled categories are added. The
+
+  In selecting mode, the CategorySelect may either be a QComboBox and
+  a QToolButton or a QListView with checkable items depending on the
+  screen size.
+
+  CategorySelect automatically updates itself if Categories has been
+  changed elsewhere in the environment.
+
+  Signals and slots are provided to notify the application of the users
+  selections.  A QToolButton is also provided so that users can edit the
+  Categories manually.
+
+  \ingroup qtopiaemb
+*/
+
+
 static QString categoryEdittingFileName()
 {
     QString str = getenv("HOME");
@@ -249,7 +285,7 @@ int CategoryCombo::currentCategory() const
 {
     int returnMe;
     returnMe = currentItem();
-    
+
     if ( returnMe == (int)d->mAppCats.count() )
 	returnMe = -1;
     else if ( returnMe > (int)d->mAppCats.count() )  // only happen on "All"
@@ -286,6 +322,26 @@ void CategoryCombo::slotValueChanged( int )
     emit sigCatChanged( currentCategory() );
 }
 
+/*!
+  Constructs a category selector with parent \a parent, name \a name.
+
+  This constructor is provided to make Opie compatible with Sharp ROM.
+*/
+CategorySelect::CategorySelect( QWidget* parent,  const char* name )
+    : QHBox( parent, name ),
+      cmbCat( 0 ),
+      cmdCat( 0 ),
+      d( 0 )
+{
+    d = new CategorySelectPrivate();
+    init(0); // default argument
+}
+/*!
+  Constructs a category selector with parent \a parent, name \a name and
+  fixed width \a width.
+
+  This constructor is provided to make integration with Qt Designer easier.
+*/
 CategorySelect::CategorySelect( QWidget *parent, const char *name,int width)
     : QHBox( parent, name ),
       cmbCat( 0 ),
@@ -296,6 +352,11 @@ CategorySelect::CategorySelect( QWidget *parent, const char *name,int width)
     init(width);
 }
 
+/*!
+  \overload
+  This constructor accepts an array \a vl of integers representing Categories.
+  \a appName is used as the visible name string.
+*/
 CategorySelect::CategorySelect( const QArray<int> &vl,
 				const QString &appName, QWidget *parent,
 				const char *name ,int width)
@@ -308,6 +369,13 @@ CategorySelect::CategorySelect( const QArray<int> &vl,
     setCategories( vl, appName, appName );
 }
 
+/*!
+  \overload
+
+  This constructor accepts an array \a vl of integers representing Categories.
+  \a visibleName is the string used when the name of this widget is required
+  to be displayed. \a width is an integer used as the fixed width of the widget.
+*/
 CategorySelect::CategorySelect( const QArray<int> &vl,
 				const QString &appName,
 				const QString &visibleName,
@@ -319,11 +387,17 @@ CategorySelect::CategorySelect( const QArray<int> &vl,
     setCategories( vl, appName, visibleName );
 }
 
+/*!
+  Destructs a CategorySelect widget.
+*/
 CategorySelect::~CategorySelect()
 {
     delete d;
 }
 
+/*!
+  This slot is called when the user pushes the button to edit Categories.
+*/
 void CategorySelect::slotDialog()
 {
     if (QFile::exists( categoryEdittingFileName() )){
@@ -357,6 +431,10 @@ void CategorySelect::slotDialog()
     QFile::remove( categoryEdittingFileName() );
 }
 
+
+/*!
+  This slot is called when a new Category is available.
+*/
 void CategorySelect::slotNewCat( int newUid )
 {
     if ( newUid != -1 ) {
@@ -376,12 +454,28 @@ void CategorySelect::slotNewCat( int newUid )
     emit signalSelected( currentCategory() );
 }
 
+/*!
+  \overload
+
+  Resets the CategorySelect to select the \a vlCats for
+  the Categories assoicated with \a appName.
+
+  This function should only be called if <i>filtering</i>
+  on Categories and not selecting and therefore possibly
+  allowing the user to edit Categories.
+*/
 QString CategorySelect::setCategories( const QArray<int> &rec,
 				    const QString &appName )
 {
     return setCategories( rec, appName, appName );
 }
 
+/*!
+  Resets the CategorySelect to select the \a vlCats for
+  the Categories assoicated with \a appName and displays
+  the \a visibleName if the user is selecting and therefore editing
+  new Categories.
+ */
 QString CategorySelect::setCategories( const QArray<int> &rec,
 				    const QString &appName,
 				    const QString &visibleName )
@@ -406,23 +500,31 @@ void CategorySelect::init(int width)
     cmdCat->setFocusPolicy( TabFocus );
 }
 
-
+/*!
+  Return the value of the currently selected category.
+ */
 int CategorySelect::currentCategory() const
 {
     return cmbCat->currentCategory();
 }
 
+
 void CategorySelect::setCurrentCategory( int newCatUid )
 {
     cmbCat->setCurrentCategory( newCatUid );
 }
 
-
+/*!
+  Returns a shallow copy of the categories in this CategorySelect.
+ */
 const QArray<int> &CategorySelect::currentCategories() const
 {
     return d->mRec;
 }
 
+/*!
+  Hides the edit section of the CategorySelect widget if \a remove is TRUE.
+ */
 void CategorySelect::setRemoveCategoryEdit( bool remove )
 {
     if ( remove ) {
@@ -434,6 +536,9 @@ void CategorySelect::setRemoveCategoryEdit( bool remove )
     }
 }
 
+/*!
+  Changes this CategorySelect to the All category if \a all is TRUE.
+ */
 void CategorySelect::setAllCategories( bool add )
 {
     d->usingAll = add;
@@ -445,6 +550,9 @@ void CategorySelect::setAllCategories( bool add )
 }
 
 // 01.12.21 added
+/*!
+  Sets the fixed width of the widget to \a width.
+  */
 void CategorySelect::setFixedWidth(int width)
 {
   width -= cmdCat->width();