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