Event Admin introduction and tutorial.

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.
+
+*/