| -rw-r--r-- | library/categoryselect.cpp | 112 |
1 files changed, 110 insertions, 2 deletions
diff --git a/library/categoryselect.cpp b/library/categoryselect.cpp index 21b3f91..8473aeb 100644 --- a/library/categoryselect.cpp +++ b/library/categoryselect.cpp @@ -1,14 +1,15 @@ /********************************************************************** ** 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 ** packaging of this file. ** ** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE ** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. ** ** See http://www.trolltech.com/gpl/ for GPL licensing information. @@ -22,24 +23,59 @@ #include <qpe/palmtoprecord.h> #include <qmessagebox.h> #include <qlayout.h> #include <qtoolbutton.h> #include <qfile.h> #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; } class CategoryComboPrivate { public: CategoryComboPrivate(QObject *o) : mCat( o ) @@ -277,62 +313,100 @@ void CategoryCombo::setCurrentText( const QString &str ) if ( text( i ) == str ) { setCurrentItem( i ); break; } } } 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; } QFile f( categoryEdittingFileName() ); if ( !f.open( IO_WriteOnly) ){ return; } @@ -348,105 +422,139 @@ void CategorySelect::slotDialog() sv->addChild( &ce ); editDlg.showMaximized(); if ( editDlg.exec() ) { d->mRec = ce.newCategories(); cmbCat->initCombo( d->mRec, mStrAppName ); } 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 ) { alreadyIn = true; break; } } if ( !alreadyIn ) { d->mRec.resize( 1 ); d->mRec[ 0 ] = 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; d->mRec = cmbCat->initComboWithRefind( rec, appName ); return Qtopia::Record::idsToString(d->mRec); } void CategorySelect::init(int width) { cmbCat = new CategoryCombo( this, 0, width); QObject::connect( cmbCat, SIGNAL(sigCatChanged(int)), this, SLOT(slotNewCat(int)) ); cmdCat = new QToolButton( this ); QObject::connect( cmdCat, SIGNAL(clicked()), this, SLOT(slotDialog()) ); 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); } |