vaikene.ee Git - evaf/blob - src/libs/Common/ieventqueue.h

   1 /**
   2  * @file Common/ieventqueue.h
   3  * @brief Event queue interface
   4  * @author Enar Vaikene
   5  *
   6  * Copyright (c) 2011 Enar Vaikene
   7  *
   8  * This file is part of the eVaf C++ cross-platform application development framework.
   9  *
  10  * This file can be used under the terms of the GNU General Public License
  11  * version 3.0 as published by the Free Software Foundation and appearing in
  12  * the file LICENSE included in the packaging of this file. Please review the
  13  * the following information to ensure the GNU General Public License version
  14  * 3.0 requirements will be met: http://www.gnu.org/copyleft/gpl.html.
  15  *
  16  * Alternatively, this file may be used in accordance with the Commercial License
  17  * Agreement provided with the Software.
  18  */
  19
  20 #ifndef __COMMON_IEVENTQUEUE_H
  21 #define __COMMON_IEVENTQUEUE_H
  22
  23 #include "libcommon.h"
  24
  25 #include <QObject>
  26 #include <QString>
  27
  28 namespace eVaf {
  29 namespace Common {
  30
  31 class Event;
  32
  33 /**
  34  * The eVaf event queue interface
  35  * @code#include <Common/iEventQueue>@endcode
  36  *
  37  * This interface is used to work with eVaf events. Functions in this interface register new events,
  38  * subscribe to existing events and broadcast events to the rest of the application.
  39  * Events are implemented using the Qt event loop.
  40  */
  41 class COMMON_EXPORT iEventQueue : public QObject
  42 {
  43     Q_OBJECT
  44
  45 public:
  46
  47     /// Interface constructor
  48     iEventQueue() : QObject() {}
  49
  50     /// Empty virtual destructor
  51     virtual ~iEventQueue() {}
  52
  53     /**
  54      * Returns the instance of the iEventQueue interface
  55      * @return The iEventQueue interface
  56      */
  57     static iEventQueue * instance();
  58
  59     /**
  60      * Registers an event
  61      * @param name Name of the event
  62      * @return Unique ID of the event
  63      *
  64      * This function registers an event and returns a unique ID for the event. The event ID value
  65      * is always greater than zero.
  66      *
  67      * If an event with the given name already exists, then returns the event ID for the existing
  68      * event.
  69      */
  70     virtual uint registerEvent(QString const & name) = 0;
  71
  72     /**
  73      * Queries for an existing event
  74      * @param name Name of the event
  75      * @return The ID of the event or 0 if not found
  76      *
  77      * This function returns the ID of the event or zero if no such event is found.
  78      */
  79     virtual uint queryEvent(QString const & name) const = 0;
  80
  81     /**
  82      * Unregisters an event
  83      * @param id The ID of the event
  84      *
  85      * This function removes an event. It also unsubscribes all the subscribers from this event.
  86      */
  87     virtual void unregisterEvent(uint id) = 0;
  88
  89     /**
  90      * Subscribes to an event
  91      * @param id The ID of the event (can be zero)
  92      * @param obj The subscriber object
  93      * @return The ID of the event; or zero if failed to subscribe
  94      *
  95      * This function subscribes to an event identified by the ID value. Every object that wants to
  96      * receive specific events, needs to subscribe to them.
  97      *
  98      * The id parameter can be zero and the following example code is correct even when the event
  99      * called "my-event" does not exist. The value of myEventId will be set to zero if the event
 100      * does not exist.
 101      * @code
 102      * int myEventId = iEventQueue::instance()->subscribeEvent(iEventQueue::instance()->queryEvent("my-event"), this);
 103      * @endcode
 104      */
 105     virtual uint subscribeEvent(uint id, QObject * obj) = 0;
 106
 107     /**
 108      * Unsubscribes from an event
 109      * @param id The ID of the event (can be zero)
 110      * @param obj The subscriber object
 111      *
 112      * This function removes the subscriber object from the list of subscribers for the given event identified
 113      * by the event ID value. After this function call the subscriber does no more receive these events.
 114      */
 115     virtual void unsubscribeEvent(uint id, QObject * obj) = 0;
 116
 117     /**
 118      * Sends the event to all the subscribers
 119      * @param event The event object
 120      *
 121      * This function sends the event to all the subscribers. The event object is destroyed when the event loop
 122      * is finished for this event.
 123      *
 124      * The event object shall be allocated in the heap.
 125      */
 126     virtual void broadcastEvent(Event * event) = 0;
 127
 128 };
 129
 130 } // namespace eVaf::Common
 131 } // namespace eVaf
 132
 133 #endif // ieventqueue.h