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