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

   1 /**
   2  * @file Common/ieventqueue.h
   3  * @brief Event queue interfaces
   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 /**
  32  * The eVaf event queue interface
  33  * @code#include <Common/iEventQueue>@endcode
  34  *
  35  * This interface is used to work with eVaf events. Functions in this interface register new events,
  36  * subscribe to existing events and broadcast events to the rest of the application.
  37  * Events are implemented using the Qt event loop.
  38  */
  39 class COMMON_EXPORT iEventQueue : public QObject
  40 {
  41     Q_OBJECT
  42
  43 public:
  44
  45     /// Interface constructor
  46     iEventQueue() : QObject() {}
  47
  48     /// Empty virtual destructor
  49     virtual ~iEventQueue() {}
  50
  51     /**
  52      * Registers an event
  53      * @param name Name of the event
  54      * @return Unique ID of the event
  55      *
  56      * This function registers an event and returns a unique ID for the event. The event ID value
  57      * is always greater than zero.
  58      *
  59      * If an event with the given name already exists, then returns the event ID for the existing
  60      * event.
  61      */
  62     virtual uint registerEvent(QString const & name) = 0;
  63
  64     /**
  65      * Queries for an existing event
  66      * @param name Name of the event
  67      * @return The ID of the event or 0 if not found
  68      *
  69      * This function returns the ID of the event or zero if no such event is found.
  70      */
  71     virtual uint queryEvent(QString const & name) const = 0;
  72
  73     /**
  74      * Unregisters an event
  75      * @param id The ID of the event
  76      *
  77      * This function removes an event. It also unsubscribes all the subscribers from this event.
  78      */
  79     virtual void unregisterEvent(uint id) = 0;
  80
  81     /**
  82      * Subscribes to an event
  83      * @param id The ID of the event (can be zero)
  84      * @param obj The subscriber object
  85      * @param return The ID of the event; or zero if failed to subscribe
  86      *
  87      * This function subscribes to an event identified by the ID value. Every object that wants to
  88      * receive specific events, needs to subscribe to them.
  89      *
  90      * The id parameter can be zero and the following example code is correct even when the event
  91      * called "my-event" does not exist. The value of myEventId will be set to zero if the event
  92      * does not exist.
  93      * @code
  94      * int myEventId = iEventQueue::instance()->subscribeEvent(iEventQueue::instance()->queryEvent("my-event"), this);
  95      * @endcode
  96      */
  97     virtual uint subscribeEvent(uint id, QObject * obj) = 0;
  98
  99     /**
 100      * Unsubscribes from an event
 101      * @param id The ID of the event (can be zero)
 102      * @param obj The subscriber object
 103      *
 104      * This function removes the subscriber object from the list of subscribers for the given event identified
 105      * by the event ID value. After this function call the subscriber does no more receive these events.
 106      */
 107     virtual void unsubscribeEvent(uint id, QObject * obj) = 0;
 108
 109     /**
 110      * Sends the event to all the subscribers
 111      * @param event The event object
 112      *
 113      * This function sends the event to all the subscribers. The event object is destroyed when the event loop
 114      * is finished for this event.
 115      *
 116      * The event object shall be allocated in the heap.
 117      */
 118     virtual void broadcastEvent(Event * event) = 0;
 119
 120 };
 121
 122 } // namespace eVaf::Common
 123 } // namespace eVaf
 124
 125 #endif // ieventqueue.h