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