comments/docs by drw

3 files changed, 236 insertions, 40 deletions

diff --git a/libopie/colordialog.h b/libopie/colordialog.h
index 474bc61..926f8f2 100644
--- a/libopie/colordialog.h
+++ b/libopie/colordialog.h
@@ -1,77 +1,89 @@
 /****************************************************************************
 ** $Id$
 **
 ** Definition of OColorDialog class
 **
 ** Created : 990222
 **
 ** Copyright (C) 1992-2000 Trolltech AS.  All rights reserved.
 **
 ** This file is part of the dialogs module of the Qt GUI Toolkit.
 **
 ** 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.
 **
 **********************************************************************/
 
 #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,
 			 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&
     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 17e2c0a..510a2ad 100644
--- a/libopie/colorpopupmenu.cpp
+++ b/libopie/colorpopupmenu.cpp
@@ -1,148 +1,159 @@
-/**********************************************************************
-** ColorPopupMenu
-**
-** Popup menu for selecting colors
-**
-** Based on colorpanel by S. Prud'homme <prudhomme@laposte.net>
-**
-** Copyright (C) 2002, Dan Williams
-**                    williamsdr@acm.org
-**                    http://draknor.net
-**
-** This file may be distributed and/or modified under the terms of the
-** GNU General Public License version 2 as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL included in the
-** packaging of this file.
-**
-** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
-** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
-**
-**********************************************************************/
+/*
+                            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 )
     : QFrame( parent, name )
 {
     m_color = color;
 
     setFixedSize( 16, 16 );
     setActive( FALSE );
 }
 
 ColorPanelButton::~ColorPanelButton()
 {
 }
 
 void ColorPanelButton::setActive( bool active )
 {
     m_active = active;
 
     if ( m_active ) {
         setFrameStyle( Panel | Sunken );
     } else {
         setFrameStyle( NoFrame );
     }
 }
 
 void ColorPanelButton::enterEvent( QEvent* e )
 {
     Q_UNUSED( e )
 
     if ( !m_active ) {
         setFrameStyle( Panel | Sunken );
     }
 }
 
 void ColorPanelButton::leaveEvent( QEvent* e )
 {
     Q_UNUSED( e )
 
     if ( !m_active ) {
         setFrameStyle( NoFrame );
     }
 }
 
 void ColorPanelButton::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 )
 {
     Q_UNUSED( e )
 
     emit selected( m_color );
 }
 
 ColorPopupMenu::ColorPopupMenu( 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()
 {
 }
 
 void ColorPopupMenu::addColor( const QColor& color, int row, int col )
 {
     ColorPanelButton* panelButton = new ColorPanelButton( color, colorPanel );
     connect( panelButton, SIGNAL( selected( const QColor& ) ), this, SLOT( buttonSelected( const QColor& ) ) );
diff --git a/libopie/colorpopupmenu.h b/libopie/colorpopupmenu.h
index 1a6ab08..b0453b2 100644
--- a/libopie/colorpopupmenu.h
+++ b/libopie/colorpopupmenu.h
@@ -1,81 +1,254 @@
-/**********************************************************************
-** ColorPopupMenu
-**
-** Popup menu for selecting colors
-**
-** Based on colorpanel by S. Prud'homme <prudhomme@laposte.net>
-**
-** Copyright (C) 2002, Dan Williams
-**                    williamsdr@acm.org
-**                    http://draknor.net
-**
-** This file may be distributed and/or modified under the terms of the
-** GNU General Public License version 2 as published by the Free Software
-** Foundation and appearing in the file LICENSE.GPL included in the
-** packaging of this file.
-**
-** This file is provided AS IS with NO WARRANTY OF ANY KIND, INCLUDING THE
-** WARRANTY OF DESIGN, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
-**
-**********************************************************************/
+/*
+                            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.
+ *
+ * @see ColorPopupMenu
+ *
+ * The ColorPanelButton 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.
+ */
 class ColorPanelButton : public QFrame
 {
     Q_OBJECT
 
 public:
+
+/**
+ * @fn ColorPanelButton( 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);
+
+/**
+ * @fn ~ColorPanelButton()
+ * @brief Object destructor.
+ */
     ~ColorPanelButton();
 
+/**
+ * @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
+ *        popup menu.
+ *
+ * ColorPopupMenu 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
 {
     Q_OBJECT
 
 public:
+
+/**
+ * @fn ColorPopupMenu( 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.
+ */
     ColorPopupMenu( const QColor& color, QWidget* parent = 0, const char* name = 0 );
+
+/**
+ * @fn ~ColorPopupMenu()
+ * @brief Object destructor.
+ */
     ~ColorPopupMenu();
 
 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.
+ */
     void buttonSelected( const QColor& color );
+
+/**
+ * @fn moreColorClicked()
+ * @brief Slot to process display color selection dialog.
+ *
+ * @see colorSelected()
+ *
+ * This slot executes when the 'More...' option is selected at the bottom of the menu.
+ * It performs the following functions:
+ * - Constructs and executes a OColorDialog to allow finer color selection.
+ * - Emit the colorSelected signal with the color selected.
+ * - Hide the menu.
+ */
     void moreColorClicked();
 };
 
 #endif // COLORPOPUPMENUANEL_H