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,8 +1,9 @@
 /**********************************************************************
 ** Copyright (C) 2001 Trolltech AS.  All rights reserved.
+** Copyright (C) 2003 zecke introduce a needed symbol
 **
 ** This file is part of Qtopia Environment.
 **
 ** This file may be distributed and/or modified under the terms of the
 ** GNU General Public License version 2 as published by the Free Software
 ** Foundation and appearing in the file LICENSE.GPL included in the
@@ -28,12 +29,47 @@
 
 #include "categorywidget.h"
 #include "categoryselect.h"
 
 #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");
     str +="/.cateditting";
     return str;
 }
@@ -246,13 +282,13 @@ CategoryCombo::~CategoryCombo()
 }
 
 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"
 	returnMe = -2;
     else
 	returnMe =  d->mAppCats[returnMe];
@@ -283,50 +319,88 @@ void CategoryCombo::setCurrentText( const QString &str )
 
 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 ),
       cmdCat( 0 ),
       d( 0 )
 {
     d = new CategorySelectPrivate();
     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)
     : QHBox( parent, name )
 {
     d = new CategorySelectPrivate( vl );
 
     init(width);
 
     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,
 				QWidget *parent, const char *name , int width)
     : QHBox( parent, name )
 {
     d = new CategorySelectPrivate( vl );
     init(width);
     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() )){
         QMessageBox::warning(this,tr("Error"),
 	   tr("Sorry, another application is\nediting categories.") );
         return;
@@ -354,12 +428,16 @@ void CategorySelect::slotDialog()
     }
 
     f.close();
     QFile::remove( categoryEdittingFileName() );
 }
 
+
+/*!
+  This slot is called when a new Category is available.
+*/
 void CategorySelect::slotNewCat( int newUid )
 {
     if ( newUid != -1 ) {
 	bool alreadyIn = false;
 	for ( uint it = 0; it < d->mRec.count(); ++it ) {
 	    if ( d->mRec[it] == newUid ) {
@@ -373,18 +451,34 @@ void CategorySelect::slotNewCat( int newUid )
 	}
     } else
     d->mRec.resize(0);  // now Unfiled.
     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 )
 {
     d->mVisibleName = visibleName;
     mStrAppName = appName;
@@ -403,50 +497,64 @@ void CategorySelect::init(int width)
     cmdCat->setTextLabel( "...", FALSE );
     cmdCat->setUsesTextLabel( true );
     cmdCat->setMaximumSize( cmdCat->sizeHint() );
     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 ) {
 	cmdCat->setEnabled( FALSE );
 	cmdCat->hide();
     } else {
 	cmdCat->setEnabled( TRUE );
 	cmdCat->show();
     }
 }
 
+/*!
+  Changes this CategorySelect to the All category if \a all is TRUE.
+ */
 void CategorySelect::setAllCategories( bool add )
 {
     d->usingAll = add;
     if ( add ) {
 	cmbCat->insertItem( tr( "All" ), cmbCat->count() );
 	cmbCat->setCurrentItem( cmbCat->count() - 1 );
     } else
 	cmbCat->removeItem( cmbCat->count() - 1 );
 }
 
 // 01.12.21 added
+/*!
+  Sets the fixed width of the widget to \a width.
+  */
 void CategorySelect::setFixedWidth(int width)
 {
   width -= cmdCat->width();
   cmbCat->setFixedWidth(width);
 }