]> vaikene.ee Git - evaf/blob - src/libs/Common/ieventqueue.h
Fixed mistake in the documentation.
[evaf] / 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