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

1 files changed, 102 insertions, 6 deletions

diff --git a/libopie/odevice.cpp b/libopie/odevice.cpp
index 9b2a954..8f954b1 100644
--- a/libopie/odevice.cpp
+++ b/libopie/odevice.cpp
@@ -44,25 +44,25 @@
 
 #define OD_IOC(dir,type,number,size)    (( dir << 30 ) | ( type << 8 ) | ( number ) | ( size << 16 ))
 
 #define OD_IO(type,number)              OD_IOC(0,type,number,0)
 #define OD_IOW(type,number,size)        OD_IOC(1,type,number,sizeof(size))
 #define OD_IOR(type,number,size)        OD_IOC(2,type,number,sizeof(size))
 #define OD_IORW(type,number,size)       OD_IOC(3,type,number,sizeof(size))
 
 using namespace Opie;
 
 class ODeviceData {
 public:
-        bool m_qwsserver;
+        bool m_qwsserver : 1;
 
         QString m_vendorstr;
         OVendor m_vendor;
 
         QString m_modelstr;
         OModel m_model;
 
         QString m_systemstr;
         OSystem m_system;
 
         QString m_sysverstr;
 
@@ -261,24 +261,27 @@ ODevice::ODevice ( )
 
 void ODevice::systemMessage ( const QCString &msg, const QByteArray & )
 {
         if ( msg == "deviceButtonMappingChanged()" ) {
                 reloadButtonMapping ( );
         }
 }
 
 void ODevice::init ( )
 {
 }
 
+/**
+ * This method initialises the  button mapping
+ */
 void ODevice::initButtons ( )
 {
         if ( d-> m_buttons )
                 return;
 
         // Simulation uses iPAQ 3660 device buttons
 
         qDebug ( "init Buttons" );
         d-> m_buttons = new QValueList <ODeviceButton>;
 
         for ( uint i = 0; i < ( sizeof( ipaq_buttons ) / sizeof( i_button )); i++ ) {
                 i_button *ib = ipaq_buttons + i;
@@ -304,25 +307,35 @@ ODevice::~ODevice ( )
         delete d;
 }
 
 bool ODevice::setSoftSuspend ( bool /*soft*/ )
 {
         return false;
 }
 
 //#include <linux/apm_bios.h>
 
 #define APM_IOC_SUSPEND          OD_IO( 'A', 2 )
 
-
+/**
+ * This method will try to suspend the device
+ * It only works if the user is the QWS Server and the apm application
+ * is installed.
+ * It tries to suspend and then waits some time cause some distributions
+ * do have asynchronus apm implementations.
+ * This method will either fail and return false or it'll suspend the
+ * device and return once the device got woken up
+ *
+ * @return if the device got suspended
+ */
 bool ODevice::suspend ( )
 {
         if ( !d-> m_qwsserver ) // only qwsserver is allowed to suspend
                 return false;
 
         if ( d-> m_model == Model_Unknown ) // better don't suspend in qvfb / on unkown devices
                 return false;
 
         bool res = false;
 
         struct timeval tvs, tvn;
         ::gettimeofday ( &tvs, 0 );
@@ -345,169 +358,252 @@ bool ODevice::suspend ( )
 }
 
 //#include <linux/fb.h> better not rely on kernel headers in userspace ...
 
 #define FBIOBLANK             OD_IO( 'F', 0x11 ) // 0x4611
 
 /* VESA Blanking Levels */
 #define VESA_NO_BLANKING      0
 #define VESA_VSYNC_SUSPEND    1
 #define VESA_HSYNC_SUSPEND    2
 #define VESA_POWERDOWN        3
 
-
+/**
+ * This sets the display on or off
+ */
 bool ODevice::setDisplayStatus ( bool on )
 {
         if ( d-> m_model == Model_Unknown )
                 return false;
 
         bool res = false;
         int fd;
 
         if (( fd = ::open ( "/dev/fb0", O_RDWR )) >= 0 ) {
                 res = ( ::ioctl ( fd, FBIOBLANK, on ? VESA_NO_BLANKING : VESA_POWERDOWN ) == 0 );
                 ::close ( fd );
         }
         return res;
 }
 
-bool ODevice::setDisplayBrightness ( int )
+/**
+ * This sets the display brightness
+ * @return success or failure
+ */
+bool ODevice::setDisplayBrightness ( int p)
 {
+        Q_UNUSED( p )
         return false;
 }
 
 int ODevice::displayBrightnessResolution ( ) const
 {
         return 16;
 }
 
+/**
+ * This returns the vendor as string
+ * @return Vendor as QString
+ */
 QString ODevice::vendorString ( ) const
 {
         return d-> m_vendorstr;
 }
 
+/**
+ * This returns the vendor as one of the values of OVendor
+ * @return OVendor
+ */
 OVendor ODevice::vendor ( ) const
 {
         return d-> m_vendor;
 }
 
+/**
+ * This returns the model as a string
+ * @return A string representing the model
+ */
 QString ODevice::modelString ( ) const
 {
         return d-> m_modelstr;
 }
 
+/**
+ * This does return the OModel used
+ */
 OModel ODevice::model ( ) const
 {
         return d-> m_model;
 }
 
+/**
+ * This does return the systen name
+ */
 QString ODevice::systemString ( ) const
 {
         return d-> m_systemstr;
 }
 
+/**
+ * Return System as OSystem value
+ */
 OSystem ODevice::system ( ) const
 {
         return d-> m_system;
 }
 
+/**
+ * @return the version string of the base system
+ */
 QString ODevice::systemVersionString ( ) const
 {
         return d-> m_sysverstr;
 }
 
+/**
+ *  @return the current Transformation
+ */
 Transformation ODevice::rotation ( ) const
 {
         return d-> m_rotation;
 }
 
+/**
+ * This plays an alarmSound
+ */
 void ODevice::alarmSound ( )
 {
 #ifndef QT_NO_SOUND
         static Sound snd ( "alarm" );
 
         if ( snd. isFinished ( ))
                 snd. play ( );
 #endif
 }
 
+/**
+ * This plays a key sound
+ */
 void ODevice::keySound ( )
 {
 #ifndef QT_NO_SOUND
         static Sound snd ( "keysound" );
 
         if ( snd. isFinished ( ))
                 snd. play ( );
 #endif
 }
 
+/**
+ * This plays a touch sound
+ */
 void ODevice::touchSound ( )
 {
 
 #ifndef QT_NO_SOUND
         static Sound snd ( "touchsound" );
 
         if ( snd. isFinished ( ))
                 snd. play ( );
 #endif
 }
 
-
+/**
+ * This method will return a list of leds
+ * available on this device
+ * @return a list of LEDs.
+ */
 QValueList <OLed> ODevice::ledList ( ) const
 {
         return QValueList <OLed> ( );
 }
 
+/**
+ * This does return the state of the LEDs
+ */
 QValueList <OLedState> ODevice::ledStateList ( OLed /*which*/ ) const
 {
         return QValueList <OLedState> ( );
 }
 
+/**
+ * @return the state for a given OLed
+ */
 OLedState ODevice::ledState ( OLed /*which*/ ) const
 {
         return Led_Off;
 }
 
-bool ODevice::setLedState ( OLed /*which*/, OLedState /*st*/ )
+/**
+ * Set the state for a LED
+ * @param which Which OLed to use
+ * @param st The state to set
+ * @return success or failure
+ */
+bool ODevice::setLedState ( OLed which, OLedState st )
 {
+        Q_UNUSED( which )
+        Q_UNUSED( st    )
         return false;
 }
 
+/**
+ * @return if the device has a light sensor
+ */
 bool ODevice::hasLightSensor ( ) const
 {
         return false;
 }
 
+/**
+ * @return a value from the light senso
+ */
 int ODevice::readLightSensor ( )
 {
         return -1;
 }
 
+/**
+ * @return the light sensor resolution whatever that is ;)
+ */
 int ODevice::lightSensorResolution ( ) const
 {
         return 0;
 }
 
+/**
+ * @return a list of hardware buttons
+ */
 const QValueList <ODeviceButton> &ODevice::buttons ( )
 {
         initButtons ( );
 
         return *d-> m_buttons;
 }
 
+/**
+ * @return The amount of time that would count as a hold
+ */
 uint ODevice::buttonHoldTime ( ) const
 {
         return d-> m_holdtime;
 }
 
+/**
+ * This method return a ODeviceButton for a key code
+ * or 0 if no special hardware button is available for the device
+ *
+ * @return The devicebutton or 0l
+ * @see ODeviceButton
+ */
 const ODeviceButton *ODevice::buttonForKeycode ( ushort code )
 {
         initButtons ( );
 
         for ( QValueListConstIterator<ODeviceButton> it = d-> m_buttons-> begin ( ); it != d-> m_buttons-> end ( ); ++it ) {
                 if ( (*it). keycode ( ) == code )
                         return &(*it);
         }
         return 0;
 }
 
 void ODevice::reloadButtonMapping ( )