Cleanup: remove redundant doxygen \file argument
[blender.git] / intern / ghost / GHOST_IWindow.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_IWindow interface class.
22  */
23
24 #ifndef __GHOST_IWINDOW_H__
25 #define __GHOST_IWINDOW_H__
26
27 #include "STR_String.h"
28 #include "GHOST_Rect.h"
29 #include "GHOST_Types.h"
30
31
32 /**
33  * Interface for GHOST windows.
34  *
35  * You can create a window with the system's GHOST_ISystem::createWindow
36  * method.
37  * \see GHOST_ISystem#createWindow
38  *
39  * There are two coordinate systems:
40  *
41  * - The screen coordinate system. The origin of the screen is located in the
42  *   upper left corner of the screen.</li>
43  * - The client rectangle coordinate system. The client rectangle of a window
44  *   is the area that is drawable by the application (excluding title bars etc.).
45  */
46 class GHOST_IWindow
47 {
48 public:
49         /**
50          * Destructor.
51          */
52         virtual ~GHOST_IWindow()
53         {
54         }
55
56         /**
57          * Returns indication as to whether the window is valid.
58          * \return The validity of the window.
59          */
60         virtual bool getValid() const = 0;
61
62         /**
63          * Returns the associated OS object/handle
64          * \return The associated OS object/handle
65          */
66         virtual void *getOSWindow() const = 0;
67
68         /**
69          * Returns the type of drawing context used in this window.
70          * \return The current type of drawing context.
71          */
72         virtual GHOST_TDrawingContextType getDrawingContextType() = 0;
73
74         /**
75          * Tries to install a rendering context in this window.
76          * \param type  The type of rendering context installed.
77          * \return Indication as to whether installation has succeeded.
78          */
79         virtual GHOST_TSuccess setDrawingContextType(GHOST_TDrawingContextType type) = 0;
80
81         /**
82          * Sets the title displayed in the title bar.
83          * \param title The title to display in the title bar.
84          */
85         virtual void setTitle(const STR_String& title) = 0;
86
87         /**
88          * Returns the title displayed in the title bar.
89          * \param title The title displayed in the title bar.
90          */
91         virtual void getTitle(STR_String& title) const = 0;
92
93         /**
94          * Returns the window rectangle dimensions.
95          * These are screen coordinates.
96          * \param bounds The bounding rectangle of the window.
97          */
98         virtual void getWindowBounds(GHOST_Rect& bounds) const = 0;
99
100         /**
101          * Returns the client rectangle dimensions.
102          * The left and top members of the rectangle are always zero.
103          * \param bounds The bounding rectangle of the client area of the window.
104          */
105         virtual void getClientBounds(GHOST_Rect& bounds) const = 0;
106
107         /**
108          * Resizes client rectangle width.
109          * \param width The new width of the client area of the window.
110          */
111         virtual GHOST_TSuccess setClientWidth(GHOST_TUns32 width) = 0;
112
113         /**
114          * Resizes client rectangle height.
115          * \param height The new height of the client area of the window.
116          */
117         virtual GHOST_TSuccess setClientHeight(GHOST_TUns32 height) = 0;
118
119         /**
120          * Resizes client rectangle.
121          * \param width     The new width of the client area of the window.
122          * \param height    The new height of the client area of the window.
123          */
124         virtual GHOST_TSuccess setClientSize(GHOST_TUns32 width, GHOST_TUns32 height) = 0;
125
126         /**
127          * Converts a point in screen coordinates to client rectangle coordinates
128          * \param inX   The x-coordinate on the screen.
129          * \param inY   The y-coordinate on the screen.
130          * \param outX  The x-coordinate in the client rectangle.
131          * \param outY  The y-coordinate in the client rectangle.
132          */
133         virtual void screenToClient(GHOST_TInt32 inX, GHOST_TInt32 inY, GHOST_TInt32& outX, GHOST_TInt32& outY) const = 0;
134
135         /**
136          * Converts a point in screen coordinates to client rectangle coordinates
137          * \param inX   The x-coordinate in the client rectangle.
138          * \param inY   The y-coordinate in the client rectangle.
139          * \param outX  The x-coordinate on the screen.
140          * \param outY  The y-coordinate on the screen.
141          */
142         virtual void clientToScreen(GHOST_TInt32 inX, GHOST_TInt32 inY, GHOST_TInt32& outX, GHOST_TInt32& outY) const = 0;
143
144         /**
145          * Tells if the ongoing drag'n'drop object can be accepted upon mouse drop
146          */
147         virtual void setAcceptDragOperation(bool canAccept) = 0;
148
149         /**
150          * Returns acceptance of the dropped object
151          * Usually called by the "object dropped" event handling function
152          */
153         virtual bool canAcceptDragOperation() const = 0;
154
155         /**
156          * Returns the state of the window (normal, minimized, maximized).
157          * \return The state of the window.
158          */
159         virtual GHOST_TWindowState getState() const = 0;
160
161         /**
162          * Sets the state of the window (normal, minimized, maximized).
163          * \param state The state of the window.
164          * \return Indication of success.
165          */
166         virtual GHOST_TSuccess setState(GHOST_TWindowState state) = 0;
167
168         /**
169          * Sets the window "modified" status, indicating unsaved changes
170          * \param isUnsavedChanges Unsaved changes or not
171          * \return Indication of success.
172          */
173         virtual GHOST_TSuccess setModifiedState(bool isUnsavedChanges) = 0;
174
175         /**
176          * Gets the window "modified" status, indicating unsaved changes
177          * \return True if there are unsaved changes
178          */
179         virtual bool getModifiedState() = 0;
180
181         /**
182          * Sets the order of the window (bottom, top).
183          * \param order The order of the window.
184          * \return Indication of success.
185          */
186         virtual GHOST_TSuccess setOrder(GHOST_TWindowOrder order) = 0;
187
188         /**
189          * Swaps front and back buffers of a window.
190          * \return  A boolean success indicator.
191          */
192         virtual GHOST_TSuccess swapBuffers() = 0;
193
194         /**
195          * Sets the swap interval for swapBuffers.
196          * \param interval The swap interval to use.
197          * \return A boolean success indicator.
198          */
199         virtual GHOST_TSuccess setSwapInterval(int interval) = 0;
200
201         /**
202          * Gets the current swap interval for swapBuffers.
203          * \param intervalOut pointer to location to return swap interval (left untouched if there is an error)
204          * \return A boolean success indicator of if swap interval was successfully read.
205          */
206         virtual GHOST_TSuccess getSwapInterval(int& intervalOut) = 0;
207
208         /**
209          * Gets the current swap interval for swapBuffers.
210          * \return Number of AA Samples (0 if there is no multisample buffer)
211          */
212         virtual GHOST_TUns16 getNumOfAASamples() = 0;
213
214         /**
215          * Activates the drawing context of this window.
216          * \return  A boolean success indicator.
217          */
218         virtual GHOST_TSuccess activateDrawingContext() = 0;
219
220         /**
221          * Invalidates the contents of this window.
222          * \return Indication of success.
223          */
224         virtual GHOST_TSuccess invalidate() = 0;
225
226         /**
227          * Returns the window user data.
228          * \return The window user data.
229          */
230         virtual GHOST_TUserDataPtr getUserData() const = 0;
231
232         /**
233          * Changes the window user data.
234          * \param userData The window user data.
235          */
236         virtual void setUserData(const GHOST_TUserDataPtr userData) = 0;
237
238         /**
239          * Returns the tablet data (pressure etc).
240          * \return The tablet data (pressure etc).
241          */
242         virtual const GHOST_TabletData *GetTabletData() = 0;
243
244         /***************************************************************************************
245          * Progress bar functionality
246          ***************************************************************************************/
247
248         /**
249          * Sets the progress bar value displayed in the window/application icon
250          * \param progress The progress %
251          */
252         virtual GHOST_TSuccess setProgressBar(float progress) = 0;
253
254         /**
255          * Hides the progress bar in the icon
256          */
257         virtual GHOST_TSuccess endProgressBar() = 0;
258
259         /***************************************************************************************
260          * Cursor management functionality
261          ***************************************************************************************/
262
263         /**
264          * Returns the current cursor shape.
265          * \return  The current cursor shape.
266          */
267         virtual GHOST_TStandardCursor getCursorShape() const = 0;
268
269         /**
270          * Set the shape of the cursor.
271          * \param cursorShape:  The new cursor shape type id.
272          * \return Indication of success.
273          */
274         virtual GHOST_TSuccess setCursorShape(GHOST_TStandardCursor cursorShape) = 0;
275
276         /**
277          * Set the shape of the cursor to a custom cursor.
278          * \param   bitmap  The bitmap data for the cursor.
279          * \param   mask    The mask data for the cursor.
280          * \param   hotX    The X coordinate of the cursor hotspot.
281          * \param   hotY    The Y coordinate of the cursor hotspot.
282          * \return  Indication of success.
283          */
284         virtual GHOST_TSuccess setCustomCursorShape(GHOST_TUns8 bitmap[16][2],
285                                                     GHOST_TUns8 mask[16][2],
286                                                     int hotX,
287                                                     int hotY) = 0;
288
289         virtual GHOST_TSuccess setCustomCursorShape(GHOST_TUns8 *bitmap,
290                                                     GHOST_TUns8 *mask,
291                                                     int sizex, int sizey,
292                                                     int hotX, int hotY,
293                                                     int fg_color, int bg_color) = 0;
294
295         /**
296          * Returns the visibility state of the cursor.
297          * \return  The visibility state of the cursor.
298          */
299         virtual bool getCursorVisibility() const = 0;
300
301         /**
302          * Shows or hides the cursor.
303          * \param   visible The new visibility state of the cursor.
304          * \return  Indication of success.
305          */
306         virtual GHOST_TSuccess setCursorVisibility(bool visible) = 0;
307
308         /**
309          * Grabs the cursor for a modal operation.
310          * \param   grab The new grab state of the cursor.
311          * \return  Indication of success.
312          */
313         virtual GHOST_TSuccess setCursorGrab(GHOST_TGrabCursorMode /*mode*/,
314                                              GHOST_Rect * /*bounds*/,
315                                              GHOST_TInt32 /*mouse_ungrab_xy*/[2]) { return GHOST_kSuccess; }
316
317         /** */
318         virtual GHOST_TSuccess beginFullScreen() const = 0;
319         virtual GHOST_TSuccess endFullScreen() const = 0;
320
321         virtual float getNativePixelSize(void) = 0;
322
323         /**
324          * Returns the recommended DPI for this window.
325          * \return The recommended DPI for this window.
326          */
327         virtual GHOST_TUns16 getDPIHint() = 0;
328
329 #ifdef WITH_INPUT_IME
330         /**
331          * Enable IME attached to the given window, i.e. allows user-input
332          * events to be dispatched to the IME.
333          * \param x Requested x-coordinate of the rectangle
334          * \param y Requested y-coordinate of the rectangle
335          * \param w Requested width of the rectangle
336          * \param h Requested height of the rectangle
337          * \param complete Whether or not to complete the ongoing composition
338          * true:  Start a new composition
339          * false: Move the IME windows to the given position without finishing it.
340          */
341         virtual void beginIME(
342                 GHOST_TInt32 x, GHOST_TInt32 y,
343                 GHOST_TInt32 w, GHOST_TInt32 h,
344                 int completed) = 0;
345
346         /**
347          * Disable the IME attached to the given window, i.e. prohibits any user-input
348          * events from being dispatched to the IME.
349          */
350         virtual void endIME() = 0;
351 #endif /* WITH_INPUT_IME */
352
353 #ifdef WITH_CXX_GUARDEDALLOC
354         MEM_CXX_CLASS_ALLOC_FUNCS("GHOST:GHOST_IWindow")
355 #endif
356 };
357
358 #endif // __GHOST_IWINDOW_H__