Merge branch 'event-admin-docu'

* event-admin-docu:
  Event Admin introduction and tutorial.
  Generalize the event property documentation.

Libs/PluginFramework/Documentation/CTKPluginFramework.dox

@@ -1,7 +1,10 @@
 /**
 \defgroup PluginFramework CTK Plugin Framework
 \ingroup Libs
-The CTK Plugin Framework is an OSGi like modularization framework for building cross-platform, dynamic, and modular applications. See <a href="http://www.commontk.org/index.php/Documentation/CTK_Plugin_Framework:_Introduction">Introduction to the CTK Plugin Framework</a> for an overview.
+The CTK Plugin Framework is an OSGi like modularization framework for building
+cross-platform, dynamic, and modular applications. See
+<a href="http://www.commontk.org/index.php/Documentation/Plugin_Framework">
+Introduction to the CTK Plugin Framework</a> for an overview.
 
 \defgroup ConfigAdmin Configuration Admin
 \ingroup PluginFramework
@@ -16,3 +19,20 @@ The CTK Plugin Framework is an OSGi like modularization framework for building c
 \ingroup PluginFramework
 
 */
+
+/**
+
+\page PluginFramework_Page The CTK Plugin Framework
+ 
+The CTK Plugin Framework can shortly be described as a dynamic component system
+for C++. It is directly based on the <a href="http://www.osgi.org">OSGi</a>
+specifications, hence any material explaining OSGi also applies to the CTK Plugin
+Framework (without the Java specifics, of course).
+
+Please see the <a href="http://www.commontk.org/index.php/Documentation/Plugin_Framework">
+the wiki page</a> for more information.
+
+Related pages about implemented OSGi specifications:
+
+- \subpage PluginFramework_EventAdmin_Page
+*/

Libs/PluginFramework/Documentation/CTKPluginFramework_EventAdmin.dox

@@ -0,0 +1,118 @@
+/**
+
+\page PluginFramework_EventAdmin_Page Event Admin
+
+The Event Admin Service Specification, part of the OSGi Compendium specification,
+defines a general inter-plug-in communication mechanism. The communication conforms
+to the popular publish/subscribe paradigm and can be performed in a synchronous
+or asysnchronous manner.
+
+The main components in a publish/subscribe communication are:
+
+- <b>Event Publisher</b> - sends events or messages related to a specific topic
+- <b>Event Handler</b> (or Subscriber) - expresses interest in one or more topics and
+  receives all the messages belonging to such topics.
+
+Events are composed of two attributes:
+
+- A \b topic defining the nature of the event. Topic names are usually arranged in a hierarchical namespace, where slashes are used to separate the levels (i.e. "org/commontk/PluginFrameworkEvent/STARTED") and
+- A set of \b properties describing the event.
+
+\section EventAdmin_CreatePublisher Creating an Event Publisher
+
+An event publisher can either be a simple C++ class that creates events and sends
+them using the <code>ctkEventAdmin</code> service interface or a Qt signal which
+is registered as a "publisher" using the <code>ctkEventAdmin</code> service
+interface.
+
+\subsection EventAdmin_CreatePublisher_Class Using a simple C++ class
+
+The publisher is a function which creates a <code>ctkEvent</code> object and
+sends it by using the <code>ctkEventAdmin</code> service interface.
+
+\snippet EventAdmin-Intro/ctkSnippetReportManager.h Publish event
+
+The <code>ctkEventAdmin::sendEvent()</code> method sends the <code>ctkEvent</code>
+object synchronously. To send it asynchronously, use the <code>ctkEventAdmin::postEvent()</code>
+method, such as:
+
+\snippet EventAdmin-Intro/ctkSnippetReportManager.h Publish event async
+
+\subsection EventAdmin_CreatePublisher_Signal Using a Qt signal
+
+Using a Qt signal to publish an event requires declaring a signal and registering (publishing)
+it with the Event Admin:
+
+\snippet EventAdmin-Intro/ctkSnippetReportManager.h Declare signal
+
+Register the signal using a specific topic (emitting the signal will always send
+<code>ctkEvent</code> objects with this topic as <code>EVENT_TOPIC</code> property):
+
+\snippet EventAdmin-Intro/ctkSnippetReportManager.h Register signal
+
+Emitting the signal will automatically create a <code>ctkEvent</code> object, sending
+it synchronuously or asynchronuously, depending on the Qt::ConnectionType used when
+publishing the signal.
+
+\snippet EventAdmin-Intro/ctkSnippetReportManager.h Emit signal
+
+\subsection EventAdmin_CreatePublisher_Compare Comparison
+
+The act of sending an event is simplified by using a Qt signal, after it was registered
+with the Event Admin. However, the Qt signal approach is less performant since the
+signal emission needs to go through the Qt meta object system. Further, the signal is
+tied to a specific event topic.
+
+\section EventAdmin_CreateHandler Creating and registering an Event Handler
+
+An event handler can either be a class implementing the <code>ctkEventHandler</code>
+interface which is registered as a service object or a Qt slot which is registered with the Event Admin (subscribed to certain
+topics).
+
+\subsection EventAdmin_CreateHandler_Service Event Handler as a Service
+
+Create an event handler by implementing the <code>ctkEventHandler</code> interface:
+
+\snippet EventAdmin-Intro/ctkSnippetReportManager.h Event Handler service
+
+To receive event notifications, the event handler must be registered as a service under the
+<code>ctkEventHandler</code> interface. When registering the service, a <code>QString</code>
+or <code>QStringList</code> property named <code>EVENT_TOPIC</code> must be specified. This
+property describes the list of topics in which the event handler is interested. For example:
+
+\snippet EventAdmin-Intro/main.cpp Event Handler service registration
+
+It is possible to use '*' as a wildcard in the final character of the <code>EVENT_TOPIC</code>:
+
+\snippet EventAdmin-Intro/main.cpp Event Handler service registration wildcard
+
+Finally, it is possible to specify an additional <code>EVENT_FILTER</code> property to filter
+event notifications. The filter expression follows the normal LDAP syntax:
+
+\snippet EventAdmin-Intro/main.cpp Event Handler service registration filter
+
+\subsection EventAdmin_CreateHandler_Slot Event Handler as a Qt slot
+
+Every Qt slot taking a <code>ctkEvent</code> object as an argument can be subscribed to
+receive event notifications. For example, a slot like
+
+\snippet EventAdmin-Intro/ctkSnippetReportManager.h Event Handler slot
+
+can be subscribed to receive events like
+
+\snippet EventAdmin-Intro/main.cpp Event Handler service registration slot
+
+You can use the same expressions for <code>EVENT_TOPIC</code> and
+<code>EVENT_FILTER</code> as in the examples above for registering the event
+handler as a service object implementing <code>ctkEventHandler</code>.
+
+\subsection EventAdmin_CreateHandler_Compare Comparison
+
+Registering an event handler using either the <code>ctkEventHandler</code> interface or
+a Qt slot involves approximately the same amount of code. However, using slots
+will be less performant (which might be neglectable, depending on your use case). Further,
+subscribing slots means that you require a registered Event Admin service implementation.
+The <code>ctkEventHandler</code> approach does not need to know anything about the Event
+Admin, since you register your handler as a service object in the framework.
+
+*/

Libs/PluginFramework/service/event/ctkEventConstants.h

@@ -37,14 +37,14 @@
 struct CTK_PLUGINFW_EXPORT ctkEventConstants {
 
   /**
-   * Qt slot property (named <code>event.topics</code>)
-   * specifying the <code>ctkEvent</code> topics of interest to a
-   * subscribed slot.
+   * Registration property (named <code>event.topics</code>)
+   * specifying the <code>ctkEvent</code> topics of interest to an Event Handler
+   * (a service object or a subscribed slot).
    * <p>
-   * Subscribed slots SHOULD be registered with this property. The value of the
+   * Event handlers SHOULD be registered with this property. The value of the
    * property is a QString or a QStringList that describes the topics in
    * which the handler is interested. An asterisk ('*') may be used as a
-   * trailing wildcard. Subscribed slots which do not have a value for this
+   * trailing wildcard. Event handlers which do not have a value for this
    * property must not receive events. More precisely, the value of each
    * string must conform to the following grammar:
    *
@@ -58,19 +58,19 @@ struct CTK_PLUGINFW_EXPORT ctkEventConstants {
   static const QString EVENT_TOPIC; // = "event.topics"
 
   /**
-   * Qt slot property (named <code>event.filter</code>)
+   * Registration property (named <code>event.filter</code>)
    * specifying a filter to further select <code>ctkEvent</code> s of interest to
-   * a subscribed slot.
+   * an Event Handler (a service object or a subscribed slot).
    * <p>
-   * Subscribed slots MAY be registered with this property. The value of this
+   * Event handlers MAY be registered with this property. The value of this
    * property is a QString containing an LDAP-style filter specification. Any
    * of the event's properties may be used in the filter expression. Each
-   * subscribed slot is notified for any event which belongs to the topics in
-   * which the slot has expressed an interest. If the slot is also
+   * event handler is notified for any event which belongs to the topics in
+   * which the handler has expressed an interest. If the event handler is also
    * registered with this property, then the properties of the event
-   * must also match the filter for the event to be delivered to the slot.
+   * must also match the filter for the event to be delivered to the event handler.
    * <p>
-   * If the filter syntax is invalid, then the slot must be ignored
+   * If the filter syntax is invalid, then the Event Handler must be ignored
    * and a warning should be logged.
    *
    * @see ctkEvent