Documentation for statusbar interface

git-svn-id: http://www.openflipper.org/svnrepo/OpenFlipper/branches/Free@11023 383ad7c9-94d9-4d36-a494-682f7c89f535

BasePlugin/StatusbarInterface.hh

@@ -43,20 +43,42 @@
 #ifndef STATUSBARINTERFACE_HH
 #define STATUSBARINTERFACE_HH
 
- #include <QtGui>
- #include <OpenFlipper/common/Types.hh>
- #include <QStatusBar>
+#include <QtGui>
+#include <OpenFlipper/common/Types.hh>
+#include <QStatusBar>
 
+
+/** \file StatusbarInterface.hh
+*
+* Interface for controlling OpenFlippers statusbar .\ref statusbarInterfacePage
+*/
+
+/** Namespace for Application status enum
+ *
+ */
 namespace ApplicationStatus {
   
-/** Enum for the statusBar Status Icon
- */
-enum applicationStatus { READY , PROCESSING, BLOCKED};
+  /** \brief Enum for the statusBar Status Icon
+   *
+   * This enum is used to controll the small activity icon of OpenFlipper.
+   * See \ref statusbarInterfacePage
+   */
+  enum applicationStatus {
+    READY,     //!< Status is ready (green light)
+    PROCESSING,//!< Status is processing but system will allow interaction (yellow light)
+    BLOCKED    //!< Status is processing and blocked system will not allow interaction (red light)
+  };
 
 }
 
 
- /**
+ /** \brief Control OpenFlippers status bar
+ *
+ * \ref statusbarInterfacePage "Detailed description"
+ * \n
+ *
+ * This interface can be used to send messages to OpenFlippers statusbar.
+ * It is also possible to add your own widget to the bar.
  */
 class StatusbarInterface {
 
@@ -74,13 +96,17 @@ class StatusbarInterface {
        * You can specify a timeout if the message should be removed after
        * _timeout milliseconds
        */
-      virtual void showStatusMessage(QString /*_message*/, int /*_timeout*/ = 0) {};
+      virtual void showStatusMessage(QString _message, int _timeout = 0) {};
       
       
-      /** \brief Sets the icon of the StatusBar
+      /** \brief Sets the status icon of the StatusBar
+       *
+       * OpenFlipper statusbar contains a small icon in the statusbar which can be used to indicate
+       * the current status of the application. The valid values are defined in the enum ApplicationStatus::applicationStatus.
        * 
+       * @param _status New status
        */
-      void setStatus( ApplicationStatus::applicationStatus /*_status*/) {};
+      void setStatus( ApplicationStatus::applicationStatus _status) {};
       
       /** \brief Removes the current message from the statusBar
        * 
@@ -89,11 +115,72 @@ class StatusbarInterface {
       
       /** \brief Add a widget on the right side of the statusBar
        * 
+       * Use this function if you want to add an additional widget to the statusbar.
+       * It will be added on the right side.
+       *
+       * @param _widget The widget that should be added to the statusbar
        */
-      void addWidgetToStatusbar(QWidget* /*_widget*/) {};
+      void addWidgetToStatusbar(QWidget* _widget) {};
       
 };
 
+
+/** \page statusbarInterfacePage Statusbar Interface
+\image html StatusbarInterface.png
+\n
+The StatusbarInterface can be used by plugins to send messages to OpenFlippers
+statusbar. The statusbar is located below the GL viewer.
+
+Messages can be controlled via StatusbarInterface::setStatus(),StatusbarInterface::clearStatusMessage()
+
+Additionally it is possible to add small widgets to it ( StatusbarInterface::addWidgetToStatusbar).
+
+A small icon can be controlled to indicate OpenFlippers status via StatusbarInterface::setStatus().
+
+To use the StatusbarInterface:
+<ul>
+<li> include StatusbarInterface in your plugins header file
+<li> derive your plugin from the class StatusbarInterface
+<li> add Q_INTERFACES(StatusbarInterface) to your plugin class
+<li> And add the signals or slots you want to use to your plugin class (You don't need to implement all of them)
+</ul>
+
+The following code shows a simple example to send a message to the statusbar.
+\code
+void ExamplePlugin::function()
+{
+  ...
+
+  // Print the text "Your Status Message" for 4 seconds in the statusBar
+  emit showStatusMessage( tr("Your Status Message"), 4000 );
+
+  ...
+}
+\endcode
+
+The following code shows a simple example to add a widget to the statusbar.
+Usually you should implement the BaseInterface::pluginsInitialized() function from BaseInterface.
+In this function you can setup your widget for the status bar.
+\code
+void ExamplePlugin::pluginsInitialized()
+{
+
+  // Create the widget
+  QWidget* infoBar = new QWidget();
+
+  // Setup buttons or anything else in your widget
+  ...
+
+  // Add the new widget to the statusBar
+  emit addWidgetToStatusbar(infoBar);
+
+}
+\endcode
+
+*/
+
+
+
 Q_DECLARE_INTERFACE(StatusbarInterface,"OpenFlipper.StatusbarInterface/1.0")
 
 #endif // STATUSBARINTERFACE_HH

BasePlugin/ToolbarInterface.hh

@@ -55,7 +55,7 @@
 */
 
 
-/**
+/** \brief Add a toolbox to OpenFlipper
  *
  * \ref toolbarInterfacePage "Detailed description"
  * \n

Documentation/DeveloperHelpSources/Interfaces.docu

@@ -63,6 +63,9 @@ Provides functions to create a separate widget in the toolbox on the right ( \re
 Provides a function to add toolbar buttons. ( \ref toolbarInterfacePage  )
 \n
 
+\subpage statusbarInterfacePage
+\image html StatusbarInterface.png
+This interface is used to display messages in the status bar or adding widgets to it ( \ref statusbarInterfacePage ).
 
 
 \section pluginInterfacesOtherOverview Available Interfaces for controlling other functions
@@ -137,10 +140,6 @@ This interface is used to add additional view widgets ( ViewInterface ).
 For plugins who provide scriptable functions ( ScriptInterface )
 
 
-\subsection StatusPlugin Status Bar Interface
-\image html StatusbarInterface.png
-This interface is used to display messages in the status bar ( StatusbarInterface )
-
 
 \subsection OptionsPlugin Options Interface
 \image html OptionsInterface.png