Merge branch 'master' into blender2.8
[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  * The 'name' argument to the macro is the 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 GHOST_DECLARE_HANDLE(GHOST_ContextHandle);
56
57
58 /**
59  * Definition of a callback routine that receives events.
60  * \param event The event received.
61  * \param userdata The callback's user data, supplied to GHOST_CreateSystem.
62  */
63 typedef int (*GHOST_EventCallbackProcPtr)(GHOST_EventHandle event, GHOST_TUserDataPtr userdata);
64
65
66 /**
67  * Creates the one and only system.
68  * \return a handle to the system.
69  */
70 extern GHOST_SystemHandle GHOST_CreateSystem(void);
71
72 /**
73  * Disposes the one and only system.
74  * \param systemhandle The handle to the system
75  * \return An indication of success.
76  */
77 extern GHOST_TSuccess GHOST_DisposeSystem(GHOST_SystemHandle systemhandle);
78
79
80 /**
81  * Creates an event consumer object
82  * \param eventCallback The event callback routine.
83  * \param userdata Pointer to user data returned to the callback routine.
84  */
85 extern GHOST_EventConsumerHandle GHOST_CreateEventConsumer(GHOST_EventCallbackProcPtr eventCallback,
86                                                            GHOST_TUserDataPtr userdata);
87
88 /**
89  * Disposes an event consumer object
90  * \param consumerhandle Handle to the event consumer.
91  * \return An indication of success.
92  */
93 extern GHOST_TSuccess GHOST_DisposeEventConsumer(GHOST_EventConsumerHandle consumerhandle);
94
95 /**
96  * Returns the system time.
97  * Returns the number of milliseconds since the start of the system process.
98  * Based on ANSI clock() routine.
99  * \param systemhandle The handle to the system
100  * \return The number of milliseconds.
101  */
102 extern GHOST_TUns64 GHOST_GetMilliSeconds(GHOST_SystemHandle systemhandle);
103
104 /**
105  * Installs a timer.
106  * Note that, on most operating systems, messages need to be processed in order
107  * for the timer callbacks to be invoked.
108  * \param systemhandle The handle to the system
109  * \param delay The time to wait for the first call to the timerProc (in milliseconds)
110  * \param interval The interval between calls to the timerProc (in milliseconds)
111  * \param timerProc The callback invoked when the interval expires,
112  * \param userData Placeholder for user data.
113  * \return A timer task (0 if timer task installation failed).
114  */
115 extern GHOST_TimerTaskHandle GHOST_InstallTimer(GHOST_SystemHandle systemhandle,
116                                                 GHOST_TUns64 delay,
117                                                 GHOST_TUns64 interval,
118                                                 GHOST_TimerProcPtr timerProc,
119                                                 GHOST_TUserDataPtr userData);
120
121 /**
122  * Removes a timer.
123  * \param systemhandle The handle to the system
124  * \param timertaskhandle Timer task to be removed.
125  * \return Indication of success.
126  */
127 extern GHOST_TSuccess GHOST_RemoveTimer(GHOST_SystemHandle systemhandle,
128                                         GHOST_TimerTaskHandle timertaskhandle);
129
130 /***************************************************************************************
131  * Display/window management functionality
132  ***************************************************************************************/
133
134 /**
135  * Returns the number of displays on this system.
136  * \param systemhandle The handle to the system
137  * \return The number of displays.
138  */
139 extern GHOST_TUns8 GHOST_GetNumDisplays(GHOST_SystemHandle systemhandle);
140
141 /**
142  * Returns the dimensions of the main display on this system.
143  * \param systemhandle The handle to the system
144  * \param width A pointer the width gets put in
145  * \param height A pointer the height gets put in
146  * \return void.
147  */
148 extern void GHOST_GetMainDisplayDimensions(GHOST_SystemHandle systemhandle,
149                                            GHOST_TUns32 *width,
150                                            GHOST_TUns32 *height);
151
152 /**
153  * Returns the dimensions of all displays combine
154  * (the current workspace).
155  * No need to worry about overlapping monitors.
156  * \param systemhandle The handle to the system
157  * \param width A pointer the width gets put in
158  * \param height A pointer the height gets put in
159  * \return void.
160  */
161 extern void GHOST_GetAllDisplayDimensions(GHOST_SystemHandle systemhandle,
162                                            GHOST_TUns32 *width,
163                                            GHOST_TUns32 *height);
164
165
166 /**
167  * Create a new window.
168  * The new window is added to the list of windows managed.
169  * Never explicitly delete the window, use disposeWindow() instead.
170  * \param systemhandle The handle to the system
171  * \param title The name of the window (displayed in the title bar of the window if the OS supports it).
172  * \param left The coordinate of the left edge of the window.
173  * \param top The coordinate of the top edge of the window.
174  * \param width The width the window.
175  * \param height The height the window.
176  * \param state The state of the window when opened.
177  * \param type The type of drawing context installed in this window.
178  * \param glSettings: Misc OpenGL options.
179  * \return A handle to the new window ( == NULL if creation failed).
180  */
181 extern GHOST_WindowHandle GHOST_CreateWindow(
182         GHOST_SystemHandle systemhandle,
183         const char *title,
184         GHOST_TInt32 left,
185         GHOST_TInt32 top,
186         GHOST_TUns32 width,
187         GHOST_TUns32 height,
188         GHOST_TWindowState state,
189         GHOST_TDrawingContextType type,
190         GHOST_GLSettings glSettings);
191
192 /**
193  * Create a new offscreen context.
194  * Never explicitly delete the context, use disposeContext() instead.
195  * \param systemhandle The handle to the system
196  * \return A handle to the new context ( == NULL if creation failed).
197  */
198 extern GHOST_ContextHandle GHOST_CreateOpenGLContext(GHOST_SystemHandle systemhandle);
199
200 /**
201  * Dispose of a context.
202  * \param systemhandle The handle to the system
203  * \param contexthandle Handle to the context to be disposed.
204  * \return Indication of success.
205  */
206 extern GHOST_TSuccess GHOST_DisposeOpenGLContext(GHOST_SystemHandle systemhandle,
207                                                     GHOST_ContextHandle contexthandle);
208
209 /**
210  * Returns the window user data.
211  * \param windowhandle The handle to the window
212  * \return The window user data.
213  */
214 extern GHOST_TUserDataPtr GHOST_GetWindowUserData(GHOST_WindowHandle windowhandle);
215
216 /**
217  * Changes the window user data.
218  * \param windowhandle The handle to the window
219  * \param userdata The window user data.
220  */
221 extern void GHOST_SetWindowUserData(GHOST_WindowHandle windowhandle,
222                                     GHOST_TUserDataPtr userdata);
223
224 /**
225  * Dispose a window.
226  * \param systemhandle The handle to the system
227  * \param windowhandle Handle to the window to be disposed.
228  * \return Indication of success.
229  */
230 extern GHOST_TSuccess GHOST_DisposeWindow(GHOST_SystemHandle systemhandle,
231                                           GHOST_WindowHandle windowhandle);
232
233 /**
234  * Returns whether a window is valid.
235  * \param systemhandle The handle to the system
236  * \param windowhandle Handle to the window to be checked.
237  * \return Indication of validity.
238  */
239 extern int GHOST_ValidWindow(GHOST_SystemHandle systemhandle,
240                              GHOST_WindowHandle windowhandle);
241
242 /**
243  * Begins full screen mode.
244  * \param systemhandle The handle to the system
245  * \param setting The new setting of the display.
246  * \param stereoVisual Option for stereo display.
247  * \return A handle to the window displayed in full screen.
248  *         This window is invalid after full screen has been ended.
249  */
250 extern GHOST_WindowHandle GHOST_BeginFullScreen(GHOST_SystemHandle systemhandle,
251                                                 GHOST_DisplaySetting *setting,
252                                                 const int stereoVisual);
253
254 /**
255  * Ends full screen mode.
256  * \param systemhandle The handle to the system
257  * \return Indication of success.
258  */
259 extern GHOST_TSuccess GHOST_EndFullScreen(GHOST_SystemHandle systemhandle);
260
261 /**
262  * Returns current full screen mode status.
263  * \param systemhandle The handle to the system
264  * \return The current status.
265  */
266 extern int GHOST_GetFullScreen(GHOST_SystemHandle systemhandle);
267
268 /***************************************************************************************
269  * Event management functionality
270  ***************************************************************************************/
271
272 /**
273  * Retrieves events from the system and stores them in the queue.
274  * \param systemhandle The handle to the system
275  * \param waitForEvent Boolean to indicate that ProcessEvents should
276  * wait (block) until the next event before returning.
277  * \return Indication of the presence of events.
278  */
279 extern int GHOST_ProcessEvents(GHOST_SystemHandle systemhandle, int waitForEvent);
280
281 /**
282  * Retrieves events from the queue and send them to the event consumers.
283  * \param systemhandle The handle to the system
284  */
285 extern void GHOST_DispatchEvents(GHOST_SystemHandle systemhandle);
286
287 /**
288  * Adds the given event consumer to our list.
289  * \param systemhandle The handle to the system
290  * \param consumerhandle The event consumer to add.
291  * \return Indication of success.
292  */
293 extern GHOST_TSuccess GHOST_AddEventConsumer(GHOST_SystemHandle systemhandle,
294                                              GHOST_EventConsumerHandle consumerhandle);
295
296 /**
297  * Remove the given event consumer to our list.
298  * \param systemhandle The handle to the system
299  * \param consumerhandle The event consumer to remove.
300  * \return Indication of success.
301  */
302 extern GHOST_TSuccess GHOST_RemoveEventConsumer(GHOST_SystemHandle systemhandle,
303                                                 GHOST_EventConsumerHandle consumerhandle);
304
305 /***************************************************************************************
306  * Progress bar functionality
307  ***************************************************************************************/
308
309 /**
310  * Sets the progress bar value displayed in the window/application icon
311  * \param windowhandle The handle to the window
312  * \param progress The progress % (0.0 to 1.0)
313  */
314 extern GHOST_TSuccess GHOST_SetProgressBar(GHOST_WindowHandle windowhandle, float progress);
315
316 /**
317  * Hides the progress bar in the icon
318  * \param windowhandle The handle to the window
319  */
320 extern GHOST_TSuccess GHOST_EndProgressBar(GHOST_WindowHandle windowhandle);
321
322 /***************************************************************************************
323  * Cursor management functionality
324  ***************************************************************************************/
325
326 /**
327  * Returns the current cursor shape.
328  * \param windowhandle The handle to the window
329  * \return The current cursor shape.
330  */
331 extern GHOST_TStandardCursor GHOST_GetCursorShape(GHOST_WindowHandle windowhandle);
332
333 /**
334  * Set the shape of the cursor.
335  * \param windowhandle The handle to the window
336  * \param cursorshape The new cursor shape type id.
337  * \return Indication of success.
338  */
339 extern GHOST_TSuccess GHOST_SetCursorShape(GHOST_WindowHandle windowhandle,
340                                            GHOST_TStandardCursor cursorshape);
341
342 /**
343  * Set the shape of the cursor to a custom cursor.
344  * \param windowhandle The handle to the window
345  * \param bitmap The bitmap data for the cursor.
346  * \param  mask The mask data for the cursor.
347  * \param hotX The X coordinate of the cursor hotspot.
348  * \param hotY The Y coordinate of the cursor hotspot.
349  * \return Indication of success.
350  */
351 extern GHOST_TSuccess GHOST_SetCustomCursorShape(GHOST_WindowHandle windowhandle,
352                                                  GHOST_TUns8 bitmap[16][2],
353                                                  GHOST_TUns8 mask[16][2],
354                                                  int hotX,
355                                                  int hotY);
356 /**
357  * Set the shape of the cursor to a custom cursor of specified size.
358  * \param windowhandle The handle to the window
359  * \param bitmap The bitmap data for the cursor.
360  * \param mask The mask data for the cursor.
361  * \param sizex The width of the cursor
362  * \param sizey The height of the cursor
363  * \param hotX The X coordinate of the cursor hotspot.
364  * \param hotY The Y coordinate of the cursor hotspot.
365  * \param   fg_color, bg_color  Colors of the cursor
366  * \return Indication of success.
367  */
368 extern GHOST_TSuccess GHOST_SetCustomCursorShapeEx(GHOST_WindowHandle windowhandle,
369                                                    GHOST_TUns8 *bitmap,
370                                                    GHOST_TUns8 *mask,
371                                                    int sizex, int sizey,
372                                                    int hotX,  int hotY,
373                                                    int fg_color, int bg_color);
374
375 /**
376  * Returns the visibility state of the cursor.
377  * \param windowhandle The handle to the window
378  * \return The visibility state of the cursor.
379  */
380 extern int GHOST_GetCursorVisibility(GHOST_WindowHandle windowhandle);
381
382 /**
383  * Shows or hides the cursor.
384  * \param windowhandle The handle to the window
385  * \param visible The new visibility state of the cursor.
386  * \return Indication of success.
387  */
388 extern GHOST_TSuccess GHOST_SetCursorVisibility(GHOST_WindowHandle windowhandle,
389                                                 int visible);
390
391 /**
392  * Returns the current location of the cursor (location in screen coordinates)
393  * \param systemhandle The handle to the system
394  * \param x The x-coordinate of the cursor.
395  * \param y The y-coordinate of the cursor.
396  * \return Indication of success.
397  */
398 extern GHOST_TSuccess GHOST_GetCursorPosition(GHOST_SystemHandle systemhandle,
399                                               GHOST_TInt32 *x,
400                                               GHOST_TInt32 *y);
401
402 /**
403  * Updates the location of the cursor (location in screen coordinates).
404  * Not all operating systems allow the cursor to be moved (without the input device being moved).
405  * \param systemhandle The handle to the system
406  * \param x The x-coordinate of the cursor.
407  * \param y The y-coordinate of the cursor.
408  * \return Indication of success.
409  */
410 extern GHOST_TSuccess GHOST_SetCursorPosition(GHOST_SystemHandle systemhandle,
411                                               GHOST_TInt32 x,
412                                               GHOST_TInt32 y);
413
414 /**
415  * Grabs the cursor for a modal operation, to keep receiving
416  * events when the mouse is outside the window. X11 only, others
417  * do this automatically.
418  * \param windowhandle The handle to the window
419  * \param mode The new grab state of the cursor.
420  * \param bounds The grab region (optional) - left,top,right,bottom
421  * \param mouse_ungrab_xy XY for new mouse location (optional) - x,y
422  * \return Indication of success.
423  */
424 extern GHOST_TSuccess GHOST_SetCursorGrab(GHOST_WindowHandle windowhandle,
425                                           GHOST_TGrabCursorMode mode,
426                                           int bounds[4], const int mouse_ungrab_xy[2]);
427
428 /***************************************************************************************
429  * Access to mouse button and keyboard states.
430  ***************************************************************************************/
431
432 /**
433  * Returns the state of a modifier key (ouside the message queue).
434  * \param systemhandle The handle to the system
435  * \param mask The modifier key state to retrieve.
436  * \param isDown Pointer to return modifier state in.
437  * \return Indication of success.
438  */
439 extern GHOST_TSuccess GHOST_GetModifierKeyState(GHOST_SystemHandle systemhandle,
440                                                 GHOST_TModifierKeyMask mask,
441                                                 int *isDown);
442
443 /**
444  * Returns the state of a mouse button (ouside the message queue).
445  * \param systemhandle The handle to the system
446  * \param mask The button state to retrieve.
447  * \param isDown Pointer to return button state in.
448  * \return Indication of success.
449  */
450 extern GHOST_TSuccess GHOST_GetButtonState(GHOST_SystemHandle systemhandle,
451                                            GHOST_TButtonMask mask,
452                                            int *isDown);
453
454 #ifdef WITH_INPUT_NDOF
455 /***************************************************************************************
456  * Access to 3D mouse.
457  ***************************************************************************************/
458
459 /**
460  * Sets 3D mouse deadzone
461  * \param deadzone Deadzone of the 3D mouse (both for rotation and pan) relative to full range
462  */
463 extern void GHOST_setNDOFDeadZone(float deadzone);
464 #endif
465
466
467 /***************************************************************************************
468  * Drag'n'drop operations
469  ***************************************************************************************/
470
471 /**
472  * Tells if the ongoing drag'n'drop object can be accepted upon mouse drop
473  */
474 extern void GHOST_setAcceptDragOperation(GHOST_WindowHandle windowhandle, GHOST_TInt8 canAccept);
475
476 /**
477  * Returns the event type.
478  * \param eventhandle The handle to the event
479  * \return The event type.
480  */
481 extern GHOST_TEventType GHOST_GetEventType(GHOST_EventHandle eventhandle);
482
483 /**
484  * Returns the time this event was generated.
485  * \param eventhandle The handle to the event
486  * \return The event generation time.
487  */
488 extern GHOST_TUns64 GHOST_GetEventTime(GHOST_EventHandle eventhandle);
489
490 /**
491  * Returns the window this event was generated on,
492  * or NULL if it is a 'system' event.
493  * \param eventhandle The handle to the event
494  * \return The generating window.
495  */
496 extern GHOST_WindowHandle GHOST_GetEventWindow(GHOST_EventHandle eventhandle);
497
498 /**
499  * Returns the event data.
500  * \param eventhandle The handle to the event
501  * \return The event data.
502  */
503 extern GHOST_TEventDataPtr GHOST_GetEventData(GHOST_EventHandle eventhandle);
504
505 /**
506  * Returns the timer callback.
507  * \param timertaskhandle The handle to the timertask
508  * \return The timer callback.
509  */
510 extern GHOST_TimerProcPtr GHOST_GetTimerProc(GHOST_TimerTaskHandle timertaskhandle);
511
512 /**
513  * Changes the timer callback.
514  * \param timertaskhandle The handle to the timertask
515  * \param timerProc The timer callback.
516  */
517 extern void GHOST_SetTimerProc(GHOST_TimerTaskHandle timertaskhandle,
518                                GHOST_TimerProcPtr timerProc);
519
520 /**
521  * Returns the timer user data.
522  * \param timertaskhandle The handle to the timertask
523  * \return The timer user data.
524  */
525 extern GHOST_TUserDataPtr GHOST_GetTimerTaskUserData(GHOST_TimerTaskHandle timertaskhandle);
526
527 /**
528  * Changes the time user data.
529  * \param timertaskhandle The handle to the timertask
530  * \param userdata The timer user data.
531  */
532 extern void GHOST_SetTimerTaskUserData(GHOST_TimerTaskHandle timertaskhandle,
533                                        GHOST_TUserDataPtr userdata);
534
535 /**
536  * Returns indication as to whether the window is valid.
537  * \param windowhandle The handle to the window
538  * \return The validity of the window.
539  */
540 extern int GHOST_GetValid(GHOST_WindowHandle windowhandle);
541
542 /**
543  * Returns the type of drawing context used in this window.
544  * \param windowhandle The handle to the window
545  * \return The current type of drawing context.
546  */
547 extern GHOST_TDrawingContextType GHOST_GetDrawingContextType(GHOST_WindowHandle windowhandle);
548
549 /**
550  * Tries to install a rendering context in this window.
551  * \param windowhandle The handle to the window
552  * \param type The type of rendering context installed.
553  * \return Indication as to whether installation has succeeded.
554  */
555 extern GHOST_TSuccess GHOST_SetDrawingContextType(GHOST_WindowHandle windowhandle,
556                                                   GHOST_TDrawingContextType type);
557
558 /**
559  * Sets the title displayed in the title bar.
560  * \param windowhandle The handle to the window
561  * \param title The title to display in the title bar.
562  */
563 extern void GHOST_SetTitle(GHOST_WindowHandle windowhandle,
564                            const char *title);
565
566 /**
567  * Returns the title displayed in the title bar. The title
568  * should be free'd with free().
569  *
570  * \param windowhandle The handle to the window
571  * \return The title, free with free().
572  */
573 extern char *GHOST_GetTitle(GHOST_WindowHandle windowhandle);
574
575 /**
576  * Returns the window rectangle dimensions.
577  * These are screen coordinates.
578  * \param windowhandle The handle to the window
579  * \return A handle to the bounding rectangle of the window.
580  */
581 extern GHOST_RectangleHandle GHOST_GetWindowBounds(GHOST_WindowHandle windowhandle);
582
583 /**
584  * Returns the client rectangle dimensions.
585  * The left and top members of the rectangle are always zero.
586  * \param windowhandle The handle to the window
587  * \return A handle to the bounding rectangle of the window.
588  */
589 extern GHOST_RectangleHandle GHOST_GetClientBounds(GHOST_WindowHandle windowhandle);
590
591 /**
592  * Disposes a rectangle object
593  * \param rectanglehandle Handle to the rectangle.
594  */
595 void GHOST_DisposeRectangle(GHOST_RectangleHandle rectanglehandle);
596
597 /**
598  * Resizes client rectangle width.
599  * \param windowhandle The handle to the window
600  * \param width The new width of the client area of the window.
601  * \return Indication of success.
602  */
603 extern GHOST_TSuccess GHOST_SetClientWidth(GHOST_WindowHandle windowhandle,
604                                            GHOST_TUns32 width);
605
606 /**
607  * Resizes client rectangle height.
608  * \param windowhandle The handle to the window
609  * \param height The new height of the client area of the window.
610  * \return Indication of success.
611  */
612 extern GHOST_TSuccess GHOST_SetClientHeight(GHOST_WindowHandle windowhandle,
613                                             GHOST_TUns32 height);
614
615 /**
616  * Resizes client rectangle.
617  * \param windowhandle The handle to the window
618  * \param width The new width of the client area of the window.
619  * \param height The new height of the client area of the window.
620  * \return Indication of success.
621  */
622 extern GHOST_TSuccess GHOST_SetClientSize(GHOST_WindowHandle windowhandle,
623                                           GHOST_TUns32 width,
624                                           GHOST_TUns32 height);
625
626 /**
627  * Converts a point in screen coordinates to client rectangle coordinates
628  * \param windowhandle The handle to the window
629  * \param inX The x-coordinate on the screen.
630  * \param inY The y-coordinate on the screen.
631  * \param outX The x-coordinate in the client rectangle.
632  * \param outY The y-coordinate in the client rectangle.
633  */
634 extern void GHOST_ScreenToClient(GHOST_WindowHandle windowhandle,
635                                  GHOST_TInt32 inX,
636                                  GHOST_TInt32 inY,
637                                  GHOST_TInt32 *outX,
638                                  GHOST_TInt32 *outY);
639
640 /**
641  * Converts a point in screen coordinates to client rectangle coordinates
642  * \param windowhandle The handle to the window
643  * \param inX The x-coordinate in the client rectangle.
644  * \param inY The y-coordinate in the client rectangle.
645  * \param outX The x-coordinate on the screen.
646  * \param outY The y-coordinate on the screen.
647  */
648 extern void GHOST_ClientToScreen(GHOST_WindowHandle windowhandle,
649                                  GHOST_TInt32 inX,
650                                  GHOST_TInt32 inY,
651                                  GHOST_TInt32 *outX,
652                                  GHOST_TInt32 *outY);
653
654 /**
655  * Returns the state of the window (normal, minimized, maximized).
656  * \param windowhandle The handle to the window
657  * \return The state of the window.
658  */
659 extern GHOST_TWindowState GHOST_GetWindowState(GHOST_WindowHandle windowhandle);
660
661 /**
662  * Sets the state of the window (normal, minimized, maximized).
663  * \param windowhandle The handle to the window
664  * \param state The state of the window.
665  * \return Indication of success.
666  */
667 extern GHOST_TSuccess GHOST_SetWindowState(GHOST_WindowHandle windowhandle,
668                                            GHOST_TWindowState state);
669
670
671 /**
672  * Sets the window "modified" status, indicating unsaved changes
673  * \param windowhandle The handle to the window
674  * \param isUnsavedChanges Unsaved changes or not
675  * \return Indication of success.
676  */
677 extern GHOST_TSuccess GHOST_SetWindowModifiedState(GHOST_WindowHandle windowhandle,
678                                                    GHOST_TUns8 isUnsavedChanges);
679
680 /**
681  * Sets the order of the window (bottom, top).
682  * \param windowhandle The handle to the window
683  * \param order The order of the window.
684  * \return Indication of success.
685  */
686 extern GHOST_TSuccess GHOST_SetWindowOrder(GHOST_WindowHandle windowhandle,
687                                            GHOST_TWindowOrder order);
688
689 /**
690  * Swaps front and back buffers of a window.
691  * \param windowhandle The handle to the window
692  * \return A success indicator.
693  */
694 extern GHOST_TSuccess GHOST_SwapWindowBuffers(GHOST_WindowHandle windowhandle);
695
696 /**
697  * Sets the swap interval for swapBuffers.
698  * \param interval The swap interval to use.
699  * \return A boolean success indicator.
700  */
701 extern GHOST_TSuccess GHOST_SetSwapInterval(GHOST_WindowHandle windowhandle, int interval);
702
703 /**
704  * Gets the current swap interval for swapBuffers.
705  * \param windowhandle The handle to the window
706  * \param intervalOut pointer to location to return swap interval (left untouched if there is an error)
707  * \return A boolean success indicator of if swap interval was successfully read.
708  */
709 extern GHOST_TSuccess GHOST_GetSwapInterval(GHOST_WindowHandle windowhandle, int* intervalOut);
710
711 /**
712  * Gets the current swap interval for swapBuffers.
713  * \return Number of AA Samples (0 if there is no multisample buffer)
714  */
715 extern GHOST_TUns16 GHOST_GetNumOfAASamples(GHOST_WindowHandle windowhandle);
716
717 /**
718  * Activates the drawing context of this window.
719  * \param windowhandle The handle to the window
720  * \return A success indicator.
721  */
722 extern GHOST_TSuccess GHOST_ActivateWindowDrawingContext(GHOST_WindowHandle windowhandle);
723
724 /**
725  * Invalidates the contents of this window.
726  * \param windowhandle The handle to the window
727  * \return Indication of success.
728  */
729 extern GHOST_TSuccess GHOST_InvalidateWindow(GHOST_WindowHandle windowhandle);
730
731 /**
732  * Activates the drawing context of this context.
733  * \param contexthandle The handle to the context
734  * \return A success indicator.
735  */
736 extern GHOST_TSuccess GHOST_ActivateOpenGLContext(GHOST_ContextHandle contexthandle);
737
738 /**
739  * Release the drawing context bound to this thread.
740  * \param contexthandle The handle to the context
741  * \return A success indicator.
742  */
743 extern GHOST_TSuccess GHOST_ReleaseOpenGLContext(GHOST_ContextHandle contexthandle);
744
745 /**
746  * Returns the status of the tablet
747  * \param windowhandle The handle to the window
748  * \return Status of tablet
749  */
750 extern const GHOST_TabletData *GHOST_GetTabletData(GHOST_WindowHandle windowhandle);
751
752 /**
753  * Access to rectangle width.
754  * \param rectanglehandle The handle to the rectangle
755  * \return width of the rectangle
756  */
757 extern GHOST_TInt32 GHOST_GetWidthRectangle(GHOST_RectangleHandle rectanglehandle);
758
759 /**
760  * Access to rectangle height.
761  * \param rectanglehandle The handle to the rectangle
762  * \return height of the rectangle
763  */
764 extern GHOST_TInt32 GHOST_GetHeightRectangle(GHOST_RectangleHandle rectanglehandle);
765
766 /**
767  * Gets all members of the rectangle.
768  * \param rectanglehandle The handle to the rectangle
769  * \param l Pointer to return left coordinate in.
770  * \param t Pointer to return top coordinate in.
771  * \param r Pointer to return right coordinate in.
772  * \param b Pointer to return bottom coordinate in.
773  */
774 extern void GHOST_GetRectangle(GHOST_RectangleHandle rectanglehandle,
775                                GHOST_TInt32 *l,
776                                GHOST_TInt32 *t,
777                                GHOST_TInt32 *r,
778                                GHOST_TInt32 *b);
779
780 /**
781  * Sets all members of the rectangle.
782  * \param rectanglehandle The handle to the rectangle
783  * \param l requested left coordinate of the rectangle
784  * \param t requested top coordinate of the rectangle
785  * \param r requested right coordinate of the rectangle
786  * \param b requested bottom coordinate of the rectangle
787  */
788 extern void GHOST_SetRectangle(GHOST_RectangleHandle rectanglehandle,
789                                GHOST_TInt32 l,
790                                GHOST_TInt32 t,
791                                GHOST_TInt32 r,
792                                GHOST_TInt32 b);
793
794 /**
795  * Returns whether this rectangle is empty.
796  * Empty rectangles are rectangles that have width==0 and/or height==0.
797  * \param rectanglehandle The handle to the rectangle
798  * \return Success value (true == empty rectangle)
799  */
800 extern GHOST_TSuccess GHOST_IsEmptyRectangle(GHOST_RectangleHandle rectanglehandle);
801
802 /**
803  * Returns whether this rectangle is valid.
804  * Valid rectangles are rectangles that have m_l <= m_r and m_t <= m_b. Thus, empty rectangles are valid.
805  * \param rectanglehandle The handle to the rectangle
806  * \return Success value (true == valid rectangle)
807  */
808 extern GHOST_TSuccess GHOST_IsValidRectangle(GHOST_RectangleHandle rectanglehandle);
809
810 /**
811  * Grows (or shrinks the rectangle).
812  * The method avoids negative insets making the rectangle invalid
813  * \param rectanglehandle The handle to the rectangle
814  * \param i The amount of offset given to each extreme (negative values shrink the rectangle).
815  */
816 extern void GHOST_InsetRectangle(GHOST_RectangleHandle rectanglehandle,
817                                  GHOST_TInt32 i);
818
819 /**
820  * Does a union of the rectangle given and this rectangle.
821  * The result is stored in this rectangle.
822  * \param rectanglehandle The handle to the rectangle
823  * \param anotherrectanglehandle The rectangle that is input for the union operation.
824  */
825 extern void GHOST_UnionRectangle(GHOST_RectangleHandle rectanglehandle,
826                                  GHOST_RectangleHandle anotherrectanglehandle);
827
828 /**
829  * Grows the rectangle to included a point.
830  * \param rectanglehandle The handle to the rectangle
831  * \param x The x-coordinate of the point.
832  * \param y The y-coordinate of the point.
833  */
834 extern void GHOST_UnionPointRectangle(GHOST_RectangleHandle rectanglehandle,
835                                       GHOST_TInt32 x,
836                                       GHOST_TInt32 y);
837
838 /**
839  * Returns whether the point is inside this rectangle.
840  * Point on the boundary is considered inside.
841  * \param rectanglehandle The handle to the rectangle
842  * \param x x-coordinate of point to test.
843  * \param y y-coordinate of point to test.
844  * \return Success value (true if point is inside).
845  */
846 extern GHOST_TSuccess GHOST_IsInsideRectangle(GHOST_RectangleHandle rectanglehandle,
847                                               GHOST_TInt32 x,
848                                               GHOST_TInt32 y);
849
850 /**
851  * Returns whether the rectangle is inside this rectangle.
852  * \param rectanglehandle The handle to the rectangle
853  * \param anotherrectanglehandle The rectangle to test.
854  * \return visibility (not, partially or fully visible).
855  */
856 extern GHOST_TVisibility GHOST_GetRectangleVisibility(GHOST_RectangleHandle rectanglehandle,
857                                                       GHOST_RectangleHandle anotherrectanglehandle);
858
859 /**
860  * Sets rectangle members.
861  * Sets rectangle members such that it is centered at the given location.
862  * \param rectanglehandle The handle to the rectangle
863  * \param cx Requested center x-coordinate of the rectangle
864  * \param cy Requested center y-coordinate of the rectangle
865  */
866 extern void GHOST_SetCenterRectangle(GHOST_RectangleHandle rectanglehandle,
867                                      GHOST_TInt32 cx,
868                                      GHOST_TInt32 cy);
869
870 /**
871  * Sets rectangle members.
872  * Sets rectangle members such that it is centered at the given location,
873  * with the width requested.
874  * \param rectanglehandle The handle to the rectangle
875  * \param cx requested center x-coordinate of the rectangle
876  * \param cy requested center y-coordinate of the rectangle
877  * \param w requested width of the rectangle
878  * \param h requested height of the rectangle
879  */
880 extern void GHOST_SetRectangleCenter(GHOST_RectangleHandle rectanglehandle,
881                                      GHOST_TInt32 cx,
882                                      GHOST_TInt32 cy,
883                                      GHOST_TInt32 w,
884                                      GHOST_TInt32 h);
885
886 /**
887  * Clips a rectangle.
888  * Updates the rectangle given such that it will fit within this one.
889  * This can result in an empty rectangle.
890  * \param rectanglehandle The handle to the rectangle
891  * \param anotherrectanglehandle The rectangle to clip
892  * \return Whether clipping has occurred
893  */
894 extern GHOST_TSuccess GHOST_ClipRectangle(GHOST_RectangleHandle rectanglehandle,
895                                           GHOST_RectangleHandle anotherrectanglehandle);
896
897 /**
898  * Return the data from the clipboard
899  * \param selection Boolean to return the selection instead, X11 only feature.
900  * \return clipboard data
901  */
902 extern GHOST_TUns8 *GHOST_getClipboard(int selection);
903
904 /**
905  * Put data to the Clipboard
906  * \param buffer the string buffer to set.
907  * \param selection Set the selection instead, X11 only feature.
908  */
909 extern void GHOST_putClipboard(GHOST_TInt8 *buffer, int selection);
910
911
912
913 /**
914  * Toggles console
915  * \param action
916  * - 0: Hides
917  * - 1: Shows
918  * - 2: Toggles
919  * - 3: Hides if it runs not from  command line
920  * - *: Does nothing
921  * \return current status (1 -visible, 0 - hidden)
922  */
923 extern int GHOST_toggleConsole(int action);
924
925
926 /**
927  * Confirms quitting he program when there is just one window left open
928  * in the application
929  */
930 extern int GHOST_confirmQuit(GHOST_WindowHandle windowhandle);
931
932 /**
933  * Informs if the system provides native dialogs (eg. confirm quit)
934  */
935 extern int GHOST_SupportsNativeDialogs(void);
936
937 /**
938  * Use native pixel size (MacBook pro 'retina'), if supported.
939  */
940 extern int GHOST_UseNativePixels(void);
941
942 /**
943  * If window was opened using native pixel size, it returns scaling factor.
944  */
945 extern float GHOST_GetNativePixelSize(GHOST_WindowHandle windowhandle);
946
947 /**
948  * Returns the suggested DPI for this window.
949  */
950 extern GHOST_TUns16 GHOST_GetDPIHint(GHOST_WindowHandle windowhandle);
951
952 /**
953  * Enable IME attached to the given window, i.e. allows user-input
954  * events to be dispatched to the IME.
955  * \param windowhandle Window handle of the caller
956  * \param x Requested x-coordinate of the rectangle
957  * \param y Requested y-coordinate of the rectangle
958  * \param w Requested width of the rectangle
959  * \param h Requested height of the rectangle
960  * \param complete Whether or not to complete the ongoing composition
961  * true:  Start a new composition
962  * false: Move the IME windows to the given position without finishing it.
963  */
964 extern void GHOST_BeginIME(GHOST_WindowHandle windowhandle,
965                             GHOST_TInt32 x,
966                             GHOST_TInt32 y,
967                             GHOST_TInt32 w,
968                             GHOST_TInt32 h,
969                             int complete);
970 /**
971  * Disable the IME attached to the given window, i.e. prohibits any user-input
972  * events from being dispatched to the IME.
973  * \param windowhandle The window handle of the caller
974  */
975 extern void GHOST_EndIME(GHOST_WindowHandle windowhandle);
976
977 #ifdef __cplusplus
978 }
979 #endif
980
981 #endif