Add API docu

2 files changed, 118 insertions, 0 deletions

diff --git a/library/alarmserver.cpp b/library/alarmserver.cpp
index a75fc7e..6f6f32d 100644
--- a/library/alarmserver.cpp
+++ b/library/alarmserver.cpp
@@ -1,452 +1,512 @@
 /**********************************************************************
 ** Copyright (C) 2000-2002 Trolltech AS.  All rights reserved.
 **
 ** This file is part of the Qtopia Environment.
 **
 ** 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.
 **
 ** 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.
 **
 **********************************************************************/
 
 #include <qdir.h>
 #include <qfile.h>
 #include <qmessagebox.h>
 #include <qtextstream.h>
 
 
 #include <qpe/qpeapplication.h>
 #include "global.h"
 #include "resource.h"
 
 #include <qpe/qcopenvelope_qws.h>
 #include "alarmserver.h"
 #include <qpe/timeconversion.h>
 
 #include <sys/types.h>
 #include <sys/stat.h>
 
 #include <stdlib.h>
 #include <unistd.h>
 
 
 #undef USE_ATD   // not used anymore -- we run opie-alarm on suspend/resume
 
 
 struct timerEventItem
 {
 	time_t UTCtime;
 	QCString channel, message;
 	int data;
 	bool operator==( const timerEventItem &right ) const
 	{
 		return ( UTCtime == right.UTCtime
 		         && channel == right.channel
 		         && message == right.message
 		         && data == right.data );
 	}
 };
 
 class TimerReceiverObject : public QObject
 {
 public:
 	TimerReceiverObject()
 	{ }
 	~TimerReceiverObject()
 	{ }
 	void resetTimer();
 	void setTimerEventItem();
 	void deleteTimer();
 protected:
 	void timerEvent( QTimerEvent *te );
 
 #ifdef USE_ATD
 private:
 	QString atfilename;
 #endif
 };
 
 TimerReceiverObject *timerEventReceiver = NULL;
 QList<timerEventItem> timerEventList;
 timerEventItem *nearestTimerEvent = NULL;
 
 
 // set the timer to go off on the next event in the list
 void setNearestTimerEvent()
 {
 	nearestTimerEvent = NULL;
 	QListIterator<timerEventItem> it( timerEventList );
 	if ( *it )
 		nearestTimerEvent = *it;
 	for ( ; *it; ++it )
 		if ( (*it)->UTCtime < nearestTimerEvent->UTCtime )
 			nearestTimerEvent = *it;
 	if (nearestTimerEvent)
 		timerEventReceiver->resetTimer();
 	else
 		timerEventReceiver->deleteTimer();
 }
 
 
 //store current state to file
 //Simple implementation. Should run on a timer.
 
 static void saveState()
 {
 	QString savefilename = Global::applicationFileName( "AlarmServer", "saveFile" );
 	if ( timerEventList.isEmpty() ) {
 		unlink( savefilename );
 		return ;
 	}
 
 	QFile savefile(savefilename + ".new");
 	if ( savefile.open(IO_WriteOnly) ) {
 		QDataStream ds( &savefile );
 
 		//save
 
 		QListIterator<timerEventItem> it( timerEventList );
 		for ( ; *it; ++it ) {
 			ds << it.current()->UTCtime;
 			ds << it.current()->channel;
 			ds << it.current()->message;
 			ds << it.current()->data;
 		}
 
 
 		savefile.close();
 		unlink( savefilename );
 		QDir d;
 		d.rename(savefilename + ".new", savefilename);
 
 	}
 }
 
 /*!
   Sets up the alarm server. Restoring to previous state (session management).
  */
 void AlarmServer::initialize()
 {
 	//read autosave file and put events in timerEventList
 
 	QString savefilename = Global::applicationFileName( "AlarmServer", "saveFile" );
 
 	QFile savefile(savefilename);
 	if ( savefile.open(IO_ReadOnly) ) {
 		QDataStream ds( &savefile );
 		while ( !ds.atEnd() ) {
 			timerEventItem *newTimerEventItem = new timerEventItem;
 			ds >> newTimerEventItem->UTCtime;
 			ds >> newTimerEventItem->channel;
 			ds >> newTimerEventItem->message;
 			ds >> newTimerEventItem->data;
 			timerEventList.append( newTimerEventItem );
 		}
 		savefile.close();
 		if (!timerEventReceiver)
 			timerEventReceiver = new TimerReceiverObject;
 		setNearestTimerEvent();
 	}
 }
 
 
 #ifdef USE_ATD
 
 static const char* atdir = "/var/spool/at/";
 
 static bool triggerAtd( bool writeHWClock = FALSE )
 {
 	QFile trigger(QString(atdir) + "trigger");
 	if ( trigger.open(IO_WriteOnly | IO_Raw) ) {
 		if ( trigger.writeBlock("\n", 2) != 2 ) {
 			QMessageBox::critical( 0, QObject::tr( "Out of Space" ),
 			                       QObject::tr( "Unable to schedule alarm.\nFree some memory and try again." ) );
 			trigger.close();
 			QFile::remove
 				( trigger.name() );
 			return FALSE;
 		}
 		return TRUE;
 	}
 	return FALSE;
 }
 
 #else
 
 static bool writeResumeAt ( time_t wakeup )
 {
 	FILE *fp = ::fopen ( "/var/run/resumeat", "w" );
 
 	if ( fp ) {
 		::fprintf ( fp, "%d\n", (int) wakeup );
 		::fclose ( fp );
 	}
 	else
 		qWarning ( "Failed to write wakeup time to /var/run/resumeat" );
 
 	return ( fp );
 }
 
 #endif
 
 void TimerReceiverObject::deleteTimer()
 {
 #ifdef USE_ATD
 	if ( !atfilename.isEmpty() ) {
 		unlink( atfilename );
 		atfilename = QString::null;
 		triggerAtd( FALSE );
 	}
 #else
 	writeResumeAt ( 0 );
 #endif
 }
 
 void TimerReceiverObject::resetTimer()
 {
 	const int maxsecs = 2147000;
 	QDateTime nearest = TimeConversion::fromUTC(nearestTimerEvent->UTCtime);
 	QDateTime now = QDateTime::currentDateTime();
 	if ( nearest < now )
 		nearest = now;
 	int secs = TimeConversion::secsTo( now, nearest );
 	if ( secs > maxsecs ) {
 		// too far for millisecond timing
 		secs = maxsecs;
 	}
 
 	// System timer (needed so that we wake from deep sleep),
 	// from the Epoch in seconds.
 	//
 	int at_secs = TimeConversion::toUTC(nearest);
 	// qDebug("reset timer to %d seconds from Epoch",at_secs);
 
 #ifdef USE_ATD
 
 	QString fn = atdir + QString::number(at_secs) + "."
 	             + QString::number(getpid());
 	if ( fn != atfilename ) {
 		QFile atfile(fn + ".new");
 		if ( atfile.open(IO_WriteOnly | IO_Raw) ) {
 			int total_written;
 
 			// just wake up and delete the at file
 			QString cmd = "#!/bin/sh\nrm " + fn;
 			total_written = atfile.writeBlock(cmd.latin1(), cmd.length());
 			if ( total_written != int(cmd.length()) ) {
 				QMessageBox::critical( 0, tr("Out of Space"),
 				                       tr("Unable to schedule alarm.\n"
 				                          "Please free up space and try again") );
 				atfile.close();
 				QFile::remove
 					( atfile.name() );
 				return ;
 			}
 			atfile.close();
 			unlink( atfilename );
 			QDir d;
 			d.rename(fn + ".new", fn);
 			chmod(fn.latin1(), 0755);
 			atfilename = fn;
 			triggerAtd( FALSE );
 		}
 		else {
 			qWarning("Cannot open atd file %s", fn.latin1());
 		}
 	}
 #else
     writeResumeAt ( at_secs );
 
 #endif
 
 	// Qt timers (does the actual alarm)
 	// from now in milliseconds
 	//
 	qDebug("AlarmServer waiting %d seconds", secs);
 	startTimer( 1000 * secs + 500 );
 }
 
 void TimerReceiverObject::timerEvent( QTimerEvent * )
 {
 	bool needSave = FALSE;
 	killTimers();
 	if (nearestTimerEvent) {
 		if ( nearestTimerEvent->UTCtime
 		        <= TimeConversion::toUTC(QDateTime::currentDateTime()) ) {
 #ifndef QT_NO_COP
 			QCopEnvelope e( nearestTimerEvent->channel,
 			                nearestTimerEvent->message );
 			e << TimeConversion::fromUTC( nearestTimerEvent->UTCtime )
 			<< nearestTimerEvent->data;
 #endif
 
 			timerEventList.remove( nearestTimerEvent );
 			needSave = TRUE;
 		}
 		setNearestTimerEvent();
 	}
 	else {
 		resetTimer();
 	}
 	if ( needSave )
 		saveState();
 }
 
 /*!
   \class AlarmServer alarmserver.h
   \brief The AlarmServer class allows alarms to be scheduled and unscheduled.
 
     Applications can schedule alarms with addAlarm() and can
     unschedule alarms with deleteAlarm(). When the time for an alarm
     to go off is reached the specified \link qcop.html QCop\endlink
     message is sent on the specified channel (optionally with
     additional data).
 
     Scheduling an alarm using this class is important (rather just using
     a QTimer) since the machine may be asleep and needs to get woken up using
     the Linux kernel which implements this at the kernel level to minimize
     battery usage while asleep.
 
+    A small example on how to use AlarmServer.
+
+    First we need to connect a slot the AppMessage QCOP call. appMessage
+    will be emitted if QPE/Application/appname gets called.
+
+    \code
+     TestApp::TestApp(QWidget *parent, const char* name, WFlags fl )
+         : QMainWindow(parent,name,fl){
+         connect(qApp,SIGNAL(appMessage(const QCString&,const QByteArray&)),
+                 this,SLOT(slotAppMessage(const QCString&,const QByteArray&)));
+     }
+    \endcode
+
+    To add / delete an alarm, you can use the static method AlarmServer::addAlarm and
+    AlarmServer::deleteAlarm. Note that an old (expired) alarm will automatically be deleted
+    from the alarmserver list, but a change in timing will have the effect, that both
+    alarms will be emitted. So if you change an Alarm be sure to delete the old one!
+    @see addAlarm
+
+    \code
+       QDateTime oldDt = oldAlarmDateTime();
+       QPEApplication::execDialog(ourDlg);
+       QDateTime newDt = ourDlg->dateTime();
+       if(newDt == oldDt ) return;
+       @slash* code is missing for unsetting an alarm *@slash
+
+       AlarmServer::deleteAlarm(oldDt,"QPE/Application/appname","checkAlarm(QDateTime,int)",0);
+       AlarmServer::addAlarm(   newDt,"QPE/AlarmServer/appname","checkAlarm(QDateTime,int)",0);
+
+    \endcode
+
+    Now once the Alarm is emitted you need to check the appMessage and then do what you want.
+    \code
+       void TestApp::slotAppMessage(const QCString& str, const QByteArray& ar ){
+           QDataStream stream(ar,IO_ReadOnly);
+           if(str == "checkAlarm(QDateTime,int)" ){
+              QDateTime dt;
+              int a;
+              stream >> dt >> a;
+              // fire up alarm
+           }
+       }
+    \endcode
+
     \ingroup qtopiaemb
     \sa QCopEnvelope
+    @see QPEApplication::appMessage(const QCString&,const QByteArray&)
+    @see OPimMainWindow
+    @see ODevice::alarmSound()
+    @see Sound::soundAlarm()
 */
 
 /*!
   Schedules an alarm to go off at (or soon after) time \a when. When
   the alarm goes off, the \link qcop.html QCop\endlink \a message will
   be sent to \a channel, with \a data as a parameter.
 
   If this function is called with exactly the same data as a previous
   call the subsequent call is ignored, so there is only ever one alarm
   with a given set of parameters.
 
+  Once an alarm is emitted. The \a channel with a  \a message will be emitted
+  and data will be send.
+  The QDateTime and int  are the two parameters included in the QCOP message.
+  You can specify channel, message and the integer parameter. QDateTime will be
+  the datetime of the QCop call.
+
+  @param when The QDateTime of the alarm
+  @param channel The channel which gets called once the alarm is emitted
+  @param message The message to be send to the channel
+  @param data Additional data as integer
+
+  @see QCopChannel
   \sa deleteAlarm()
 */
 void AlarmServer::addAlarm ( QDateTime when, const QCString& channel,
                              const QCString& message, int data)
 {
 	if ( qApp->type() == QApplication::GuiServer ) {
 		bool needSave = FALSE;
 		// Here we are the server so either it has been directly called from
 		// within the server or it has been sent to us from a client via QCop
 		if (!timerEventReceiver)
 			timerEventReceiver = new TimerReceiverObject;
 
 		timerEventItem *newTimerEventItem = new timerEventItem;
 		newTimerEventItem->UTCtime = TimeConversion::toUTC( when );
 		newTimerEventItem->channel = channel;
 		newTimerEventItem->message = message;
 		newTimerEventItem->data = data;
 		// explore the case of already having the event in here...
 		QListIterator<timerEventItem> it( timerEventList );
 		for ( ; *it; ++it )
 			if ( *(*it) == *newTimerEventItem )
 				return ;
 		// if we made it here, it is okay to add the item...
 		timerEventList.append( newTimerEventItem );
 		needSave = TRUE;
 		// quicker than using setNearestTimerEvent()
 		if ( nearestTimerEvent ) {
 			if (newTimerEventItem->UTCtime < nearestTimerEvent->UTCtime) {
 				nearestTimerEvent = newTimerEventItem;
 				timerEventReceiver->killTimers();
 				timerEventReceiver->resetTimer();
 			}
 		}
 		else {
 			nearestTimerEvent = newTimerEventItem;
 			timerEventReceiver->resetTimer();
 		}
 		if ( needSave )
 			saveState();
 	}
 	else {
 #ifndef QT_NO_COP
 		QCopEnvelope e( "QPE/System", "addAlarm(QDateTime,QCString,QCString,int)" );
 		e << when << channel << message << data;
 #endif
 
 	}
 }
 
 /*!
   Deletes previously scheduled alarms which match \a when, \a channel,
   \a message, and \a data.
 
   Passing null values for \a when, \a channel, or for the \link
   qcop.html QCop\endlink \a message, acts as a wildcard meaning "any".
   Similarly, passing -1 for \a data indicates "any".
 
   If there is no matching alarm, nothing happens.
 
   \sa addAlarm()
 
 */
 void AlarmServer::deleteAlarm (QDateTime when, const QCString& channel, const QCString& message, int data)
 {
 	if ( qApp->type() == QApplication::GuiServer) {
 		bool needSave = FALSE;
 		if ( timerEventReceiver != NULL ) {
 			timerEventReceiver->killTimers();
 
 			// iterate over the list of events
 			QListIterator<timerEventItem> it( timerEventList );
 			time_t deleteTime = TimeConversion::toUTC( when );
 			for ( ; *it; ++it ) {
 				// if its a match, delete it
 				if ( ( (*it)->UTCtime == deleteTime || when.isNull() )
 				        && ( channel.isNull() || (*it)->channel == channel )
 				        && ( message.isNull() || (*it)->message == message )
 				        && ( data == -1 || (*it)->data == data ) ) {
 					// if it's first, then we need to update the timer
 					if ( (*it) == nearestTimerEvent ) {
 						timerEventList.remove(*it);
 						setNearestTimerEvent();
 					}
 					else {
 						timerEventList.remove(*it);
 					}
 					needSave = TRUE;
 				}
 			}
 			if ( nearestTimerEvent )
 				timerEventReceiver->resetTimer();
 		}
 		if ( needSave )
 			saveState();
 	}
 	else {
 #ifndef QT_NO_COP
 		QCopEnvelope e( "QPE/System", "deleteAlarm(QDateTime,QCString,QCString,int)" );
 		e << when << channel << message << data;
 #endif
 
 	}
 }
 
 /*!
   The implementation depends on the mode of AlarmServer. If the AlarmServer
   uses atd the current system time will be written to the hardware clock.
   If the AlarmServer relies on opie-alarm the time will be written once the
   device gets suspended. opie-alarm is used by the Zaurus, iPAQs and SIMpad
 */
 void Global::writeHWClock()
 {
 #ifdef USE_ATD
 	if ( !triggerAtd( TRUE ) ) {
 		// atd not running? set it ourselves
 		system("/sbin/hwclock --systohc"); // ##### UTC?
 	}
 #else
 	// hwclock is written on suspend
 #endif
 }
diff --git a/library/dummy_api_docu.cpp b/library/dummy_api_docu.cpp
index 6b76401..f2153df 100644
--- a/library/dummy_api_docu.cpp
+++ b/library/dummy_api_docu.cpp
@@ -1,311 +1,369 @@
 /*
  * A place to explain various headers
  */
 
 /*
  * applicationinterface.h
  */
 
 /**
  * \class ApplicationInterface
  * \brief Application interface currently used by the quicklaunch framework
  *
  *  This is the interface to be exposed by applications available as DSO
  *  Normally one would use the OApplicationFactory which does the magic of
  *  exposing the interface.
  *
  *  Resulting dynamic shared objects (dso) need to go into the
  *  OPIEDIR/plugins/application.
  *
  *
  *  You can use this interface to load applications into your application.
  *  @todo  Implement Services + Trader
  *  @since Opie 1.0.2
  */
 /**
  * \fn QWidget* ApplicationInterface::createMainWindow(const QString& appName, QWidget* parent, const char* name, Qt::WFlags f)
  * \brief create the mainwindow for the giving application name
  * Create a main window for the giving application name
  *
  * @param appName The application widget to be created
  * @param parent The parent of the newly created widget
  * @param name The name of the QObject
  * @param f Possible Window Flags
  *
  * @return the widget or 0l
  */
 /**
  * \fn QStringList ApplicationInterface::applications()const
  * The list of application windows supported
  */
 
 /*
  * Font Factory
  */
 
 /**
  * \class FontFactoryInterface
  * \brief Interface for additional Font Factories
  *
  * To add special types of fonts TrueTypes or your very own
  * format. If you implement this Interface you can add
  * custom font loading.
  *
  * The dynamic shared object goes to
  * OPIEDIR/plugins/fontfactories.
  *
  * As of version Opie 1.0.2 loading of the plugins is not
  * yet implemented
  *
  */
 
 /**
  * \fn QFontFactory* FontFactoryInterface::fontFactory()
  *
  * Create a new QFontFactory and return it
  */
 
 
 /*
  * ImageCodec
  */
 
 /**
  * \class ImageCodecInterface
  * \brief add Image Codecs
  *
  * This interface will be queried to add new Image loading
  * and saving routines.
  *
  * The ImageCodec needs to be placed in OPIEDIR/plugins/imagecodecs.
  *
  * @see QImage
  * @see QImageIO
  **/
 
 /**
  * \fn QStringList ImageCodecInterface::keys()const
  * \brief Query for the list of supported formats
  *
  *  Return a QStringList of the supported formats
  *
  */
 
 /**
  * \fn bool ImageCodecInterface::installIOHandler(const QString& format )
  * \brief install codec to QIageIO for the specefic format
  *
  * Install a QImage codec for the requested format
  */
 
 /*
  * Input Methods
  */
 
 /**
  * \class InputMethodInterface
  * \brief Interface class for inputting keyboard events
  *
  * InputMethods are loaded by the Launcher/Server/Taskbar
  * and are located inside OPIEDIR/plugins/inputmethods
  *
  * Depending on the device these InputMethods are the only way
  * to input charachters
  *
  */
 
 
 /**
  * \fn QWidget InputMethodInterface::inputMethod(QWidget*parent, Qt::WFlags f)
  * \brief create a new widget which should be used as input
  *
  * This method will be called if the inputmethod is to be shown.
  * Make sure that your widget is not too large. As of Opie1.1 InputMethods
  * can be floating as well.
  *
  * Delete the Widget yourself.
  *
  *
  * @param parent The parent of the to be created Input widget.
  * @param f The Qt::WFlags for the widget
  */
 
 /**
  * \fn void InputMethodInterface::resetState()
  * \brief Reset the state of the inputmethod
  *
  *  If you're shown reset the state of the keyboard to the
  *  the default.
  */
 
 /**
  * \fn QPixmap* InputMethodInterface::icon()
  * \brief The icon of your Input method
  *
  * Return a pointer to a QPixmap symboling your inputmethod
  * You need to delete the pixmap later yourself.
  */
 
 /**
  * \fn void InputMethodInterface::onKeyPress(QObject* receiver, const char* slot)
  * \brief pass your key event through
  *
  * In your actual Input Implementation you'll need a SIGNAL with this
  * void key(ushort,ushort,ushort,bool,bool) signal. The host of your input method
  * requests you to connect your signal with the signal out of receiver and slot.
  *
  * ushort == unicode value
  * ushort == keycode
  * ushort == modifiers from Qt::ButtonState
  * bool   == true if the key is pressed and false if released
  * bool   == autorepeat on or off.
  *
  * See the QWSServer for more information about emitting keys
  *
  *
  * @param receiver the receiver to QObject::connect to
  * @param slot the slot to QObject::connect to
  *
  */
 
 /*
  * MediaPlayer Plugins
  */
 
 /**
  * \class MediaPlayerPluginInterface
  * \brief Plugins for the Opie Player I
  *
  * You can extend the Opie Player I by plugins placed in
  * OPIEDIR/plugins/codecs
  *
  *
  */
 
 /**
  * \fn MediaPlayerDecoder MediaPlayerPluginInterface::decoder()
  *
  * Create a new MediaPlayerDecoder
  *
  */
 
 
 /*
  * MenuApplet Interface
  */
 
 /**
  * \class MenuAppletInterface
  * \brief Plugins for the Menu Applet/StartMenu
  *
  *  You can extend the startmenu by plugins implementing this
  * interface. You need to place the plugin in plugins/applets
  * from where they will be loaded.
  *
  *
  */
 
 /**
  * \fn QString MenuAppletInterface::name()const
  * \brief Translated name of the Menu Applet
  *
  * Return a translated name using QObject::tr  of your plugin
  */
 
 /**
  * \fn int MenuAppletInterface::position()const
  * \brief the wished position of this applet
  *
  *  The position where you want to be placed. 0 for the down most
  *
  */
 
 /**
  * \fn QIconSet MenuAppletInterface::icon()const
  * \brief return a QIconSet.
  *
  * The returned icon set will be shown next
  * to text().
  * Make use of AppLnk::smallIconSize()
  */
 
 /**
  * \fn QString MenuAppletInterface::text()const
  * \brief return a Text shown to the user in the menu
  */
 
 /**
  * \fn QPopupMenu* MenuAppletInterface::popup( QWidget* parent)const
  * \brief Provide a SubMenu popup if you want
  *
  * You can provide a Submenu popup for your item as well. If you return
  * 0 no popup will be shown.
  *
  * You can use the QPopupMenu::aboutToShow() signal to be informed before
  * showing the popup
  *
  * @param parent The parent of the to be created popup.
  * @see QPopupMenu
  */
 
 
 /**
  * \fn void MenuAppletInterface::activated()
  * \brief This method gets called once the user clicked on the item
  *
  * This is the way you get informed about user input. Your plugin
  * has just been clicked
  */
 
 /*
  * StyleInterface
  */
 
 /**
  * \class StyleInterface
  * \brief StyleInterface base class
  *
  * Opie styles should implement StyleExtendedInterface.
  * StyleInterface is only for compability reasons present and should
  * not be used for new styles.
  *
  * Styles need to be put into OPIEDIR/plugins/styles
  */
 
 
 /**
  * \class StyleExtendedInterface
  * \brief The Plugin Interface for all Opie styles
  *
  * If you want to create a new QStyle for Opie use this class.
  *
  * key(ushort,ushort,ushort,bool,bool)
  */
 
 /*
  * Taskbar Applets
  */
 
 
 /**
  * \class TaskbarAppletInterface
  *
  * This is the base class of all Applets shown in the taskbar
  * An applets need to provide a position and a widget.
  *
  * Applets need to be put into OPIEDIR/plugins/applets
  *
  */
 /**
  * \fn QWidget* TaskbarAppletInterface::applet( QWidget* parent )
  * \brief return the new Applet Widget
  *
  * @param parent The parent of the Applet normally the taskbar
  */
 
 /**
  * \fn int TaskbarAppletInterface::position()const;
  * \brief the wished position
  *
  * From left to right. 0 is left. The clock uses 10
  */
+
+
+/**
+ * \class WindowDecorationInterface
+ *
+ * Interface class for Window Decorations. Yu need to implement
+ * metric and drawing functions.
+ */
+
+/**
+ * \class WindowDecorationInterface::WindowData
+ *
+ * Window informations like the QRect, Palette, Caption
+ * and flag
+ */
+
+/**
+ * \fn int WindowDecorationInterface::metric(Metric m,const WindowData* )
+ *
+ * Return the width for the item out of Metric.
+ * Normally you will case Metric and default: should call the interface
+ * method. Also return 0
+ */
+
+/**
+ * \fn void WindowDecorationInterface::drawArea( Area a, QPainter* , const WindowData* )const
+ *
+ * draw the Area specefic in a to the QPainter
+ */
+
+/**
+ * \fn void WindowDecorationInterface::drawButton(Button b,QPainter*p ,const WindowData* d, int x, int y, int w,int h, QWSButton::State s)const
+ *
+ * @param b The Button to be drawn
+ * @param p The painter to draw at
+ * @param d The Window Data
+ * @param x The X position of the button
+ * @param y The Y position of the button
+ * @param w The width of the button
+ * @param h The height of the button
+ * @param s The state of the button
+ */
+
+/**
+ * \fn QRegion WindowDecorationInterface::mask( const WindowData* )const
+ *
+ * The mask of the Decoration.
+ *
+ * \code
+ *     int th = metric(TitleHeight,wd);
+ *   QRect rect( wd->rect );
+ *   QRect r(rect.left() - metric(LeftBorder,wd),
+ *          rect.top() - th - metric(TopBorder,wd),
+ *          rect.width() + metric(LeftBorder,wd) + metric(RightBorder,wd),
+ *          rect.height() + th + metric(TopBorder,wd) + metric(BottomBorder,wd));
+ *  return QRegion(r) - rect;
+ * \endcode
+ */