From 0b311079ff19798866291034663757103c6ba935 Mon Sep 17 00:00:00 2001 From: zecke Date: Sun, 13 Apr 2003 16:57:28 +0000 Subject: 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 --- diff --git a/libopie/colordialog.cpp b/libopie/colordialog.cpp index 684d6ea..35f15d6 100644 --- a/libopie/colordialog.cpp +++ b/libopie/colordialog.cpp @@ -57,6 +57,11 @@ static inline void rgb2hsv( QRgb rgb, int&h, int&s, int&v ) c.getHsv(h,s,v); } +/* + * avoid clashes with the original Qt + */ +namespace { + class QColorPicker : public QFrame { Q_OBJECT @@ -607,13 +612,15 @@ void QColorShower::setHsv( int h, int s, int v ) 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 ); } @@ -637,7 +644,7 @@ void OColorDialogPrivate::newHsv( int h, int s, int v ) } //sets all widgets to display rgb -void OColorDialogPrivate::setCurrentColor( QRgb rgb ) +void OColorDialogPrivate::setCurrentColor( const QRgb& rgb ) { cs->setRgb( rgb ); newColorTypedIn( rgb ); @@ -726,7 +733,7 @@ OColorDialog::OColorDialog(QWidget* parent, const char* name, bool modal) : 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(); @@ -763,7 +770,7 @@ QColor OColorDialog::getColor( QColor initial, QWidget *parent, 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(); @@ -819,7 +826,7 @@ OColorDialog::~OColorDialog() \sa color() */ -void OColorDialog::setColor( QColor c ) +void OColorDialog::setColor( const QColor& c ) { d->setCurrentColor( c.rgb() ); } diff --git a/libopie/colordialog.h b/libopie/colordialog.h index 926f8f2..e9bb7ed 100644 --- a/libopie/colordialog.h +++ b/libopie/colordialog.h @@ -61,15 +61,15 @@ 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: diff --git a/libopie/colorpopupmenu.cpp b/libopie/colorpopupmenu.cpp index 510a2ad..dac10e9 100644 --- a/libopie/colorpopupmenu.cpp +++ b/libopie/colorpopupmenu.cpp @@ -37,7 +37,7 @@ #include #include -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; @@ -46,11 +46,11 @@ ColorPanelButton::ColorPanelButton( const QColor& color, QWidget* parent, const setActive( FALSE ); } -ColorPanelButton::~ColorPanelButton() +OColorPanelButton::~OColorPanelButton() { } -void ColorPanelButton::setActive( bool active ) +void OColorPanelButton::setActive( bool active ) { m_active = active; @@ -61,25 +61,21 @@ void ColorPanelButton::setActive( bool active ) } } -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 ); @@ -91,14 +87,12 @@ void ColorPanelButton::paintEvent( QPaintEvent* e ) 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; @@ -149,25 +143,25 @@ ColorPopupMenu::ColorPopupMenu( const QColor& color, QWidget* parent, const char 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; diff --git a/libopie/colorpopupmenu.h b/libopie/colorpopupmenu.h index b0453b2..184b132 100644 --- a/libopie/colorpopupmenu.h +++ b/libopie/colorpopupmenu.h @@ -40,23 +40,23 @@ 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. @@ -65,13 +65,13 @@ public: * * 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 ) @@ -150,11 +150,11 @@ private: }; /** - * @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. * @@ -162,29 +162,29 @@ private: * 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; diff --git a/libopie/ocheckitem.cpp b/libopie/ocheckitem.cpp index d6ddc79..082d7a2 100644 --- a/libopie/ocheckitem.cpp +++ b/libopie/ocheckitem.cpp @@ -14,32 +14,63 @@ #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 ) { diff --git a/libopie/ocheckitem.h b/libopie/ocheckitem.h index 7885032..2387134 100644 --- a/libopie/ocheckitem.h +++ b/libopie/ocheckitem.h @@ -3,7 +3,7 @@ ** ** 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 @@ -14,6 +14,18 @@ #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: diff --git a/libopie/oclickablelabel.cpp b/libopie/oclickablelabel.cpp index 5768529..bc7037b 100644 --- a/libopie/oclickablelabel.cpp +++ b/libopie/oclickablelabel.cpp @@ -1,8 +1,15 @@ #include "oclickablelabel.h" #include -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) { @@ -13,10 +20,18 @@ OClickableLabel::OClickableLabel(QWidget* parent, 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); @@ -25,6 +40,9 @@ void OClickableLabel::mousePressEvent( QMouseEvent * /*e*/ ) { } } +/** + * @internal + */ void OClickableLabel::mouseReleaseEvent( QMouseEvent *e ) { if (rect().contains(e->pos()) && isToggle) isDown=!isDown; @@ -42,6 +60,9 @@ void OClickableLabel::mouseReleaseEvent( QMouseEvent *e ) { } } +/** + * @internal + */ void OClickableLabel::mouseMoveEvent( QMouseEvent *e ) { if (rect().contains(e->pos())) { if (isToggle && isDown) { @@ -58,6 +79,11 @@ void OClickableLabel::mouseMoveEvent( QMouseEvent *e ) { } } +/** + * this toggles the label and inverts the color of + * the label + * @param on + */ void OClickableLabel::showState(bool on) { if (on) { //setFrameShape(Panel); @@ -82,6 +108,9 @@ void OClickableLabel::setInverted(bool on) { } } +/** + * @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,29 +1,52 @@ #ifndef CLICKABLELABEL #define CLICKABLELABEL -#include +#include -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 + * + * 
+ *  QLabel* lbl = new OClickableLabel( parent, "PushLabel" );
+ *  lbl->setPixmap( "config" );
+ *  QWhatsThis::add( lbl, tr("Click here to do something") );
+ *
+ * + * @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); }; diff --git a/libopie/ocolorbutton.cpp b/libopie/ocolorbutton.cpp index ddb6c4f..113a77a 100644 --- a/libopie/ocolorbutton.cpp +++ b/libopie/ocolorbutton.cpp @@ -34,18 +34,26 @@ #include -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 & ))); @@ -57,37 +65,50 @@ OColorButton::OColorButton ( QWidget *parent, const QColor &color, const char *n 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; @@ -100,7 +121,7 @@ void OColorButton::updateColor ( const QColor &c ) 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; @@ -114,7 +135,7 @@ void OColorButton::updateColor ( const QColor &c ) 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 @@ -34,6 +34,13 @@ 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: @@ -47,13 +54,13 @@ signals: 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 @@ -53,7 +53,7 @@ using namespace Opie; class ODeviceData { public: - bool m_qwsserver; + bool m_qwsserver : 1; QString m_vendorstr; OVendor m_vendor; @@ -270,6 +270,9 @@ void ODevice::init ( ) { } +/** + * This method initialises the button mapping + */ void ODevice::initButtons ( ) { if ( d-> m_buttons ) @@ -313,7 +316,17 @@ bool ODevice::setSoftSuspend ( bool /*soft*/ ) #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 @@ -354,7 +367,9 @@ bool ODevice::suspend ( ) #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 ) @@ -370,8 +385,13 @@ bool ODevice::setDisplayStatus ( bool on ) 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; } @@ -380,46 +400,76 @@ 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 @@ -430,6 +480,9 @@ void ODevice::alarmSound ( ) #endif } +/** + * This plays a key sound + */ void ODevice::keySound ( ) { #ifndef QT_NO_SOUND @@ -440,6 +493,9 @@ void ODevice::keySound ( ) #endif } +/** + * This plays a touch sound + */ void ODevice::touchSound ( ) { @@ -451,42 +507,72 @@ void ODevice::touchSound ( ) #endif } - +/** + * This method will return a list of leds + * available on this device + * @return a list of LEDs. + */ QValueList ODevice::ledList ( ) const { return QValueList ( ); } +/** + * This does return the state of the LEDs + */ QValueList ODevice::ledStateList ( OLed /*which*/ ) const { return QValueList ( ); } +/** + * @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 &ODevice::buttons ( ) { initButtons ( ); @@ -494,11 +580,21 @@ const QValueList &ODevice::buttons ( ) 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 ( ); diff --git a/libopie/odevice.h b/libopie/odevice.h index ff578d8..45a790b 100644 --- a/libopie/odevice.h +++ b/libopie/odevice.h @@ -1,16 +1,16 @@ /* 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, @@ -32,9 +32,12 @@ class ODeviceData; namespace Opie { +/** + * The available devices + */ enum OModel { - Model_Unknown, - + Model_Unknown, // = 0 + Model_Series_Mask = 0xff000000, Model_iPAQ = ( 1 << 24 ), @@ -55,13 +58,19 @@ enum OModel { 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, @@ -94,30 +103,44 @@ enum OHardKey { 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; @@ -128,7 +151,7 @@ public: Transformation rotation ( ) const; -// system +// system virtual bool setSoftSuspend ( bool on ); virtual bool suspend ( ); @@ -136,9 +159,9 @@ public: 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 ( ); @@ -159,7 +182,7 @@ public: * button. Note that this list only contains "user mappable" buttons. */ const QValueList &buttons ( ); - + /** * Returns the DeviceButton for the \a keyCode. If \a keyCode is not found, it * returns 0L @@ -175,7 +198,7 @@ public: /** * 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 ); /** @@ -183,12 +206,12 @@ public: */ uint buttonHoldTime ( ) const; -signals: +signals: void buttonMappingChanged ( ); - -private slots: + +private slots: void systemMessage ( const QCString &, const QByteArray & ); - + protected: void reloadButtonMapping ( ); }; diff --git a/libopie/odevicebutton.h b/libopie/odevicebutton.h index 5281ab2..cf91bbd 100644 --- a/libopie/odevicebutton.h +++ b/libopie/odevicebutton.h @@ -58,6 +58,10 @@ private: * 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 diff --git a/libopie/ofiledialog.cc b/libopie/ofiledialog.cc index 4783004..9e725c2 100644 --- a/libopie/ofiledialog.cc +++ b/libopie/ofiledialog.cc @@ -33,6 +33,17 @@ #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, @@ -60,18 +71,42 @@ OFileDialog::OFileDialog(const QString &caption, 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, @@ -88,6 +123,11 @@ QString OFileDialog::getOpenFileName(int selector, return ret; } + +/** + * This opens up a file dialog in save mode + * @see getOpenFileName + */ QString OFileDialog::getSaveFileName(int selector, const QString &startDir, const QString &file, diff --git a/libopie/ofiledialog.h b/libopie/ofiledialog.h index e14253c..309086b 100644 --- a/libopie/ofiledialog.h +++ b/libopie/ofiledialog.h @@ -34,6 +34,29 @@ #include +/** + * 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. + * + * 
+ * QMap 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);
+ *
+ * + * @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: diff --git a/libopie/ofileselector.h b/libopie/ofileselector.h index 17c494e..06ac806 100644 --- a/libopie/ofileselector.h +++ b/libopie/ofileselector.h @@ -121,6 +121,8 @@ class OFileSelector : public QWidget { ~OFileSelector(); // currently only for the FILESELECTOR Mode + /** + */ void setNewVisible( bool /*b*/ ); void setCloseVisible(bool /*b*/ ); diff --git a/libopie/ofontmenu.cc b/libopie/ofontmenu.cc index 52ff3ee..d16c5e5 100644 --- a/libopie/ofontmenu.cc +++ b/libopie/ofontmenu.cc @@ -4,7 +4,13 @@ #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 &list ) : QPopupMenu( parent, name ) { @@ -20,11 +26,24 @@ OFontMenu::OFontMenu(QWidget *parent, const char *name, const QList &li 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" ); @@ -47,22 +66,47 @@ void OFontMenu::restore(Config *cfg ) } setFontSize( m_size ); } + +/** + * set the list of widgets + * @param list the widget list + */ void OFontMenu::setWidgets(const QList &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 &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; diff --git a/libopie/ofontmenu.h b/libopie/ofontmenu.h index 5fd515f..6e143ca 100644 --- a/libopie/ofontmenu.h +++ b/libopie/ofontmenu.h @@ -4,24 +4,24 @@                =. This file is part of the OPIE Project              .=l. Copyright (c) 2002 zecke            .>+-= - _;:,     .>    :=|. 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_,=:_.      -       _;_. +    .i_,=:_.      -`: 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. @@ -37,7 +37,9 @@ #include #include - +/* + * @internal + */ namespace { struct WidSize { QWidget *wid; @@ -46,8 +48,30 @@ namespace { }; -// 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 + * + * 
+ * QTable* tbl = new QTable();
+ * QList wid;
+ * wid.append( tbl );
+ * OFontMenu* menu = new OFontMenu(this, "Popup Menu", wid );
+ * Config cfg("mycfg");
+ * menu->restore( cfg );
+ *
+ * + * @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: @@ -61,13 +85,19 @@ class OFontMenu : public QPopupMenu { const QList &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 m_list; QList m_wids; int m_size; class OFontMenuPrivate; OFontMenuPrivate *d; + private slots: virtual void slotSmall(); virtual void slotMedium(); diff --git a/libopie/ofontselector.cpp b/libopie/ofontselector.cpp index b905474..c8471cc 100644 --- a/libopie/ofontselector.cpp +++ b/libopie/ofontselector.cpp @@ -38,17 +38,18 @@ #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: @@ -57,7 +58,7 @@ public: m_name = t; m_styles = styles; m_sizes = sizes; - + QString str = t; str [0] = str [0]. upper ( ); setText ( str ); @@ -67,17 +68,17 @@ public: { return m_name; } - + const QStringList &styles ( ) const { return m_styles; } - + const QValueList &sizes ( ) const { return m_sizes; } - + private: QStringList m_styles; QValueList m_sizes; @@ -94,7 +95,8 @@ static int findItemCB ( QComboBox *box, const QString &str ) return -1; } - +} +/* static same as anon. namespace */ static int qt_version ( ) { const char *qver = qVersion ( ); @@ -102,7 +104,13 @@ static int qt_version ( ) 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 ( ); @@ -135,7 +143,7 @@ OFontSelector::OFontSelector ( bool withpreview, QWidget *parent, const char *na 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 ); @@ -152,12 +160,25 @@ 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 ); @@ -166,7 +187,7 @@ bool OFontSelector::setSelectedFont ( const QString &familyStr, const QString &s 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 ); @@ -184,10 +205,18 @@ bool OFontSelector::setSelectedFont ( const QString &familyStr, const QString &s 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; @@ -195,29 +224,44 @@ bool OFontSelector::selectedFont ( QString &family, QString &style, int &size ) } +/** + * 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 ( )); @@ -225,14 +269,18 @@ QString OFontSelector::fontCharSet ( ) const 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; @@ -246,20 +294,20 @@ bool OFontSelector::selectedFont ( QString &family, QString &style, int &size, Q } - + void OFontSelector::loadFonts ( QListBox *list ) { QStringList f = d-> m_fdb. families ( ); - + for ( QStringList::ConstIterator it = f. begin ( ); it != f. end ( ); ++it ) { QValueList ps = d-> m_fdb. pointSizes ( *it ); - + if ( d-> m_pointbug ) { for ( QValueList ::Iterator it = ps. begin ( ); it != ps. end ( ); it++ ) *it /= 10; } - + list-> insertItem ( new FontListItem ( *it, d-> m_fdb. styles ( *it ), ps )); } } @@ -268,30 +316,30 @@ 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 sl = fli-> sizes ( ); - - for ( QValueList::Iterator it = sl. begin ( ); it != sl. end ( ); ++it ) + + for ( QValueList::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 ); @@ -299,17 +347,17 @@ void OFontSelector::fontFamilyClicked ( int index ) 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*/ ) @@ -327,15 +375,17 @@ void OFontSelector::changeFont ( ) 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, \ @@ -355,8 +405,8 @@ void OFontSelector::resizeEvent ( QResizeEvent *re ) } 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 @@ -26,15 +26,25 @@ */ -#ifndef __OPIE_FONTSELECTOR_H__ -#define __OPIE_FONTSELECTOR_H__ +#ifndef OPIE_FONTSELECTOR_H__ +#define OPIE_FONTSELECTOR_H__ #include 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 @@ -45,7 +55,7 @@ public: bool selectedFont ( QString &family, QString &style, int &size ); bool selectedFont ( QString &family, QString &style, int &size, QString &charset ); - + QFont selectedFont ( ); bool setSelectedFont ( const QFont & ); @@ -57,6 +67,9 @@ public: QString fontCharSet ( ) const; signals: + /** + * This signal gets emitted when a font got chosen + */ void fontSelected ( const QFont & ); protected slots: @@ -71,7 +84,7 @@ private: void loadFonts ( QListBox * ); void changeFont ( ); - + private: OFontSelectorPrivate *d; }; diff --git a/libopie/orecurrancewidget.cpp b/libopie/orecurrancewidget.cpp index db86184..471249d 100644 --- a/libopie/orecurrancewidget.cpp +++ b/libopie/orecurrancewidget.cpp @@ -26,7 +26,15 @@ 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, @@ -43,6 +51,17 @@ ORecurranceWidget::ORecurranceWidget( bool startOnMonday, 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, @@ -59,13 +78,28 @@ ORecurranceWidget::ORecurranceWidget( bool startOnMonday, 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(); @@ -123,6 +157,11 @@ void ORecurranceWidget::setRecurrence( const ORecur& rp, const QDate& date ) { } else cmdEnd->setText( TimeString::shortDate( end ) ); } + +/** + * the user selected recurrence rule. + * @return The recurrence rule. + */ ORecur ORecurranceWidget::recurrence()const { QListIterator it( listRTypeButtons ); QListIterator itExtra( listExtra ); @@ -180,6 +219,11 @@ ORecur ORecurranceWidget::recurrence()const { // 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; } diff --git a/libopie/orecurrancewidget.h b/libopie/orecurrancewidget.h index 4a8dd08..af87ce9 100644 --- a/libopie/orecurrancewidget.h +++ b/libopie/orecurrancewidget.h @@ -17,6 +17,18 @@ #include // 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: diff --git a/libopie/otabbar.h b/libopie/otabbar.h index 16797a3..c413611 100644 --- a/libopie/otabbar.h +++ b/libopie/otabbar.h @@ -57,6 +57,7 @@ public: * * Constructs a new OTabBar control with parent and name. */ + // FIXME Allow WFlags? -zecke OTabBar( QWidget * = 0, const char * = 0 ); protected: diff --git a/libopie/otabwidget.h b/libopie/otabwidget.h index 0aa9bb8..23fe774 100644 --- a/libopie/otabwidget.h +++ b/libopie/otabwidget.h @@ -99,6 +99,7 @@ public: * 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 ); /** @@ -197,6 +198,7 @@ public: * @fn getCurrentTab( ) * @brief returns current tab id. */ + //FIXME TT coding style currentTab() -zecke int getCurrentTab(); diff --git a/libopie/oticker.h b/libopie/oticker.h index 5df08da..30b7517 100644 --- a/libopie/oticker.h +++ b/libopie/oticker.h @@ -40,13 +40,13 @@ #include #include #include -/*! + +/** * @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: @@ -92,7 +92,7 @@ public: * @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 @@ -106,7 +106,7 @@ public: * @param length int scroll length. * */ - void setScrollLength(int length); + void setScrollLength(int length); signals: /*! * @fn mousePressed() diff --git a/libopie/otimepicker.cpp b/libopie/otimepicker.cpp index 8e8a4e7..115d39b 100644 --- a/libopie/otimepicker.cpp +++ b/libopie/otimepicker.cpp @@ -7,10 +7,18 @@ #include #include -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; @@ -20,8 +28,8 @@ OTimePicker::OTimePicker(QWidget* parent, const char* name, 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); @@ -44,7 +52,7 @@ OTimePicker::OTimePicker(QWidget* parent, const char* name, 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); @@ -58,6 +66,14 @@ OTimePicker::OTimePicker(QWidget* parent, const char* name, } } +/** + * This method return the current time + * @return the time + */ +QTime OTimePicker::time()const { + return tm; +} + void OTimePicker::slotHour(bool b) { OClickableLabel *r = (OClickableLabel *) sender(); @@ -92,6 +108,32 @@ void OTimePicker::slotMinute(bool b) { } +/** + * 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; @@ -101,11 +143,14 @@ void OTimePicker::setMinute(int m) { 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; @@ -115,11 +160,18 @@ void OTimePicker::setHour(int h) { 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) { @@ -133,10 +185,18 @@ OTimePickerDialog::OTimePickerDialog ( QWidget* parent, const char* name, WFlags } -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; @@ -154,9 +214,14 @@ void OTimePickerDialog::setTime( const QTime& time ) 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 ) ){ @@ -166,6 +231,11 @@ void OTimePickerDialog::setHour ( const QString& hour ) } +/** + * 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 ) ){ diff --git a/libopie/otimepicker.h b/libopie/otimepicker.h index 825e2d6..495c806 100644 --- a/libopie/otimepicker.h +++ b/libopie/otimepicker.h @@ -9,28 +9,58 @@ #include #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 hourLst; QValueList 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 @@ -38,7 +68,7 @@ class OTimePickerDialog: public OTimePickerDialogBase { OTimePickerDialog ( QWidget* parent = 0, const char* name = NULL, WFlags fl = 0 ); ~OTimePickerDialog() { }; - QTime& time(); + QTime time()const; public slots: void setTime( const QTime& time ); diff --git a/libopie/owait.cpp b/libopie/owait.cpp index c90bb72..0fdf08d 100644 --- a/libopie/owait.cpp +++ b/libopie/owait.cpp @@ -29,8 +29,18 @@ 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 ); diff --git a/libopie/owait.h b/libopie/owait.h index d22e141..6217e31 100644 --- a/libopie/owait.h +++ b/libopie/owait.h @@ -29,15 +29,19 @@ /** * 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 */ @@ -45,9 +49,10 @@ public: /** * 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: /** @@ -57,7 +62,7 @@ public: private: void timerEvent( QTimerEvent * ) ; - void paintEvent( QPaintEvent * ); + void paintEvent( QPaintEvent * ); QPixmap m_pix; QLabel *m_lb; diff --git a/libopie/todayconfigwidget.h b/libopie/todayconfigwidget.h index 48cf379..6b49efc 100644 --- a/libopie/todayconfigwidget.h +++ b/libopie/todayconfigwidget.h @@ -3,11 +3,29 @@ #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() {}; diff --git a/libopie/todayplugininterface.h b/libopie/todayplugininterface.h index 6ee2a06..29a12bc 100644 --- a/libopie/todayplugininterface.h +++ b/libopie/todayplugininterface.h @@ -14,7 +14,12 @@ class QWidget; /** * + * 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 { @@ -25,21 +30,28 @@ public: /** * 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 @@ -49,11 +61,14 @@ public: /** * 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; @@ -81,7 +96,9 @@ public: }; - +/** + * This is part of the QCOM works. See example plugins how to do it right + */ struct TodayPluginInterface : public QUnknownInterface { virtual TodayPluginObject *guiPart() = 0; }; -- cgit v0.9.0.2