2 * @file Common/ieventqueue.h
3 * @brief Event queue interfaces
6 * Copyright (c) 2011 Enar Vaikene
8 * This file is part of the eVaf C++ cross-platform application development framework.
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.
16 * Alternatively, this file may be used in accordance with the Commercial License
17 * Agreement provided with the Software.
20 #ifndef __COMMON_IEVENTQUEUE_H
21 #define __COMMON_IEVENTQUEUE_H
23 #include "libcommon.h"
32 * The eVaf event queue interface
33 * @code#include <Common/iEventQueue>@endcode
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.
39 class COMMON_EXPORT iEventQueue
: public QObject
45 /// Interface constructor
46 iEventQueue() : QObject() {}
48 /// Empty virtual destructor
49 virtual ~iEventQueue() {}
53 * @param name Name of the event
54 * @return Unique ID of the event
56 * This function registers an event and returns a unique ID for the event. The event ID value
57 * is always greater than zero.
59 * If an event with the given name already exists, then returns the event ID for the existing
62 virtual uint
registerEvent(QString
const & name
) = 0;
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
69 * This function returns the ID of the event or zero if no such event is found.
71 virtual uint
queryEvent(QString
const & name
) const = 0;
74 * Unregisters an event
75 * @param id The ID of the event
77 * This function removes an event. It also unsubscribes all the subscribers from this event.
79 virtual void unregisterEvent(uint id
) = 0;
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
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.
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
94 * int myEventId = iEventQueue::instance()->subscribeEvent(iEventQueue::instance()->queryEvent("my-event"), this);
97 virtual uint
subscribeEvent(uint id
, QObject
* obj
) = 0;
100 * Unsubscribes from an event
101 * @param id The ID of the event (can be zero)
102 * @param obj The subscriber object
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.
107 virtual void unsubscribeEvent(uint id
, QObject
* obj
) = 0;
110 * Sends the event to all the subscribers
111 * @param event The event object
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.
116 * The event object shall be allocated in the heap.
118 virtual void broadcastEvent(Event
* event
) = 0;
122 } // namespace eVaf::Common
125 #endif // ieventqueue.h