add api docu

6 files changed, 116 insertions, 15 deletions

diff --git a/library/applicationinterface.h b/library/applicationinterface.h
index b37a2c5..b7648f6 100644
--- a/library/applicationinterface.h
+++ b/library/applicationinterface.h
@@ -1,32 +1,65 @@
 /*
  * GPLv2 (C) 2002-2003 Trolltech
  *       (C) 2003 zecke@handhelds.org
  */
 
 
 #ifndef APPLICATIONINTERFACE_H
 #define APPLICATIONINTERFACE_H
 
 #include <qstringlist.h>
 #include <qtopia/qcom.h>
 
 #ifndef QT_NO_COMPONENT
 // {07E15B48-B947-4334-B866-D2AD58157D8C}
 #ifndef IID_QtopiaApplication
 #define IID_QtopiaApplication QUuid( 0x07e15b48, 0xb947, 0x4334, 0xb8, 0x66, 0xd2, 0xad, 0x58, 0x15, 0x7d, 0x8c)
 #endif
 #endif
 
+
+/**
+ * \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
+ */
 struct ApplicationInterface : public QUnknownInterface
 {
 public:
+
+    /**
+     * \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
+     */
     virtual QWidget *createMainWindow( const QString &appName, QWidget *parent=0,
                                        const char *name=0, Qt::WFlags f=0 ) = 0;
+
+   /**
+    * The list of application windows supported
+    */
     virtual QStringList applications() const = 0;
 };
 
 /*
  * Use an extended interface for QObejct, Opie::Part in the future
  */
 
 #endif
diff --git a/library/fontfactoryinterface.h b/library/fontfactoryinterface.h
index ed65dfa..68b0be5 100644
--- a/library/fontfactoryinterface.h
+++ b/library/fontfactoryinterface.h
@@ -12,30 +12,45 @@
 ** 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.
 **
 **********************************************************************/
 #ifndef FONTFACTORYINTERFACE_H
 #define FONTFACTORYINTERFACE_H
 
 #include <qnamespace.h>
 #include <qstring.h>
 #include <qpe/qcom.h>
 
 class QFontFactory;
 
 #ifndef QT_NO_COMPONENT
 // {7F194DD6-FAA3-498F-8F30-9C297A570DFA}
 #ifndef IID_FontFactory
 #define IID_FontFactory QUuid( 0x7f194dd6, 0xfaa3, 0x498f, 0x8f, 0x30, 0x9c, 0x29, 0x7a, 0x57, 0x0d, 0xfa)
 #endif
 #endif
 
+
+/**
+ * \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
+ *
+ */
 struct FontFactoryInterface : public QUnknownInterface
 {
     virtual QFontFactory *fontFactory() = 0;
 };
 
 #endif
diff --git a/library/imagecodecinterface.h b/library/imagecodecinterface.h
index 8306b68..3b1cd7b 100644
--- a/library/imagecodecinterface.h
+++ b/library/imagecodecinterface.h
@@ -8,32 +8,45 @@
 ** 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.
 **
 **********************************************************************/
 #ifndef IMAGECODECINTERFACE_H
 #define IMAGECODECINTERFACE_H
 
 #include <qstringlist.h>
 #include <qpe/qcom.h>
 
 #ifndef QT_NO_COMPONENT
 #ifndef IID_QtopiaImageCodec
 #define IID_QtopiaImageCodec QUuid(0x09bf6906, 0x1549, 0xbb4a, 0x18, 0xba, 0xb9, 0xe7, 0x0a, 0x6e, 0x4d, 0x1e)
 #endif
 #endif
 
+
+/**
+ *
+ * \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
+ **/
 struct ImageCodecInterface : public QUnknownInterface
 {
 public:
     virtual QStringList keys() const = 0;
     virtual bool installIOHandler( const QString &format ) = 0;
 };
 
 #endif
diff --git a/library/qpeapplication.cpp b/library/qpeapplication.cpp
index a97efc0..6f2e43b 100644
--- a/library/qpeapplication.cpp
+++ b/library/qpeapplication.cpp
@@ -414,50 +414,50 @@ static void setBass( int t = 0, int percent = -1 )
 
 static void setTreble( int t = 0, int percent = -1 )
 {
 	switch ( t ) {
 		case 0: {
 				Config cfg( "qpe" );
 				cfg.setGroup( "Volume" );
 				if ( percent < 0 )
 					percent = cfg.readNumEntry( "TreblePercent", 50 );
 
 #ifndef QT_NO_SOUND
 				int fd = 0;
 				int treble = percent;
 				if ( ( fd = open( "/dev/mixer", O_RDWR ) ) >= 0 ) {
 					ioctl( fd, MIXER_WRITE( SOUND_MIXER_TREBLE ), &treble );
 					::close( fd );
 				}
 #endif
 			}
 			break;
 	}
 }
 
 
-/*!
-  \class QPEApplication qpeapplication.h
+/**
+  \class QPEApplication 
   \brief The QPEApplication class implements various system services
     that are available to all Qtopia applications.
 
   Simply by using QPEApplication instead of QApplication, a standard Qt
   application becomes a Qtopia application. It automatically follows
   style changes, quits and raises, and in the
   case of \link docwidget.html document-oriented\endlink applications,
   changes the currently displayed document in response to the environment.
 
   To create a \link docwidget.html document-oriented\endlink
   application use showMainDocumentWidget(); to create a
   non-document-oriented application use showMainWidget(). The
   keepRunning() function indicates whether the application will
   continue running after it's processed the last \link qcop.html
   QCop\endlink message. This can be changed using setKeepRunning().
 
   A variety of signals are emitted when certain events occur, for
   example, timeChanged(), clockChanged(), weekChanged(),
   dateFormatChanged() and volumeChanged(). If the application receives
   a \link qcop.html QCop\endlink message on the application's
   QPE/Application/\e{appname} channel, the appMessage() signal is
   emitted. There are also flush() and reload() signals, which
   are emitted when synching begins and ends respectively - upon these
   signals, the application should save and reload any data
@@ -1550,68 +1550,70 @@ void QPEApplication::pidMessage( const QCString& msg, const QByteArray& data)
                 raiseAppropriateWindow();
                 if ( !p ) {
                     // Tell the system we're still chugging along...
 #ifndef QT_NO_COP
                     QCopEnvelope e("QPE/System", "appRaised(QString)");
                     e << d->appName;
 #endif
                 }
             }
             if ( p )
                 d->keep_running = p;
 	}
 #endif
 }
 
 
 /*!
   Sets widget \a mw as the mainWidget() and shows it. For small windows,
   consider passing TRUE for \a nomaximize rather than the default FALSE.
 
   \sa showMainDocumentWidget()
 */
 void QPEApplication::showMainWidget( QWidget* mw, bool nomaximize )
 {
+	    setMainWidget(mw);
             d->show(mw, nomaximize );
 }
 
 /*!
   Sets widget \a mw as the mainWidget() and shows it. For small windows,
   consider passing TRUE for \a nomaximize rather than the default FALSE.
 
   This calls designates the application as
   a \link docwidget.html document-oriented\endlink application.
 
   The \a mw widget \e must have this slot: setDocument(const QString&).
 
   \sa showMainWidget()
 */
 void QPEApplication::showMainDocumentWidget( QWidget* mw, bool nomaximize )
 {
 	if ( mw && argc() == 2 )
 		Global::setDocument( mw, QString::fromUtf8(argv()[1]) );
 
 
+	setMainWidget(mw);
 	d->show(mw, nomaximize );
 }
 
 
 /*!
   If an application is started via a \link qcop.html QCop\endlink
   message, the application will process the \link qcop.html
   QCop\endlink message and then quit. If the application calls this
   function while processing a \link qcop.html QCop\endlink message,
   after processing its outstanding \link qcop.html QCop\endlink
   messages the application will start 'properly' and show itself.
 
   \sa keepRunning()
 */
 void QPEApplication::setKeepRunning()
 {
 	if ( qApp && qApp->inherits( "QPEApplication" ) ) {
 		QPEApplication * qpeApp = ( QPEApplication* ) qApp;
 		qpeApp->d->keep_running = TRUE;
 	}
 }
 
 /*!
   Returns TRUE if the application will quit after processing the
diff --git a/library/qpeapplication.h b/library/qpeapplication.h
index 729cf2b..3ef8b46 100644
--- a/library/qpeapplication.h
+++ b/library/qpeapplication.h
@@ -16,49 +16,87 @@
 ** Contact info@trolltech.com if any conditions of this licensing are
 ** not clear to you.
 **
 **********************************************************************/
 #ifndef __QPE_APPLICATION_H__
 #define __QPE_APPLICATION_H__
 
 #include <stdlib.h> // for setenv()
 
 #include <qglobal.h>
 #include <qapplication.h>
 #include <qdialog.h>
 #include <qwsdisplay_qws.h>
 #if defined(_WS_QWS_) && !defined(Q_WS_QWS)
 #define Q_WS_QWS
 #endif
 #include "qpedecoration_qws.h"
 #include "timestring.h"
 
 class QCopChannel;
 class QPEApplicationData;
 class QWSEvent;
 class QWSKeyEvent;
 
-
+/**
+  \brief The QPEApplication class implements various system services
+    that are available to all Qtopia applications.
+
+  Simply by using QPEApplication instead of QApplication, a standard Qt
+  application becomes a Qtopia application. It automatically follows
+  style changes, quits and raises, and in the
+  case of \link docwidget.html document-oriented\endlink applications,
+  changes the currently displayed document in response to the environment.
+
+  To create a \link docwidget.html document-oriented\endlink
+  application use showMainDocumentWidget(); to create a
+  non-document-oriented application use showMainWidget(). The
+  keepRunning() function indicates whether the application will
+  continue running after it's processed the last \link qcop.html
+  QCop\endlink message. This can be changed using setKeepRunning().
+
+  A variety of signals are emitted when certain events occur, for
+  example, timeChanged(), clockChanged(), weekChanged(),
+  dateFormatChanged() and volumeChanged(). If the application receives
+  a \link qcop.html QCop\endlink message on the application's
+  QPE/Application/\e{appname} channel, the appMessage() signal is
+  emitted. There are also flush() and reload() signals, which
+  are emitted when synching begins and ends respectively - upon these
+  signals, the application should save and reload any data
+  files that are involved in synching. Most of these signals will initially
+  be received and unfiltered through the appMessage() signal.
+
+  This class also provides a set of useful static functions. The
+  qpeDir() and documentDir() functions return the respective paths.
+  The grabKeyboard() and ungrabKeyboard() functions are used to
+  control whether the application takes control of the device's
+  physical buttons (e.g. application launch keys). The stylus' mode of
+  operation is set with setStylusOperation() and retrieved with
+  stylusOperation(). There are also setInputMethodHint() and
+  inputMethodHint() functions.
+
+  \ingroup qtopiaemb
+*/
 class QPEApplication : public QApplication
 {
     Q_OBJECT
 public:
     QPEApplication( int& argc, char **argv, Type=GuiClient );
     ~QPEApplication();
 
     static QString qpeDir();
     static QString documentDir();
     void applyStyle();
     void reset();
     static int defaultRotation();
     static void setDefaultRotation(int r);
     static void setCurrentRotation(int r);
     static void setCurrentMode(int x, int y, int depth );
     static void grabKeyboard();
     static void ungrabKeyboard();
 
     enum StylusMode {
         LeftOnly,
         RightOnHold
         // RightOnHoldLeftDelayed, etc.
     };
     static void setStylusOperation( QWidget*, StylusMode );
diff --git a/library/styleinterface.h b/library/styleinterface.h
index 8a900c7..872a4a5 100644
--- a/library/styleinterface.h
+++ b/library/styleinterface.h
@@ -4,64 +4,64 @@
 ** This file is part of OPIE (http://www.opie.info).
 **
 ** 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.
 **
 **********************************************************************/
 
 #ifndef STYLEINTERFACE_H
 #define STYLEINTERFACE_H
 
 #include <qpe/qcom.h>
 
 #ifndef QT_NO_COMPONENT
 
 // {17AF792C-E461-49A9-9B71-068B9A8DDAE4}
 #ifndef IID_Style
 #define IID_Style QUuid( 0x17af792c, 0xe461, 0x49a9, 0x9b, 0x71, 0x06, 0x8b, 0x9a, 0x8d, 0xda, 0xe4)
 #endif
 
-// {6C33B4F9-D529-453A-8FB3-DA42B21872BD}  
+// {6C33B4F9-D529-453A-8FB3-DA42B21872BD}
 # ifndef IID_StyleExtended
-#  define IID_StyleExtended QUuid( 0x6c33b4f9, 0xd529, 0x453a, 0x8f, 0xb3, 0xda, 0x42, 0xb2, 0x18, 0x72, 0xbd) 
+#  define IID_StyleExtended QUuid( 0x6c33b4f9, 0xd529, 0x453a, 0x8f, 0xb3, 0xda, 0x42, 0xb2, 0x18, 0x72, 0xbd)
 #endif
 
 #endif
 
 class QWidget;
 class QStyle;
 
 
 class QStyle;
 
 struct StyleInterface : public QUnknownInterface
 {
-	//! Return a new style.
+         /*! Return a new style.*/
 	virtual QStyle *style() = 0;
-	//! Return a short name for the style.
+         /*! Return a short name for the style. */
 	virtual QString name() const = 0;
 };
 
 struct StyleExtendedInterface : public StyleInterface
 {
-	//! Return a (longer) description for the style.
+        /*! Return a (longer) description for the style. */
 	virtual QString description ( ) const = 0;
 
-	//! Does this style support customization
+        /*! Does this style support customization */
 	virtual bool hasSettings ( ) const = 0;
-	
-	//! Return a new settings page.
+
+        /*! Return a new settings page. */
 	virtual QWidget *create ( QWidget *parent, const char *name = 0 ) = 0;
-	
-	//! Callback for appearance app when OK is clicked (return true when style has to re-applied).
+
+        /*! Callback for appearance app when OK is clicked (return true when style has to re-applied). */
 	virtual bool accept ( ) = 0;
-	
-	//! Callback for appeaeance app when Cancel is clicked.
+
+        /*! Callback for appeaeance app when Cancel is clicked. */
 	virtual void reject ( ) = 0;
 };
 
 #endif