Cleanup: remove redundant doxygen \file argument
[blender.git] / intern / ghost / intern / GHOST_EventManager.h
1 /*
2  * This program is free software; you can redistribute it and/or
3  * modify it under the terms of the GNU General Public License
4  * as published by the Free Software Foundation; either version 2
5  * of the License, or (at your option) any later version.
6  *
7  * This program is distributed in the hope that it will be useful,
8  * but WITHOUT ANY WARRANTY; without even the implied warranty of
9  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
10  * GNU General Public License for more details.
11  *
12  * You should have received a copy of the GNU General Public License
13  * along with this program; if not, write to the Free Software Foundation,
14  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
15  *
16  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
17  * All rights reserved.
18  */
19
20 /** \file \ingroup GHOST
21  * Declaration of GHOST_EventManager class.
22  */
23
24 #ifndef __GHOST_EVENTMANAGER_H__
25 #define __GHOST_EVENTMANAGER_H__
26
27 #include <deque>
28 #include <vector>
29
30 #include "GHOST_IEventConsumer.h"
31
32
33 /**
34  * Manages an event stack and a list of event consumers.
35  * The stack works on a FIFO (First In First Out) basis.
36  * Events are pushed on the front of the stack and retrieved from the back.
37  * Ownership of the event is transferred to the event manager as soon as an event is pushed.
38  * Ownership of the event is transferred from the event manager as soon as an event is popped.
39  * Events can be dispatched to the event consumers.
40  */
41 class GHOST_EventManager
42 {
43 public:
44         /**
45          * Constructor.
46          */
47         GHOST_EventManager();
48
49         /**
50          * Destructor.
51          */
52         ~GHOST_EventManager();
53
54         /**
55          * Returns the number of events currently on the stack.
56          * \return The number of events on the stack.
57          */
58         GHOST_TUns32 getNumEvents();
59
60         /**
61          * Returns the number of events of a certain type currently on the stack.
62          * \param type The type of events to be counted.
63          * \return The number of events on the stack of this type.
64          */
65         GHOST_TUns32 getNumEvents(GHOST_TEventType type);
66
67         /**
68          * Pushes an event on the stack.
69          * To dispatch it, call dispatchEvent() or dispatchEvents().
70          * Do not delete the event!
71          * \param event The event to push on the stack.
72          */
73         GHOST_TSuccess pushEvent(GHOST_IEvent *event);
74
75         /**
76          * Dispatches the given event directly, bypassing the event stack.
77          */
78         void dispatchEvent(GHOST_IEvent *event);
79
80         /**
81          * Dispatches the event at the back of the stack.
82          * The event will be removed from the stack.
83          */
84         void dispatchEvent();
85
86         /**
87          * Dispatches all the events on the stack.
88          * The event stack will be empty afterwards.
89          */
90         void dispatchEvents();
91
92         /**
93          * Adds a consumer to the list of event consumers.
94          * \param consumer The consumer added to the list.
95          * \return Indication as to whether addition has succeeded.
96          */
97         GHOST_TSuccess addConsumer(GHOST_IEventConsumer *consumer);
98
99         /**
100          * Removes a consumer from the list of event consumers.
101          * \param consumer The consumer removed from the list.
102          * \return Indication as to whether removal has succeeded.
103          */
104         GHOST_TSuccess removeConsumer(GHOST_IEventConsumer *consumer);
105
106         /**
107          * Removes all events for a window from the stack.
108          * \param       window  The window to remove events for.
109          */
110         void
111         removeWindowEvents(
112             GHOST_IWindow *window
113             );
114
115         /**
116          * Removes all events of a certain type from the stack.
117          * The window parameter is optional. If non-null, the routine will remove
118          * events only associated with that window.
119          * \param       type    The type of events to be removed.
120          * \param       window  The window to remove the events for.
121          */
122         void
123         removeTypeEvents(
124             GHOST_TEventType type,
125             GHOST_IWindow *window = NULL
126             );
127
128 protected:
129
130         /**
131          * Removes all events from the stack.
132          */
133         void disposeEvents();
134
135         /** A stack with events. */
136         typedef std::deque<GHOST_IEvent *> TEventStack;
137
138         /** The event stack. */
139         std::deque<GHOST_IEvent *> m_events;
140         std::deque<GHOST_IEvent *> m_handled_events;
141
142         /** A vector with event consumers. */
143         typedef std::vector<GHOST_IEventConsumer *> TConsumerVector;
144
145         /** The list with event consumers. */
146         TConsumerVector m_consumers;
147
148
149 #ifdef WITH_CXX_GUARDEDALLOC
150         MEM_CXX_CLASS_ALLOC_FUNCS("GHOST:GHOST_EventManager")
151 #endif
152 };
153
154 #endif // __GHOST_EVENTMANAGER_H__