Merged changes in the trunk up to revision 41368.
[blender.git] / intern / ghost / GHOST_C-api.h
1 /*
2  * ***** BEGIN GPL LICENSE BLOCK *****
3  *
4  * This program is free software; you can redistribute it and/or
5  * modify it under the terms of the GNU General Public License
6  * as published by the Free Software Foundation; either version 2
7  * of the License, or (at your option) any later version.
8  *
9  * This program is distributed in the hope that it will be useful,
10  * but WITHOUT ANY WARRANTY; without even the implied warranty of
11  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12  * GNU General Public License for more details.
13  *
14  * You should have received a copy of the GNU General Public License
15  * along with this program; if not, write to the Free Software Foundation,
16  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
17  *
18  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
19  * All rights reserved.
20  *
21  * The Original Code is: all of this file.
22  *
23  * Contributor(s): none yet.
24  *
25  * ***** END GPL LICENSE BLOCK *****
26  */
27 /** \ingroup GHOST
28  *
29  * \file        GHOST_C-api.h
30  * \brief GHOST C-API function and type declarations.
31  */
32
33 #ifndef GHOST_C_API_H
34 #define GHOST_C_API_H
35
36 #include "GHOST_Types.h"
37
38 #ifdef __cplusplus
39 extern "C" { 
40 #endif
41
42 /**
43  * Creates a "handle" for a C++ GHOST object.
44  * A handle is just an opaque pointer to an empty struct.
45  * In the API the pointer is casted to the actual C++ class.
46  * \param       name    Name of the handle to create.
47  */
48
49 GHOST_DECLARE_HANDLE(GHOST_SystemHandle);
50 GHOST_DECLARE_HANDLE(GHOST_TimerTaskHandle);
51 GHOST_DECLARE_HANDLE(GHOST_WindowHandle);
52 GHOST_DECLARE_HANDLE(GHOST_EventHandle);
53 GHOST_DECLARE_HANDLE(GHOST_RectangleHandle);
54 GHOST_DECLARE_HANDLE(GHOST_EventConsumerHandle);
55
56
57 /**
58  * Definition of a callback routine that receives events.
59  * @param event The event received.
60  * @param userdata The callback's user data, supplied to GHOST_CreateSystem.
61  */
62 typedef int (*GHOST_EventCallbackProcPtr)(GHOST_EventHandle event, GHOST_TUserDataPtr userdata);
63
64
65 /**
66  * Creates the one and only system.
67  * @return a handle to the system.
68  */
69 extern GHOST_SystemHandle GHOST_CreateSystem(void);
70
71 /**
72  * Disposes the one and only system.
73  * @param systemhandle The handle to the system
74  * @return An indication of success.
75  */
76 extern GHOST_TSuccess GHOST_DisposeSystem(GHOST_SystemHandle systemhandle);
77
78
79 /**
80  * Creates an event consumer object
81  * @param eventCallback The event callback routine.
82  * @param userdata              Pointer to user data returned to the callback routine.
83  */
84 extern GHOST_EventConsumerHandle GHOST_CreateEventConsumer(GHOST_EventCallbackProcPtr eventCallback, GHOST_TUserDataPtr userdata);
85
86 /**
87  * Disposes an event consumer object
88  * @param consumerhandle        Handle to the event consumer.
89  * @return An indication of success.
90  */
91 extern GHOST_TSuccess GHOST_DisposeEventConsumer(GHOST_EventConsumerHandle consumerhandle);
92
93
94 /**
95  * Returns the system time.
96  * Returns the number of milliseconds since the start of the system process.
97  * Based on ANSI clock() routine.
98  * @param systemhandle The handle to the system
99  * @return The number of milliseconds.
100  */
101 extern GHOST_TUns64 GHOST_GetMilliSeconds(GHOST_SystemHandle systemhandle);
102
103 /**
104  * Installs a timer.
105  * Note that, on most operating systems, messages need to be processed in order 
106  * for the timer callbacks to be invoked.
107  * @param systemhandle The handle to the system
108  * @param delay         The time to wait for the first call to the timerProc (in milliseconds)
109  * @param interval      The interval between calls to the timerProc (in milliseconds)
110  * @param timerProc     The callback invoked when the interval expires,
111  * @param userData      Placeholder for user data.
112  * @return A timer task (0 if timer task installation failed).
113  */
114 extern GHOST_TimerTaskHandle GHOST_InstallTimer(GHOST_SystemHandle systemhandle,
115                                                                                                 GHOST_TUns64 delay,
116                                                                                                 GHOST_TUns64 interval,
117                                                                                                 GHOST_TimerProcPtr timerProc,
118                                                                                                 GHOST_TUserDataPtr userData);
119
120 /**
121  * Removes a timer.
122  * @param systemhandle The handle to the system
123  * @param timerTask Timer task to be removed.
124  * @return Indication of success.
125  */
126 extern GHOST_TSuccess GHOST_RemoveTimer(GHOST_SystemHandle systemhandle,
127                                                                                 GHOST_TimerTaskHandle timertaskhandle);
128
129 /***************************************************************************************
130  ** Display/window management functionality
131  ***************************************************************************************/
132
133 /**
134  * Returns the number of displays on this system.
135  * @param systemhandle The handle to the system
136  * @return The number of displays.
137  */
138 extern GHOST_TUns8 GHOST_GetNumDisplays(GHOST_SystemHandle systemhandle);
139
140 /**
141  * Returns the dimensions of the main display on this system.
142  * @param systemhandle The handle to the system
143  * @param width         A pointer the width gets put in
144  * @param height        A pointer the height gets put in
145  * @return void.
146  */
147 extern void GHOST_GetMainDisplayDimensions(GHOST_SystemHandle systemhandle,
148                                                                                    GHOST_TUns32* width,
149                                                                                    GHOST_TUns32* height);
150
151 /**
152  * Create a new window.
153  * The new window is added to the list of windows managed. 
154  * Never explicitly delete the window, use disposeWindow() instead.
155  * @param systemhandle The handle to the system
156  * @param       title   The name of the window (displayed in the title bar of the window if the OS supports it).
157  * @param       left    The coordinate of the left edge of the window.
158  * @param       top             The coordinate of the top edge of the window.
159  * @param       width   The width the window.
160  * @param       height  The height the window.
161  * @param       state   The state of the window when opened.
162  * @param       type    The type of drawing context installed in this window.
163  * @param stereoVisual          Stereo visual for quad buffered stereo.
164  * @param numOfAASamples        Number of samples used for AA (zero if no AA)
165  * @return      A handle to the new window ( == NULL if creation failed).
166  */
167 extern GHOST_WindowHandle GHOST_CreateWindow(GHOST_SystemHandle systemhandle,
168         const char* title,
169         GHOST_TInt32 left,
170         GHOST_TInt32 top,
171         GHOST_TUns32 width,
172         GHOST_TUns32 height,
173         GHOST_TWindowState state,
174         GHOST_TDrawingContextType type,
175         const int stereoVisual,
176         const GHOST_TUns16 numOfAASamples);
177
178 /**
179  * Returns the window user data.
180  * @param windowhandle  The handle to the window
181  * @return The window user data.
182  */
183 extern GHOST_TUserDataPtr GHOST_GetWindowUserData(GHOST_WindowHandle windowhandle);
184         
185 /**
186  * Changes the window user data.
187  * @param windowhandle  The handle to the window
188  * @param data The window user data.
189  */
190 extern void GHOST_SetWindowUserData(GHOST_WindowHandle windowhandle, 
191         GHOST_TUserDataPtr userdata);
192
193 /**
194  * Dispose a window.
195  * @param systemhandle The handle to the system
196  * @param       window Handle to the window to be disposed.
197  * @return      Indication of success.
198  */
199 extern GHOST_TSuccess GHOST_DisposeWindow(GHOST_SystemHandle systemhandle,
200                                                                                   GHOST_WindowHandle windowhandle);
201
202 /**
203  * Returns whether a window is valid.
204  * @param systemhandle The handle to the system
205  * @param       window Handle to the window to be checked.
206  * @return      Indication of validity.
207  */
208 extern int GHOST_ValidWindow(GHOST_SystemHandle systemhandle,
209                                                                                 GHOST_WindowHandle windowhandle);
210
211 /**
212  * Begins full screen mode.
213  * @param systemhandle The handle to the system
214  * @param setting       The new setting of the display.
215  * @return                      A handle to the window displayed in full screen.
216  *                                      This window is invalid after full screen has been ended.
217  */
218 extern GHOST_WindowHandle GHOST_BeginFullScreen(GHOST_SystemHandle systemhandle,
219         GHOST_DisplaySetting* setting,
220         const int stereoVisual);
221
222 /**
223  * Ends full screen mode.
224  * @param systemhandle The handle to the system
225  * @return      Indication of success.
226  */
227 extern GHOST_TSuccess GHOST_EndFullScreen(GHOST_SystemHandle systemhandle);
228
229 /**
230  * Returns current full screen mode status.
231  * @param systemhandle The handle to the system
232  * @return The current status.
233  */
234 extern int GHOST_GetFullScreen(GHOST_SystemHandle systemhandle);
235
236 /***************************************************************************************
237  ** Event management functionality
238  ***************************************************************************************/
239
240 /**
241  * Retrieves events from the system and stores them in the queue.
242  * @param systemhandle The handle to the system
243  * @param waitForEvent Boolean to indicate that ProcessEvents should
244  * wait (block) until the next event before returning.
245  * @return Indication of the presence of events.
246  */
247 extern int GHOST_ProcessEvents(GHOST_SystemHandle systemhandle, int waitForEvent);
248
249 /**
250  * Retrieves events from the queue and send them to the event consumers.
251  * @param systemhandle The handle to the system
252  * @return Indication of the presence of events.
253  */
254 extern int GHOST_DispatchEvents(GHOST_SystemHandle systemhandle);
255
256 /**
257  * Adds the given event consumer to our list.
258  * @param systemhandle The handle to the system
259  * @param consumerhandle The event consumer to add.
260  * @return Indication of success.
261  */
262 extern GHOST_TSuccess GHOST_AddEventConsumer(GHOST_SystemHandle systemhandle,
263                                                                                           GHOST_EventConsumerHandle consumerhandle);
264
265 /**
266  * Remove the given event consumer to our list.
267  * @param systemhandle The handle to the system
268  * @param consumerhandle The event consumer to remove.
269  * @return Indication of success.
270  */
271 extern GHOST_TSuccess GHOST_RemoveEventConsumer(GHOST_SystemHandle systemhandle,
272                                                                                           GHOST_EventConsumerHandle consumerhandle);
273
274 /***************************************************************************************
275  ** Progress bar functionality
276  ***************************************************************************************/
277
278 /**
279  * Sets the progress bar value displayed in the window/application icon
280  * @param windowhandle The handle to the window
281  * @param progress The progress % (0.0 to 1.0)
282  */
283 extern GHOST_TSuccess GHOST_SetProgressBar(GHOST_WindowHandle windowhandle, float progress);
284
285 /**
286  * Hides the progress bar in the icon
287  * @param windowhandle The handle to the window
288  */
289 extern GHOST_TSuccess GHOST_EndProgressBar(GHOST_WindowHandle windowhandle);
290
291 /***************************************************************************************
292  ** Cursor management functionality
293  ***************************************************************************************/
294
295 /**
296  * Returns the current cursor shape.
297  * @param windowhandle The handle to the window
298  * @return      The current cursor shape.
299  */
300 extern GHOST_TStandardCursor GHOST_GetCursorShape(GHOST_WindowHandle windowhandle);
301
302 /**
303  * Set the shape of the cursor.
304  * @param windowhandle The handle to the window
305  * @param       cursor  The new cursor shape type id.
306  * @return      Indication of success.
307  */
308 extern GHOST_TSuccess GHOST_SetCursorShape(GHOST_WindowHandle windowhandle,
309                                                                                    GHOST_TStandardCursor cursorshape);
310
311 /**
312  * Set the shape of the cursor to a custom cursor.
313  * @param windowhandle The handle to the window
314  * @param       bitmap  The bitmap data for the cursor.
315  * @param       mask    The mask data for the cursor.
316  * @param       hotX    The X coordinate of the cursor hotspot.
317  * @param       hotY    The Y coordinate of the cursor hotspot.
318  * @return      Indication of success.
319  */
320 extern GHOST_TSuccess GHOST_SetCustomCursorShape(GHOST_WindowHandle windowhandle,
321                                                                                                  GHOST_TUns8 bitmap[16][2], 
322                                                                                                  GHOST_TUns8 mask[16][2], 
323                                                                                                  int hotX, 
324                                                                                                  int hotY);
325 /**
326  * Set the shape of the cursor to a custom cursor of specified size.
327  * @param windowhandle The handle to the window
328  * @param       bitmap  The bitmap data for the cursor.
329  * @param       mask    The mask data for the cursor.
330  * @parm    sizex, sizey  The size of the cursor
331  * @param       hotX    The X coordinate of the cursor hotspot.
332  * @param       hotY    The Y coordinate of the cursor hotspot.
333  * @param   fg_color, bg_color  Colors of the cursor
334  * @return      Indication of success.
335   */
336 extern GHOST_TSuccess GHOST_SetCustomCursorShapeEx(GHOST_WindowHandle windowhandle,
337                                                                                                  GHOST_TUns8 *bitmap, 
338                                                                                                  GHOST_TUns8 *mask, 
339                                                                                                  int sizex, int sizey, 
340                                                                                                  int hotX,  int hotY,
341                                                                                                  int fg_color, int bg_color );
342
343 /**
344  * Returns the visibility state of the cursor.
345  * @param windowhandle The handle to the window
346  * @return      The visibility state of the cursor.
347  */
348 extern int GHOST_GetCursorVisibility(GHOST_WindowHandle windowhandle);
349
350 /**
351  * Shows or hides the cursor.
352  * @param windowhandle The handle to the window
353  * @param       visible The new visibility state of the cursor.
354  * @return      Indication of success.
355  */
356 extern GHOST_TSuccess GHOST_SetCursorVisibility(GHOST_WindowHandle windowhandle,
357                                                                                                 int visible);
358
359 /**
360  * Returns the current location of the cursor (location in screen coordinates)
361  * @param systemhandle The handle to the system
362  * @param x                     The x-coordinate of the cursor.
363  * @param y                     The y-coordinate of the cursor.
364  * @return                      Indication of success.
365  */
366 extern GHOST_TSuccess GHOST_GetCursorPosition(GHOST_SystemHandle systemhandle,
367                                                                                           GHOST_TInt32* x,
368                                                                                           GHOST_TInt32* y);
369
370 /**
371  * Updates the location of the cursor (location in screen coordinates).
372  * Not all operating systems allow the cursor to be moved (without the input device being moved).
373  * @param systemhandle The handle to the system
374  * @param x                     The x-coordinate of the cursor.
375  * @param y                     The y-coordinate of the cursor.
376  * @return                      Indication of success.
377  */
378 extern GHOST_TSuccess GHOST_SetCursorPosition(GHOST_SystemHandle systemhandle,
379                                                                                           GHOST_TInt32 x,
380                                                                                           GHOST_TInt32 y);
381
382 /**
383  * Grabs the cursor for a modal operation, to keep receiving
384  * events when the mouse is outside the window. X11 only, others
385  * do this automatically.
386  * @param windowhandle The handle to the window
387  * @param       mode The new grab state of the cursor.
388  * @param       bounds The grab ragion (optional) - left,top,right,bottom
389  * @return      Indication of success.
390  */
391 extern GHOST_TSuccess GHOST_SetCursorGrab(GHOST_WindowHandle windowhandle,
392                                                                                                 GHOST_TGrabCursorMode mode,
393                                                                                                 int* bounds);
394
395 /***************************************************************************************
396  ** Access to mouse button and keyboard states.
397  ***************************************************************************************/
398
399 /**
400  * Returns the state of a modifier key (ouside the message queue).
401  * @param systemhandle The handle to the system
402  * @param mask          The modifier key state to retrieve.
403  * @param isDown        Pointer to return modifier state in.
404  * @return                      Indication of success.
405  */
406 extern GHOST_TSuccess GHOST_GetModifierKeyState(GHOST_SystemHandle systemhandle,
407                                                                                                 GHOST_TModifierKeyMask mask,
408                                                                                                 int* isDown);
409
410 /**
411  * Returns the state of a mouse button (ouside the message queue).
412  * @param systemhandle The handle to the system
413  * @param mask          The button state to retrieve.
414  * @param isDown        Pointer to return button state in.
415  * @return                      Indication of success.
416  */
417 extern GHOST_TSuccess GHOST_GetButtonState(GHOST_SystemHandle systemhandle,
418                                                                                    GHOST_TButtonMask mask,
419                                                                                    int* isDown);
420
421
422 /***************************************************************************************
423  ** Drag'n'drop operations
424  ***************************************************************************************/
425
426 /**
427  * Tells if the ongoing drag'n'drop object can be accepted upon mouse drop
428  */
429 extern void GHOST_setAcceptDragOperation(GHOST_WindowHandle windowhandle, GHOST_TInt8 canAccept);
430         
431         
432 /**
433  * Returns the event type.
434  * @param eventhandle The handle to the event
435  * @return The event type.
436  */
437 extern GHOST_TEventType GHOST_GetEventType(GHOST_EventHandle eventhandle);
438
439 /**
440  * Returns the time this event was generated.
441  * @param eventhandle The handle to the event
442  * @return The event generation time.
443  */
444 extern GHOST_TUns64 GHOST_GetEventTime(GHOST_EventHandle eventhandle);
445
446 /**
447  * Returns the window this event was generated on, 
448  * or NULL if it is a 'system' event.
449  * @param eventhandle The handle to the event
450  * @return The generating window.
451  */
452 extern GHOST_WindowHandle GHOST_GetEventWindow(GHOST_EventHandle eventhandle);
453
454 /**
455  * Returns the event data.
456  * @param eventhandle The handle to the event
457  * @return The event data.
458  */
459 extern GHOST_TEventDataPtr GHOST_GetEventData(GHOST_EventHandle eventhandle);
460
461 /**
462  * Returns the timer callback.
463  * @param timertaskhandle       The handle to the timertask
464  * @return The timer callback.
465  */
466 extern GHOST_TimerProcPtr GHOST_GetTimerProc(GHOST_TimerTaskHandle timertaskhandle);
467
468 /**
469  * Changes the timer callback.
470  * @param timertaskhandle The handle to the timertask
471  * @param timerProc The timer callback.
472  */
473 extern void GHOST_SetTimerProc(GHOST_TimerTaskHandle timertaskhandle,
474                                                            GHOST_TimerProcPtr timerProc);
475
476 /**
477  * Returns the timer user data.
478  * @param timertaskhandle       The handle to the timertask
479  * @return The timer user data.
480  */
481 extern GHOST_TUserDataPtr GHOST_GetTimerTaskUserData(GHOST_TimerTaskHandle timertaskhandle);
482         
483 /**
484  * Changes the time user data.
485  * @param timertaskhandle       The handle to the timertask
486  * @param data The timer user data.
487  */
488 extern void GHOST_SetTimerTaskUserData(GHOST_TimerTaskHandle timertaskhandle,
489                                                                            GHOST_TUserDataPtr userData);
490
491 /**
492  * Returns indication as to whether the window is valid.
493  * @param windowhandle The handle to the window
494  * @return The validity of the window.
495  */
496 extern int GHOST_GetValid(GHOST_WindowHandle windowhandle) ;
497
498 /**
499  * Returns the type of drawing context used in this window.
500  * @param windowhandle The handle to the window
501  * @return The current type of drawing context.
502  */
503 extern GHOST_TDrawingContextType GHOST_GetDrawingContextType(GHOST_WindowHandle windowhandle);
504
505 /**
506  * Tries to install a rendering context in this window.
507  * @param windowhandle The handle to the window
508  * @param type  The type of rendering context installed.
509  * @return Indication as to whether installation has succeeded.
510  */
511 extern GHOST_TSuccess GHOST_SetDrawingContextType(GHOST_WindowHandle windowhandle,
512                                                                                                   GHOST_TDrawingContextType type);
513
514 /**
515  * Sets the title displayed in the title bar.
516  * @param windowhandle The handle to the window
517  * @param title The title to display in the title bar.
518  */
519 extern void GHOST_SetTitle(GHOST_WindowHandle windowhandle,
520                                                    const char* title);
521
522 /**
523  * Returns the title displayed in the title bar. The title
524  * should be free'd with free().
525  * 
526  * @param windowhandle The handle to the window
527  * @return The title, free with free().
528  */
529 extern char* GHOST_GetTitle(GHOST_WindowHandle windowhandle);
530
531 /**
532  * Returns the window rectangle dimensions.
533  * These are screen coordinates.
534  * @param windowhandle The handle to the window
535  * @return A handle to the bounding rectangle of the window.
536  */
537 extern GHOST_RectangleHandle GHOST_GetWindowBounds(GHOST_WindowHandle windowhandle);
538
539 /**
540  * Returns the client rectangle dimensions.
541  * The left and top members of the rectangle are always zero.
542  * @param windowhandle The handle to the window
543  * @return A handle to the bounding rectangle of the window.
544  */
545 extern GHOST_RectangleHandle GHOST_GetClientBounds(GHOST_WindowHandle windowhandle);
546
547 /**
548  * Disposes a rectangle object
549  * @param rectanglehandle       Handle to the rectangle.
550  */
551 void GHOST_DisposeRectangle(GHOST_RectangleHandle rectanglehandle);
552
553 /**
554  * Resizes client rectangle width.
555  * @param windowhandle The handle to the window
556  * @param width The new width of the client area of the window.
557  * @return      Indication of success.
558  */
559 extern GHOST_TSuccess GHOST_SetClientWidth(GHOST_WindowHandle windowhandle,
560                                                                                    GHOST_TUns32 width);
561
562 /**
563  * Resizes client rectangle height.
564  * @param windowhandle The handle to the window
565  * @param height The new height of the client area of the window.
566  * @return      Indication of success.
567  */
568 extern GHOST_TSuccess GHOST_SetClientHeight(GHOST_WindowHandle windowhandle,
569                                                                                         GHOST_TUns32 height);
570
571 /**
572  * Resizes client rectangle.
573  * @param windowhandle The handle to the window
574  * @param width         The new width of the client area of the window.
575  * @param height        The new height of the client area of the window.
576  * @return                      Indication of success.
577  */
578 extern GHOST_TSuccess GHOST_SetClientSize(GHOST_WindowHandle windowhandle,
579                                                                                   GHOST_TUns32 width,
580                                                                                   GHOST_TUns32 height);
581
582 /**
583  * Converts a point in screen coordinates to client rectangle coordinates
584  * @param windowhandle The handle to the window
585  * @param inX   The x-coordinate on the screen.
586  * @param inY   The y-coordinate on the screen.
587  * @param outX  The x-coordinate in the client rectangle.
588  * @param outY  The y-coordinate in the client rectangle.
589  */
590 extern void GHOST_ScreenToClient(GHOST_WindowHandle windowhandle,
591                                                                  GHOST_TInt32 inX,
592                                                                  GHOST_TInt32 inY,
593                                                                  GHOST_TInt32* outX,
594                                                                  GHOST_TInt32* outY) ;
595
596 /**
597  * Converts a point in screen coordinates to client rectangle coordinates
598  * @param windowhandle The handle to the window
599  * @param inX   The x-coordinate in the client rectangle.
600  * @param inY   The y-coordinate in the client rectangle.
601  * @param outX  The x-coordinate on the screen.
602  * @param outY  The y-coordinate on the screen.
603  */
604 extern void GHOST_ClientToScreen(GHOST_WindowHandle windowhandle,
605                                                                  GHOST_TInt32 inX,
606                                                                  GHOST_TInt32 inY,
607                                                                  GHOST_TInt32* outX,
608                                                                  GHOST_TInt32* outY);
609
610 /**
611  * Returns the state of the window (normal, minimized, maximized).
612  * @param windowhandle The handle to the window
613  * @return The state of the window.
614  */
615 extern GHOST_TWindowState GHOST_GetWindowState(GHOST_WindowHandle windowhandle);
616
617 /**
618  * Sets the state of the window (normal, minimized, maximized).
619  * @param windowhandle The handle to the window
620  * @param state The state of the window.
621  * @return Indication of success.
622  */
623 extern GHOST_TSuccess GHOST_SetWindowState(GHOST_WindowHandle windowhandle,
624                                                                                    GHOST_TWindowState state);
625
626         
627 /**
628  * Sets the window "modified" status, indicating unsaved changes
629  * @param windowhandle The handle to the window
630  * @param isUnsavedChanges Unsaved changes or not
631  * @return Indication of success.
632  */
633 extern GHOST_TSuccess GHOST_SetWindowModifiedState(GHOST_WindowHandle windowhandle,
634                                                                                                    GHOST_TUns8 isUnsavedChanges);
635         
636 /**
637  * Sets the order of the window (bottom, top).
638  * @param windowhandle The handle to the window
639  * @param order The order of the window.
640  * @return Indication of success.
641  */
642 extern GHOST_TSuccess GHOST_SetWindowOrder(GHOST_WindowHandle windowhandle,
643                                                                                    GHOST_TWindowOrder order);
644
645 /**
646  * Swaps front and back buffers of a window.
647  * @param windowhandle The handle to the window
648  * @return      An intean success indicator.
649  */
650 extern GHOST_TSuccess GHOST_SwapWindowBuffers(GHOST_WindowHandle windowhandle);
651
652 /**
653  * Activates the drawing context of this window.
654  * @param windowhandle The handle to the window
655  * @return      An intean success indicator.
656  */
657 extern GHOST_TSuccess GHOST_ActivateWindowDrawingContext(GHOST_WindowHandle windowhandle);
658
659 /**
660  * Invalidates the contents of this window.
661  * @param windowhandle The handle to the window
662  * @return Indication of success.
663  */
664 extern GHOST_TSuccess GHOST_InvalidateWindow(GHOST_WindowHandle windowhandle);
665
666 /**
667  * Returns the status of the tablet
668  * @param windowhandle The handle to the window
669  * @return Status of tablet
670  */
671 extern const GHOST_TabletData *GHOST_GetTabletData(GHOST_WindowHandle windowhandle);
672
673 /**
674  * Access to rectangle width.
675  * @param rectanglehandle The handle to the rectangle
676  * @return      width of the rectangle
677  */
678 extern GHOST_TInt32 GHOST_GetWidthRectangle(GHOST_RectangleHandle rectanglehandle);
679
680 /**
681  * Access to rectangle height.
682  * @param rectanglehandle The handle to the rectangle
683  * @return      height of the rectangle
684  */
685 extern GHOST_TInt32 GHOST_GetHeightRectangle(GHOST_RectangleHandle rectanglehandle);
686
687 /**
688  * Gets all members of the rectangle.
689  * @param rectanglehandle The handle to the rectangle
690  * @param       l       Pointer to return left coordinate in.
691  * @param       t       Pointer to return top coordinate in.
692  * @param       r       Pointer to return right coordinate in.
693  * @param       b       Pointer to return bottom coordinate in.
694  */
695 extern void GHOST_GetRectangle(GHOST_RectangleHandle rectanglehandle,
696                                                            GHOST_TInt32* l,
697                                                            GHOST_TInt32* t,
698                                                            GHOST_TInt32* r,
699                                                            GHOST_TInt32* b);
700
701 /**
702  * Sets all members of the rectangle.
703  * @param rectanglehandle The handle to the rectangle
704  * @param       l       requested left coordinate of the rectangle
705  * @param       t       requested top coordinate of the rectangle
706  * @param       r       requested right coordinate of the rectangle
707  * @param       b       requested bottom coordinate of the rectangle
708  */
709 extern void GHOST_SetRectangle(GHOST_RectangleHandle rectanglehandle,
710                                                            GHOST_TInt32 l,
711                                                            GHOST_TInt32 t,
712                                                            GHOST_TInt32 r,
713                                                            GHOST_TInt32 b);
714
715 /**
716  * Returns whether this rectangle is empty.
717  * Empty rectangles are rectangles that have width==0 and/or height==0.
718  * @param rectanglehandle The handle to the rectangle
719  * @return      intean value (true == empty rectangle)
720  */
721 extern GHOST_TSuccess GHOST_IsEmptyRectangle(GHOST_RectangleHandle rectanglehandle);
722
723 /**
724  * Returns whether this rectangle is valid.
725  * Valid rectangles are rectangles that have m_l <= m_r and m_t <= m_b. Thus, emapty rectangles are valid.
726  * @param rectanglehandle The handle to the rectangle
727  * @return      intean value (true==valid rectangle)
728  */
729 extern GHOST_TSuccess GHOST_IsValidRectangle(GHOST_RectangleHandle rectanglehandle);
730
731 /**
732  * Grows (or shrinks the rectangle).
733  * The method avoids negative insets making the rectangle invalid
734  * @param rectanglehandle The handle to the rectangle
735  * @param       i       The amount of offset given to each extreme (negative values shrink the rectangle).
736  */
737 extern void GHOST_InsetRectangle(GHOST_RectangleHandle rectanglehandle,
738                                                                  GHOST_TInt32 i);
739
740 /**
741  * Does a union of the rectangle given and this rectangle.
742  * The result is stored in this rectangle.
743  * @param rectanglehandle The handle to the rectangle
744  * @param       r       The rectangle that is input for the union operation.
745  */
746 extern void GHOST_UnionRectangle(GHOST_RectangleHandle rectanglehandle,
747                                                                  GHOST_RectangleHandle anotherrectanglehandle);
748
749 /**
750  * Grows the rectangle to included a point.
751  * @param rectanglehandle The handle to the rectangle
752  * @param       x       The x-coordinate of the point.
753  * @param       y       The y-coordinate of the point.
754  */
755 extern void GHOST_UnionPointRectangle(GHOST_RectangleHandle rectanglehandle,
756                                                                           GHOST_TInt32 x,
757                                                                           GHOST_TInt32 y);
758
759 /**
760  * Returns whether the point is inside this rectangle.
761  * Point on the boundary is considered inside.
762  * @param rectanglehandle The handle to the rectangle
763  * @param x     x-coordinate of point to test.
764  * @param y y-coordinate of point to test.
765  * @return intean value (true if point is inside).
766  */
767 extern GHOST_TSuccess GHOST_IsInsideRectangle(GHOST_RectangleHandle rectanglehandle,
768                                                                                           GHOST_TInt32 x,
769                                                                                           GHOST_TInt32 y);
770
771 /**
772  * Returns whether the rectangle is inside this rectangle.
773  * @param rectanglehandle The handle to the rectangle
774  * @param       r       rectangle to test.
775  * @return      visibility (not, partially or fully visible).
776  */
777 extern GHOST_TVisibility GHOST_GetRectangleVisibility(GHOST_RectangleHandle rectanglehandle,
778                                                                                                           GHOST_RectangleHandle anotherrectanglehandle);
779
780 /**
781  * Sets rectangle members.
782  * Sets rectangle members such that it is centered at the given location.
783  * @param rectanglehandle The handle to the rectangle
784  * @param       cx      requested center x-coordinate of the rectangle
785  * @param       cy      requested center y-coordinate of the rectangle
786  */
787 extern void GHOST_SetCenterRectangle(GHOST_RectangleHandle rectanglehandle,
788                                                                          GHOST_TInt32 cx,
789                                                                          GHOST_TInt32 cy);
790
791 /**
792  * Sets rectangle members.
793  * Sets rectangle members such that it is centered at the given location,
794  * with the width requested.
795  * @param rectanglehandle The handle to the rectangle
796  * @param       cx      requested center x-coordinate of the rectangle
797  * @param       cy      requested center y-coordinate of the rectangle
798  * @param       w       requested width of the rectangle
799  * @param       h       requested height of the rectangle
800  */
801 extern void GHOST_SetRectangleCenter(GHOST_RectangleHandle rectanglehandle,
802                                                                          GHOST_TInt32 cx,
803                                                                          GHOST_TInt32 cy,
804                                                                          GHOST_TInt32 w,
805                                                                          GHOST_TInt32 h);
806
807 /**
808  * Clips a rectangle.
809  * Updates the rectangle given such that it will fit within this one.
810  * This can result in an empty rectangle.
811  * @param rectanglehandle The handle to the rectangle
812  * @param       r       the rectangle to clip
813  * @return      whether clipping has occurred
814  */
815 extern GHOST_TSuccess GHOST_ClipRectangle(GHOST_RectangleHandle rectanglehandle,
816                                                                                   GHOST_RectangleHandle anotherrectanglehandle);
817
818 /**
819  * Return the data from the clipboad
820  * @param       return the selection instead, X11 only feature
821  * @return      clipboard data
822  */
823 extern GHOST_TUns8* GHOST_getClipboard(int selection);
824
825 /**
826  * Put data to the Clipboard
827  * @param       set the selection instead, X11 only feature
828  */
829 extern void GHOST_putClipboard(GHOST_TInt8 *buffer, int selection);
830
831
832
833 /**
834  * Toggles console
835  * @action      0 - Hides
836  *                      1 - Shows
837  *                      2 - Toggles
838  *                      3 - Hides if it runs not from  command line
839  *                      * - Does nothing
840  * @return current status (1 -visible, 0 - hidden)
841  */
842 extern int GHOST_toggleConsole(int action);
843
844 #ifdef __cplusplus
845 }
846 #endif
847
848 #endif