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