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
@@ -23,48 +23,60 @@
 ** 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=
diff --git a/libopie/colorpopupmenu.cpp b/libopie/colorpopupmenu.cpp
index 17e2c0a..510a2ad 100644
--- a/libopie/colorpopupmenu.cpp
+++ b/libopie/colorpopupmenu.cpp
@@ -1,44 +1,55 @@
-/**********************************************************************
-** 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;
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