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