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