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