Jumbo API documentation update

and some API fixed
ColorDialog is now OColorDialog!!! keep the namespace tidy!
ColorPopupMenu is now OColorPopupMenu!!! keep the namespace tidy
ColorDialog TT couldn't break bc we can so make it const QColor&
OTimePicker add some convience methods

more I might have forgot

31 files changed, 832 insertions, 174 deletions

diff --git a/libopie/colordialog.cpp b/libopie/colordialog.cpp
index 684d6ea..35f15d6 100644
--- a/libopie/colordialog.cpp
+++ b/libopie/colordialog.cpp
@@ -12,96 +12,101 @@
 ** This file may be distributed under the terms of the Q Public License
 ** as defined by Trolltech AS of Norway and appearing in the file
 ** LICENSE.QPL included in the packaging of this file.
 **
 ** 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.
 **
 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
 ** licenses may use this file in accordance with the Qt Commercial License
 ** Agreement provided with the Software.
 **
 ** 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/pricing.html or email sales@trolltech.com for
 **   information about Qt Commercial License Agreements.
 ** See http://www.trolltech.com/qpl/ for QPL licensing information.
 ** See http://www.trolltech.com/gpl/ for GPL licensing information.
 **
 ** Contact info@trolltech.com if any conditions of this licensing are
 ** not clear to you.
 **
 **********************************************************************/
 
 #include "colordialog.h"
 
 #include "qpainter.h"
 #include "qlayout.h"
 #include "qlabel.h"
 #include "qpushbutton.h"
 #include "qlineedit.h"
 #include "qimage.h"
 #include "qpixmap.h"
 #include "qdrawutil.h"
 #include "qvalidator.h"
 #include "qdragobject.h"
 #include "qapplication.h"
 #include "qdragobject.h"
 
 static inline void rgb2hsv( QRgb rgb, int&h, int&s, int&v )
 {
     QColor c;
     c.setRgb( rgb );
     c.getHsv(h,s,v);
 }
 
+/*
+ * avoid clashes with the original Qt
+ */
+namespace {
+
 class QColorPicker : public QFrame
 {
     Q_OBJECT
 public:
     QColorPicker(QWidget* parent=0, const char* name=0);
     ~QColorPicker();
 
 public slots:
     void setCol( int h, int s );
 
 signals:
     void newCol( int h, int s );
 
 protected:
     QSize sizeHint() const;
     QSizePolicy sizePolicy() const;
     void drawContents(QPainter* p);
     void mouseMoveEvent( QMouseEvent * );
     void mousePressEvent( QMouseEvent * );
 
 private:
     int hue;
     int sat;
 
     QPoint colPt();
     int huePt( const QPoint &pt );
     int satPt( const QPoint &pt );
     void setCol( const QPoint &pt );
 
     QPixmap *pix;
 };
 
 static int pWidth = 200;
 static int pHeight = 200;
 
 class QColorLuminancePicker : public QWidget
 {
     Q_OBJECT
 public:
     QColorLuminancePicker(QWidget* parent=0, const char* name=0);
     ~QColorLuminancePicker();
 
 public slots:
     void setCol( int h, int s, int v );
     void setCol( int h, int s );
 
 signals:
     void newHsv( int h, int s, int v );
@@ -562,290 +567,292 @@ void QColorShower::hsvEd()
     val = vEd->val();
 
     curCol = QColor( hue, sat, val, QColor::Hsv ).rgb();
 
     rEd->setNum( qRed(currentColor()) );
     gEd->setNum( qGreen(currentColor()) );
     bEd->setNum( qBlue(currentColor()) );
 
     showCurrentColor();
     emit newCol( currentColor() );
 }
 
 void QColorShower::setRgb( QRgb rgb )
 {
     rgbOriginal = TRUE;
     curCol = rgb;
 
     rgb2hsv( currentColor(), hue, sat, val );
 
     hEd->setNum( hue );
     sEd->setNum( sat );
     vEd->setNum( val );
 
     rEd->setNum( qRed(currentColor()) );
     gEd->setNum( qGreen(currentColor()) );
     bEd->setNum( qBlue(currentColor()) );
 
     showCurrentColor();
 }
 
 void QColorShower::setHsv( int h, int s, int v )
 {
     rgbOriginal = FALSE;
     hue = h; val = v; sat = s; //Range check###
     curCol = QColor( hue, sat, val, QColor::Hsv ).rgb();
 
     hEd->setNum( hue );
     sEd->setNum( sat );
     vEd->setNum( val );
 
     rEd->setNum( qRed(currentColor()) );
     gEd->setNum( qGreen(currentColor()) );
     bEd->setNum( qBlue(currentColor()) );
 
 
     showCurrentColor();
 }
 
+}
+
 class OColorDialogPrivate : public QObject
 {
 Q_OBJECT
 public:
     OColorDialogPrivate( OColorDialog *p );
     QRgb currentColor() const { return cs->currentColor(); }
-    void setCurrentColor( QRgb rgb );
+    void setCurrentColor( const QRgb& rgb );
 
     int currentAlpha() const { return cs->currentAlpha(); }
     void setCurrentAlpha( int a ) { cs->setCurrentAlpha( a ); }
     void showAlpha( bool b ) { cs->showAlpha( b ); }
 
 private slots:
     void newHsv( int h, int s, int v );
     void newColorTypedIn( QRgb rgb );
 private:
     QColorPicker *cp;
     QColorLuminancePicker *lp;
     QColorShower *cs;
 };
 
 //sets all widgets to display h,s,v
 void OColorDialogPrivate::newHsv( int h, int s, int v )
 {
     cs->setHsv( h, s, v );
     cp->setCol( h, s );
     lp->setCol( h, s, v );
 }
 
 //sets all widgets to display rgb
-void OColorDialogPrivate::setCurrentColor( QRgb rgb )
+void OColorDialogPrivate::setCurrentColor( const QRgb& rgb )
 {
     cs->setRgb( rgb );
     newColorTypedIn( rgb );
 }
 
 //sets all widgets exept cs to display rgb
 void OColorDialogPrivate::newColorTypedIn( QRgb rgb )
 {
     int h, s, v;
     rgb2hsv(rgb, h, s, v );
     cp->setCol( h, s );
     lp->setCol( h, s, v);
 }
 
 OColorDialogPrivate::OColorDialogPrivate( OColorDialog *dialog ) :
     QObject(dialog)
 {
     int border = 2;
     QVBoxLayout *topLay = new QVBoxLayout( dialog, border, 2 );
 
     QHBoxLayout *pickLay = new QHBoxLayout( topLay );
 
 
     cp = new QColorPicker( dialog );
     cp->setFrameStyle( QFrame::Panel + QFrame::Sunken );
     pickLay->addWidget( cp );
 
     pickLay->addStretch();
 
     lp = new QColorLuminancePicker( dialog );
     lp->setFixedWidth( 20 ); //###
     pickLay->addWidget( lp );
 
     connect( cp, SIGNAL(newCol(int,int)), lp, SLOT(setCol(int,int)) );
     connect( lp, SIGNAL(newHsv(int,int,int)), this, SLOT(newHsv(int,int,int)) );
 
     topLay->addStretch();
 
     cs = new QColorShower( dialog );
     connect( cs, SIGNAL(newCol(QRgb)), this, SLOT(newColorTypedIn(QRgb)));
     topLay->addWidget( cs );
 
 }
 
 
 // BEING REVISED: jo
 /*!
   \class OColorDialog OColorDialog.h
   \brief The OColorDialog class provides a dialog widget for specifying colors.
   \ingroup dialogs
 
   The color dialog's function is to allow users to choose colors -
   for instance, you might use this in a drawing program to allow the
   user to set the brush color.
 
   This version of Qt only provides modal color dialogs. The static
   getColor() function shows the dialog and allows the user to specify a color,
   while getRgba() does the same but allows the user to specify a color with an
   alpha channel (transparency) value.
 
   The user can store customCount() different custom colors. The custom
   colors are shared by all color dialogs, and remembered during the
   execution of the program. Use setCustomColor() to set the
   custom colors, and customColor() to get them.
 
   <img src=qcolordlg-m.png> <img src=qcolordlg-w.png>
 */
 
 /*!
   Constructs a default color dialog. Use setColor() for setting an initial value.
 
   \sa getColor()
 */
 
 OColorDialog::OColorDialog(QWidget* parent, const char* name, bool modal) :
     QDialog(parent, name, modal )
 {
     d = new OColorDialogPrivate( this );
 }
 
 
 /*!
   Pops up a modal color dialog letting the user choose a color and returns
   that color. The color is initially set to \a initial. Returns an  \link QColor::isValid() invalid\endlink color if the user cancels
   the dialog. All colors allocated by the dialog will be deallocated
   before this function returns.
 */
 
-QColor OColorDialog::getColor( QColor initial, QWidget *parent,
+QColor OColorDialog::getColor( const QColor& initial, QWidget *parent,
                                const char *name )
 {
     int allocContext = QColor::enterAllocContext();
     OColorDialog *dlg = new OColorDialog( parent, name, TRUE );  //modal
     if ( parent && parent->icon() && !parent->icon()->isNull() )
         dlg->setIcon( *parent->icon() );
     else if ( qApp->mainWidget() && qApp->mainWidget()->icon() && !qApp->mainWidget()->icon()->isNull() )
         dlg->setIcon( *qApp->mainWidget()->icon() );
 
     dlg->setCaption( OColorDialog::tr( "Select color" ) );
     dlg->setColor( initial );
     dlg->showMaximized();
     int resultCode = dlg->exec();
     QColor::leaveAllocContext();
     QColor result;
     if ( resultCode == QDialog::Accepted ) {
         result = dlg->color();
     } else {
         result = initial;
     }
     QColor::destroyAllocContext(allocContext);
     delete dlg;
     return result;
 }
 
 
 /*!
   Pops up a modal color dialog, letting the user choose a color and an
   alpha channel value. The color+alpha is initially set to \a initial.
 
   If \a ok is non-null, \c *ok is set to TRUE if the user clicked OK,
   and FALSE if the user clicked Cancel.
 
   If the user clicks Cancel the \a initial value is returned.
 */
 
-QRgb OColorDialog::getRgba( QRgb initial, bool *ok,
+QRgb OColorDialog::getRgba( const QRgb& initial, bool *ok,
                             QWidget *parent, const char* name )
 {
     int allocContext = QColor::enterAllocContext();
     OColorDialog *dlg = new OColorDialog( parent, name, TRUE );  //modal
     dlg->setColor( initial );
     dlg->setSelectedAlpha( qAlpha(initial) );
     dlg->showMaximized();
     int resultCode = dlg->exec();
     QColor::leaveAllocContext();
     QRgb result = initial;
     if ( resultCode == QDialog::Accepted ) {
         QRgb c = dlg->color().rgb();
         int alpha = dlg->selectedAlpha();
         result = qRgba( qRed(c), qGreen(c), qBlue(c), alpha );
     }
     if ( ok )
         *ok = resultCode == QDialog::Accepted;
 
     QColor::destroyAllocContext(allocContext);
     delete dlg;
     return result;
 }
 
 
 
 
 
 /*!
   Returns the color currently selected in the dialog.
 
   \sa setColor()
 */
 
 QColor OColorDialog::color() const
 {
     return QColor(d->currentColor());
 }
 
 
 /*! Destructs the dialog and frees any memory it allocated.
 
 */
 
 OColorDialog::~OColorDialog()
 {
     //d inherits QObject, so it is deleted by Qt.
 }
 
 
 /*!
   Sets the color shown in the dialog to \a c.
 
   \sa color()
 */
 
-void OColorDialog::setColor( QColor c )
+void OColorDialog::setColor( const QColor& c )
 {
     d->setCurrentColor( c.rgb() );
 }
 
 
 
 
 /*!
   Sets the initial alpha channel value to \a a, and show the alpha channel
   entry box.
 */
 
 void OColorDialog::setSelectedAlpha( int a )
 {
     d->showAlpha( TRUE );
     d->setCurrentAlpha( a );
 }
 
 
 /*!
   Returns the value selected for the alpha channel.
 */
 
 int OColorDialog::selectedAlpha() const
 {
     return d->currentAlpha();
 }
 
 #include "colordialog.moc"
diff --git a/libopie/colordialog.h b/libopie/colordialog.h
index 926f8f2..e9bb7ed 100644
--- a/libopie/colordialog.h
+++ b/libopie/colordialog.h
@@ -16,74 +16,74 @@
 ** 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.
 **
 ** Licensees holding valid Qt Enterprise Edition or Qt Professional Edition
 ** licenses may use this file in accordance with the Qt Commercial License
 ** Agreement provided with the Software.
 **
 ** 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/pricing.html or email sales@trolltech.com for
 **   information about Qt Commercial License Agreements.
 ** See http://www.trolltech.com/qpl/ for QPL licensing information.
 ** See http://www.trolltech.com/gpl/ for GPL licensing information.
 **
 ** Contact info@trolltech.com if any conditions of this licensing are
 ** not clear to you.
 **
 **********************************************************************/
 
 #ifndef OColorDialog_H
 #define OColorDialog_H
 
 #ifndef QT_H
 #include <qdialog.h>
 #endif // QT_H
 
 class OColorDialogPrivate;
 
 /**
  * @class OColorDialog
  * @brief The OColorDialog class is a copy of QColorDialog for use in Opie.
  *
  * OColorDialog is a copy of TrollTech's QColorDialog for use in Opie.  The default
  * build of QT/Embedded used by Opie does not include QColorDialog, so it is provided
  * here.  It is renamed to prevent conflicts in the event the QColorDialog is included
  * at a later date in QP/E.
  *
  * See http://doc.trolltech.com/2.3/qcolordialog.html for complete documentation of
  * QColorDialog.
  */
 class Q_EXPORT OColorDialog : public QDialog
 {
     Q_OBJECT
 
 public:
-    static QColor getColor( QColor, QWidget *parent=0, const char* name=0 ); // ### 3.0: make const QColor&
-    static QRgb getRgba( QRgb, bool* ok = 0,
+    static QColor getColor( const QColor&, QWidget *parent=0, const char* name=0 ); 
+    static QRgb getRgba( const QRgb&, bool* ok = 0,
                          QWidget *parent=0, const char* name=0 );
 
 private:
     ~OColorDialog();
 
     OColorDialog( QWidget* parent=0, const char* name=0, bool modal=FALSE );
-    void setColor( QColor ); // ### 3.0: make const QColor&
+    void setColor( const QColor& );
     QColor color() const;
 
 private:
     void setSelectedAlpha( int );
     int selectedAlpha() const;
 private:
     OColorDialogPrivate *d;
     friend class OColorDialogPrivate;
 
         private:// Disabled copy constructor and operator=
 #if defined(Q_DISABLE_COPY)
     OColorDialog( const OColorDialog & );
     OColorDialog& operator=( const OColorDialog & );
 #endif
 };
 
 #endif
diff --git a/libopie/colorpopupmenu.cpp b/libopie/colorpopupmenu.cpp
index 510a2ad..dac10e9 100644
--- a/libopie/colorpopupmenu.cpp
+++ b/libopie/colorpopupmenu.cpp
@@ -1,176 +1,170 @@
 /*
                             This file is part of the Opie Project
 
                  Copyright (c)  2002 S. Prud'homme <prudhomme@laposte.net>
                                      Dan Williams <williamsdr@acm.org>
               =.
             .=l.
            .>+-=
  _;:,     .>    :=|.         This program is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This program is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 #include "colorpopupmenu.h"
 #include "colordialog.h"
 
 #include <qaction.h>
 #include <qlayout.h>
 #include <qpainter.h>
 
-ColorPanelButton::ColorPanelButton( const QColor& color, QWidget* parent, const char* name )
+OColorPanelButton::OColorPanelButton( const QColor& color, QWidget* parent, const char* name )
     : QFrame( parent, name )
 {
     m_color = color;
 
     setFixedSize( 16, 16 );
     setActive( FALSE );
 }
 
-ColorPanelButton::~ColorPanelButton()
+OColorPanelButton::~OColorPanelButton()
 {
 }
 
-void ColorPanelButton::setActive( bool active )
+void OColorPanelButton::setActive( bool active )
 {
     m_active = active;
 
     if ( m_active ) {
         setFrameStyle( Panel | Sunken );
     } else {
         setFrameStyle( NoFrame );
     }
 }
 
-void ColorPanelButton::enterEvent( QEvent* e )
+void OColorPanelButton::enterEvent( QEvent*  )
 {
-    Q_UNUSED( e )
-
     if ( !m_active ) {
         setFrameStyle( Panel | Sunken );
     }
 }
 
-void ColorPanelButton::leaveEvent( QEvent* e )
+void OColorPanelButton::leaveEvent( QEvent*  )
 {
-    Q_UNUSED( e )
-
     if ( !m_active ) {
         setFrameStyle( NoFrame );
     }
 }
 
-void ColorPanelButton::paintEvent( QPaintEvent* e )
+void OColorPanelButton::paintEvent( QPaintEvent* e )
 {
     QFrame::paintEvent( e );
 
     QPainter painter;
     painter.begin( this );
     painter.fillRect( 2, 2, 12, 12, m_color );
     painter.setPen( Qt::black );
     painter.drawRect( 2, 2, 12, 12 );
     painter.end();
 }
 
-void ColorPanelButton::mouseReleaseEvent( QMouseEvent* e )
+void OColorPanelButton::mouseReleaseEvent( QMouseEvent*   )
 {
-    Q_UNUSED( e )
-
     emit selected( m_color );
 }
 
-ColorPopupMenu::ColorPopupMenu( const QColor& color, QWidget* parent, const char* name )
+OColorPopupMenu::OColorPopupMenu( const QColor& color, QWidget* parent, const char* name )
     : QPopupMenu( parent, name )
 {
     m_color = color;
 
     colorPanel = new QWidget( this );
 
     colorLayout = new QGridLayout(colorPanel, 5, 6);
 
     addColor(QColor(255, 255, 255), 0, 1);
     addColor(QColor(192, 192, 192), 0, 2);
     addColor(QColor(128, 128, 128), 0, 3);
     addColor(QColor(64, 64, 64), 0, 4);
     addColor(QColor(0, 0, 0), 0, 5);
 
     addColor(QColor(255, 0, 0), 1, 0);
     addColor(QColor(255, 128, 0), 1, 1);
     addColor(QColor(255, 255, 0), 1, 2);
     addColor(QColor(128, 255, 0), 1, 3);
     addColor(QColor(0, 255, 0), 1, 4);
     addColor(QColor(0, 255, 128), 1, 5);
 
     addColor(QColor(128, 0, 0), 2, 0);
     addColor(QColor(128, 64, 0), 2, 1);
     addColor(QColor(128, 128, 0), 2, 2);
     addColor(QColor(64, 128, 0), 2, 3);
     addColor(QColor(0, 128, 0), 2, 4);
     addColor(QColor(0, 128, 64), 2, 5);
 
     addColor(QColor(0, 255, 255), 3, 0);
     addColor(QColor(0, 128, 255), 3, 1);
     addColor(QColor(0, 0, 255), 3, 2);
     addColor(QColor(128, 0, 255), 3, 3);
     addColor(QColor(255, 0, 255), 3, 4);
     addColor(QColor(255, 0, 128), 3, 5);
 
     addColor(QColor(0, 128, 128), 4, 0);
     addColor(QColor(0, 64, 128), 4, 1);
     addColor(QColor(0, 0, 128), 4, 2);
     addColor(QColor(64, 0, 128), 4, 3);
     addColor(QColor(128, 0, 128), 4, 4);
     addColor(QColor(128, 0, 64), 4, 5);
 
     insertItem( colorPanel );
     insertSeparator();
     QAction* chooseColorAction = new QAction( tr( "More" ), tr( "More..." ), 0, colorPanel, "More" );
     connect( chooseColorAction, SIGNAL( activated() ), this, SLOT( moreColorClicked() ) );
     chooseColorAction->addTo( this );
     activateItemAt( 0 );
 }
 
-ColorPopupMenu::~ColorPopupMenu()
+OColorPopupMenu::~OColorPopupMenu()
 {
 }
 
-void ColorPopupMenu::addColor( const QColor& color, int row, int col )
+void OColorPopupMenu::addColor( const QColor& color, int row, int col )
 {
-    ColorPanelButton* panelButton = new ColorPanelButton( color, colorPanel );
+    OColorPanelButton* panelButton = new OColorPanelButton( color, colorPanel );
     connect( panelButton, SIGNAL( selected( const QColor& ) ), this, SLOT( buttonSelected( const QColor& ) ) );
     colorLayout->addWidget( panelButton, row, col );
 }
 
-void ColorPopupMenu::buttonSelected( const QColor& color )
+void OColorPopupMenu::buttonSelected( const QColor& color )
 {
     m_color = color;
     emit colorSelected( color );
     hide();
 }
 
-void ColorPopupMenu::moreColorClicked()
+void OColorPopupMenu::moreColorClicked()
 {
     QColor color = OColorDialog::getColor( m_color );
     m_color = color;
     emit colorSelected( color );
     hide();
 }
diff --git a/libopie/colorpopupmenu.h b/libopie/colorpopupmenu.h
index b0453b2..184b132 100644
--- a/libopie/colorpopupmenu.h
+++ b/libopie/colorpopupmenu.h
@@ -1,235 +1,235 @@
 /*
                             This file is part of the Opie Project
 
                  Copyright (c)  2002 S. Prud'homme <prudhomme@laposte.net>
                                      Dan Williams <williamsdr@acm.org>
               =.
             .=l.
            .>+-=
  _;:,     .>    :=|.         This program is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This program is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 #ifndef COLORPOPUPMENU_H
 #define COLORPOPUPMENU_H
 
 #include <qframe.h>
 #include <qpopupmenu.h>
 
 class QWidget;
 class QGridLayout;
 
 /**
- * @class ColorPanelButton
- * @brief The ColorPanelButton class provides a button for color selection.
+ * @class OColorPanelButton
+ * @brief The OColorPanelButton class provides a button for color selection.
  *
- * @see ColorPopupMenu
+ * @see OColorPopupMenu
  *
- * The ColorPanelButton class provides a button for color selection.  The button
+ * The OColorPanelButton class provides a button for color selection.  The button
  * is drawn with the desired color and no border.  This class is used internally
- * by the ColorPopupMenu class to displaying colors in its menu.
+ * by the OColorPopupMenu class to displaying colors in its menu.
  */
-class ColorPanelButton : public QFrame
+class OColorPanelButton : public QFrame
 {
     Q_OBJECT
 
 public:
 
 /**
- * @fn ColorPanelButton( const QColor& color, QWidget* parent = 0, const char* name = 0 )
+ * @fn OColorPanelButton( const QColor& color, QWidget* parent = 0, const char* name = 0 )
  * @brief Object constructor.
  *
  * @param color Desired color.
  * @param parent Pointer to parent of this control.
  * @param name Name of control.
  *
  * Constructs a new ColorPanelButton control with parent, name and desired color.
  */
-    ColorPanelButton(const QColor& color, QWidget* parent = 0, const char* name = 0);
+    OColorPanelButton(const QColor& color, QWidget* parent = 0, const char* name = 0);
 
 /**
  * @fn ~ColorPanelButton()
  * @brief Object destructor.
  */
-    ~ColorPanelButton();
+    ~OColorPanelButton();
 
 /**
  * @fn setActive( bool active )
  * @brief Sets button selection state.
  *
  * @param active Boolean indicator of new button state.
  *
  * Changes button selection state.  If button is selected, a highlighted border
  * is drawn.
  */
     void setActive(bool active);
 
 /**
  * @fn enterEvent( QEvent* e )
  * @brief Reimplemented for internal reasons.
  *
  * @param e Event currently being processed.
  *
  * Reimplemented to ensure correct display of button based on whether it is
  * active or not.
  */
     void enterEvent(QEvent* e);
 
 /**
  * @fn leaveEvent( QEvent* e )
  * @brief Reimplemented for internal reasons.
  *
  * @param e Event currently being processed.
  *
  * Reimplemented to ensure correct display of button based on whether it is
  * active or not.
  */
     void leaveEvent(QEvent* e);
 
 /**
  * @fn paintEvent( QEvent* e )
  * @brief Reimplemented for internal reasons.
  *
  * @param e Event currently being processed.
  *
  * Reimplemented to ensure correct display of button.
  */
     void paintEvent(QPaintEvent* e);
 
 /**
  * @fn mouseReleaseEvent( QMouseEvent* e )
  * @brief Slot executed when button is pressed.
  *
  * @param e Mouse event currently being processed.
  *
  * @see selected()
  *
  * This slot executes when the button has been pressed.  It emits the selected
  * signal as notification that it has been pressed.
  */
     void mouseReleaseEvent(QMouseEvent* e);
 
 signals:
 
 /**
  * @fn selected( const QColor& color )
  * @brief Signal to indicate button has been pressed.
  *
  * @param color Button color.
  *
  * This signal is emitted when the button is pressed.  It provides the color
  * associated to this button.
  */
     void selected(const QColor&);
 
 private:
     QColor m_color;
     bool m_active : 1;
     class ColorPanelButtonPrivate;
     ColorPanelButtonPrivate *d;
 };
 
 /**
- * @class ColorPopupMenu
- * @brief The ColorPopupMenu class provides a small color selection
+ * @class OColorPopupMenu
+ * @brief The OColorPopupMenu class provides a small color selection
  *        popup menu.
  *
- * ColorPopupMenu is a derivation of TrollTech's QPopupMenu and provides
+ * OColorPopupMenu is a derivation of TrollTech's QPopupMenu and provides
  * a small color selection popup menu which can be attached to another control
  * such as a toolbar button of menu item.
  *
  * The popup menu displays 30 default colors available in a grid, and also
  * includes an option at the bottom to display a color selection dialog box for
  * finer color control.
  */
-class ColorPopupMenu : public QPopupMenu
+class OColorPopupMenu : public QPopupMenu
 {
     Q_OBJECT
 
 public:
 
 /**
- * @fn ColorPopupMenu( const QColor& color, QWidget* parent = 0, const char* name = 0 )
+ * @fn OColorPopupMenu( const QColor& color, QWidget* parent = 0, const char* name = 0 )
  * @brief Object constructor.
  *
  * @param color Initial color selected in menu.
  * @param parent Pointer to parent of this control.
  * @param name Name of control.
  *
- * Constructs a new ColorPopupMenu control with parent, name and initial color selected.
+ * Constructs a new OColorPopupMenu control with parent, name and initial color selected.
  */
-    ColorPopupMenu( const QColor& color, QWidget* parent = 0, const char* name = 0 );
+    OColorPopupMenu( const QColor& color, QWidget* parent = 0, const char* name = 0 );
 
 /**
- * @fn ~ColorPopupMenu()
+ * @fn ~OColorPopupMenu()
  * @brief Object destructor.
  */
-    ~ColorPopupMenu();
+    ~OColorPopupMenu();
 
 private:
     class ColorPopupMenuPrivate;
     ColorPopupMenuPrivate *d;
     QColor       m_color;
     QWidget*     colorPanel;
     QGridLayout* colorLayout;
 
 /**
  * @fn addColor( const QColor& color, int row, int col )
  * @brief Adds color selection option to popup menu.
  *
  * @param color Color to be displayed in menu.
  * @param row Row where color is to appear in menu.
  * @param col Column where color is to appear in menu.
  *
  * Adds a color selection option to popup menu.  Used internally when
  * initially constructing the menu control.
  */
     void addColor( const QColor& color, int row, int col );
 
 signals:
 
 /**
  * @fn colorSelected( const QColor& color )
  * @brief Signal to indicate color chosen from the menu.
  *
  * @param color Color selected from the menu.
  *
  * This signal is emitted when a color has been selected either directly from
  * the menu, or chosen from the color selection dialog.
  */
     void colorSelected( const QColor& color );
 
 protected slots:
 
 /**
  * @fn buttonSelected( const QColor& color )
  * @brief Slot to process selected color.
  *
  * @param color Color selected from the menu.
  *
  * @see colorSelected()
  *
  * This slot executes when a color has been selected from the menu.  It performs
  * two functions:
  * - Emit the colorSelected signal with the color selected.
  * - Hide the menu.
diff --git a/libopie/ocheckitem.cpp b/libopie/ocheckitem.cpp
index d6ddc79..082d7a2 100644
--- a/libopie/ocheckitem.cpp
+++ b/libopie/ocheckitem.cpp
@@ -1,75 +1,106 @@
 /**********************************************************************
 ** Copyright (C) 2002 Stefan Eilers (se, eilers.stefan@epost.de
 **
 ** This file may be distributed and/or modified under the terms of the
 ** GNU Library 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.
 **********************************************************************/
 
 #include <qpainter.h>
 
 #include "ocheckitem.h"
 
+/**
+ * Constructs an CheckItem with a QTable as parent
+ * and a sort key for.
+ * The sort key will be used by QTable to sort the table later
+ * @param t The parent QTable where the check item belongs
+ * @param key A sort key
+ */
 OCheckItem::OCheckItem( QTable *t, const QString &key )
     : QTableItem( t, Never, "" ), m_checked( FALSE ), m_sortKey( key )
 {
 }
 
+/**
+ * reimplemted for internal reasons
+ * @return Returns the sort key of the Item
+ * @see QTableItem
+ */
 QString OCheckItem::key() const
 {
     return m_sortKey;
 }
 
+/**
+ * This method can check or uncheck the item. It will
+ * call QTable to update the cell.
+ *
+ * @param b Whether to check or uncheck the item
+ */
 void OCheckItem::setChecked( bool b )
 {
     m_checked = b;
     table()->updateCell( row(), col() );
 }
 
+/**
+ * This will toggle the item. If it is checked it'll get
+ * unchecked by this method or vice versa.
+ */
 void OCheckItem::toggle()
 {
     m_checked = !m_checked;
 }
 
+/**
+ * This will return the state of the item.
+ *
+ * @return Returns true if the item is checked
+ */
 bool OCheckItem::isChecked() const
 {
     return m_checked;
 }
 
+/**
+ * @internal
+ * This paints the item
+ */
 void OCheckItem::paint( QPainter *p, const QColorGroup &cg, const QRect &cr,
                        bool )
 {
     p->fillRect( 0, 0, cr.width(), cr.height(), cg.brush( QColorGroup::Base ) );
 
     int marg = ( cr.width() - BoxSize ) / 2;
     int x = 0;
     int y = ( cr.height() - BoxSize ) / 2;
     p->setPen( QPen( cg.text() ) );
     p->drawRect( x + marg, y, BoxSize, BoxSize );
     p->drawRect( x + marg+1, y+1, BoxSize-2, BoxSize-2 );
     p->setPen( darkGreen );
     x += 1;
     y += 1;
     if ( m_checked ) {
         QPointArray a( 7*2 );
         int i, xx, yy;
         xx = x+1+marg;
         yy = y+2;
         for ( i=0; i<3; i++ ) {
             a.setPoint( 2*i,   xx, yy );
             a.setPoint( 2*i+1, xx, yy+2 );
             xx++; yy++;
         }
         yy -= 2;
         for ( i=3; i<7; i++ ) {
             a.setPoint( 2*i,   xx, yy );
             a.setPoint( 2*i+1, xx, yy+2 );
             xx++; yy--;
         }
         p->drawLineSegments( a );
     }
 }
diff --git a/libopie/ocheckitem.h b/libopie/ocheckitem.h
index 7885032..2387134 100644
--- a/libopie/ocheckitem.h
+++ b/libopie/ocheckitem.h
@@ -1,41 +1,53 @@
 /**********************************************************************
 ** Copyright (C) 2002 Stefan Eilers (se, eilers.stefan@epost.de)
 **
 ** This file may be distributed and/or modified under the terms of the
 ** GNU Library General Public License version 2 as published by the
-**  Free Software Foundation and appearing in the file LICENSE.GPL 
+**  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.
 **********************************************************************/
 #include <qtable.h>
 
 #ifndef CHECKITEM_H__
 #define CHECKITEM_H__
 
+/**
+ * This class represents a checkable QTableItem. This can
+ * be added to any QTable.
+ *
+ *
+ * @see QTable
+ * @see QTableItem
+ * @short An checkable QTableItem
+ * @version 1.0
+ * @author Stefan Eilers ( eilers@handhelds.org )
+ */
+
 class OCheckItem : public QTableItem
 {
 public:
     enum Size { BoxSize = 10 };
     OCheckItem( QTable *t, const QString &sortkey );
 
     virtual void setChecked( bool b );
     virtual void toggle();
     bool isChecked() const;
     void setKey( const QString &key ) { m_sortKey = key; }
     virtual QString key() const;
 
     void paint( QPainter *p, const QColorGroup &cg, const QRect &cr, bool selected );
 
     //static const int BoxSize = 10;
 
 private:
     class OCheckItemPrivate;
     OCheckItemPrivate *d;
     bool m_checked: 1;
     QString m_sortKey;
 
 };
 
 #endif
diff --git a/libopie/oclickablelabel.cpp b/libopie/oclickablelabel.cpp
index 5768529..bc7037b 100644
--- a/libopie/oclickablelabel.cpp
+++ b/libopie/oclickablelabel.cpp
@@ -1,88 +1,117 @@
 #include "oclickablelabel.h"
 #include <stdio.h>
 
-OClickableLabel::OClickableLabel(QWidget* parent, 
-                               const char* name, 
+/**
+ * This constructs the clickable ButtonLabel
+ *
+ * @param parent The parent of this label
+ * @param name A name of this label @see QObject
+ * @param fl The windowing flags
+ */
+OClickableLabel::OClickableLabel(QWidget* parent,
+                               const char* name,
                                WFlags fl) :
   QLabel(parent,name,fl)
 {
     textInverted=false;
     isToggle=false;
     isDown=false;
     showState(false);
     setFrameShadow(Sunken);
 }
 
+/**
+ * This method makes the label behave as a toggle button
+ *
+ * @param t Whether or not to behave like a toggle button
+ */
 void OClickableLabel::setToggleButton(bool t) {
     isToggle=t;
 }
 
+/**
+ * @internal
+ */
 void OClickableLabel::mousePressEvent( QMouseEvent * /*e*/ ) {
     if (isToggle && isDown) {
         showState(false);
     } else {
         showState(true);
     }
 }
 
+/**
+ * @internal
+ */
 void OClickableLabel::mouseReleaseEvent( QMouseEvent *e ) {
     if (rect().contains(e->pos()) && isToggle) isDown=!isDown;
 
     if (isToggle && isDown) {
         showState(true);
     } else {
         showState(false);
     }
 
     if (rect().contains(e->pos())) {
         if (isToggle) {
             emit toggled(isDown);
         }
         emit clicked();
     }
 }
 
+/**
+ * @internal
+ */
 void OClickableLabel::mouseMoveEvent( QMouseEvent *e ) {
     if (rect().contains(e->pos())) {
         if (isToggle && isDown) {
             showState(false);
         } else {
             showState(true);
         }
     } else {
         if (isToggle && isDown) {
             showState(true);
         } else {
             showState(false);
         }
     }
 }
 
+/**
+ * this toggles the label and inverts the color of
+ * the label
+ * @param on
+ */
 void OClickableLabel::showState(bool on) {
   if (on) {
     //setFrameShape(Panel);
     setInverted(true);
     setBackgroundMode(PaletteHighlight);
   } else {
     //setFrameShape(NoFrame);
     setInverted(false);
     setBackgroundMode(PaletteBackground);
   }
   repaint();
 }
 
 void OClickableLabel::setInverted(bool on) {
     if ( (!textInverted && on) || (textInverted && !on) ) {
         QPalette pal=palette();
         QColor col=pal.color(QPalette::Normal, QColorGroup::Foreground);
         col.setRgb(255-col.red(),255-col.green(),255-col.blue());
         pal.setColor(QPalette::Normal, QColorGroup::Foreground, col);
         setPalette(pal);
         textInverted=!textInverted;
     }
 }
 
+/**
+ * @param on if the Label is down or up
+ */
 void OClickableLabel::setOn(bool on) {
   isDown=on;
   showState(isDown);
 }
diff --git a/libopie/oclickablelabel.h b/libopie/oclickablelabel.h
index f65c440..4b6dcbc 100644
--- a/libopie/oclickablelabel.h
+++ b/libopie/oclickablelabel.h
@@ -1,30 +1,53 @@
 #ifndef CLICKABLELABEL
 #define CLICKABLELABEL
 
-#include <qlabel.h> 
+#include <qlabel.h>
 
-class OClickableLabel: public QLabel 
+/**
+ * This class is a special QLabel which can behave
+ * as a QPushButton or QToggleButton.
+ * The reason to use a clickable is if you want to save space
+ * or you want to skip the border of a normal button
+ *
+ * <pre>
+ *  QLabel* lbl = new OClickableLabel( parent, "PushLabel" );
+ *  lbl->setPixmap( "config" );
+ *  QWhatsThis::add( lbl, tr("Click here to do something") );
+ * </pre>
+ *
+ * @short A Label behaving as button
+ * @author Hakan Ardo, Maximillian Reiß ( harlekin@handhelds.org )
+ * @see QLabel
+ * @see QPushButton
+ * @see QToggleButton
+ * @version 1.0
+ */
+
+class OClickableLabel: public QLabel
 {
   Q_OBJECT
 public:
-    OClickableLabel(QWidget* parent = 0, const char* name = 0, 
+    OClickableLabel(QWidget* parent = 0, const char* name = 0,
                    WFlags fl = 0);
     void setToggleButton(bool t);
+
  protected:
     void mousePressEvent( QMouseEvent *e );
     void mouseReleaseEvent( QMouseEvent *e );
     void mouseMoveEvent( QMouseEvent *e );
+
  public slots:
     void setOn(bool on);
  signals:
     void clicked();
     void toggled(bool on);
  private:
-    bool isToggle;
-    bool isDown;
+    bool isToggle : 1;
+    bool isDown : 1;
+    bool textInverted : 1;
+
     void showState(bool on);
-    bool textInverted;
     void setInverted(bool on);
 };
 
 #endif
diff --git a/libopie/ocolorbutton.cpp b/libopie/ocolorbutton.cpp
index ddb6c4f..113a77a 100644
--- a/libopie/ocolorbutton.cpp
+++ b/libopie/ocolorbutton.cpp
@@ -1,121 +1,142 @@
 /*
                =.            This file is part of the OPIE Project
              .=l.            Copyright (c)  2002 Robert Griebl <sandman@handhelds.org>
            .>+-=
  _;:,     .>    :=|.         This library is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This library is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 #include <opie/colorpopupmenu.h>
 #include <opie/ocolorbutton.h>
 #include <qcolor.h>
 #include <qpixmap.h>
 #include <qimage.h>
 
 #include <qpe/resource.h>
 
-class OColorButtonPrivate {
-public:
-        QPopupMenu *m_menu;
-        QColor m_color;
+struct OColorButtonPrivate {
+    QPopupMenu *m_menu;
+    QColor m_color;
 };
 
+
+/**
+ * This concstructs a Color Button with @param color as the start color
+ * It'll use a OColorPopupMenu internally
+ *
+ * @param parent The parent of the Color Button
+ * @param color The color from where to start on
+ * @param name @see QObject
+ */
 OColorButton::OColorButton ( QWidget *parent, const QColor &color, const char *name )
         : QPushButton ( parent, name )
 {
         d = new OColorButtonPrivate;
 
-        d-> m_menu = new ColorPopupMenu ( color, 0, 0 );
+        d-> m_menu = new OColorPopupMenu ( color, 0, 0 );
         setPopup ( d-> m_menu );
         //setPopupDelay ( 0 );
         connect ( d-> m_menu, SIGNAL( colorSelected ( const QColor & )), this, SLOT( updateColor ( const QColor & )));
 
         updateColor ( color );
 
         QSize s = sizeHint ( ) + QSize ( 12, 0 );
         setMinimumSize ( s );
         setMaximumSize ( s. width ( ) * 2, s. height ( ));
 }
 
+/**
+ * This destructs the object
+ */
 OColorButton::~OColorButton ( )
 {
         delete d;
 }
 
+/**
+ * @return Returns the current color of the button
+ */
 QColor OColorButton::color ( ) const
 {
         return d-> m_color;
 }
 
+/**
+ * This method sets the color of the button
+ * @param c The color to be set.
+ */
 void OColorButton::setColor ( const QColor &c )
 {
         updateColor ( c );
 }
 
+/**
+ * @internal
+ */
 void OColorButton::updateColor ( const QColor &c )
 {
         d-> m_color = c;
-        
+
         QImage img ( 16, 16, 32 );
         img. fill ( 0 );
-        
+
         int r, g, b;
         c. rgb ( &r, &g, &b );
-        
+
         int w = img. width ( );
         int h = img. height ( );
-        
+
         int dx = w * 20 / 100; // 15%
         int dy = h * 20 / 100;
-        
+
         for ( int y = 0; y < h; y++ ) {
                 for ( int x = 0; x < w; x++ ) {
                         double alpha = 1.0;
 
                         if ( x < dx )
                                 alpha *= ( double ( x + 1 ) / dx );
                         else if ( x >= w - dx )
                                 alpha *= ( double ( w - x ) / dx );
                         if ( y < dy )
                                 alpha *= ( double ( y + 1 ) / dy );
                         else if ( y >= h - dy )
                                 alpha *= ( double ( h - y ) / dy );
-                                
+
                         int a = int ( alpha * 255.0 );
                         if ( a < 0 )
                                 a = 0;
                         if ( a > 255 )
                                 a = 255;
 
                         img. setPixel ( x, y, qRgba ( r, g, b, a ));
                 }
         }
         img. setAlphaBuffer ( true );
 
         QPixmap pix;
         pix. convertFromImage ( img );
-                setPixmap ( pix );
+        setPixmap ( pix );
 
         emit colorSelected ( c );
 }
 
diff --git a/libopie/ocolorbutton.h b/libopie/ocolorbutton.h
index fe40fae..338e654 100644
--- a/libopie/ocolorbutton.h
+++ b/libopie/ocolorbutton.h
@@ -1,59 +1,66 @@
 /*
                =.            This file is part of the OPIE Project
              .=l.            Copyright (c)  2002 Robert Griebl <sandman@handhelds.org>
            .>+-=
  _;:,     .>    :=|.         This library is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This library is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 #ifndef __OPIE_OCOLORBUTTON_H__
 #define __OPIE_OCOLORBUTTON_H__
 
 #include <qpushbutton.h>
 
 class OColorButtonPrivate;
 class QColor;
 
+/**
+ *
+ * @short A Button which will show a OColorPopupMenu
+ * @author Robert Griebl ( sandman@handhelds.org )
+ * @version 1.0
+ * @see QPushButton
+ */
 class OColorButton : public QPushButton {
         Q_OBJECT
 public:
         OColorButton ( QWidget *parent = 0, const QColor & = black, const char *name = 0 );
         virtual ~OColorButton ( );
 
         QColor color ( ) const;
 
 signals:
         void colorSelected ( const QColor & );
 
 public slots:
         virtual void setColor ( const QColor & );
-        
-        protected slots:
+
+protected slots:
         virtual void updateColor ( const QColor & );
-        
+
 private:
         OColorButtonPrivate *d;
-        };
+};
 
 #endif
 
diff --git a/libopie/odevice.cpp b/libopie/odevice.cpp
index 9b2a954..8f954b1 100644
--- a/libopie/odevice.cpp
+++ b/libopie/odevice.cpp
@@ -8,97 +8,97 @@
 
     This library is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Library General Public License for more details.
 
     You should have received a copy of the GNU Library General Public License
     along with this library; see the file COPYING.LIB.  If not, write to
     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
     Boston, MA 02111-1307, USA.
 */
 
 #include <stdlib.h>
 #include <unistd.h>
 #include <fcntl.h>
 #include <sys/ioctl.h>
 #include <signal.h>
 #include <sys/time.h>
 #include <linux/soundcard.h>
 #include <math.h>
 
 #include <qapplication.h>
 
 #include <qfile.h>
 #include <qtextstream.h>
 #include <qpe/sound.h>
 #include <qpe/resource.h>
 #include <qpe/config.h>
 #include <qpe/qcopenvelope_qws.h>
 
 #include "odevice.h"
 
 #include <qwindowsystem_qws.h>
 
 
 // _IO and friends are only defined in kernel headers ...
 
 #define OD_IOC(dir,type,number,size)    (( dir << 30 ) | ( type << 8 ) | ( number ) | ( size << 16 ))
 
 #define OD_IO(type,number)              OD_IOC(0,type,number,0)
 #define OD_IOW(type,number,size)        OD_IOC(1,type,number,sizeof(size))
 #define OD_IOR(type,number,size)        OD_IOC(2,type,number,sizeof(size))
 #define OD_IORW(type,number,size)       OD_IOC(3,type,number,sizeof(size))
 
 using namespace Opie;
 
 class ODeviceData {
 public:
-        bool m_qwsserver;
+        bool m_qwsserver : 1;
 
         QString m_vendorstr;
         OVendor m_vendor;
 
         QString m_modelstr;
         OModel m_model;
 
         QString m_systemstr;
         OSystem m_system;
 
         QString m_sysverstr;
 
         Transformation m_rotation;
 
         QValueList <ODeviceButton> *m_buttons;
         uint                        m_holdtime;
 };
 
 
 class iPAQ : public ODevice, public QWSServer::KeyboardFilter {
 protected:
         virtual void init ( );
         virtual void initButtons ( );
 
 public:
         virtual bool setSoftSuspend ( bool soft );
 
         virtual bool setDisplayBrightness ( int b );
         virtual int displayBrightnessResolution ( ) const;
 
         virtual void alarmSound ( );
 
     virtual QValueList <OLed> ledList ( ) const;
         virtual QValueList <OLedState> ledStateList ( OLed led ) const;
         virtual OLedState ledState ( OLed led ) const;
         virtual bool setLedState ( OLed led, OLedState st );
 
         virtual bool hasLightSensor ( ) const;
         virtual int readLightSensor ( );
         virtual int lightSensorResolution ( ) const;
 
 protected:
         virtual bool filter ( int unicode, int keycode, int modifiers, bool isPress, bool autoRepeat );
         virtual void timerEvent ( QTimerEvent *te );
 
         int m_power_timer;
 
         OLedState m_leds [2];
@@ -225,325 +225,421 @@ ODevice *ODevice::inst ( )
                 else if ( QFile::exists ( "/dev/sharp_buz" ) || QFile::exists ( "/dev/sharp_led" ))
                         dev = new Zaurus ( );
                 else
                         dev = new ODevice ( );
 
                 dev-> init ( );
         }
         return dev;
 }
 
 
 /**************************************************
  *
  * common
  *
  **************************************************/
 
 
 ODevice::ODevice ( )
 {
         d = new ODeviceData;
 
         d-> m_qwsserver = qApp ? ( qApp-> type ( ) == QApplication::GuiServer ) : false;
 
         d-> m_modelstr = "Unknown";
         d-> m_model = Model_Unknown;
         d-> m_vendorstr = "Unknown";
         d-> m_vendor = Vendor_Unknown;
         d-> m_systemstr = "Unknown";
         d-> m_system = System_Unknown;
         d-> m_sysverstr = "0.0";
         d-> m_rotation = Rot0;
 
         d-> m_holdtime = 1000; // 1000ms
         d-> m_buttons = 0;
 }
 
 void ODevice::systemMessage ( const QCString &msg, const QByteArray & )
 {
         if ( msg == "deviceButtonMappingChanged()" ) {
                 reloadButtonMapping ( );
         }
 }
 
 void ODevice::init ( )
 {
 }
 
+/**
+ * This method initialises the  button mapping
+ */
 void ODevice::initButtons ( )
 {
         if ( d-> m_buttons )
                 return;
 
         // Simulation uses iPAQ 3660 device buttons
 
         qDebug ( "init Buttons" );
         d-> m_buttons = new QValueList <ODeviceButton>;
 
         for ( uint i = 0; i < ( sizeof( ipaq_buttons ) / sizeof( i_button )); i++ ) {
                 i_button *ib = ipaq_buttons + i;
                 ODeviceButton b;
 
                 if (( ib-> model & Model_iPAQ_H36xx ) == Model_iPAQ_H36xx ) {
                         b. setKeycode ( ib-> code );
                         b. setUserText ( QObject::tr ( "Button", ib-> utext ));
                         b. setPixmap ( Resource::loadPixmap ( ib-> pix ));
                         b. setFactoryPresetPressedAction ( OQCopMessage ( makeChannel ( ib-> fpressedservice ), ib-> fpressedaction ));
                         b. setFactoryPresetHeldAction ( OQCopMessage ( makeChannel ( ib-> fheldservice ), ib-> fheldaction ));
                         d-> m_buttons-> append ( b );
                 }
         }
         reloadButtonMapping ( );
 
         QCopChannel *sysch = new QCopChannel ( "QPE/System", this );
         connect ( sysch, SIGNAL( received( const QCString &, const QByteArray & )), this, SLOT( systemMessage ( const QCString &, const QByteArray & )));
 }
 
 ODevice::~ODevice ( )
 {
         delete d;
 }
 
 bool ODevice::setSoftSuspend ( bool /*soft*/ )
 {
         return false;
 }
 
 //#include <linux/apm_bios.h>
 
 #define APM_IOC_SUSPEND          OD_IO( 'A', 2 )
 
-
+/**
+ * This method will try to suspend the device
+ * It only works if the user is the QWS Server and the apm application
+ * is installed.
+ * It tries to suspend and then waits some time cause some distributions
+ * do have asynchronus apm implementations.
+ * This method will either fail and return false or it'll suspend the
+ * device and return once the device got woken up
+ *
+ * @return if the device got suspended
+ */
 bool ODevice::suspend ( )
 {
         if ( !d-> m_qwsserver ) // only qwsserver is allowed to suspend
                 return false;
 
         if ( d-> m_model == Model_Unknown ) // better don't suspend in qvfb / on unkown devices
                 return false;
 
         bool res = false;
 
         struct timeval tvs, tvn;
         ::gettimeofday ( &tvs, 0 );
 
         ::sync ( ); // flush fs caches
         res = ( ::system ( "apm --suspend" ) == 0 );
 
         // This is needed because the iPAQ apm implementation is asynchronous and we
         // can not be sure when exactly the device is really suspended
         // This can be deleted as soon as a stable familiar with a synchronous apm implementation exists.
 
         if ( res ) {
                 do { // wait at most 1.5 sec: either suspend didn't work or the device resumed
                         ::usleep ( 200 * 1000 );
                         ::gettimeofday ( &tvn, 0 );
                 } while ((( tvn. tv_sec - tvs. tv_sec ) * 1000 + ( tvn. tv_usec - tvs. tv_usec ) / 1000 ) < 1500 );
         }
 
         return res;
 }
 
 //#include <linux/fb.h> better not rely on kernel headers in userspace ...
 
 #define FBIOBLANK             OD_IO( 'F', 0x11 ) // 0x4611
 
 /* VESA Blanking Levels */
 #define VESA_NO_BLANKING      0
 #define VESA_VSYNC_SUSPEND    1
 #define VESA_HSYNC_SUSPEND    2
 #define VESA_POWERDOWN        3
 
-
+/**
+ * This sets the display on or off
+ */
 bool ODevice::setDisplayStatus ( bool on )
 {
         if ( d-> m_model == Model_Unknown )
                 return false;
 
         bool res = false;
         int fd;
 
         if (( fd = ::open ( "/dev/fb0", O_RDWR )) >= 0 ) {
                 res = ( ::ioctl ( fd, FBIOBLANK, on ? VESA_NO_BLANKING : VESA_POWERDOWN ) == 0 );
                 ::close ( fd );
         }
         return res;
 }
 
-bool ODevice::setDisplayBrightness ( int )
+/**
+ * This sets the display brightness
+ * @return success or failure
+ */
+bool ODevice::setDisplayBrightness ( int p)
 {
+        Q_UNUSED( p )
         return false;
 }
 
 int ODevice::displayBrightnessResolution ( ) const
 {
         return 16;
 }
 
+/**
+ * This returns the vendor as string
+ * @return Vendor as QString
+ */
 QString ODevice::vendorString ( ) const
 {
         return d-> m_vendorstr;
 }
 
+/**
+ * This returns the vendor as one of the values of OVendor
+ * @return OVendor
+ */
 OVendor ODevice::vendor ( ) const
 {
         return d-> m_vendor;
 }
 
+/**
+ * This returns the model as a string
+ * @return A string representing the model
+ */
 QString ODevice::modelString ( ) const
 {
         return d-> m_modelstr;
 }
 
+/**
+ * This does return the OModel used
+ */
 OModel ODevice::model ( ) const
 {
         return d-> m_model;
 }
 
+/**
+ * This does return the systen name
+ */
 QString ODevice::systemString ( ) const
 {
         return d-> m_systemstr;
 }
 
+/**
+ * Return System as OSystem value
+ */
 OSystem ODevice::system ( ) const
 {
         return d-> m_system;
 }
 
+/**
+ * @return the version string of the base system
+ */
 QString ODevice::systemVersionString ( ) const
 {
         return d-> m_sysverstr;
 }
 
+/**
+ *  @return the current Transformation
+ */
 Transformation ODevice::rotation ( ) const
 {
         return d-> m_rotation;
 }
 
+/**
+ * This plays an alarmSound
+ */
 void ODevice::alarmSound ( )
 {
 #ifndef QT_NO_SOUND
         static Sound snd ( "alarm" );
 
         if ( snd. isFinished ( ))
                 snd. play ( );
 #endif
 }
 
+/**
+ * This plays a key sound
+ */
 void ODevice::keySound ( )
 {
 #ifndef QT_NO_SOUND
         static Sound snd ( "keysound" );
 
         if ( snd. isFinished ( ))
                 snd. play ( );
 #endif
 }
 
+/**
+ * This plays a touch sound
+ */
 void ODevice::touchSound ( )
 {
 
 #ifndef QT_NO_SOUND
         static Sound snd ( "touchsound" );
 
         if ( snd. isFinished ( ))
                 snd. play ( );
 #endif
 }
 
-
+/**
+ * This method will return a list of leds
+ * available on this device
+ * @return a list of LEDs.
+ */
 QValueList <OLed> ODevice::ledList ( ) const
 {
         return QValueList <OLed> ( );
 }
 
+/**
+ * This does return the state of the LEDs
+ */
 QValueList <OLedState> ODevice::ledStateList ( OLed /*which*/ ) const
 {
         return QValueList <OLedState> ( );
 }
 
+/**
+ * @return the state for a given OLed
+ */
 OLedState ODevice::ledState ( OLed /*which*/ ) const
 {
         return Led_Off;
 }
 
-bool ODevice::setLedState ( OLed /*which*/, OLedState /*st*/ )
+/**
+ * Set the state for a LED
+ * @param which Which OLed to use
+ * @param st The state to set
+ * @return success or failure
+ */
+bool ODevice::setLedState ( OLed which, OLedState st )
 {
+        Q_UNUSED( which )
+        Q_UNUSED( st    )
         return false;
 }
 
+/**
+ * @return if the device has a light sensor
+ */
 bool ODevice::hasLightSensor ( ) const
 {
         return false;
 }
 
+/**
+ * @return a value from the light senso
+ */
 int ODevice::readLightSensor ( )
 {
         return -1;
 }
 
+/**
+ * @return the light sensor resolution whatever that is ;)
+ */
 int ODevice::lightSensorResolution ( ) const
 {
         return 0;
 }
 
+/**
+ * @return a list of hardware buttons
+ */
 const QValueList <ODeviceButton> &ODevice::buttons ( )
 {
         initButtons ( );
 
         return *d-> m_buttons;
 }
 
+/**
+ * @return The amount of time that would count as a hold
+ */
 uint ODevice::buttonHoldTime ( ) const
 {
         return d-> m_holdtime;
 }
 
+/**
+ * This method return a ODeviceButton for a key code
+ * or 0 if no special hardware button is available for the device
+ *
+ * @return The devicebutton or 0l
+ * @see ODeviceButton
+ */
 const ODeviceButton *ODevice::buttonForKeycode ( ushort code )
 {
         initButtons ( );
 
         for ( QValueListConstIterator<ODeviceButton> it = d-> m_buttons-> begin ( ); it != d-> m_buttons-> end ( ); ++it ) {
                 if ( (*it). keycode ( ) == code )
                         return &(*it);
         }
         return 0;
 }
 
 void ODevice::reloadButtonMapping ( )
 {
         initButtons ( );
 
         Config cfg ( "ButtonSettings" );
 
         for ( uint i = 0; i < d-> m_buttons-> count ( ); i++ ) {
                 ODeviceButton &b = ( *d-> m_buttons ) [i];
                 QString group = "Button" + QString::number ( i );
 
                 QCString pch, hch;
                 QCString pm, hm;
                 QByteArray pdata, hdata;
 
                 if ( cfg. hasGroup ( group )) {
                         cfg. setGroup ( group );
                         pch = cfg. readEntry ( "PressedActionChannel" ). latin1 ( );
                         pm  = cfg. readEntry ( "PressedActionMessage" ). latin1 ( );
                         // pdata = decodeBase64 ( buttonFile. readEntry ( "PressedActionArgs" ));
 
                         hch = cfg. readEntry ( "HeldActionChannel" ). latin1 ( );
                         hm  = cfg. readEntry ( "HeldActionMessage" ). latin1 ( );
                         // hdata = decodeBase64 ( buttonFile. readEntry ( "HeldActionArgs" ));
                 }
 
                 b. setPressedAction ( OQCopMessage ( pch, pm, pdata ));
 
                 b. setHeldAction ( OQCopMessage ( hch, hm, hdata ));
         }
 }
 
 void ODevice::remapPressedAction ( int button, const OQCopMessage &action )
 {
         initButtons ( );
 
         QString mb_chan;
 
diff --git a/libopie/odevice.h b/libopie/odevice.h
index ff578d8..45a790b 100644
--- a/libopie/odevice.h
+++ b/libopie/odevice.h
@@ -1,199 +1,222 @@
 /*  This file is part of the OPIE libraries
     Copyright (C) 2002 Robert Griebl (sandman@handhelds.org)
-            
+
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Library General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later version.
-                             
+
     This library is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Library General Public License for more details.
-                                          
+
     You should have received a copy of the GNU Library General Public License
     along with this library; see the file COPYING.LIB.  If not, write to
     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
     Boston, MA 02111-1307, USA.
 */
 
 #ifndef _LIBOPIE_ODEVICE_H_
 #define _LIBOPIE_ODEVICE_H_
 
 #include <qobject.h>
 #include <qstring.h>
 #include <qnamespace.h>
 
 #include <opie/odevicebutton.h>
 
 #include <qpe/qpeapplication.h> /* for Transformation enum.. */
 
 class ODeviceData;
 
 namespace Opie {
 
+/**
+ * The available devices
+ */
 enum OModel {
-        Model_Unknown,
-        
+        Model_Unknown, // = 0
+
         Model_Series_Mask   = 0xff000000,
 
         Model_iPAQ          = ( 1 << 24 ),
 
         Model_iPAQ_All      = ( Model_iPAQ | 0xffffff ),
         Model_iPAQ_H31xx    = ( Model_iPAQ | 0x000001 ),
         Model_iPAQ_H36xx    = ( Model_iPAQ | 0x000002 ),
         Model_iPAQ_H37xx    = ( Model_iPAQ | 0x000004 ),
         Model_iPAQ_H38xx    = ( Model_iPAQ | 0x000008 ),
         Model_iPAQ_H39xx    = ( Model_iPAQ | 0x000010 ),
 
         Model_Zaurus        = ( 2 << 24 ),
 
         Model_Zaurus_SL5000 = ( Model_Zaurus | 0x000001 ),
         Model_Zaurus_SL5500 = ( Model_Zaurus | 0x000002 ),
         Model_Zaurus_SLA300 = ( Model_Zaurus | 0x000003 ),
         Model_Zaurus_SLB600 = ( Model_Zaurus | 0x000004 ),
         Model_Zaurus_SLC700 = ( Model_Zaurus | 0x000005 ),
 };
 
-        enum OVendor {
+/**
+ * The vendor of the device
+ */
+enum OVendor {
         Vendor_Unknown,
 
         Vendor_HP,
         Vendor_Sharp
-        };
+};
 
+/**
+ * The System used
+ */
 enum OSystem {
         System_Unknown,
 
         System_Familiar,
         System_Zaurus,
         System_OpenZaurus
 };
 
 enum OLedState {
         Led_Off,
         Led_On,
         Led_BlinkSlow,
         Led_BlinkFast
 };
 
 enum OLed {
         Led_Mail,
         Led_Power,
         Led_BlueTooth
 };
 
 enum OHardKey {
         HardKey_Datebook  = Qt::Key_F9,
         HardKey_Contacts  = Qt::Key_F10,
         HardKey_Menu      = Qt::Key_F11,
         HardKey_Home      = Qt::Key_F12,
         HardKey_Mail      = Qt::Key_F13,
         HardKey_Record    = Qt::Key_F24,
         HardKey_Suspend   = Qt::Key_F34,
         HardKey_Backlight = Qt::Key_F35,
 };
 
+/**
+ * A singleton which gives informations about device specefic option
+ * like the Hardware used, LEDs, the Base Distribution and
+ * hardware key mappings.
+ *
+ *
+ * @short A small class for device specefic options
+ * @see QObject
+ * @author Robert Griebl
+ * @version 1.0
+ */
 class ODevice : public QObject {
         Q_OBJECT
-        
+
 private:
+        /* disable copy */
         ODevice ( const ODevice & );
 
 protected:
         ODevice ( );
         virtual void init ( );
         virtual void initButtons ( );
-        
+
         ODeviceData *d;
 
 public:
+    // sandman do we want to allow destructions? -zecke?
         virtual ~ODevice ( );
 
+
         static ODevice *inst ( );
 
 // information
 
-        QString modelString ( ) const; 
+        QString modelString ( ) const;
         OModel model ( ) const;
         inline OModel series ( ) const { return (OModel) ( model ( ) & Model_Series_Mask ); }
-        
+
         QString vendorString ( ) const;
         OVendor vendor ( ) const;
 
         QString systemString ( ) const;
         OSystem system ( ) const;
 
         QString systemVersionString ( ) const;
 
         Transformation rotation ( ) const;
 
-        // system
+// system
 
         virtual bool setSoftSuspend ( bool on );
         virtual bool suspend ( );
 
         virtual bool setDisplayStatus ( bool on );
         virtual bool setDisplayBrightness ( int brightness );
         virtual int displayBrightnessResolution ( ) const;
-        
-// input / output
 
+// input / output
+        //FIXME playAlarmSound and al might be better -zecke
         virtual void alarmSound ( );
         virtual void keySound ( );
         virtual void touchSound ( );
 
         virtual QValueList <OLed> ledList ( ) const;
         virtual QValueList <OLedState> ledStateList ( OLed led ) const;
         virtual OLedState ledState ( OLed led ) const;
         virtual bool setLedState ( OLed led, OLedState st );
 
         virtual bool hasLightSensor ( ) const;
         virtual int readLightSensor ( );
         virtual int lightSensorResolution ( ) const;
 
         /**
          * Returns the available buttons on this device.  The number and location
          * of buttons will vary depending on the device.  Button numbers will be assigned
          * by the device manufacturer and will be from most preferred button to least preffered
          * button.  Note that this list only contains "user mappable" buttons.
          */
         const QValueList<ODeviceButton> &buttons ( );
-        
+
         /**
          * Returns the DeviceButton for the \a keyCode.  If \a keyCode is not found, it
          * returns 0L
          */
         const ODeviceButton *buttonForKeycode ( ushort keyCode );
 
         /**
          * Reassigns the pressed action for \a button.  To return to the factory
          * default pass an empty string as \a qcopMessage.
          */
         void remapPressedAction ( int button, const OQCopMessage &qcopMessage );
 
         /**
          * Reassigns the held action for \a button.  To return to the factory
          * default pass an empty string as \a qcopMessage.
-                 */ 
+         */
         void remapHeldAction ( int button, const OQCopMessage &qcopMessage );
 
         /**
          * How long (in ms) you have to press a button for a "hold" action
          */
         uint buttonHoldTime ( ) const;
 
-        signals:
+signals:
         void buttonMappingChanged ( );
-        
-        private slots:
+
+private slots:
         void systemMessage ( const QCString &, const QByteArray & );
-        
+
 protected:
         void reloadButtonMapping ( );
 };
 
 }
 
 #endif
 
diff --git a/libopie/odevicebutton.h b/libopie/odevicebutton.h
index 5281ab2..cf91bbd 100644
--- a/libopie/odevicebutton.h
+++ b/libopie/odevicebutton.h
@@ -13,85 +13,89 @@
 **
 ** See http://www.trolltech.com/gpl/ for GPL licensing information.
 **
 ** Contact info@trolltech.com if any conditions of this licensing are
 ** not clear to you.
 **
 **********************************************************************/
 #ifndef DEVICE_BUTTON_H
 #define DEVICE_BUTTON_H
 
 #include <qpixmap.h>
 #include <qstring.h>
 
 class OQCopMessageData;
 
 namespace Opie
 {
 
 class OQCopMessage {
 public:
         OQCopMessage ( );
         OQCopMessage ( const OQCopMessage &copy );
         OQCopMessage ( const QCString &m_channel, const QCString &message, const QByteArray &args = QByteArray ( ));
 
         OQCopMessage &operator = ( const OQCopMessage &assign );
 
         void setChannel ( const QCString &channel );
         void setMessage ( const QCString &message );
         void setData ( const QByteArray &ba );
 
         QCString channel ( ) const;
         QCString message ( ) const;
         QByteArray data ( ) const;
 
         bool send ( );
 
 private:
         void init ( const QCString &m_channel, const QCString &message, const QByteArray &args );
 
         OQCopMessageData *d;
 };
 
 
 /**
  * This class represents a physical button on a Qtopia device.  A device may
  * have n "user programmable" buttons, which are number 1..n.  The location
  * and number of buttons will vary from device to device.  userText() and pixmap()
  * may be used to describe this button to the user in help documentation.
+ *
+ * @version 1.0
+ * @author Trolltech
+ * @short A representation of buttons
  */
 
 class ODeviceButton
 {
 public:
         ODeviceButton();
         virtual ~ODeviceButton();
 
         ushort keycode ( ) const;
         QString userText ( ) const;
         QPixmap pixmap ( ) const;
         OQCopMessage factoryPresetPressedAction ( ) const;
         OQCopMessage pressedAction ( ) const;
         OQCopMessage factoryPresetHeldAction ( ) const;
         OQCopMessage heldAction ( ) const;
 
         void setKeycode ( ushort keycode );
         void setUserText ( const QString& text );
         void setPixmap ( const QPixmap& picture );
         void setFactoryPresetPressedAction ( const OQCopMessage& qcopMessage );
         void setPressedAction ( const OQCopMessage& qcopMessage );
         void setFactoryPresetHeldAction ( const OQCopMessage& qcopMessage );
         void setHeldAction ( const OQCopMessage& qcopMessage );
 
 private:
         ushort m_Keycode;
         QString m_UserText;
         QPixmap m_Pixmap;
         OQCopMessage m_FactoryPresetPressedAction;
         OQCopMessage m_PressedAction;
         OQCopMessage m_FactoryPresetHeldAction;
         OQCopMessage m_HeldAction;
 };
 
 }
 
 #endif
diff --git a/libopie/ofiledialog.cc b/libopie/ofiledialog.cc
index 4783004..9e725c2 100644
--- a/libopie/ofiledialog.cc
+++ b/libopie/ofiledialog.cc
@@ -1,116 +1,156 @@
 /*
                =.            This file is part of the OPIE Project
              .=l.            Copyright (c)  2002 <>
            .>+-=
  _;:,     .>    :=|.         This library is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This library is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 #include <qpe/applnk.h>
 #include <qstring.h>
 #include <qapplication.h>
 #include <qlayout.h>
 
 #include "ofiledialog.h"
 
+/**
+ * This constructs a modal dialog
+ *
+ * @param caption The caption of the dialog
+ * @param wid The parent widget
+ * @param mode The mode of the OFileSelector @see OFileSelector
+ * @param selector The selector of the OFileSelector
+ * @param dirName the dir or resource to start from
+ * @param fileName  a proposed or existing filename
+ * @param mimetypes The mimeTypes
+ */
 OFileDialog::OFileDialog(const QString &caption,
                          QWidget *wid, int mode, int selector,
                          const QString &dirName,
                          const QString &fileName,
                          const QMap<QString,QStringList>& mimetypes )
   : QDialog( wid, "OFileDialog", true )
 {
   //  QVBoxLayout *lay = new QVBoxLayout(this);
   //showMaximized();
   QVBoxLayout *lay = new QVBoxLayout(this );
   file = new OFileSelector(this , mode, selector,
                            dirName, fileName,
                            mimetypes );
   lay->addWidget( file );
 
   //lay->addWidget( file );
   //showFullScreen();
   setCaption( caption.isEmpty() ? tr("FileDialog") : caption );
   connect(file, SIGNAL(fileSelected(const QString&) ),
           this, SLOT(slotFileSelected(const QString&) ) );
 
   connect(file, SIGNAL(dirSelected(const QString &) ),
           this, SLOT(slotDirSelected(const QString &) ) );
 
 
   file->setYesCancelVisible( false );  // relayout
 }
+/**
+ * @returns the mimetype of the selected
+ * currently it return QString::null
+ */
 QString OFileDialog::mimetype()const
 {
   return QString::null;
 }
+
+/**
+ * @return the fileName
+ */
 QString OFileDialog::fileName()const
 {
   return file->selectedName();
 }
+
+/**
+ * return a DocLnk to the current file
+ */
 DocLnk OFileDialog::selectedDocument()const
 {
   return file->selectedDocument();
 }
+
+/**
+ * This opens up a filedialog in Open mode
+ *
+ * @param selector the Selector Mode
+ * @param startDir Where to start from
+ * @param file A proposed filename
+ * @param mimes A list of MimeTypes
+ * @param wid the parent
+ * @param caption of the dialog if QString::null tr("Open") will be used
+ * @return the fileName or QString::null
+ */
 QString OFileDialog::getOpenFileName(int selector,
                                      const QString &startDir,
                                      const QString &file,
                                      const MimeTypes &mimes,
                                      QWidget *wid,
                                      const QString &caption )
 {
   QString ret;
   OFileDialog dlg( caption.isEmpty() ? tr("Open") : caption,
                    wid, OFileSelector::OPEN, selector, startDir, file, mimes);
   dlg.showMaximized();
   if( dlg.exec() )
     ret = dlg.fileName();
 
   return ret;
 }
+
+/**
+ * This opens up a file dialog in save mode
+ * @see getOpenFileName
+ */
 QString OFileDialog::getSaveFileName(int selector,
                                   const QString &startDir,
                                   const QString &file,
                                   const MimeTypes &mimes,
                                   QWidget *wid,
                                   const QString &caption )
 {
   QString ret;
   OFileDialog dlg( caption.isEmpty() ? tr("Save") : caption,
                    wid, OFileSelector::SAVE, selector, startDir, file, mimes);
   dlg.showMaximized();
   if( dlg.exec() )
     ret = dlg.fileName();
 
   return ret;
 }
 
 void OFileDialog::slotFileSelected(const QString & )
 {
   accept();
 }
 void OFileDialog::slotDirSelected(const QString & )
 {
   // if mode
   //accept();
 }
diff --git a/libopie/ofiledialog.h b/libopie/ofiledialog.h
index e14253c..309086b 100644
--- a/libopie/ofiledialog.h
+++ b/libopie/ofiledialog.h
@@ -1,77 +1,100 @@
 /*
                =.            This file is part of the OPIE Project
              .=l.            Copyright (c)  2002 zecke <zecke@handhelds.org>
            .>+-=
  _;:,     .>    :=|.         This library is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This library is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 
 #ifndef OpieFileDialog_h
 #define OpieFileDialog_h
 
 #include <qdialog.h>
 
 #include <opie/ofileselector.h>
 
+/**
+ * This class places a OFileSelector inside a QDialog.
+ * It provides static method for letting a user chose
+ * a file for either opening or saving.
+ * Most of the time  the c'tor will not be used instead using
+ * the static member functions is prefered.
+ *
+ * <pre>
+ * QMap<QString, QStringList> mimeTypes;
+ * QStringList types;
+ * types << "text/* ";
+ * mimeTypes.insert( tr("Text"), types );
+ * mimeTypes.insert( tr("All"), " * / * " ); // remove the spaces in the 2nd comment
+ * QString fileName= OFileDialog::getOpenFileName( OFileSelector::EXTENDED_ALL,
+ *                                                 "foo","bar", mimeTypes);
+ * </pre>
+ *
+ * @short A small QDialog swalloing a FileSelector
+ * @see QDialog
+ * @see OFileSelector
+ * @version 0.1-unfinished
+ * @author Holger Freyther ( zecke@handhelds.org )
+ */
 class OFileDialog : public QDialog {
   Q_OBJECT
  public:
   OFileDialog(const QString &caption,
               QWidget *, int mode, int selector,
               const QString &dirName,
               const QString &fileName = QString::null,
               const MimeTypes &mimetypes = MimeTypes()  );
   QString mimetype() const;
   QString fileName() const;
   DocLnk selectedDocument()const;
 
   // static methods
   static QString getOpenFileName(int selector,
                                  const QString& startDir = QString::null,
                                  const QString &fileName = QString::null,
                                  const MimeTypes& mime = MimeTypes(),
                                  QWidget *wid = 0,
                                  const QString &caption = QString::null );
 
   static QString getSaveFileName(int selector,
                                  const QString& startDir = QString::null,
                                  const QString& fileName = QString::null,
                                  const MimeTypes& mimefilter = MimeTypes(),
                                  QWidget *wid = 0,
                                  const QString &caption = QString::null );
 
   //let's OFileSelector catch up first
   //static QString getExistingDirectory(const QString& startDir = QString::null,
   // QWidget *parent = 0,
           //                  const QString& caption = QString::null );
  private:
   class OFileDialogPrivate;
   OFileDialogPrivate *d;
   OFileSelector *file;
 
  private slots:
   void slotFileSelected( const QString & );
   void slotDirSelected(const QString & );
 };
 #endif
diff --git a/libopie/ofileselector.h b/libopie/ofileselector.h
index 17c494e..06ac806 100644
--- a/libopie/ofileselector.h
+++ b/libopie/ofileselector.h
@@ -76,96 +76,98 @@ class OFileSelector : public QWidget {
    *  The mode of the file selector
    *  Either open, save, fileselector or dir browsing mode
    *
    */
   enum Mode {OPEN=1, SAVE=2, FILESELECTOR=4, DIR=8 };
 
   /**
    * Selector. Either NORMAL for the one shipped with
    * libqpe or EXTENDED. for the EXTENDED
    * EXTENDED_ALL also shows 'hidden' files
    */
   enum Selector{NORMAL=0, EXTENDED = 1, EXTENDED_ALL =2 };
 
   /**
    *  This is reserved for futrue views
    */
   enum View { DIRS = 1, FILES = 2, TREE = 4, ICON = 8 };
 
   /**
    *  A c'tor which should be used for advanced mode
    *  @param wid the parent
    *  @param mode the Mode of the Selector
    *  @param selector the current View of the Selector
    *  @param dirName in which dir to start
    *  @param fileName  a proposed filename
    *  @param mimetypes A list of mimetypes \
    *   QString is for a identifier name like "Text files"
    *   the coresponding QStringList is used for the mimetypes
    *   if empty it'll fill the list of mimetypes depending
    *   on the content of the current directory
    */
 
   OFileSelector(QWidget *wid, int mode, int selector,
                 const QString &dirName,
                 const QString &fileName = QString::null,
                 const MimeTypes &mimetypes = MimeTypes() );
 
 
   /**
    * This is a QPE compatible c'tor
    */
   OFileSelector(const QString &mimeFilter, QWidget *parent,
                 const char *name, bool newVisible = TRUE,
                 bool closeVisible = FALSE );
 
   ~OFileSelector();
 
   // currently only for the FILESELECTOR Mode
+  /**
+   */
   void setNewVisible( bool /*b*/ );
   void setCloseVisible(bool /*b*/ );
 
   // end file selector mode
   // deprecated
   void reread();
   // make sure not to leak please
   const DocLnk *selected();
   // end deprecated
 
   bool isToolbarVisible() const { return m_shTool;  };
   bool isPermissionBarVisible() const {  return m_shPerm; };
   bool isLineEditVisible()const { return m_shLne; };
   bool isChooserVisible( )const { return m_shChooser; };
   bool isYesCancelVisible()const { return m_shYesNo;  };
   void setYesCancelVisible( bool show );
   void setToolbarVisible( bool show );
   void setPermissionBarVisible( bool show );
   void setLineEditVisible(bool show) ;
   void setChooserVisible( bool chooser );
 
   QCheckBox* permissionCheckbox();
   bool setPermission() const;
   void setPermissionChecked( bool check );
 
   void setMode( int );
 
   bool showDirs()const { return m_dir; }
   void setShowDirs(bool );
 
   const QListView* listView() { return m_View; };
 
   bool isCaseSensetive()const {  return m_case; }
   void setCaseSensetive(bool caSe );
 
   bool showFiles()const { return m_files; };
   void setShowFiles(bool );
   bool cd(const QString &path );
 
 
   int mode()const { return m_mode;  };
   int selector()const { return m_selector; };
   void setSelector( int );
 
   bool showPopup()const { return m_showPopup; };
   void setShowPopup( bool pop ) { m_showPopup = pop; };
   void setPopupMenu( QPopupMenu * );
 
diff --git a/libopie/ofontmenu.cc b/libopie/ofontmenu.cc
index 52ff3ee..d16c5e5 100644
--- a/libopie/ofontmenu.cc
+++ b/libopie/ofontmenu.cc
@@ -1,112 +1,156 @@
 
 
 #include <qpe/config.h>
 #include "ofontmenu.h"
 
 
-
+/**
+ * Constructs the FontMenu.
+ *
+ * @param parent The parent widget
+ * @param name A name for this widget
+ * @param list The list of widgets to be controlled
+ */
 OFontMenu::OFontMenu(QWidget *parent, const char *name, const QList<QWidget> &list )
   : QPopupMenu( parent, name )
 {
   m_list = list;
   m_wids.setAutoDelete( TRUE );
 
   insertItem(tr("Large"), this, SLOT(slotLarge() ),
              0, 10);
   insertItem(tr("Medium"), this, SLOT(slotMedium() ),
              0, 11 );
   insertItem(tr("Small"), this, SLOT(slotSmall() ),
              0, 12 );
   setCheckable( true );
   m_size=10;
 }
+
+/**
+ * This method saves the font size
+ * into a Config object
+ * OFontMenu will be used as group and size as key
+ * @param cfg The Config object to be used
+ */
 void OFontMenu::save(Config *cfg )
 {
   cfg->setGroup("OFontMenu" );
   cfg->writeEntry("size", m_size );
 }
+
+/**
+ * This method restores the font size from a Config object
+ * it'll apply the sizes to the widgets and will also set the
+ * menu appropriate
+ */
 void OFontMenu::restore(Config *cfg )
 {
   cfg->setGroup("OFontMeny" );
   m_size = cfg->readNumEntry("size" );
   setItemChecked(10, false  );
   setItemChecked(11, false  );
   setItemChecked(12, false  );
   switch( m_size ){
   case 8:
     setItemChecked(12, true );
     break;
   case 14:
     setItemChecked(10, true );
     break;
   case 10:// fall through
   default:
     setItemChecked(11, true );
     m_size = 10;
     break;
   }
   setFontSize( m_size );
 }
+
+/**
+ * set the list of widgets
+ * @param list the widget list
+ */
 void OFontMenu::setWidgets(const QList<QWidget> &list )
 {
   m_list = list;
 }
+
+/**
+ * add a widget to the list
+ * @param wid The widget to be added
+ */
 void OFontMenu::addWidget( QWidget *wid )
 {
   m_list.append(wid );
 }
+
+/**
+ * removes the widget from the list of controlled objects
+ * @param wid the to be removed widget
+ */
 void OFontMenu::removeWidget( QWidget *wid )
 {
   m_list.remove( wid );
 }
+
+/**
+ * The list of controlled widgets
+ */
 const QList<QWidget> &OFontMenu::widgets()const
 {
   return m_list;
 }
+
+/**
+ * Forces a size on a widget
+ * @param wid The widget
+ * @param size The font size forced onto the widget
+ */
 void OFontMenu::forceSize(QWidget *wid, int size )
 {
   WidSize *widz = new WidSize;
   widz->wid = wid;
   widz->size = size;
   m_wids.append( widz );
 }
 void OFontMenu::slotSmall()
 {
   setItemChecked(10, false  );
   setItemChecked(11, false  );
   setItemChecked(12, true   );
   setFontSize( 8 );
 }
 void OFontMenu::slotMedium()
 {
   setItemChecked(10, false  );
   setItemChecked(11, true   );
   setItemChecked(12, false  );
   setFontSize(10 );
 }
 void OFontMenu::slotLarge()
 {
   setItemChecked(10, true   );
   setItemChecked(11, false  );
   setItemChecked(12, false  );
   setFontSize(14 );
 }
 void OFontMenu::setFontSize(int size )
 {
   m_size = size;
   QWidget *wid;
   for(wid = m_list.first(); wid !=0; wid = m_list.next() ){
     QFont font = wid->font();
     font.setPointSize( size );
     wid->setFont( font );
   }
   if(!m_wids.isEmpty() ){
     WidSize *wids;
     for( wids = m_wids.first(); wids != 0; wids = m_wids.next() ){
       QFont font = wids->wid->font();
       font.setPointSize( wids->size );
       wids->wid->setFont( font );
     }
   }
   emit fontChanged(size );
 }
diff --git a/libopie/ofontmenu.h b/libopie/ofontmenu.h
index 5fd515f..6e143ca 100644
--- a/libopie/ofontmenu.h
+++ b/libopie/ofontmenu.h
@@ -1,83 +1,113 @@
 
 /*
 
                =.            This file is part of the OPIE Project
              .=l.            Copyright (c)  2002 zecke <zecke@handhelds.org>
            .>+-=
- _;:,     .>    :=|.         This library is free software; you can 
+ _;:,     .>    :=|.         This library is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
-    .%`+i>       _;_.        
-    .i_,=:_.      -<s.       This library is distributed in the hope that  
+    .%`+i>       _;_.
+    .i_,=:_.      -<s.       This library is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
- :     =  ...= . :.=-        
+ :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
-    --        :-=`           this library; see the file COPYING.LIB. 
+    --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 
 
 
 #ifndef ofontmenu_h
 #define ofontmenu_h
 
 #include <qpopupmenu.h>
 #include <qlist.h>
 
-
+/*
+ * @internal
+ */
 namespace {
   struct WidSize {
     QWidget *wid;
     int size;
   };
 
 };
 
-// if i would be on kde this would be a KActionMenu...
+// forward declarations
 class Config;
+
+/**
+ * This class is a specialised QPopupMenu. It'll display three different
+ * font sizes. Small, Normal and large by adding widgets to the Menu
+ * you can control the font size of these widgets
+ * by using the save and restore method you can also apply font sizes
+ * over two different runtimes
+ *
+ * <pre>
+ * QTable* tbl = new QTable();
+ * QList<QWidget> wid;
+ * wid.append( tbl );
+ * OFontMenu* menu = new OFontMenu(this, "Popup Menu", wid );
+ * Config cfg("mycfg");
+ * menu->restore( cfg );
+ * </pre>
+ *
+ * @author Holger Freyther ( zecke@handhelds.org )
+ * @version 0.1
+ * @short PopupMenu which can control the size of Widgets
+ * @see QPopupMenu
+ */
 class OFontMenu : public QPopupMenu {
   Q_OBJECT
  public:
   OFontMenu(QWidget *parent, const char* name, const QList<QWidget> &list );
   void save(Config *cfg );
   void restore(Config *cfg );
   void setWidgets(const QList<QWidget> &list );
   void addWidget(QWidget *wid );
   void forceSize(QWidget *wid, int size );
   void removeWidget(QWidget *wid );
   const QList<QWidget> &widgets()const;
 
  signals:
+    /**
+     * this signal gets emitted when the font size gets changed
+     * @param size The new size of font
+     */
   void fontChanged(int size );
+
  private:
   QList<QWidget> m_list;
   QList<WidSize> m_wids;
   int m_size;
   class OFontMenuPrivate;
   OFontMenuPrivate *d;
+
  private slots:
   virtual void slotSmall();
   virtual void slotMedium();
   virtual void slotLarge();
   void setFontSize(int size );
 };
 
 #endif
 
 
 
 
 
diff --git a/libopie/ofontselector.cpp b/libopie/ofontselector.cpp
index b905474..c8471cc 100644
--- a/libopie/ofontselector.cpp
+++ b/libopie/ofontselector.cpp
@@ -1,362 +1,412 @@
 /*
                =.            This file is part of the OPIE Project
              .=l.            Copyright (c)  2002 Robert Griebl <sandman@handhelds.org>
            .>+-=
  _;:,     .>    :=|.         This library is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This library is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 #include <qlayout.h>
 #include <qlistbox.h>
 #include <qcombobox.h>
 #include <qlabel.h>
 #include <qfont.h>
 #include <qmultilineedit.h>
 
 #include <qpe/fontdatabase.h>
 
 #include "ofontselector.h"
 
 class OFontSelectorPrivate {
-public: 
+public:
         QListBox *      m_font_family_list;
         QComboBox *     m_font_style_list;
         QComboBox *     m_font_size_list;
         QMultiLineEdit *m_preview;
 
-        bool            m_pointbug;
+        bool            m_pointbug : 1;
 
         FontDatabase    m_fdb;
 };
 
+namespace {
 
 class FontListItem : public QListBoxText {
 public:
         FontListItem ( const QString &t, const QStringList &styles, const QValueList<int> &sizes ) : QListBoxText ( )
         {
                 m_name = t;
                 m_styles = styles;
                 m_sizes = sizes;
-                
+
                 QString str = t;
                 str [0] = str [0]. upper ( );
                 setText ( str );
         }
 
         QString family ( ) const
         {
                 return m_name;
         }
-        
+
         const QStringList &styles ( ) const
         {
                 return m_styles;
         }
-        
+
         const QValueList<int> &sizes ( ) const
         {
                 return m_sizes;
         }
-        
+
 private:
         QStringList m_styles;
         QValueList<int> m_sizes;
         QString m_name;
 };
 
 
 static int findItemCB ( QComboBox *box, const QString &str )
 {
         for ( int i = 0; i < box-> count ( ); i++ ) {
                 if ( box-> text ( i ) == str )
                         return i;
         }
         return -1;
 }
 
-
+}
+/* static same as anon. namespace */
 static int qt_version ( )
 {
         const char *qver = qVersion ( );
 
         return ( qver [0] - '0' ) * 100 + ( qver [2] - '0' ) * 10 + ( qver [4] - '0' );
 }
 
-
+/**
+ * Constructs the Selector object
+ * @param withpreview If a font preview should be given
+ * @param parent The parent of the Font Selector
+ * @param name The name of the object
+ * @param fl WidgetFlags
+ */
 OFontSelector::OFontSelector ( bool withpreview, QWidget *parent, const char *name, WFlags fl ) : QWidget ( parent, name, fl )
 {
         d = new OFontSelectorPrivate ( );
 
         QGridLayout *gridLayout = new QGridLayout ( this, 0, 0, 4, 4 );
         gridLayout->setRowStretch ( 4, 10 );
 
         d-> m_font_family_list = new QListBox( this, "FontListBox" );
         gridLayout->addMultiCellWidget( d-> m_font_family_list, 0, 4, 0, 0 );
         connect( d-> m_font_family_list, SIGNAL( highlighted( int ) ), this, SLOT( fontFamilyClicked( int ) ) );
 
         QLabel *label = new QLabel( tr( "Style" ), this );
         gridLayout->addWidget( label, 0, 1 );
 
         d-> m_font_style_list = new QComboBox( this, "StyleListBox" );
         connect( d-> m_font_style_list, SIGNAL(  activated( int ) ), this, SLOT( fontStyleClicked( int ) ) );
         gridLayout->addWidget( d-> m_font_style_list, 1, 1 );
 
         label = new QLabel( tr( "Size" ), this );
         gridLayout->addWidget( label, 2, 1 );
 
         d-> m_font_size_list = new QComboBox( this, "SizeListBox" );
         connect( d-> m_font_size_list, SIGNAL(  activated( int ) ),
                          this, SLOT( fontSizeClicked( int ) ) );
         gridLayout->addWidget( d-> m_font_size_list, 3, 1 );
 
         d-> m_pointbug = ( qt_version ( ) <= 233 );
 
         if ( withpreview ) {
                 d-> m_preview = new QMultiLineEdit ( this, "Preview" );
                 d-> m_preview-> setAlignment ( AlignCenter );
                 d-> m_preview-> setWordWrap ( QMultiLineEdit::WidgetWidth );
-                d-> m_preview-> setMargin ( 3 ); 
+                d-> m_preview-> setMargin ( 3 );
                 d-> m_preview-> setText ( tr( "The Quick Brown Fox Jumps Over The Lazy Dog" ));
                 gridLayout-> addRowSpacing ( 5, 4 );
                 gridLayout-> addMultiCellWidget ( d-> m_preview, 6, 6, 0, 1 );
                 gridLayout-> setRowStretch ( 6, 5 );
         }
         else
                 d-> m_preview = 0;
 
         loadFonts ( d-> m_font_family_list );
 }
 
 OFontSelector::~OFontSelector ( )
 {
         delete d;
 }
 
+/**
+ * This methods tries to set the font
+ * @param f The wishes font
+ * @return success or failure
+ */
 bool OFontSelector::setSelectedFont ( const QFont &f )
 {
         return setSelectedFont ( f. family ( ), d-> m_fdb. styleString ( f ), f. pointSize ( ), QFont::encodingName ( f. charSet ( )));
 }
 
-bool OFontSelector::setSelectedFont ( const QString &familyStr, const QString &styleStr, int sizeVal, const QString & /*charset*/ )
+
+/**
+ * This is an overloaded method @see setSelectedFont
+ * @param familyStr The family of the font
+ * @param styleStr The style of the font
+ * @param sizeVal The size of font
+ * @param charset The charset to be used. Will be deprecated by QT3
+ */
+bool OFontSelector::setSelectedFont ( const QString &familyStr, const QString &styleStr, int sizeVal, const QString & charset )
 {
         QString sizeStr = QString::number ( sizeVal );
 
         QListBoxItem *family = d-> m_font_family_list-> findItem ( familyStr );
         if ( !family )
                 family = d-> m_font_family_list-> findItem ( "Helvetica" );
         if ( !family )
                 family = d-> m_font_family_list-> firstItem ( );
-                 d-> m_font_family_list-> setCurrentItem ( family );
+            d-> m_font_family_list-> setCurrentItem ( family );
         fontFamilyClicked ( d-> m_font_family_list-> index ( family ));
 
         int style = findItemCB ( d-> m_font_style_list, styleStr );
         if ( style < 0 )
                 style = findItemCB ( d-> m_font_style_list, "Regular" );
         if ( style < 0 && d-> m_font_style_list-> count ( ) > 0 )
                 style = 0;
         d-> m_font_style_list-> setCurrentItem ( style );
         fontStyleClicked ( style );
 
         int size = findItemCB ( d-> m_font_size_list, sizeStr );
         if ( size < 0 )
                 size = findItemCB ( d-> m_font_size_list, "10" );
         if ( size < 0 && d-> m_font_size_list-> count ( ) > 0 )
                 size = 0;
         d-> m_font_size_list-> setCurrentItem ( size );
         fontSizeClicked ( size );
-        
+
         return (( family ) && ( style >= 0 ) && ( size >= 0 ));
 }
 
+/**
+ * This method returns the name, style and size of the currently selected
+ * font or false if no font is selected
+ * @param family The font family will be written there
+ * @param style The style will be written there
+ * @param size The size will be written there
+ * @return success or failure
+ */
 bool OFontSelector::selectedFont ( QString &family, QString &style, int &size )
 {
         QString dummy;
         return selectedFont ( family, style, size, dummy );
 }
 
 
+/**
+ * This method does return the font family or QString::null if there is
+ * no font item selected
+ * @return the font family
+ */
 QString OFontSelector::fontFamily ( ) const
 {
         FontListItem *fli = (FontListItem *) d-> m_font_family_list-> item ( d-> m_font_family_list-> currentItem ( ));
-        
+
         return fli ? fli-> family ( ) : QString::null;
 }
 
+/**
+ * This method will return the style of the font or QString::null
+ * @return the style of the font
+ */
 QString OFontSelector::fontStyle ( ) const
 {
         FontListItem *fli = (FontListItem *) d-> m_font_family_list-> item ( d-> m_font_family_list-> currentItem ( ));
-        int fst = d-> m_font_style_list-> currentItem ( ); 
+        int fst = d-> m_font_style_list-> currentItem ( );
 
         return ( fli && fst >= 0 ) ? fli-> styles ( ) [fst] : QString::null;
 }
 
+/**
+ * This method will return the font size or 10 if no font size is available
+ */
 int OFontSelector::fontSize ( ) const
 {
         FontListItem *fli = (FontListItem *) d-> m_font_family_list-> item ( d-> m_font_family_list-> currentItem ( ));
-        int fsi = d-> m_font_size_list-> currentItem ( ); 
+        int fsi = d-> m_font_size_list-> currentItem ( );
 
         return ( fli && fsi >= 0 ) ? fli-> sizes ( ) [fsi] : 10;
 }
 
+/**
+ * returns the charset of the font or QString::null
+ */
 QString OFontSelector::fontCharSet ( ) const
 {
         FontListItem *fli = (FontListItem *) d-> m_font_family_list-> item ( d-> m_font_family_list-> currentItem ( ));
 
         return fli ? d-> m_fdb. charSets ( fli-> family ( )) [0] : QString::null;
 }
 
+/**
+ * Overloaded member function see above
+ * @see selectedFont
+ */
 bool OFontSelector::selectedFont ( QString &family, QString &style, int &size, QString &charset )
 {
         int ffa = d-> m_font_family_list-> currentItem ( );
-        int fst = d-> m_font_style_list-> currentItem ( ); 
+        int fst = d-> m_font_style_list-> currentItem ( );
         int fsi = d-> m_font_size_list-> currentItem ( );
-        
+
         FontListItem *fli = (FontListItem *) d-> m_font_family_list-> item ( ffa );
-        
+
         if ( fli ) {
                 family = fli-> family ( );
                 style = fst >= 0 ? fli-> styles ( ) [fst] : QString::null;
                 size = fsi >= 0 ? fli-> sizes ( ) [fsi] : 10;
                 charset = d-> m_fdb. charSets ( fli-> family ( )) [0];
 
                 return true;
         }
         else
                 return false;
 }
 
 
-                        
+
 
 void OFontSelector::loadFonts ( QListBox *list )
 {
         QStringList f = d-> m_fdb. families ( );
-        
+
         for ( QStringList::ConstIterator it = f. begin ( ); it != f. end ( ); ++it ) {
                 QValueList <int> ps = d-> m_fdb. pointSizes ( *it );
-                
+
                 if ( d-> m_pointbug ) {
                         for ( QValueList <int>::Iterator it = ps. begin ( ); it != ps. end ( ); it++ )
                                 *it /= 10;
                 }
-        
+
                 list-> insertItem ( new FontListItem ( *it, d-> m_fdb. styles ( *it ), ps ));
         }
 }
 
 void OFontSelector::fontFamilyClicked ( int index )
 {
         QString oldstyle = d-> m_font_style_list-> currentText ( );
         QString oldsize  = d-> m_font_size_list-> currentText ( );
-        
+
         FontListItem *fli = (FontListItem *) d-> m_font_family_list-> item ( index );
-        
-                d-> m_font_style_list-> clear ( );
+
+        d-> m_font_style_list-> clear ( );
         d-> m_font_style_list-> insertStringList ( fli-> styles ( ));
         d-> m_font_style_list-> setEnabled ( !fli-> styles ( ). isEmpty ( ));
 
         int i;
-                
+
         i = findItemCB ( d-> m_font_style_list, oldstyle );
         if ( i < 0 )
                 i = findItemCB ( d-> m_font_style_list, "Regular" );
         if (( i < 0 ) && ( d-> m_font_style_list-> count ( ) > 0 ))
                 i = 0;
-                
+
         if ( i >= 0 ) {
-                        d-> m_font_style_list-> setCurrentItem ( i );   
+                d-> m_font_style_list-> setCurrentItem ( i );
                 fontStyleClicked ( i );
         }
-        
+
         d-> m_font_size_list-> clear ( );
         QValueList<int> sl = fli-> sizes ( );
-        
-        for ( QValueList<int>::Iterator it = sl. begin ( ); it != sl. end ( ); ++it ) 
+
+        for ( QValueList<int>::Iterator it = sl. begin ( ); it != sl. end ( ); ++it )
                 d-> m_font_size_list-> insertItem ( QString::number ( *it ));
 
         i = findItemCB ( d-> m_font_size_list, oldsize );
         if ( i < 0 )
                 i = findItemCB ( d-> m_font_size_list, "10" );
         if (( i < 0 ) && ( d-> m_font_size_list-> count ( ) > 0 ))
                 i = 0;
-                
+
         if ( i >= 0 ) {
-                        d-> m_font_size_list-> setCurrentItem ( i );                                                            
+                d-> m_font_size_list-> setCurrentItem ( i );
                 fontSizeClicked ( i );
         }
-                changeFont ( );
+        changeFont ( );
 }
 
 void OFontSelector::fontStyleClicked ( int /*index*/ )
 {
-                changeFont ( );
+        changeFont ( );
 }
 
 void OFontSelector::fontSizeClicked ( int /*index*/ )
 {
         changeFont ( );
 }
 
 void OFontSelector::changeFont ( )
 {
         QFont f = selectedFont ( );
 
         if ( d-> m_preview )
                 d-> m_preview-> setFont ( f );
 
         emit fontSelected ( f );
 }
 
-
+/**
+ * Return the selected font
+ */
 QFont OFontSelector::selectedFont ( )
 {
         int ffa = d-> m_font_family_list-> currentItem ( );
-        int fst = d-> m_font_style_list-> currentItem ( ); 
+        int fst = d-> m_font_style_list-> currentItem ( );
         int fsi = d-> m_font_size_list-> currentItem ( );
-        
+
         FontListItem *fli = (FontListItem *) d-> m_font_family_list-> item ( ffa );
-        
+
         if ( fli ) {
                 return d-> m_fdb. font ( fli-> family ( ), \
                                          fst >= 0 ? fli-> styles ( ) [fst] : QString::null, \
                                          fsi >= 0 ? fli-> sizes ( ) [fsi] : 10, \
                                          d-> m_fdb. charSets ( fli-> family ( )) [0] );
         }
         else
                 return QFont ( );
 }
 
 
 void OFontSelector::resizeEvent ( QResizeEvent *re )
 {
         if ( d-> m_preview ) {
                 d-> m_preview-> setMinimumHeight ( 1 );
                 d-> m_preview-> setMaximumHeight ( 32767 );
         }
 
         QWidget::resizeEvent ( re );
-        
+
         if ( d-> m_preview )
                 d-> m_preview-> setFixedHeight ( d-> m_preview-> height ( ));
-                
+
 }
diff --git a/libopie/ofontselector.h b/libopie/ofontselector.h
index 10d16f0..95ffd04 100644
--- a/libopie/ofontselector.h
+++ b/libopie/ofontselector.h
@@ -1,80 +1,93 @@
 /*
                =.            This file is part of the OPIE Project
              .=l.            Copyright (c)  2002 Robert Griebl <sandman@handhelds.org>
            .>+-=
  _;:,     .>    :=|.         This library is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU Library General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This library is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
-#ifndef __OPIE_FONTSELECTOR_H__
-#define __OPIE_FONTSELECTOR_H__
+#ifndef OPIE_FONTSELECTOR_H__
+#define OPIE_FONTSELECTOR_H__
 
 #include <qwidget.h>
 
 class QListBox;
 class OFontSelectorPrivate;
 
-
+/**
+ * This class lets you chose a Font out of a list of Fonts.
+ * It can show a preview too. This selector will use all available
+ * fonts
+ *
+ *
+ * @short A widget to select a font
+ * @see QWidget
+ * @see QFont
+ * @author Rober Griebl
+ */
 class OFontSelector : public QWidget
 {
     Q_OBJECT
 
 public:
     OFontSelector ( bool withpreview, QWidget* parent = 0, const char* name = 0, WFlags fl = 0 );
     virtual ~OFontSelector ( );
 
         bool selectedFont ( QString &family, QString &style, int &size );
         bool selectedFont ( QString &family, QString &style, int &size, QString &charset );
-        
+
         QFont selectedFont ( );
 
         bool setSelectedFont ( const QFont & );
         bool setSelectedFont ( const QString &family, const QString &style, int size, const QString &charset = 0 );
 
         QString fontFamily ( ) const;
         QString fontStyle ( ) const;
         int fontSize ( ) const;
         QString fontCharSet ( ) const;
 
 signals:
+        /**
+         * This signal gets emitted when a font got chosen
+         */
         void fontSelected ( const QFont & );
 
 protected slots:
     virtual void fontFamilyClicked ( int );
     virtual void fontStyleClicked ( int );
     virtual void fontSizeClicked ( int );
 
 protected:
         virtual void resizeEvent ( QResizeEvent *re );
 
 private:
         void loadFonts ( QListBox * );
 
     void changeFont ( );
-        
+
 private:
         OFontSelectorPrivate *d;
 };
 
 #endif
 
diff --git a/libopie/orecurrancewidget.cpp b/libopie/orecurrancewidget.cpp
index db86184..471249d 100644
--- a/libopie/orecurrancewidget.cpp
+++ b/libopie/orecurrancewidget.cpp
@@ -1,230 +1,274 @@
 #include <qapplication.h>
 #include <qlabel.h>
 #include <qpopupmenu.h>
 #include <qspinbox.h>
 
 #include <qpe/timestring.h>
 
 #include "orecurrancewidget.h"
 
 // Global Templates for use in setting up the repeat label...
 const QString strDayTemplate = QObject::tr("Every");
 const QString strYearTemplate = QObject::tr("%1 %2 every ");
 const QString strMonthDateTemplate = QObject::tr("The %1 every ");
 const QString strMonthDayTemplate = QObject::tr("The %1 %1 of every");
 const QString strWeekTemplate = QObject::tr("Every ");
 const QString dayLabel[] = { QObject::tr("Monday"),
                              QObject::tr("Tuesday"),
                              QObject::tr("Wednesday"),
                              QObject::tr("Thursday"),
                              QObject::tr("Friday"),
                              QObject::tr("Saturday"),
                              QObject::tr("Sunday") };
 
 
         static QString numberPlacing( int x );// return the proper word format for
                                         // x (1st, 2nd, etc)
 static int week( const QDate &dt );    // what week in the month is dt?
 
-
+/**
+ * Constructs the Widget
+ * @param startOnMonday Does the week start on monday
+ * @param newStart The start date of the recurrence
+ * @param parent The parent widget
+ * @param name the name of object
+ * @param modal if the dialog should be modal
+ * @param fl Additional window flags
+ */
 ORecurranceWidget::ORecurranceWidget( bool startOnMonday,
                                       const QDate& newStart,
                                       QWidget* parent,
                                       const char* name,
                                       bool modal,
                                       WFlags fl )
     : ORecurranceBase( parent, name, modal, fl ),
       start( newStart ),
       currInterval( None ),
       startWeekOnMonday( startOnMonday )
 {
     init();
     fraType->setButton( currInterval );
     chkNoEnd->setChecked( TRUE );
     setupNone();
 }
+
+/**
+ * Different constructor
+ * @param startOnMonday Does the week start on monday?
+ * @param rp Already set ORecur object
+ * @param startDate The start date
+ * @param parent The parent widget
+ * @param name The name of the object
+ * @param modal
+ * @param fl The flags for window
+ */
 ORecurranceWidget::ORecurranceWidget( bool startOnMonday,
                                       const ORecur& rp, const QDate& startDate,
                                       QWidget* parent, const char* name,
                                       bool modal, WFlags fl)
     : ORecurranceBase( parent, name, modal, fl ),
       start( startDate ),
       end( rp.endDate() ),
       startWeekOnMonday( startOnMonday )
 {
     // do some stuff with the repeat pattern
     init();
     setRecurrence( rp );
 }
 
 ORecurranceWidget::~ORecurranceWidget() {
 }
+
+/**
+ * set the start date
+ * @param date the new start date
+ */
 void ORecurranceWidget::setStartDate( const QDate& date ) {
     qWarning("ORecurranceWidget::setStartDate");
     setRecurrence( recurrence(), date );
 }
+/**
+ * set the recurrence
+ * @param rp  The ORecur object with the new recurrence rules
+ */
 void ORecurranceWidget::setRecurrence( const ORecur& rp ) {
     setRecurrence( rp, start );
 }
+
+/**
+ * overloaded method taking ORecur and a new start date
+ * @param rp Recurrence rule
+ * @param date The new start date
+ */
 void ORecurranceWidget::setRecurrence( const ORecur& rp, const QDate& date ) {
     start = date;
     end = rp.endDate();
     switch ( rp.type() ) {
     default:
     case ORecur::NoRepeat:
         currInterval = None;
         setupNone();
         break;
     case ORecur::Daily:
         currInterval = Day;
         setupDaily();
         break;
     case ORecur::Weekly:
         currInterval = Week;
         setupWeekly();
         int day, buttons;
         for ( day = 0x01, buttons = 0; buttons < 7;
               day = day << 1, buttons++ ) {
             if ( rp.days() & day ) {
                 if ( startWeekOnMonday )
                     fraExtra->setButton( buttons );
                 else {
                     if ( buttons == 7 )
                         fraExtra->setButton( 0 );
                     else
                         fraExtra->setButton( buttons + 1 );
                     }
                 }
             }
         slotWeekLabel();
         break;
     case ORecur::MonthlyDay:
         currInterval = Month;
         setupMonthly();
         fraExtra->setButton( 0 );
         slotMonthLabel( 0 );
         break;
     case ORecur::MonthlyDate:
         currInterval = Month;
         setupMonthly();
         fraExtra->setButton( 1 );
         slotMonthLabel( 1 );
         break;
     case ORecur::Yearly:
         currInterval = Year;
         setupYearly();
         break;
     }
     fraType->setButton( currInterval );
     spinFreq->setValue( rp.frequency() );
     if ( !rp.hasEndDate() ) {
         cmdEnd->setText( tr("No End Date") );
         chkNoEnd->setChecked( TRUE );
     } else
         cmdEnd->setText( TimeString::shortDate( end ) );
 }
+
+/**
+ * the user selected recurrence rule.
+ * @return The recurrence rule.
+ */
 ORecur ORecurranceWidget::recurrence()const {
     QListIterator<QToolButton> it( listRTypeButtons );
     QListIterator<QToolButton> itExtra( listExtra );
     ORecur rpTmp;
     int i;
     for ( i = 0; *it; ++it, i++ ) {
         if ( (*it)->isOn() ) {
             switch ( i ) {
             case None:
                 rpTmp.setType( ORecur::NoRepeat );
                 break;
             case Day:
                 rpTmp.setType( ORecur::Daily );
                 break;
             case Week:{
                 rpTmp.setType( ORecur::Weekly );
                 int day;
                 int day2 = 0;
                 for ( day = 1; *itExtra; ++itExtra, day = day << 1 ) {
                     if ( (*itExtra)->isOn() ) {
                         if ( startWeekOnMonday )
                             day2 |= day;
                         else {
                             if ( day == 1 )
                                 day2 |= Event::SUN;
                             else
                                 day2 |= day >> 1;
                         }
                     }
                 }
                 rpTmp.setDays( day2 );
             }
                 break;
             case Month:
                 if ( cmdExtra1->isOn() )
                     rpTmp.setType( ORecur::MonthlyDay );
                 else if ( cmdExtra2->isOn() )
                     rpTmp.setType( ORecur::MonthlyDate );
                 // figure out the montly day...
                 rpTmp.setPosition(  week( start ) );
                 break;
             case Year:
                 rpTmp.setType( ORecur::Yearly );
                 break;
             }
             break;  // no need to keep looking!
         }
     }
     rpTmp.setFrequency(spinFreq->value() );
     rpTmp.setHasEndDate( !chkNoEnd->isChecked() );
     if ( rpTmp.hasEndDate() ) {
         rpTmp.setEndDate( end );
     }
     // timestamp it...
 //    rpTmp.setCreateTime(  ); current DateTime is already set -zecke
     return rpTmp;
 }
+
+/**
+ * Return the end date of the recurrence. This is only
+ * valid if the recurrence rule does contain an enddate
+ */
 QDate ORecurranceWidget::endDate()const {
     return end;
 }
 void ORecurranceWidget::slotSetRType(int rtype) {
    // now call the right function based on the type...
     currInterval = static_cast<repeatButtons>(rtype);
     switch ( currInterval ) {
     case None:
         setupNone();
         break;
     case Day:
         setupDaily();
         break;
     case Week:
         setupWeekly();
         slotWeekLabel();
         break;
     case Month:
         setupMonthly();
         cmdExtra2->setOn( TRUE );
         slotMonthLabel( 1 );
         break;
     case Year:
         setupYearly();
         break;
     }
 }
 void ORecurranceWidget::endDateChanged(int y, int m, int d) {
     end.setYMD( y, m, d );
     if ( end < start )
         end = start;
     cmdEnd->setText(  TimeString::shortDate( end ) );
     repeatPicker->setDate( end.year(), end.month(), end.day() );
 }
 void ORecurranceWidget::slotNoEnd( bool unused) {
     // if the item was toggled, then go ahead and set it to the maximum date
     if ( unused ) {
         end.setYMD( 3000, 12, 31 );
         cmdEnd->setText( tr("No End Date") );
     } else {
         end = start;
         cmdEnd->setText( TimeString::shortDate(end) );
     }
 }
 void ORecurranceWidget::setupRepeatLabel( const QString& s) {
     lblVar1->setText( s );
 }
 void ORecurranceWidget::setupRepeatLabel( int x) {
diff --git a/libopie/orecurrancewidget.h b/libopie/orecurrancewidget.h
index 4a8dd08..af87ce9 100644
--- a/libopie/orecurrancewidget.h
+++ b/libopie/orecurrancewidget.h
@@ -1,67 +1,79 @@
 /*
  * GPL and based on the widget from TT
  */
 
 #ifndef OPIE_RECURRANCE_WIDGET_H
 #define OPIE_RECURRANCE_WIDGET_H
 
 #include <qlist.h>
 #include <qtoolbutton.h>
 #include <qcheckbox.h>
 #include <qdatetime.h>
 #include <qbuttongroup.h>
 
 #include <qpe/datebookmonth.h>
 
 #include "orecurrancebase.h"
 #include <opie/orecur.h>
 
 // FIXME spelling!!!! -zecke
+// FIXME spelling filenames
+
+/**
+ * A widget to let the user select rules for recurrences.
+ * This widget can take care of weekly, monthly, daily and yearly recurrence
+ * It is used inside todolist and datebook.
+ *
+ *
+ * @short Widget of selecting Recurrance
+ * @author Trolltech, Holger Freyther
+ * @version 0.9
+ */
 class ORecurranceWidget : public ORecurranceBase {
     Q_OBJECT
 public:
     ORecurranceWidget( bool startOnMonday,
                        const QDate& start, QWidget* parent = 0,
                        const char* name = 0,  bool modal = TRUE,
                        WFlags fl = 0 );
     ORecurranceWidget( bool startOnMonday,
                        const ORecur& rp, const QDate& start,
                        QWidget* parent = 0, const char* name =0,
                        bool modal = TRUE, WFlags = 0 );
     ~ORecurranceWidget();
     ORecur recurrence()const;
     QDate endDate()const;
 
 public slots:
     void slotSetRType( int );
     void endDateChanged( int, int, int );
     void slotNoEnd( bool unused );
     void setStartDate( const QDate& );
     void setRecurrence( const ORecur& recur, const QDate& start );
     void setRecurrence( const ORecur& recur );
 
 private slots:
     void setupRepeatLabel( const QString& );
     void setupRepeatLabel( int );
     void slotWeekLabel();
     void slotMonthLabel( int );
     void slotChangeStartOfWeek( bool onMonday );
 
 private:
     void setupNone();
     void setupDaily();
     void setupWeekly();
     void setupMonthly();
     void setupYearly();
 
     enum repeatButtons { None, Day, Week, Month, Year };
     void init();
     void hideExtras();
     void showRepeatStuff();
 
     QList<QToolButton> listRTypeButtons;
     QList<QToolButton> listExtra;
     QDate start;    // only used in one spot...
     QDate end;
     repeatButtons currInterval;
     bool startWeekOnMonday : 1;
diff --git a/libopie/otabbar.h b/libopie/otabbar.h
index 16797a3..c413611 100644
--- a/libopie/otabbar.h
+++ b/libopie/otabbar.h
@@ -12,64 +12,65 @@
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This program is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 #ifndef OTABBAR_H
 #define OTABBAR_H
 
 #include <qtabbar.h>
 
 /**
  * @class OTabBar
  * @brief The OTabBar class is a derivative of QTabBar.
  *
  * OTabBar is a derivation of TrollTech's QTabBar which provides
  * a row of tabs for selection.  The only difference between this
  * class and QTabBar is that there is no dotted line box around
  * the label of the tab with the current focus.
  */
 class OTabBar : public QTabBar
 {
     Q_OBJECT
 
 public:
 /**
  * @fn OTabBar( QWidget *parent = 0, const char *name = 0 )
  * @brief Object constructor.
  *
  * @param parent Pointer to parent of this control.
  * @param name Name of control.
  *
  * Constructs a new OTabBar control with parent and name.
  */
+ // FIXME Allow WFlags? -zecke
     OTabBar( QWidget * = 0, const char * = 0 );
 
 protected:
 /**
  * @fn paintLabel( QPainter* p, const QRect& br, QTab* t, bool has_focus )
  * @brief Internal function to draw a tab's label.
  *
  * @param p Pointer to QPainter used for drawing.
  * @param br QRect providing region to draw label in.
  * @param t Tab to draw label for.
  * @param has_focus Boolean value not used, retained for compatibility reasons.
  */
     void paintLabel( QPainter *, const QRect &, QTab *, bool ) const;
 };
 
 #endif
diff --git a/libopie/otabwidget.h b/libopie/otabwidget.h
index 0aa9bb8..23fe774 100644
--- a/libopie/otabwidget.h
+++ b/libopie/otabwidget.h
@@ -54,96 +54,97 @@ class QWidgetStack;
  * The normal way to use OTabWidget is to do the following in the
  * constructor:
  * - Create a OTabWidget.
  * - Create a QWidget for each of the pages in the control, insert
  *   children into it, set up geometry management for it, and use addTab()
  *   to add the widget.
  */
 class OTabWidget : public QWidget
 {
     Q_OBJECT
 public:
 
 /**
  * @enum TabStyle
  * @brief Defines how the widget selection control is displayed.
  *
  * Valid values:
  * - Global: use globally selected options (qpe.conf - TabStyle & TabPosition)
  * - TextTab: Tabbed widget selection with text labels
  * - IconTab: Tabbed widget selection with icon labels, text label for active widget
  *            (similar to Opie launcher)
  * - TextList: Drop down list widget selection with text labels
  * - IconList: Drop down list widget selection with icon & text labels
  */
     enum TabStyle { Global, TextTab, IconTab, TextList, IconList };
 
 /**
  * @enum TabPosition
  * @brief Defines where the widget selection control is drawn.
  *
  * Valid values:
  * - Top: Widget selection control is drawn above widgets
  * - Bottom: Widget selection control is drawn below widgets
  */
     enum TabPosition { Top, Bottom };
 
 /**
  * @fn OTabWidget( QWidget *parent = 0, const char *name = 0, TabStyle s = Global, TabPosition p = Top )
  * @brief Object constructor.
  *
  * @param parent Pointer to parent of this control.
  * @param name Name of control.
  * @param s Style of widget selection control.
  * @param p Position of the widget selection control.
  *
  * Constructs a new OTabWidget control with parent and name.  The style and position parameters
  * determine how the widget selection control will be displayed.
  */
+ // FIXME WFlags? -zecke
     OTabWidget( QWidget * = 0, const char * = 0, TabStyle = Global, TabPosition = Top );
 
 /**
  * @fn ~OTabWidget()
  * @brief Object destructor.
  */
     ~OTabWidget();
 
 /**
  * @fn addTab( QWidget *child, const QString &icon, const QString &label )
  * @brief Add new widget to control.
  *
  * @param child Widget control.
  * @param icon Path to icon.
  * @param label Text label.
  */
     void addTab( QWidget *, const QString &, const QString & );
 
 /**
  * @fn removePage( QWidget *widget )
  * @brief Remove widget from control.  Does not delete widget.
  *
  * @param widget Widget control to be removed.
  */
     void removePage( QWidget * );
 
 /**
  * @fn changeTab( QWidget *widget, const QIconSet &icon, const QString &label )
  * @brief Change text and/or icon for existing tab
  *
  * @param child Widget control.
  * @param icon Path to icon.
  * @param label Text label.
  */
     void changeTab( QWidget *, const QString &, const QString & );
 
 /**
  * @fn tabStyle()
  * @brief Returns current widget selection control style.
  */
     TabStyle tabStyle() const;
 
 /**
  * @fn setTabStyle( TabStyle s )
  * @brief Set the current widget selection control style.
  *
  * @param s New style to be used.
  */
@@ -152,96 +153,97 @@ public:
 /**
  * @fn tabPosition()
  * @brief Returns current widget selection control position.
  */
     TabPosition tabPosition() const;
 
 /**
  * @fn setTabPosition( TabPosition p )
  * @brief Set the current widget selection control position.
  *
  * @param p New position of widget selection control.
  */
     void setTabPosition( TabPosition );
 
 /**
  * @fn setCurrentTab( QWidget *childwidget )
  * @brief Selects and brings to top the desired widget by using widget pointer.
  *
  * @param childwidget Widget to select.
  */
     void setCurrentTab( QWidget * );
 
 /**
  * @fn setCurrentTab( const QString &tabname )
  * @brief Selects and brings to top the desired widget, by using label.
  *
  * @param tabname Text label for widget to select.
  */
     void setCurrentTab( const QString & );
 
 /**
  * @fn setCurrentTab( int )
  * @brief Selects and brings to top the desired widget, by using id.
  *
  * @param tab id for widget to select.
  */
     void setCurrentTab(int);
 
 /**
  * @fn sizeHint()
  * @brief Reimplemented for internal purposes.
  */
     QSize sizeHint() const;
 
 /**
  * @fn getCurrentTab( )
  * @brief returns current tab id.
  */
+ //FIXME TT coding style currentTab() -zecke
     int getCurrentTab();
 
 
 protected:
 
 /**
  * @fn resizeEvent( QResizeEvent * )
  * @brief Reimplemented for internal purposes.
  */
     void resizeEvent( QResizeEvent * );
 
 private:
     OTabInfoList  tabs;
     OTabInfo     *currentTab;
 
     TabStyle    tabBarStyle;
     TabPosition tabBarPosition;
 
     QWidgetStack *tabBarStack;
     OTabBar      *tabBar;
     QComboBox    *tabList;
 
     QWidgetStack *widgetStack;
 
 /**
  * @fn loadSmooth( const QString &name )
  * @brief Loads icon for widget.
  *
  * @param name Name of icon image file.
  */
     QPixmap loadSmooth( const QString & );
 
 /**
  * @fn selectTab( OTabInfo *tab )
  * @brief Internal function to select desired widget.
  *
  * @param tab Pointer to data for widget.
  */
     void    selectTab( OTabInfo * );
 
 /**
  * @fn setUpLayout()
  * @brief Internal function to adjust layout.
  */
     void    setUpLayout();
 
     
 signals:
diff --git a/libopie/oticker.h b/libopie/oticker.h
index 5df08da..30b7517 100644
--- a/libopie/oticker.h
+++ b/libopie/oticker.h
@@ -1,146 +1,146 @@
 /*
                             This file is part of the Opie Project
                              Copyright (c)  2002 L. Potter <ljp@llornkcor.com>
               =.
             .=l.
            .>+-=
  _;:,     .>    :=|.         This program is free software; you can
 .> <`_,   >  .   <=          redistribute it and/or  modify it under
 :`=1 )Y*s>-.--   :           the terms of the GNU General Public
 .="- .-=="i,     .._         License as published by the Free Software
  - .   .-<_>     .<>         Foundation; either version 2 of the License,
      ._= =}       :          or (at your option) any later version.
     .%`+i>       _;_.
     .i_,=:_.      -<s.       This program is distributed in the hope that
      +  .  -:.       =       it will be useful,  but WITHOUT ANY WARRANTY;
     : ..    .:,     . . .    without even the implied warranty of
     =_        +     =;=|`    MERCHANTABILITY or FITNESS FOR A
   _.=:.       :    :=>`:     PARTICULAR PURPOSE. See the GNU
 ..}^=.=       =       ;      Library General Public License for more
 ++=   -.     .`     .:       details.
  :     =  ...= . :.=-
  -.   .:....=;==+<;          You should have received a copy of the GNU
   -_. . .   )=.  =           Library General Public License along with
     --        :-=`           this library; see the file COPYING.LIB.
                              If not, write to the Free Software Foundation,
                              Inc., 59 Temple Place - Suite 330,
                              Boston, MA 02111-1307, USA.
 
 */
 
 #ifndef OTICKER_H
 #define OTICKER_H
 
 #include <qwidget.h>
 #include <qpainter.h>
 #include <qdrawutil.h>
 #include <qpixmap.h>
 #include <qstring.h>
 #include <qslider.h>
 #include <qlabel.h>
 #include <qframe.h>
 #include <qcolor.h>
-/*!
+
+/**
  * @class OTicker
  * @brief The OTicker class provides a QLabel widget that scroll its contents
  *
-*/
+ */
 class OTicker : public QLabel {
-//class OTicker : public QFrame {
     Q_OBJECT
 
 public:
 
 /*!
  * @fn OTicker( QWidget* parent = 0 )
  * @brief Object constructor.
  *
  * @param parent Pointer to parent of this control.
 
  * Constructs a new OTicker control with parent
  */
     OTicker( QWidget* parent=0 );
 /*!
  * @fn ~OTicker()
  * @brief Object destructor.
  */
     ~OTicker();
 /*!
  * @fn setText()
  * @brief sets text to be displayed
  * @param text QString text to be displayed.
  *
  */
     void setText( const QString& text ) ;
 /*!
  * @fn setBackgroundColor(QColor color)
  * @brief sets color of the ticker's background
  * @param color QColor color to be set.
  *
  */
     void setBackgroundColor(QColor color);
 /*!
  * @fn setForegroundColor(QColor color)
  * @brief sets color of text
  * @param color QColor color of text
  *
  */
     void setForegroundColor(QColor color);
 /*!
  * @fn setFrame(int style)
  * @brief sets frame style
  * @param style int Frame style to be see. See Qt::WidgetFlags.
  *
  */
-    void setFrame(int style); 
+    void setFrame(int style);
 /*!
  * @fn setUpdateTime(int timeout)
  * @brief sets time of update
  * @param timeout int time in milliseconds between updates.
  *
  */
     void setUpdateTime(int timeout);
 /*!
  * @fn setScrollLength(int length)
  * @brief sets amount of scrolling default is 1
  * @param length int scroll length.
  *
  */
-    void setScrollLength(int length); 
+    void setScrollLength(int length);
 signals:
 /*!
  * @fn mousePressed()
  * @brief signal mouse press event
  *
  */
     void mousePressed();
 protected:
 /*!
  * @fn timerEvent( QTimerEvent * e)
  * @brief timer timeout event
  * @param e QEvent see QEvent.
  *
  */
     void timerEvent( QTimerEvent * e);
 /*!
  * @fn drawContents( QPainter *p )
  * @brief draws widget contents
  * @param p QPainter. see QPainter
  *
  */
     void drawContents( QPainter *p );
 /*!
  * @fn mouseReleaseEvent( QMouseEvent *e)
  * @brief mouse release event
  * @param e QMouseEvent. see QMouseEvent.
  *
  */
     void mouseReleaseEvent( QMouseEvent *e);
 private:
     QColor backgroundcolor, foregroundcolor;
     QString scrollText;
     QPixmap scrollTextPixmap;
     int pos, updateTimerTime, scrollLength;
 };
 
 #endif
diff --git a/libopie/otimepicker.cpp b/libopie/otimepicker.cpp
index 8e8a4e7..115d39b 100644
--- a/libopie/otimepicker.cpp
+++ b/libopie/otimepicker.cpp
@@ -1,175 +1,245 @@
 #include "otimepicker.h"
 
 #include <qbuttongroup.h>
 #include <qtoolbutton.h>
 #include <qlayout.h>
 #include <qstring.h>
 #include <stdio.h>
 #include <qlineedit.h>
 
-OTimePicker::OTimePicker(QWidget* parent, const char* name, 
+
+/**
+ * Constructs the widget
+ * @param parent The parent of the OTimePicker
+ * @param name The name of the object
+ * @param fl Window Flags
+ */
+OTimePicker::OTimePicker(QWidget* parent, const char* name,
                        WFlags fl) :
   QWidget(parent,name,fl)
 {
+
   QVBoxLayout *vbox=new QVBoxLayout(this);
 
   OClickableLabel *r;
   QString s;
 
   // Hour Row
   QWidget *row=new QWidget(this);
   QHBoxLayout *l=new QHBoxLayout(row);
   vbox->addWidget(row);
-  
-  
+
+
   for (int i=0; i<24; i++) {
     r=new OClickableLabel(row);
     hourLst.append(r);
     s.sprintf("%.2d",i);
     r->setText(s);
     r->setToggleButton(true);
     r->setAlignment(AlignHCenter | AlignVCenter);
     l->addWidget(r);
     connect(r, SIGNAL(toggled(bool)),
             this, SLOT(slotHour(bool)));
 
     if (i==11) { // Second row
       row=new QWidget(this);
       l=new QHBoxLayout(row);
       vbox->addWidget(row);
     }
   }
 
   // Minute Row
   row=new QWidget(this);
   l=new QHBoxLayout(row);
   vbox->addWidget(row);
-  
+
   for (int i=0; i<60; i+=5) {
     r=new OClickableLabel(row);
     minuteLst.append(r);
     s.sprintf("%.2d",i);
     r->setText(s);
     r->setToggleButton(true);
     r->setAlignment(AlignHCenter | AlignVCenter);
     l->addWidget(r);
     connect(r, SIGNAL(toggled(bool)),
             this, SLOT(slotMinute(bool)));
   }
 }
 
+/**
+ * This method return the current time
+ * @return the time
+ */
+QTime OTimePicker::time()const {
+    return tm;
+}
+
 void OTimePicker::slotHour(bool b) {
 
   OClickableLabel *r = (OClickableLabel *) sender();
 
   if (b) {
     QValueListIterator<OClickableLabel *> it;
     for (it=hourLst.begin(); it!=hourLst.end(); it++) {
       if (*it != r) (*it)->setOn(false);
       else tm.setHMS((*it)->text().toInt(), tm.minute(), 0);
     }
     emit timeChanged(tm);
   } else {
     r->setOn(true);
   }
 
 }
 
 void OTimePicker::slotMinute(bool b) {
 
   OClickableLabel *r = (OClickableLabel *) sender();
 
   if (b) {
     QValueListIterator<OClickableLabel *> it;
     for (it=minuteLst.begin(); it!=minuteLst.end(); it++) {
       if (*it != r) (*it)->setOn(false);
       else tm.setHMS(tm.hour(),(*it)->text().toInt(), 0);
     }
     emit timeChanged(tm);
   } else {
     r->setOn(true);
   }
 
 }
 
+/**
+ * Method to set the time. No signal gets emitted during this method call
+ * Minutes must be within 5 minutes step starting at 0 ( 0,5,10,15,20... )
+ * @param t The time to be set
+ */
+void OTimePicker::setTime( const QTime& t) {
+    setTime( t.hour(), t.minute() );
+}
+
+/**
+ * Method to set the time. No signal gets emitted during this method call
+ * @param h The hour
+ * @param m The minute. Minutes need to set by 5 minute steps
+ */
+void OTimePicker::setTime( int h,  int m ) {
+    setHour(h);
+    setMinute(m);
+}
+
+/*
+ * FIXME round minutes to the 5 minute arrangement -zecke
+ */
+/**
+ * Method to set the minutes
+ * @param m minutes
+ */
 void OTimePicker::setMinute(int m) {
 
   QString minute;
   minute.sprintf("%.2d",m);
 
   QValueListIterator<OClickableLabel *> it;
   for (it=minuteLst.begin(); it!=minuteLst.end(); it++) {
     if ((*it)->text() == minute) (*it)->setOn(true);
     else (*it)->setOn(false);
-  }  
+  }
 
   tm.setHMS(tm.hour(),m,0);
 }
 
+/**
+ * Method to set the hour
+ */
 void OTimePicker::setHour(int h) {
 
   QString hour;
   hour.sprintf("%.2d",h);
 
   QValueListIterator<OClickableLabel *> it;
   for (it=hourLst.begin(); it!=hourLst.end(); it++) {
     if ((*it)->text() == hour) (*it)->setOn(true);
     else (*it)->setOn(false);
-  }  
+  }
   tm.setHMS(h,tm.minute(),0);
 }
 
 
+/**
+ * This is a modal Dialog.
+ *
+ * @param parent The parent widget
+ * @param name The name of the object
+ * @param fl Possible window flags
+ */
 OTimePickerDialog::OTimePickerDialog ( QWidget* parent, const char* name, WFlags fl )
         : OTimePickerDialogBase (parent , name, true , fl)
 {
 
         connect ( m_timePicker, SIGNAL( timeChanged( const QTime& ) ),
                   this, SLOT( setTime ( const QTime& ) ) );
         connect ( minuteField, SIGNAL( textChanged ( const QString& ) ),
                   this, SLOT ( setMinute ( const QString& ) ) );
         connect ( hourField, SIGNAL( textChanged ( const QString& ) ),
                   this, SLOT ( setHour ( const QString& ) ) );
 
 }
 
-QTime& OTimePickerDialog::time()
+/**
+ * @return the time
+ */
+QTime OTimePickerDialog::time()const
 {
         return m_time;
 }
+
+/**
+ * Set the time to time
+ * @param time The time to be set
+ */
 void OTimePickerDialog::setTime( const QTime& time )
 {
         m_time = time;
 
         m_timePicker->setHour ( time.hour() );
         m_timePicker->setMinute( time.minute() );
 
         // Set Textfields
         if ( time.hour() < 10 )
                 hourField->setText( "0" + QString::number( time.hour() ) );
         else
                 hourField->setText( QString::number( time.hour() ) );
 
         if ( time.minute() < 10 )
                 minuteField->setText( "0" + QString::number( time.minute() ) );
         else
                 minuteField->setText( QString::number( time.minute() ) );
-        
+
 }
 
+/**
+ * This method takes the current minute and tries to set hour
+ * to hour. This succeeds if the resulting date is valid
+ * @param hour The hour as a string
+ */
 void OTimePickerDialog::setHour ( const QString& hour )
 {
         if ( QTime::isValid ( hour.toInt(),  m_time.minute() , 00 ) ){
                 m_time.setHMS ( hour.toInt(),  m_time.minute() , 00 );
                 setTime ( m_time );
         }
 
 }
 
+/**
+ * Method to set a new minute. It tries to convert the string to int and
+ * if the resulting date is valid a new date is set.
+ * @see setHour
+ */
 void OTimePickerDialog::setMinute ( const QString& minute )
 {
         if ( QTime::isValid ( m_time.hour(), minute.toInt(), 00 ) ){
                 m_time.setHMS ( m_time.hour(), minute.toInt(), 00 );
                 setTime ( m_time );
         }
 }
diff --git a/libopie/otimepicker.h b/libopie/otimepicker.h
index 825e2d6..495c806 100644
--- a/libopie/otimepicker.h
+++ b/libopie/otimepicker.h
@@ -1,51 +1,81 @@
 #ifndef OTIMEPICKER_H
 #define OTIMEPICKER_H
 
 #include <qwidget.h>
 #include <qvaluelist.h>
 #include <qdatetime.h>
 #include <qdialog.h>
 
 #include <opie/oclickablelabel.h>
 #include "otimepickerbase.h"
 
+/**
+ * A class to pick time. It uses clickable labels
+ * internally to allow a quick selection of a time.
+ * A time can be selected by two clicks of a user
+ *
+ * @short A widget to quickly pick a QTime
+ * @version 1.0
+ * @see QWidget
+ * @see QTime
+ * @author Hakan Ardo, Stefan Eilers
+ */
 class OTimePicker: public QWidget {
   Q_OBJECT
 
  public:
-    OTimePicker(QWidget* parent = 0, const char* name = 0, 
+    OTimePicker(QWidget* parent = 0, const char* name = 0,
                WFlags fl = 0);
+ 
+         public slots:      
     void setHour(int h);
     void setMinute(int m);
+    void setTime( const QTime& );
+    void setTime( int h,  int m );
+    
+ public:
+    QTime time()const;
 
  private:
     QValueList<OClickableLabel *> hourLst;
     QValueList<OClickableLabel *> minuteLst;
     QTime tm;
+    struct Private;
+    Private *d;
 
  private slots:
     void slotHour(bool b);
     void slotMinute(bool b);
 
  signals:
+    /**
+     * gets emitted when the time got changed by the user
+     */
     void timeChanged(const QTime &);
 };
 
+/**
+ *
+ * @short
+ * @version 1.0
+ * @author Stefan Eilers
+ */
+
 class OTimePickerDialog: public OTimePickerDialogBase {
   Q_OBJECT
 
  public:
         OTimePickerDialog ( QWidget* parent = 0, const char* name = NULL, WFlags fl = 0 );
         ~OTimePickerDialog() { };
 
-        QTime& time();
+        QTime time()const;
 
  public slots:
         void setTime( const QTime& time );
         void setHour( const QString& hour );
         void setMinute( const QString& minute );
 
  private:
         QTime m_time;
 };
 #endif
diff --git a/libopie/owait.cpp b/libopie/owait.cpp
index c90bb72..0fdf08d 100644
--- a/libopie/owait.cpp
+++ b/libopie/owait.cpp
@@ -1,81 +1,91 @@
 /*  This file is part of the OPIE libraries
     Copyright (C) 2003 Maximilian Reiss  (harlekin@handhelds.org)
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Library General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later version.
 
     This library is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Library General Public License for more details.
 
     You should have received a copy of the GNU Library General Public License
     along with this library; see the file COPYING.LIB.  If not, write to
     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
     Boston, MA 02111-1307, USA.
 */
 
 #include <qlabel.h>
 #include <qlayout.h>
 #include <qtimer.h>
 #include <qpe/qpeapplication.h>
 #include <qpainter.h>
 
 #include "owait.h"
 
 #include <qpe/resource.h>
 
 static int frame = 0;
 
+/**
+ * This will construct a modal dialog.
+ *
+ * The default timer length is 10.
+ *
+ * @param parent The parent of the widget
+ * @param msg The name of the object
+ * @param dispIcon Display Icon?
+ */
 OWait::OWait(QWidget *parent, const char* msg, bool dispIcon )
-  :QDialog(parent, QObject::tr("Wait"), TRUE,WStyle_Customize) {
+  :QDialog(parent, msg, TRUE,WStyle_Customize) {
+
 
     QHBoxLayout *hbox  = new QHBoxLayout( this );
 
     m_lb = new QLabel( this );
     m_lb->setBackgroundMode ( NoBackground );
 
     hbox->addWidget( m_lb );
     hbox->activate();
 
     m_pix = Resource::loadPixmap( "BigBusy" );
     m_aniSize = m_pix.height();
     resize( m_aniSize, m_aniSize );
 
     m_timerLength = 10;
 
     m_waitTimer = new QTimer( this );
     connect( m_waitTimer, SIGNAL( timeout() ), this, SLOT( hide() ) );
 }
 
 void OWait::timerEvent( QTimerEvent * )  {
     frame = (++frame) % 4;
     repaint();
 }
 
 void OWait::paintEvent( QPaintEvent * )  {
       QPainter p( m_lb  );
       p.drawPixmap( 0, 0, m_pix, m_aniSize * frame,  0, m_aniSize, m_aniSize );
 }
 
 void OWait::show()  {
 
     move( ( ( qApp->desktop()->width() ) / 2 ) - ( m_aniSize / 2 ), ( ( qApp->desktop()->height() ) / 2 ) - ( m_aniSize / 2 ) );
     startTimer( 300 );
     m_waitTimer->start( m_timerLength * 1000, true );
     QDialog::show();
 }
 
 void OWait::hide()  {
     killTimers();
     m_waitTimer->stop();
     frame = 0;
     QDialog::hide();
 }
 
 void OWait::setTimerLength( int length )  {
     m_timerLength = length;
 }
 
diff --git a/libopie/owait.h b/libopie/owait.h
index d22e141..6217e31 100644
--- a/libopie/owait.h
+++ b/libopie/owait.h
@@ -1,69 +1,74 @@
 /*  This file is part of the OPIE libraries
     Copyright (C) 2003 Maximilian Reiss  (harlekin@handhelds.org)
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Library General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later version.
 
     This library is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Library General Public License for more details.
 
     You should have received a copy of the GNU Library General Public License
     along with this library; see the file COPYING.LIB.  If not, write to
     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
     Boston, MA 02111-1307, USA.
 */
 
 
 
 #ifndef WAITPOPUP_H
 #define WAITPOPUP_H
 
 #include <qdialog.h>
 #include <qpixmap.h>
 #include <qlabel.h>
 #include <qtimer.h>
 
 /**
  * This class displays a animated waiting icon in the middle of the screen.
+ *
+ * @short modal hour glass dialog
+ * @see QDialog
+ * @author Maximilian Reiß
  */
 class OWait : public QDialog {
 
     Q_OBJECT
 
 public:
-    OWait(QWidget *parent=0,const char* msg=0,bool dispIcon=TRUE);
+    OWait(QWidget *parent=0,const char* name=0, bool dispIcon=TRUE);
     ~OWait();
-    
+
     /**
      * reimplemented for control reasons
      */
     void show();
 
     /**
      * Set the time before the icon will be automaticly hidden
+     * The timer will be started once the widget will be shown.
      * @param length - time in seconds
      */
-    void setTimerLength( int length ); 
+    void setTimerLength( int length );
 
     public slots:
     /**
      * reimplemented for control reasons
      */
     void hide();
 
  private:
     void timerEvent( QTimerEvent * ) ;
-    void paintEvent( QPaintEvent * );  
+    void paintEvent( QPaintEvent * );
 
     QPixmap m_pix;
     QLabel *m_lb;
     QTimer *m_waitTimer;
     int m_timerLength;
     int m_aniSize;
 };
 
 #endif
diff --git a/libopie/todayconfigwidget.h b/libopie/todayconfigwidget.h
index 48cf379..6b49efc 100644
--- a/libopie/todayconfigwidget.h
+++ b/libopie/todayconfigwidget.h
@@ -1,21 +1,39 @@
 
 #ifndef CONFIG_WIDGET_H
 #define CONFIG_WIDGET_H
 
 
+/**
+ * A base class for all Today Config Widgets.
+ * This will let a Today plugin to add the possibility of configuration.
+ * Plugins need to inherit from this class and need to implement
+ * the pure virtual method to control configuration.
+ * The Plugin should read its configuration during creation of the Widget
+ *
+ *
+ * @author Maximilian Reiß
+ * @short base class of all today config widgets
+ */
 class TodayConfigWidget : public QWidget {
 
 
 public:
 
+    /**
+     * This will construct the widget. The widget gets deleted once the parent
+     * gets deleted as in any Qt application
+     *
+     * @param parent The parent of the widget
+     * @paran name The name of the object
+     */
     TodayConfigWidget( QWidget *parent,  const char *name ) : QWidget( parent,  name ) {} ;
     virtual ~TodayConfigWidget() {};
 
     /**
      * Plugins need to reimplement this in the config widget
      * Used when the config dialog is closed to write config stuff
      */
     virtual void  writeConfig() = 0;
 };
 
 #endif
diff --git a/libopie/todayplugininterface.h b/libopie/todayplugininterface.h
index 6ee2a06..29a12bc 100644
--- a/libopie/todayplugininterface.h
+++ b/libopie/todayplugininterface.h
@@ -1,89 +1,106 @@
 
 #ifndef TODAY_PLUGIN_INTERFACE
 #define TODAY_PLUGIN_INTERFACE
 
 #include <qpe/qcom.h>
 #include "todayconfigwidget.h"
 
 class QString;
 class QWidget;
 
 #ifndef IID_TodayPluginInterface
 #define IID_TodayPluginInterface QUuid( 0x70481804, 0x2b50, 0x4fba, 0x80, 0xbb, 0x0b, 0xf8, 0xdc, 0x72, 0x04, 0x14)
 #endif
 
 /**
  *
+ * A TodayPluginObject is the base for all Today Plugins.
+ * A plugin author needs to inherit this class and implement
+ * the pure virtual methods
  *
+ * @short base class for today plugins
+ * @author Maximilian Reiss
  *
  */
 class TodayPluginObject {
 
 public:
 
     virtual ~TodayPluginObject() {};
 
     /**
      * The name if the plugin
+     * @return The plugin should return its name here
      */
     virtual QString pluginName() const = 0;
 
     /**
      * Version numbering
+     * @return The plugin should return the version number
      */
     virtual double versionNumber() const = 0;
 
 
+    /**
+     * @return the pixmap name widget?! -- FIXME
+     */
     virtual  QString pixmapNameWidget() const = 0;
 
-    /**    widget for the today view
+    /**
+     * widget for the today view
      * It _needs_ a parent here.
+     * Plugin authors need to take parent as parent!
      */
-    virtual QWidget* widget( QWidget * ) = 0;
+    virtual QWidget* widget( QWidget *parent ) = 0;
 
     /**
      * Pixmap used in the config widget
      */
     virtual QString pixmapNameConfig() const = 0;
 
     /**
      * Config plugin widget - optional
      * If the plugin has a config widget, it  _needs_  a parent here.
+     * may return 0 if no config widget is needed
      */
     virtual TodayConfigWidget* configWidget( QWidget * ) = 0;
 
     /**
      * The application that should be assigned to the button (pixmap)
+     * Today will show the plugin icon. On click it tries to execute the
+     * plugin related application.
      */
     virtual QString appName() const = 0;
 
 
     /**
      * If the plugin should take part in the periodic refresh
      */
     virtual bool excludeFromRefresh() const = 0;
 
     /**
      * Refresh that plugins view. For updating the plugins
      *
      */
     virtual void refresh() {};
 
     /**
      * minimum height the plugin at least should have
      */
     // virtual int minHeight()  const = 0;
 
     /**
      *  maximum height that should be used before starting scrolling
      */
     // virtual int maxHeight() const = 0;
 
 };
 
-
+/**
+ * This is part of the QCOM works. See example plugins how to do it right
+ */
 struct TodayPluginInterface : public QUnknownInterface {
     virtual TodayPluginObject *guiPart() = 0;
 };
 
 #endif