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
@@ -12,21 +12,54 @@
 
 #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
@@ -28,14 +28,29 @@ 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
@@ -24,16 +24,29 @@
 #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
@@ -430,18 +430,18 @@ static void setTreble( int t = 0, int percent = -1 )
                                 }
 #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.
@@ -1566,16 +1566,17 @@ void QPEApplication::pidMessage( const QCString& msg, const QByteArray& data)
 /*!
   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
@@ -1586,16 +1587,17 @@ void QPEApplication::showMainWidget( QWidget* mw, bool nomaximize )
   \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
diff --git a/library/qpeapplication.h b/library/qpeapplication.h
index 729cf2b..3ef8b46 100644
--- a/library/qpeapplication.h
+++ b/library/qpeapplication.h
@@ -32,17 +32,55 @@
 #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();
diff --git a/library/styleinterface.h b/library/styleinterface.h
index 8a900c7..872a4a5 100644
--- a/library/styleinterface.h
+++ b/library/styleinterface.h
@@ -20,48 +20,48 @@
 
 #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