3c3398408f0233c07bf6cf24799963ddf0c03527
[blender.git] / intern / ghost / GHOST_ISystem.h
1 /**
2  * $Id$
3  * ***** BEGIN GPL/BL DUAL LICENSE BLOCK *****
4  *
5  * This program is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU General Public License
7  * as published by the Free Software Foundation; either version 2
8  * of the License, or (at your option) any later version. The Blender
9  * Foundation also sells licenses for use in proprietary software under
10  * the Blender License.  See http://www.blender.org/BL/ for information
11  * about this.
12  *
13  * This program is distributed in the hope that it will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
16  * GNU General Public License for more details.
17  *
18  * You should have received a copy of the GNU General Public License
19  * along with this program; if not, write to the Free Software Foundation,
20  * Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
21  *
22  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
23  * All rights reserved.
24  *
25  * The Original Code is: all of this file.
26  *
27  * Contributor(s): none yet.
28  *
29  * ***** END GPL/BL DUAL LICENSE BLOCK *****
30  */
31
32 /**
33
34  * $Id$
35  * Copyright (C) 2001 NaN Technologies B.V.
36  * @author      Maarten Gribnau
37  * @date        May 30, 2001
38  */
39
40 #ifndef _GHOST_ISYSTEM_H_
41 #define _GHOST_ISYSTEM_H_
42
43 #include "GHOST_Types.h"
44 #include "GHOST_ITimerTask.h"
45 #include "GHOST_IWindow.h"
46
47 class GHOST_IEventConsumer;
48
49 /**
50  * Interface for classes that provide access to the operating system.
51  * There should be only one system class in an application.
52  * Therefore, the routines to create and dispose the system are static.
53  * Provides:
54  * 1. Time(r) management.
55  * 2. Display/window management (windows are only created on the main display for now).
56  * 3. Event management.
57  * 4. Access to the state of the mouse buttons and the keyboard.
58  * @author      Maarten Gribnau
59  * @date        May 30, 2001
60  */
61
62 class GHOST_ISystem
63 {
64 public:
65         /**
66          * Creates the one and only system.
67          * @return An indication of success.
68          */
69         static GHOST_TSuccess createSystem();
70
71         /**
72          * Disposes the one and only system.
73          * @return An indication of success.
74          */
75         static GHOST_TSuccess disposeSystem();
76
77         /**
78          * Returns a pointer to the one and only system (nil if it hasn't been created).
79          * @return A pointer to the system.
80          */
81         static GHOST_ISystem* getSystem();
82
83 protected:
84         /**
85          * Constructor.
86          * Protected default constructor to force use of static createSystem member.
87          */
88         GHOST_ISystem() {}
89
90         /**
91          * Destructor.
92          * Protected default constructor to force use of static dispose member.
93          */
94         virtual ~GHOST_ISystem() {}
95
96 public:
97         /***************************************************************************************
98          ** Time(r) functionality
99          ***************************************************************************************/
100
101         /**
102          * Returns the system time.
103          * Returns the number of milliseconds since the start of the system process.
104          * Based on ANSI clock() routine.
105          * @return The number of milliseconds.
106          */
107         virtual GHOST_TUns64 getMilliSeconds() const = 0;
108
109         /**
110          * Installs a timer.
111          * Note that, on most operating systems, messages need to be processed in order 
112          * for the timer callbacks to be invoked.
113          * @param delay         The time to wait for the first call to the timerProc (in milliseconds)
114          * @param interval      The interval between calls to the timerProc (in milliseconds)
115          * @param timerProc     The callback invoked when the interval expires,
116          * @param userData      Placeholder for user data.
117          * @return A timer task (0 if timer task installation failed).
118          */
119         virtual GHOST_ITimerTask* installTimer(GHOST_TUns64 delay, GHOST_TUns64 interval, GHOST_TimerProcPtr timerProc, GHOST_TUserDataPtr userData = 0) = 0;
120
121         /**
122          * Removes a timer.
123          * @param timerTask Timer task to be removed.
124          * @return Indication of success.
125          */
126         virtual GHOST_TSuccess removeTimer(GHOST_ITimerTask* timerTask) = 0;
127
128         /***************************************************************************************
129          ** Display/window management functionality
130          ***************************************************************************************/
131
132         /**
133          * Returns the number of displays on this system.
134          * @return The number of displays.
135          */
136         virtual GHOST_TUns8 getNumDisplays() const = 0;
137
138         /**
139          * Returns the dimensions of the main display on this system.
140          * @return The dimension of the main display.
141          */
142         virtual void getMainDisplayDimensions(GHOST_TUns32& width, GHOST_TUns32& height) const = 0;
143         
144         /**
145          * Create a new window.
146          * The new window is added to the list of windows managed. 
147          * Never explicitly delete the window, use disposeWindow() instead.
148          * @param       title   The name of the window (displayed in the title bar of the window if the OS supports it).
149          * @param       left            The coordinate of the left edge of the window.
150          * @param       top             The coordinate of the top edge of the window.
151          * @param       width           The width the window.
152          * @param       height          The height the window.
153          * @param       state           The state of the window when opened.
154          * @param       type            The type of drawing context installed in this window.
155          * @param       stereoVisual    Create a stereo visual for quad buffered stereo.
156          * @return      The new window (or 0 if creation failed).
157          */
158         virtual GHOST_IWindow* createWindow(
159                 const STR_String& title,
160                 GHOST_TInt32 left, GHOST_TInt32 top, GHOST_TUns32 width, GHOST_TUns32 height,
161                 GHOST_TWindowState state, GHOST_TDrawingContextType type,
162                 const bool stereoVisual) = 0;
163
164         /**
165          * Dispose a window.
166          * @param       window Pointer to the window to be disposed.
167          * @return      Indication of success.
168          */
169         virtual GHOST_TSuccess disposeWindow(GHOST_IWindow* window) = 0;
170
171         /**
172          * Returns whether a window is valid.
173          * @param       window Pointer to the window to be checked.
174          * @return      Indication of validity.
175          */
176         virtual bool validWindow(GHOST_IWindow* window) = 0;
177
178         /**
179          * Begins full screen mode.
180          * @param setting       The new setting of the display.
181          * @param window        Window displayed in full screen.
182          *                                      This window is invalid after full screen has been ended.
183          * @return      Indication of success.
184          */
185         virtual GHOST_TSuccess beginFullScreen(const GHOST_DisplaySetting& setting, GHOST_IWindow** window,
186                 const bool stereoVisual) = 0;
187
188         /**
189          * Ends full screen mode.
190          * @return      Indication of success.
191          */
192         virtual GHOST_TSuccess endFullScreen(void) = 0;
193
194         /**
195          * Returns current full screen mode status.
196          * @return The current status.
197          */
198         virtual bool getFullScreen(void) = 0;
199
200         /***************************************************************************************
201          ** Event management functionality
202          ***************************************************************************************/
203
204         /**
205          * Retrieves events from the system and stores them in the queue.
206          * @param waitForEvent Flag to wait for an event (or return immediately).
207          * @return Indication of the presence of events.
208          */
209         virtual bool processEvents(bool waitForEvent) = 0;
210         
211         /**
212          * Retrieves events from the queue and send them to the event consumers.
213          * @return Indication of the presence of events.
214          */
215         virtual bool dispatchEvents() = 0;
216
217         /**
218          * Adds the given event consumer to our list.
219          * @param consumer The event consumer to add.
220          * @return Indication of success.
221          */
222         virtual GHOST_TSuccess addEventConsumer(GHOST_IEventConsumer* consumer) = 0;
223         
224         /***************************************************************************************
225          ** Cursor management functionality
226          ***************************************************************************************/
227
228         /**
229          * Returns the current location of the cursor (location in screen coordinates)
230          * @param x                     The x-coordinate of the cursor.
231          * @param y                     The y-coordinate of the cursor.
232          * @return                      Indication of success.
233          */
234         virtual GHOST_TSuccess getCursorPosition(GHOST_TInt32& x, GHOST_TInt32& y) const = 0;
235
236         /**
237          * Updates the location of the cursor (location in screen coordinates).
238          * Not all operating systems allow the cursor to be moved (without the input device being moved).
239          * @param x                     The x-coordinate of the cursor.
240          * @param y                     The y-coordinate of the cursor.
241          * @return                      Indication of success.
242          */
243         virtual GHOST_TSuccess setCursorPosition(GHOST_TInt32 x, GHOST_TInt32 y) const = 0;
244
245         /***************************************************************************************
246          ** Access to mouse button and keyboard states.
247          ***************************************************************************************/
248
249         /**
250          * Returns the state of a modifier key (ouside the message queue).
251          * @param mask          The modifier key state to retrieve.
252          * @param isDown        The state of a modifier key (true == pressed).
253          * @return                      Indication of success.
254          */
255         virtual GHOST_TSuccess getModifierKeyState(GHOST_TModifierKeyMask mask, bool& isDown) const = 0;
256
257         /**
258          * Returns the state of a mouse button (ouside the message queue).
259          * @param mask          The button state to retrieve.
260          * @param isDown        Button state.
261          * @return                      Indication of success.
262          */
263         virtual GHOST_TSuccess getButtonState(GHOST_TButtonMask mask, bool& isDown) const = 0;
264
265 protected:
266         /**
267          * Initialize the system.
268          * @return Indication of success.
269          */
270         virtual GHOST_TSuccess init() = 0;
271
272         /**
273          * Shut the system down.
274          * @return Indication of success.
275          */
276         virtual GHOST_TSuccess exit() = 0;
277
278         /** The one and only system */
279         static GHOST_ISystem* m_system;
280 };
281
282 #endif // _GHOST_ISYSTEM_H_