Add notes for API fixes and BC stuff

4 files changed, 24 insertions, 1 deletions

diff --git a/libopie/odevice.h b/libopie/odevice.h
index ee0b0ec..791d358 100644
--- a/libopie/odevice.h
+++ b/libopie/odevice.h
@@ -1,284 +1,286 @@
 /*  This file is part of the OPIE libraries
     Copyright (C) 2002 Robert Griebl (sandman@handhelds.org)
     Copyright (C) 2003 Holger 'zecke' Freyther (zecke@handhelds.org)
 
     This library is free software; you can redistribute it and/or
     modify it under the terms of the GNU Library General Public
     License as published by the Free Software Foundation; either
     version 2 of the License, or (at your option) any later version.
 
     This library is distributed in the hope that it will be useful,
     but WITHOUT ANY WARRANTY; without even the implied warranty of
     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
     Library General Public License for more details.
 
     You should have received a copy of the GNU Library General Public License
     along with this library; see the file COPYING.LIB.  If not, write to
     the Free Software Foundation, Inc., 59 Temple Place - Suite 330,
     Boston, MA 02111-1307, USA.
 */
 
 #ifndef _LIBOPIE_ODEVICE_H_
 #define _LIBOPIE_ODEVICE_H_
 
 #include <qobject.h>
 #include <qstring.h>
 #include <qnamespace.h>
 #include <qstrlist.h>
 
 #include <opie/odevicebutton.h>
 
 #include <qpe/qpeapplication.h> /* for Transformation enum.. */
 
 class ODeviceData;
 
 namespace Opie {
 
 /**
  * The available devices
  */
 enum OModel {
         Model_Unknown, // = 0
 
         Model_Series_Mask   = 0xff000000,
 
         Model_iPAQ          = ( 1 << 24 ),
 
         Model_iPAQ_All      = ( Model_iPAQ | 0xffffff ),
         Model_iPAQ_H31xx    = ( Model_iPAQ | 0x000001 ),
         Model_iPAQ_H36xx    = ( Model_iPAQ | 0x000002 ),
         Model_iPAQ_H37xx    = ( Model_iPAQ | 0x000004 ),
         Model_iPAQ_H38xx    = ( Model_iPAQ | 0x000008 ),
         Model_iPAQ_H39xx    = ( Model_iPAQ | 0x000010 ),
         Model_iPAQ_H5xxx    = ( Model_iPAQ | 0x000011 ),
 
         Model_Jornada       = ( 6 << 24 ),
         Model_Jornada_56x   = ( Model_Jornada | 0x000001 ),
 
         Model_Zaurus        = ( 2 << 24 ),
 
         Model_Zaurus_SL5000 = ( Model_Zaurus | 0x000001 ),
         Model_Zaurus_SL5500 = ( Model_Zaurus | 0x000002 ),
         Model_Zaurus_SLA300 = ( Model_Zaurus | 0x000003 ),
         Model_Zaurus_SLB600 = ( Model_Zaurus | 0x000004 ),
         Model_Zaurus_SLC7x0 = ( Model_Zaurus | 0x000005 ),
 
         Model_SIMpad        = ( 3 << 24 ),
 
         Model_SIMpad_All    = ( Model_SIMpad | 0xffffff ),
         Model_SIMpad_CL4    = ( Model_SIMpad | 0x000001 ),
         Model_SIMpad_SL4    = ( Model_SIMpad | 0x000002 ),
         Model_SIMpad_SLC    = ( Model_SIMpad | 0x000004 ),
         Model_SIMpad_TSinus = ( Model_SIMpad | 0x000008 ),
 
         Model_Ramses        = ( 4 << 24 ),
 
         Model_Ramses_All    = ( Model_Ramses | 0xffffff ),
         Model_Ramses_MNCI   = ( Model_Ramses | 0x000001 ),
 
         Model_Yopy          = ( 5 << 24 ),
 
         Model_Yopy_All      = ( Model_Yopy | 0xffffff ),
         Model_Yopy_3000     = ( Model_Yopy | 0x000001 ),
         Model_Yopy_3500     = ( Model_Yopy | 0x000002 ),
         Model_Yopy_3700     = ( Model_Yopy | 0x000003 ),
 
 };
 
 /**
  * The vendor of the device
  */
 enum OVendor {
         Vendor_Unknown,
 
         Vendor_HP,
         Vendor_Sharp,
         Vendor_SIEMENS,
         Vendor_MundN,
         Vendor_GMate,
 };
 
 /**
  * The System used
  */
 enum OSystem {
         System_Unknown,
 
         System_Familiar,
         System_Zaurus,
         System_OpenZaurus,
         System_Linupy,
 };
 
 enum OLedState {
         Led_Off,
         Led_On,
         Led_BlinkSlow,
         Led_BlinkFast
 };
 
 enum OLed {
         Led_Mail,
         Led_Power,
         Led_BlueTooth
 };
 
 enum OHardKey {
         HardKey_Datebook  = Qt::Key_F9,
         HardKey_Contacts  = Qt::Key_F10,
         HardKey_Menu      = Qt::Key_F11,
         HardKey_Home      = Qt::Key_F12,
         HardKey_Mail      = Qt::Key_F13,
         HardKey_Record    = Qt::Key_F24,
         HardKey_Suspend   = Qt::Key_F34,
         HardKey_Backlight = Qt::Key_F35,
         HardKey_Action    = Qt::Key_F10,
         HardKey_OK        = Qt::Key_F11,
         HardKey_End       = Qt::Key_F12,
 };
 
 enum ODirection {
         CW   = 0,
         CCW  = 1,
         Flip = 2,
 };
 
 enum OHingeStatus {
     CASE_CLOSED = 3,
     CASE_PORTRAIT = 2,
     CASE_LANDSCAPE = 0,
     CASE_UNKNOWN = 1,
 };
 
 /**
  * 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;
         OModel model ( ) const;
         inline OModel series ( ) const { return (OModel) ( model ( ) & Model_Series_Mask ); }
 
         QString vendorString ( ) const;
         OVendor vendor ( ) const;
 
         QString systemString ( ) const;
         OSystem system ( ) const;
 
         QString systemVersionString ( ) const;
 
         virtual Transformation rotation ( ) const;
         virtual ODirection direction ( ) const;
 
 // system
 
         virtual bool setSoftSuspend ( bool on );
         virtual bool suspend ( );
 
         virtual bool setDisplayStatus ( bool on );
         virtual bool setDisplayBrightness ( int brightness );
         virtual int displayBrightnessResolution ( ) const;
         virtual bool setDisplayContrast ( int contrast );
         virtual int displayContrastResolution ( ) const;
 
         // don't add new virtual methods, use this:
                 ///*virtual */ void boo(int i ) { return virtual_hook(1,&i); };
         // and in your subclass do do overwrite
                 //protected virtual int virtual_hook(int, void *)
         // which is defined below
 
     // input / output
     //FIXME playAlarmSound and al might be better -zecke
         virtual void alarmSound ( );
         virtual void keySound ( );
         virtual void touchSound ( );
 
         virtual QValueList <OLed> ledList ( ) const;
         virtual QValueList <OLedState> ledStateList ( OLed led ) const;
         virtual OLedState ledState ( OLed led ) const;
         virtual bool setLedState ( OLed led, OLedState st );
 
         virtual bool hasLightSensor ( ) const;
         virtual int readLightSensor ( );
         virtual int lightSensorResolution ( ) const;
 
         virtual bool hasHingeSensor ( ) const;
         virtual OHingeStatus readHingeSensor ( );
 
         const QStrList &allowedCpuFrequencies() const;
         bool setCurrentCpuFrequency(uint index);
 
         /**
          * Returns the available buttons on this device.  The number and location
          * of buttons will vary depending on the device.  Button numbers will be assigned
          * by the device manufacturer and will be from most preferred button to least preffered
          * button.  Note that this list only contains "user mappable" buttons.
+         *
+         * @todo ### make const
          */
-       const QValueList<ODeviceButton> &buttons ( ) /* ### make const */;
+       const QValueList<ODeviceButton> &buttons ( ) /** /todo ### make const */;
 
         /**
          * Returns the DeviceButton for the \a keyCode.  If \a keyCode is not found, it
          * returns 0L
          */
         const ODeviceButton *buttonForKeycode ( ushort keyCode );
 
         /**
          * Reassigns the pressed action for \a button.  To return to the factory
          * default pass an empty string as \a qcopMessage.
          */
         void remapPressedAction ( int button, const OQCopMessage &qcopMessage );
 
         /**
          * Reassigns the held action for \a button.  To return to the factory
          * default pass an empty string as \a qcopMessage.
          */
         void remapHeldAction ( int button, const OQCopMessage &qcopMessage );
 
         /**
          * How long (in ms) you have to press a button for a "hold" action
          */
         uint buttonHoldTime ( ) const;
 
 signals:
         void buttonMappingChanged ( );
 
 private slots:
         void systemMessage ( const QCString &, const QByteArray & );
 
 protected:
         void reloadButtonMapping ( );
         /*  ugly virtual hook */
         virtual void virtual_hook( int id, void* data );
 };
 
 }
 
 #endif
 
diff --git a/libopie/otimepicker.h b/libopie/otimepicker.h
index 6a9e040..8df7d10 100644
--- a/libopie/otimepicker.h
+++ b/libopie/otimepicker.h
@@ -1,83 +1,86 @@
 #ifndef OTIMEPICKER_H
 #define OTIMEPICKER_H
 
 #include <qwidget.h>
 #include <qvaluelist.h>
 #include <qdatetime.h>
 #include <qdialog.h>
 
 #include <opie/oclickablelabel.h>
 #include "otimepickerbase.h"
 
 /**
  * A class to pick time. It uses clickable labels
  * internally to allow a quick selection of a time.
  * A time can be selected by two clicks of a user
  *
  * @short A widget to quickly pick a QTime
  * @version 1.0
  * @see QWidget
  * @see QTime
  * @author Hakan Ardo, Stefan Eilers
  */
 class OTimePicker: public QWidget {
   Q_OBJECT
 
  public:
     OTimePicker(QWidget* parent = 0, const char* name = 0,
                WFlags fl = 0);
 
  public slots:
     void setHour(int h);
     void setMinute(int m);
     void setTime( const QTime& );
     void setTime( int h,  int m );
 
  public:
     QTime time()const;
 
  private:
     QValueList<OClickableLabel *> hourLst;
     QValueList<OClickableLabel *> minuteLst;
     QTime tm;
     struct Private;
     Private *d;
 
  private slots:
     void slotHour(bool b);
     void slotMinute(bool b);
 
  signals:
     /**
      * gets emitted when the time got changed by the user
      */
     void timeChanged(const QTime &);
 };
 
 /**
  *
  * @short A small dialog to pick a time
  * @version 1.0
  * @author Stefan Eilers
  */
 
 class OTimePickerDialog: public OTimePickerDialogBase {
   Q_OBJECT
 
  public:
         OTimePickerDialog ( QWidget* parent = 0, const char* name = NULL, WFlags fl = 0 );
+        /**
+         * @todo make it non line! See KDE guide for BC
+         */
         ~OTimePickerDialog() { };
 
         QTime time()const;
 
  public slots:
         void setTime( const QTime& time );
         void setHour( const QString& hour );
         void setMinute( const QString& minute );
 
  private:
         QTime m_time;
         class Private;
         Private* d;
 };
 #endif
diff --git a/libopie/pim/ocontactaccessbackend.h b/libopie/pim/ocontactaccessbackend.h
index 280e05c..0eac6dc 100644
--- a/libopie/pim/ocontactaccessbackend.h
+++ b/libopie/pim/ocontactaccessbackend.h
@@ -1,119 +1,128 @@
 /**
  * The class responsible for managing a backend.
  * The implementation of this abstract class contains
  * the complete database handling.
  *
  * Copyright (c) 2002 by Stefan Eilers (Eilers.Stefan@epost.de)
  * Copyright (c) 2002 by Holger Freyther (zecke@handhelds.org)
  *
  * =====================================================================
          *This program 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.
  * =====================================================================
  * ToDo: Define enum for query settings
  * =====================================================================
  * Version: $Id$
  * =====================================================================
  * History:
  * $Log$
+ * Revision 1.7  2004/02/19 02:05:37  zecke
+ * Add notes for API fixes and BC stuff
+ *
  * Revision 1.6  2003/08/01 12:30:16  eilers
  * Merging changes from BRANCH_1_0 to HEAD
  *
  * Revision 1.5.4.1  2003/06/30 14:34:19  eilers
  * Patches from Zecke:
  * Fixing and cleaning up extraMap handling
  * Adding d_ptr for binary compatibility in the future
  *
  * Revision 1.5  2003/04/13 18:07:10  zecke
  * More API doc
  * QString -> const QString&
  * QString = 0l -> QString::null
  *
  * Revision 1.4  2002/11/13 14:14:51  eilers
  * Added sorted for Contacts..
  *
  * Revision 1.3  2002/11/01 15:10:42  eilers
  * Added regExp-search in database for all fields in a contact.
  *
  * Revision 1.2  2002/10/07 17:34:24  eilers
  * added OBackendFactory for advanced backend access
  *
  * Revision 1.1  2002/09/27 17:11:44  eilers
  * Added API for accessing the Contact-Database ! It is compiling, but
  * please do not expect that anything is working !
  * I will debug that stuff in the next time ..
  * Please read README_COMPILE for compiling !
  *
  * =====================================================================
  *
  */
 
 #ifndef _OCONTACTACCESSBACKEND_H_
 #define _OCONTACTACCESSBACKEND_H_
 
 #include "ocontact.h"
 #include "opimaccessbackend.h"
 
 #include <qregexp.h>
 
 /**
  * This class represents the interface of all Contact Backends.
  * Derivates of this class will be used to access the contacts.
  * As implementation currently XML and vCard exist. This class needs to be implemented
  * if you want to provide your own storage.
  * In all queries a list of uids is passed on instead of loading the actual record!
  *
  * @see OContactAccessBackend_VCard
  * @see OContactAccessBackend_XML
  */
 class OContactAccessBackend: public OPimAccessBackend<OContact> {
  public:
+        /**
+         * @todo make non line in regard to BC guide of KDE
+         */
         OContactAccessBackend() {}
+        /**
+         * @todo make non inline in regard to the BC guide of KDE
+         */
         virtual ~OContactAccessBackend() {}
 
 
         /**
          * Return if database was changed externally.
          * This may just make sense on file based databases like a XML-File.
          * It is used to prevent to overwrite the current database content
          * if the file was already changed by something else !
          * If this happens, we have to reload before save our data.
          * If we use real databases, this should be handled by the database
          * management system themselve, therefore this function should always return false in
          * this case. It is not our problem to handle this conflict ...
          * @return <i>true</i> if the database was changed and if save without reload will
          * be dangerous. <i>false</i> if the database was not changed or it is save to write
          * in this situation.
          */
         virtual bool wasChangedExternally() = 0;
 
         virtual QArray<int> matchRegexp(  const QRegExp &r ) const = 0;
 
         /**
          *  Return all possible settings.
          *  @return All settings provided by the current backend
          * (i.e.: query_WildCards & query_IgnoreCase)
          */
         virtual const uint querySettings() = 0;
 
         /**
          * Check whether settings are correct.
          * @return <i>true</i> if the given settings are correct and possible.
          */
         virtual bool hasQuerySettings (uint querySettings) const = 0;
 
         /**
          * FIXME!!!
          * Returns a sorted list of records either ascendinf or descending for a giving criteria and category
          */
         virtual QArray<int> sorted( bool ascending, int sortOrder, int sortFilter, int cat ) = 0;
         
         
 private:
         class Private;
         Private *d;
 };
 #endif
diff --git a/libopie2/opiepim/backend/ocontactaccessbackend.h b/libopie2/opiepim/backend/ocontactaccessbackend.h
index 280e05c..0eac6dc 100644
--- a/libopie2/opiepim/backend/ocontactaccessbackend.h
+++ b/libopie2/opiepim/backend/ocontactaccessbackend.h
@@ -1,119 +1,128 @@
 /**
  * The class responsible for managing a backend.
  * The implementation of this abstract class contains
  * the complete database handling.
  *
  * Copyright (c) 2002 by Stefan Eilers (Eilers.Stefan@epost.de)
  * Copyright (c) 2002 by Holger Freyther (zecke@handhelds.org)
  *
  * =====================================================================
          *This program 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.
  * =====================================================================
  * ToDo: Define enum for query settings
  * =====================================================================
  * Version: $Id$
  * =====================================================================
  * History:
  * $Log$
+ * Revision 1.7  2004/02/19 02:05:37  zecke
+ * Add notes for API fixes and BC stuff
+ *
  * Revision 1.6  2003/08/01 12:30:16  eilers
  * Merging changes from BRANCH_1_0 to HEAD
  *
  * Revision 1.5.4.1  2003/06/30 14:34:19  eilers
  * Patches from Zecke:
  * Fixing and cleaning up extraMap handling
  * Adding d_ptr for binary compatibility in the future
  *
  * Revision 1.5  2003/04/13 18:07:10  zecke
  * More API doc
  * QString -> const QString&
  * QString = 0l -> QString::null
  *
  * Revision 1.4  2002/11/13 14:14:51  eilers
  * Added sorted for Contacts..
  *
  * Revision 1.3  2002/11/01 15:10:42  eilers
  * Added regExp-search in database for all fields in a contact.
  *
  * Revision 1.2  2002/10/07 17:34:24  eilers
  * added OBackendFactory for advanced backend access
  *
  * Revision 1.1  2002/09/27 17:11:44  eilers
  * Added API for accessing the Contact-Database ! It is compiling, but
  * please do not expect that anything is working !
  * I will debug that stuff in the next time ..
  * Please read README_COMPILE for compiling !
  *
  * =====================================================================
  *
  */
 
 #ifndef _OCONTACTACCESSBACKEND_H_
 #define _OCONTACTACCESSBACKEND_H_
 
 #include "ocontact.h"
 #include "opimaccessbackend.h"
 
 #include <qregexp.h>
 
 /**
  * This class represents the interface of all Contact Backends.
  * Derivates of this class will be used to access the contacts.
  * As implementation currently XML and vCard exist. This class needs to be implemented
  * if you want to provide your own storage.
  * In all queries a list of uids is passed on instead of loading the actual record!
  *
  * @see OContactAccessBackend_VCard
  * @see OContactAccessBackend_XML
  */
 class OContactAccessBackend: public OPimAccessBackend<OContact> {
  public:
+        /**
+         * @todo make non line in regard to BC guide of KDE
+         */
         OContactAccessBackend() {}
+        /**
+         * @todo make non inline in regard to the BC guide of KDE
+         */
         virtual ~OContactAccessBackend() {}
 
 
         /**
          * Return if database was changed externally.
          * This may just make sense on file based databases like a XML-File.
          * It is used to prevent to overwrite the current database content
          * if the file was already changed by something else !
          * If this happens, we have to reload before save our data.
          * If we use real databases, this should be handled by the database
          * management system themselve, therefore this function should always return false in
          * this case. It is not our problem to handle this conflict ...
          * @return <i>true</i> if the database was changed and if save without reload will
          * be dangerous. <i>false</i> if the database was not changed or it is save to write
          * in this situation.
          */
         virtual bool wasChangedExternally() = 0;
 
         virtual QArray<int> matchRegexp(  const QRegExp &r ) const = 0;
 
         /**
          *  Return all possible settings.
          *  @return All settings provided by the current backend
          * (i.e.: query_WildCards & query_IgnoreCase)
          */
         virtual const uint querySettings() = 0;
 
         /**
          * Check whether settings are correct.
          * @return <i>true</i> if the given settings are correct and possible.
          */
         virtual bool hasQuerySettings (uint querySettings) const = 0;
 
         /**
          * FIXME!!!
          * Returns a sorted list of records either ascendinf or descending for a giving criteria and category
          */
         virtual QArray<int> sorted( bool ascending, int sortOrder, int sortFilter, int cat ) = 0;
         
         
 private:
         class Private;
         Private *d;
 };
 #endif