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