intern/ghost/GHOST_C-api.h

   1 /**
   2  * $Id$
   3  * ***** BEGIN GPL 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.
   9  *
  10  * This program is distributed in the hope that it will be useful,
  11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13  * GNU General Public License for more details.
  14  *
  15  * You should have received a copy of the GNU General Public License
  16  * along with this program; if not, write to the Free Software Foundation,
  17  * Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA.
  18  *
  19  * The Original Code is Copyright (C) 2001-2002 by NaN Holding BV.
  20  * All rights reserved.
  21  *
  22  * The Original Code is: all of this file.
  23  *
  24  * Contributor(s): none yet.
  25  *
  26  * ***** END GPL LICENSE BLOCK *****
  27  */
  28 /**
  29  * @file        GHOST_C-api.h
  30  * GHOST C-API function and type declarations.
  31  * The C-API wraps the C++ objects with the
  32  */
  33
  34 #ifndef GHOST_C_API_H
  35 #define GHOST_C_API_H
  36
  37 #include "GHOST_Types.h"
  38
  39 #ifdef __cplusplus
  40 extern "C" {
  41 #endif
  42
  43 /**
  44  * Creates a &quot;handle&quot; for a C++ GHOST object.
  45  * A handle is just an opaque pointer to an empty struct.
  46  * In the API the pointer is casted to the actual C++ class.
  47  * @param       name    Name of the handle to create.
  48  */
  49 #define GHOST_DECLARE_HANDLE(name) typedef struct name##__ { int unused; } *name
  50
  51 GHOST_DECLARE_HANDLE(GHOST_SystemHandle);
  52 GHOST_DECLARE_HANDLE(GHOST_TimerTaskHandle);
  53 GHOST_DECLARE_HANDLE(GHOST_WindowHandle);
  54 GHOST_DECLARE_HANDLE(GHOST_EventHandle);
  55 GHOST_DECLARE_HANDLE(GHOST_RectangleHandle);
  56 GHOST_DECLARE_HANDLE(GHOST_EventConsumerHandle);
  57
  58
  59 /**
  60  * Definition of a callback routine that receives events.
  61  * @param event The event received.
  62  * @param userdata The callback's user data, supplied to GHOST_CreateSystem.
  63  */
  64 typedef int (*GHOST_EventCallbackProcPtr)(GHOST_EventHandle event, GHOST_TUserDataPtr userdata);
  65
  66
  67 /**
  68  * Creates the one and only system.
  69  * @return a handle to the system.
  70  */
  71 extern GHOST_SystemHandle GHOST_CreateSystem(void);
  72
  73 /**
  74  * Disposes the one and only system.
  75  * @param systemhandle The handle to the system
  76  * @return An indication of success.
  77  */
  78 extern GHOST_TSuccess GHOST_DisposeSystem(GHOST_SystemHandle systemhandle);
  79
  80
  81 /**
  82  * Creates an event consumer object
  83  * @param eventCallback The event callback routine.
  84  * @param userdata              Pointer to user data returned to the callback routine.
  85  */
  86 extern GHOST_EventConsumerHandle GHOST_CreateEventConsumer(GHOST_EventCallbackProcPtr eventCallback, GHOST_TUserDataPtr userdata);
  87
  88 /**
  89  * Disposes an event consumer object
  90  * @param consumerhandle        Handle to the event consumer.
  91  * @return An indication of success.
  92  */
  93 extern GHOST_TSuccess GHOST_DisposeEventConsumer(GHOST_EventConsumerHandle consumerhandle);
  94
  95
  96 /**
  97  * Returns the system time.
  98  * Returns the number of milliseconds since the start of the system process.
  99  * Based on ANSI clock() routine.
 100  * @param systemhandle The handle to the system
 101  * @return The number of milliseconds.
 102  */
 103 extern GHOST_TUns64 GHOST_GetMilliSeconds(GHOST_SystemHandle systemhandle);
 104
 105 /**
 106  * Installs a timer.
 107  * Note that, on most operating systems, messages need to be processed in order
 108  * for the timer callbacks to be invoked.
 109  * @param systemhandle The handle to the system
 110  * @param delay         The time to wait for the first call to the timerProc (in milliseconds)
 111  * @param interval      The interval between calls to the timerProc (in milliseconds)
 112  * @param timerProc     The callback invoked when the interval expires,
 113  * @param userData      Placeholder for user data.
 114  * @return A timer task (0 if timer task installation failed).
 115  */
 116 extern GHOST_TimerTaskHandle GHOST_InstallTimer(GHOST_SystemHandle systemhandle,
 117                                                                                                 GHOST_TUns64 delay,
 118                                                                                                 GHOST_TUns64 interval,
 119                                                                                                 GHOST_TimerProcPtr timerProc,
 120                                                                                                 GHOST_TUserDataPtr userData);
 121
 122 /**
 123  * Removes a timer.
 124  * @param systemhandle The handle to the system
 125  * @param timerTask Timer task to be removed.
 126  * @return Indication of success.
 127  */
 128 extern GHOST_TSuccess GHOST_RemoveTimer(GHOST_SystemHandle systemhandle,
 129                                                                                 GHOST_TimerTaskHandle timertaskhandle);
 130
 131 /***************************************************************************************
 132  ** Display/window management functionality
 133  ***************************************************************************************/
 134
 135 /**
 136  * Returns the number of displays on this system.
 137  * @param systemhandle The handle to the system
 138  * @return The number of displays.
 139  */
 140 extern GHOST_TUns8 GHOST_GetNumDisplays(GHOST_SystemHandle systemhandle);
 141
 142 /**
 143  * Returns the dimensions of the main display on this system.
 144  * @param systemhandle The handle to the system
 145  * @param width         A pointer the width gets put in
 146  * @param height        A pointer the height gets put in
 147  * @return void.
 148  */
 149 extern void GHOST_GetMainDisplayDimensions(GHOST_SystemHandle systemhandle,
 150                                                                                    GHOST_TUns32* width,
 151                                                                                    GHOST_TUns32* height);
 152
 153 /**
 154  * Create a new window.
 155  * The new window is added to the list of windows managed.
 156  * Never explicitly delete the window, use disposeWindow() instead.
 157  * @param systemhandle The handle to the system
 158  * @param       title   The name of the window (displayed in the title bar of the window if the OS supports it).
 159  * @param       left    The coordinate of the left edge of the window.
 160  * @param       top             The coordinate of the top edge of the window.
 161  * @param       width   The width the window.
 162  * @param       height  The height the window.
 163  * @param       state   The state of the window when opened.
 164  * @param       type    The type of drawing context installed in this window.
 165  * @param stereoVisual          Stereo visual for quad buffered stereo.
 166  * @param numOfAASamples        Number of samples used for AA (zero if no AA)
 167  * @return      A handle to the new window ( == NULL if creation failed).
 168  */
 169 extern GHOST_WindowHandle GHOST_CreateWindow(GHOST_SystemHandle systemhandle,
 170         char* title,
 171         GHOST_TInt32 left,
 172         GHOST_TInt32 top,
 173         GHOST_TUns32 width,
 174         GHOST_TUns32 height,
 175         GHOST_TWindowState state,
 176         GHOST_TDrawingContextType type,
 177         const int stereoVisual,
 178         const GHOST_TUns16 numOfAASamples);
 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 int 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 /***************************************************************************************
 283  ** Cursor management functionality
 284  ***************************************************************************************/
 285
 286 /**
 287  * Returns the current cursor shape.
 288  * @param windowhandle The handle to the window
 289  * @return      The current cursor shape.
 290  */
 291 extern GHOST_TStandardCursor GHOST_GetCursorShape(GHOST_WindowHandle windowhandle);
 292
 293 /**
 294  * Set the shape of the cursor.
 295  * @param windowhandle The handle to the window
 296  * @param       cursor  The new cursor shape type id.
 297  * @return      Indication of success.
 298  */
 299 extern GHOST_TSuccess GHOST_SetCursorShape(GHOST_WindowHandle windowhandle,
 300                                                                                    GHOST_TStandardCursor cursorshape);
 301
 302 /**
 303  * Set the shape of the cursor to a custom cursor.
 304  * @param windowhandle The handle to the window
 305  * @param       bitmap  The bitmap data for the cursor.
 306  * @param       mask    The mask data for the cursor.
 307  * @param       hotX    The X coordinate of the cursor hotspot.
 308  * @param       hotY    The Y coordinate of the cursor hotspot.
 309  * @return      Indication of success.
 310  */
 311 extern GHOST_TSuccess GHOST_SetCustomCursorShape(GHOST_WindowHandle windowhandle,
 312                                                                                                  GHOST_TUns8 bitmap[16][2],
 313                                                                                                  GHOST_TUns8 mask[16][2],
 314                                                                                                  int hotX,
 315                                                                                                  int hotY);
 316 /**
 317  * Set the shape of the cursor to a custom cursor of specified size.
 318  * @param windowhandle The handle to the window
 319  * @param       bitmap  The bitmap data for the cursor.
 320  * @param       mask    The mask data for the cursor.
 321  * @parm    sizex, sizey  The size of the cursor
 322  * @param       hotX    The X coordinate of the cursor hotspot.
 323  * @param       hotY    The Y coordinate of the cursor hotspot.
 324  * @param   fg_color, bg_color  Colors of the cursor
 325  * @return      Indication of success.
 326   */
 327 extern GHOST_TSuccess GHOST_SetCustomCursorShapeEx(GHOST_WindowHandle windowhandle,
 328                                                                                                  GHOST_TUns8 *bitmap,
 329                                                                                                  GHOST_TUns8 *mask,
 330                                                                                                  int sizex, int sizey,
 331                                                                                                  int hotX,  int hotY,
 332                                                                                                  int fg_color, int bg_color );
 333
 334 /**
 335  * Returns the visibility state of the cursor.
 336  * @param windowhandle The handle to the window
 337  * @return      The visibility state of the cursor.
 338  */
 339 extern int GHOST_GetCursorVisibility(GHOST_WindowHandle windowhandle);
 340
 341 /**
 342  * Shows or hides the cursor.
 343  * @param windowhandle The handle to the window
 344  * @param       visible The new visibility state of the cursor.
 345  * @return      Indication of success.
 346  */
 347 extern GHOST_TSuccess GHOST_SetCursorVisibility(GHOST_WindowHandle windowhandle,
 348                                                                                                 int visible);
 349
 350 /**
 351  * Returns the current location of the cursor (location in screen coordinates)
 352  * @param systemhandle The handle to the system
 353  * @param x                     The x-coordinate of the cursor.
 354  * @param y                     The y-coordinate of the cursor.
 355  * @return                      Indication of success.
 356  */
 357 extern GHOST_TSuccess GHOST_GetCursorPosition(GHOST_SystemHandle systemhandle,
 358                                                                                           GHOST_TInt32* x,
 359                                                                                           GHOST_TInt32* y);
 360
 361 /**
 362  * Updates the location of the cursor (location in screen coordinates).
 363  * Not all operating systems allow the cursor to be moved (without the input device being moved).
 364  * @param systemhandle The handle to the system
 365  * @param x                     The x-coordinate of the cursor.
 366  * @param y                     The y-coordinate of the cursor.
 367  * @return                      Indication of success.
 368  */
 369 extern GHOST_TSuccess GHOST_SetCursorPosition(GHOST_SystemHandle systemhandle,
 370                                                                                           GHOST_TInt32 x,
 371                                                                                           GHOST_TInt32 y);
 372
 373 /**
 374  * Grabs the cursor for a modal operation, to keep receiving
 375  * events when the mouse is outside the window. X11 only, others
 376  * do this automatically.
 377  * @param windowhandle The handle to the window
 378  * @param       mode The new grab state of the cursor.
 379  * @param       bounds The grab ragion (optional) - left,top,right,bottom
 380  * @return      Indication of success.
 381  */
 382 extern GHOST_TSuccess GHOST_SetCursorGrab(GHOST_WindowHandle windowhandle,
 383                                                                                                 GHOST_TGrabCursorMode mode,
 384                                                                                                 int* bounds);
 385
 386 /***************************************************************************************
 387  ** Access to mouse button and keyboard states.
 388  ***************************************************************************************/
 389
 390 /**
 391  * Returns the state of a modifier key (ouside the message queue).
 392  * @param systemhandle The handle to the system
 393  * @param mask          The modifier key state to retrieve.
 394  * @param isDown        Pointer to return modifier state in.
 395  * @return                      Indication of success.
 396  */
 397 extern GHOST_TSuccess GHOST_GetModifierKeyState(GHOST_SystemHandle systemhandle,
 398                                                                                                 GHOST_TModifierKeyMask mask,
 399                                                                                                 int* isDown);
 400
 401 /**
 402  * Returns the state of a mouse button (ouside the message queue).
 403  * @param systemhandle The handle to the system
 404  * @param mask          The button state to retrieve.
 405  * @param isDown        Pointer to return button state in.
 406  * @return                      Indication of success.
 407  */
 408 extern GHOST_TSuccess GHOST_GetButtonState(GHOST_SystemHandle systemhandle,
 409                                                                                    GHOST_TButtonMask mask,
 410                                                                                    int* isDown);
 411
 412
 413 /***************************************************************************************
 414  ** Drag'n'drop operations
 415  ***************************************************************************************/
 416
 417 /**
 418  * Tells if the ongoing drag'n'drop object can be accepted upon mouse drop
 419  */
 420 extern void GHOST_setAcceptDragOperation(GHOST_WindowHandle windowhandle, GHOST_TInt8 canAccept);
 421
 422
 423 /**
 424  * Returns the event type.
 425  * @param eventhandle The handle to the event
 426  * @return The event type.
 427  */
 428 extern GHOST_TEventType GHOST_GetEventType(GHOST_EventHandle eventhandle);
 429
 430 /**
 431  * Returns the time this event was generated.
 432  * @param eventhandle The handle to the event
 433  * @return The event generation time.
 434  */
 435 extern GHOST_TUns64 GHOST_GetEventTime(GHOST_EventHandle eventhandle);
 436
 437 /**
 438  * Returns the window this event was generated on,
 439  * or NULL if it is a 'system' event.
 440  * @param eventhandle The handle to the event
 441  * @return The generating window.
 442  */
 443 extern GHOST_WindowHandle GHOST_GetEventWindow(GHOST_EventHandle eventhandle);
 444
 445 /**
 446  * Returns the event data.
 447  * @param eventhandle The handle to the event
 448  * @return The event data.
 449  */
 450 extern GHOST_TEventDataPtr GHOST_GetEventData(GHOST_EventHandle eventhandle);
 451
 452 /**
 453  * Returns the timer callback.
 454  * @param timertaskhandle       The handle to the timertask
 455  * @return The timer callback.
 456  */
 457 extern GHOST_TimerProcPtr GHOST_GetTimerProc(GHOST_TimerTaskHandle timertaskhandle);
 458
 459 /**
 460  * Changes the timer callback.
 461  * @param timertaskhandle The handle to the timertask
 462  * @param timerProc The timer callback.
 463  */
 464 extern void GHOST_SetTimerProc(GHOST_TimerTaskHandle timertaskhandle,
 465                                                            GHOST_TimerProcPtr timerProc);
 466
 467 /**
 468  * Returns the timer user data.
 469  * @param timertaskhandle       The handle to the timertask
 470  * @return The timer user data.
 471  */
 472 extern GHOST_TUserDataPtr GHOST_GetTimerTaskUserData(GHOST_TimerTaskHandle timertaskhandle);
 473
 474 /**
 475  * Changes the time user data.
 476  * @param timertaskhandle       The handle to the timertask
 477  * @param data The timer user data.
 478  */
 479 extern void GHOST_SetTimerTaskUserData(GHOST_TimerTaskHandle timertaskhandle,
 480                                                                            GHOST_TUserDataPtr userData);
 481
 482 /**
 483  * Returns indication as to whether the window is valid.
 484  * @param windowhandle The handle to the window
 485  * @return The validity of the window.
 486  */
 487 extern int GHOST_GetValid(GHOST_WindowHandle windowhandle) ;
 488
 489 /**
 490  * Returns the type of drawing context used in this window.
 491  * @param windowhandle The handle to the window
 492  * @return The current type of drawing context.
 493  */
 494 extern GHOST_TDrawingContextType GHOST_GetDrawingContextType(GHOST_WindowHandle windowhandle);
 495
 496 /**
 497  * Tries to install a rendering context in this window.
 498  * @param windowhandle The handle to the window
 499  * @param type  The type of rendering context installed.
 500  * @return Indication as to whether installation has succeeded.
 501  */
 502 extern GHOST_TSuccess GHOST_SetDrawingContextType(GHOST_WindowHandle windowhandle,
 503                                                                                                   GHOST_TDrawingContextType type);
 504
 505 /**
 506  * Sets the title displayed in the title bar.
 507  * @param windowhandle The handle to the window
 508  * @param title The title to display in the title bar.
 509  */
 510 extern void GHOST_SetTitle(GHOST_WindowHandle windowhandle,
 511                                                    char* title);
 512
 513 /**
 514  * Returns the title displayed in the title bar. The title
 515  * should be free'd with free().
 516  *
 517  * @param windowhandle The handle to the window
 518  * @return The title, free with free().
 519  */
 520 extern char* GHOST_GetTitle(GHOST_WindowHandle windowhandle);
 521
 522 /**
 523  * Returns the window rectangle dimensions.
 524  * These are screen coordinates.
 525  * @param windowhandle The handle to the window
 526  * @return A handle to the bounding rectangle of the window.
 527  */
 528 extern GHOST_RectangleHandle GHOST_GetWindowBounds(GHOST_WindowHandle windowhandle);
 529
 530 /**
 531  * Returns the client rectangle dimensions.
 532  * The left and top members of the rectangle are always zero.
 533  * @param windowhandle The handle to the window
 534  * @return A handle to the bounding rectangle of the window.
 535  */
 536 extern GHOST_RectangleHandle GHOST_GetClientBounds(GHOST_WindowHandle windowhandle);
 537
 538 /**
 539  * Disposes a rectangle object
 540  * @param rectanglehandle       Handle to the rectangle.
 541  */
 542 void GHOST_DisposeRectangle(GHOST_RectangleHandle rectanglehandle);
 543
 544 /**
 545  * Resizes client rectangle width.
 546  * @param windowhandle The handle to the window
 547  * @param width The new width of the client area of the window.
 548  * @return      Indication of success.
 549  */
 550 extern GHOST_TSuccess GHOST_SetClientWidth(GHOST_WindowHandle windowhandle,
 551                                                                                    GHOST_TUns32 width);
 552
 553 /**
 554  * Resizes client rectangle height.
 555  * @param windowhandle The handle to the window
 556  * @param height The new height of the client area of the window.
 557  * @return      Indication of success.
 558  */
 559 extern GHOST_TSuccess GHOST_SetClientHeight(GHOST_WindowHandle windowhandle,
 560                                                                                         GHOST_TUns32 height);
 561
 562 /**
 563  * Resizes client rectangle.
 564  * @param windowhandle The handle to the window
 565  * @param width         The new width of the client area of the window.
 566  * @param height        The new height of the client area of the window.
 567  * @return                      Indication of success.
 568  */
 569 extern GHOST_TSuccess GHOST_SetClientSize(GHOST_WindowHandle windowhandle,
 570                                                                                   GHOST_TUns32 width,
 571                                                                                   GHOST_TUns32 height);
 572
 573 /**
 574  * Converts a point in screen coordinates to client rectangle coordinates
 575  * @param windowhandle The handle to the window
 576  * @param inX   The x-coordinate on the screen.
 577  * @param inY   The y-coordinate on the screen.
 578  * @param outX  The x-coordinate in the client rectangle.
 579  * @param outY  The y-coordinate in the client rectangle.
 580  */
 581 extern void GHOST_ScreenToClient(GHOST_WindowHandle windowhandle,
 582                                                                  GHOST_TInt32 inX,
 583                                                                  GHOST_TInt32 inY,
 584                                                                  GHOST_TInt32* outX,
 585                                                                  GHOST_TInt32* outY) ;
 586
 587 /**
 588  * Converts a point in screen coordinates to client rectangle coordinates
 589  * @param windowhandle The handle to the window
 590  * @param inX   The x-coordinate in the client rectangle.
 591  * @param inY   The y-coordinate in the client rectangle.
 592  * @param outX  The x-coordinate on the screen.
 593  * @param outY  The y-coordinate on the screen.
 594  */
 595 extern void GHOST_ClientToScreen(GHOST_WindowHandle windowhandle,
 596                                                                  GHOST_TInt32 inX,
 597                                                                  GHOST_TInt32 inY,
 598                                                                  GHOST_TInt32* outX,
 599                                                                  GHOST_TInt32* outY);
 600
 601 /**
 602  * Returns the state of the window (normal, minimized, maximized).
 603  * @param windowhandle The handle to the window
 604  * @return The state of the window.
 605  */
 606 extern GHOST_TWindowState GHOST_GetWindowState(GHOST_WindowHandle windowhandle);
 607
 608 /**
 609  * Sets the state of the window (normal, minimized, maximized).
 610  * @param windowhandle The handle to the window
 611  * @param state The state of the window.
 612  * @return Indication of success.
 613  */
 614 extern GHOST_TSuccess GHOST_SetWindowState(GHOST_WindowHandle windowhandle,
 615                                                                                    GHOST_TWindowState state);
 616
 617
 618 /**
 619  * Sets the window "modified" status, indicating unsaved changes
 620  * @param windowhandle The handle to the window
 621  * @param isUnsavedChanges Unsaved changes or not
 622  * @return Indication of success.
 623  */
 624 extern GHOST_TSuccess GHOST_SetWindowModifiedState(GHOST_WindowHandle windowhandle,
 625                                                                                                    GHOST_TUns8 isUnsavedChanges);
 626
 627 /**
 628  * Sets the order of the window (bottom, top).
 629  * @param windowhandle The handle to the window
 630  * @param order The order of the window.
 631  * @return Indication of success.
 632  */
 633 extern GHOST_TSuccess GHOST_SetWindowOrder(GHOST_WindowHandle windowhandle,
 634                                                                                    GHOST_TWindowOrder order);
 635
 636 /**
 637  * Swaps front and back buffers of a window.
 638  * @param windowhandle The handle to the window
 639  * @return      An intean success indicator.
 640  */
 641 extern GHOST_TSuccess GHOST_SwapWindowBuffers(GHOST_WindowHandle windowhandle);
 642
 643 /**
 644  * Activates the drawing context of this window.
 645  * @param windowhandle The handle to the window
 646  * @return      An intean success indicator.
 647  */
 648 extern GHOST_TSuccess GHOST_ActivateWindowDrawingContext(GHOST_WindowHandle windowhandle);
 649
 650 /**
 651  * Invalidates the contents of this window.
 652  * @param windowhandle The handle to the window
 653  * @return Indication of success.
 654  */
 655 extern GHOST_TSuccess GHOST_InvalidateWindow(GHOST_WindowHandle windowhandle);
 656
 657 /**
 658  * Returns the status of the tablet
 659  * @param windowhandle The handle to the window
 660  * @return Status of tablet
 661  */
 662 extern const GHOST_TabletData *GHOST_GetTabletData(GHOST_WindowHandle windowhandle);
 663
 664 /**
 665  * Access to rectangle width.
 666  * @param rectanglehandle The handle to the rectangle
 667  * @return      width of the rectangle
 668  */
 669 extern GHOST_TInt32 GHOST_GetWidthRectangle(GHOST_RectangleHandle rectanglehandle);
 670
 671 /**
 672  * Access to rectangle height.
 673  * @param rectanglehandle The handle to the rectangle
 674  * @return      height of the rectangle
 675  */
 676 extern GHOST_TInt32 GHOST_GetHeightRectangle(GHOST_RectangleHandle rectanglehandle);
 677
 678 /**
 679  * Gets all members of the rectangle.
 680  * @param rectanglehandle The handle to the rectangle
 681  * @param       l       Pointer to return left coordinate in.
 682  * @param       t       Pointer to return top coordinate in.
 683  * @param       r       Pointer to return right coordinate in.
 684  * @param       b       Pointer to return bottom coordinate in.
 685  */
 686 extern void GHOST_GetRectangle(GHOST_RectangleHandle rectanglehandle,
 687                                                            GHOST_TInt32* l,
 688                                                            GHOST_TInt32* t,
 689                                                            GHOST_TInt32* r,
 690                                                            GHOST_TInt32* b);
 691
 692 /**
 693  * Sets all members of the rectangle.
 694  * @param rectanglehandle The handle to the rectangle
 695  * @param       l       requested left coordinate of the rectangle
 696  * @param       t       requested top coordinate of the rectangle
 697  * @param       r       requested right coordinate of the rectangle
 698  * @param       b       requested bottom coordinate of the rectangle
 699  */
 700 extern void GHOST_SetRectangle(GHOST_RectangleHandle rectanglehandle,
 701                                                            GHOST_TInt32 l,
 702                                                            GHOST_TInt32 t,
 703                                                            GHOST_TInt32 r,
 704                                                            GHOST_TInt32 b);
 705
 706 /**
 707  * Returns whether this rectangle is empty.
 708  * Empty rectangles are rectangles that have width==0 and/or height==0.
 709  * @param rectanglehandle The handle to the rectangle
 710  * @return      intean value (true == empty rectangle)
 711  */
 712 extern GHOST_TSuccess GHOST_IsEmptyRectangle(GHOST_RectangleHandle rectanglehandle);
 713
 714 /**
 715  * Returns whether this rectangle is valid.
 716  * Valid rectangles are rectangles that have m_l <= m_r and m_t <= m_b. Thus, emapty rectangles are valid.
 717  * @param rectanglehandle The handle to the rectangle
 718  * @return      intean value (true==valid rectangle)
 719  */
 720 extern GHOST_TSuccess GHOST_IsValidRectangle(GHOST_RectangleHandle rectanglehandle);
 721
 722 /**
 723  * Grows (or shrinks the rectangle).
 724  * The method avoids negative insets making the rectangle invalid
 725  * @param rectanglehandle The handle to the rectangle
 726  * @param       i       The amount of offset given to each extreme (negative values shrink the rectangle).
 727  */
 728 extern void GHOST_InsetRectangle(GHOST_RectangleHandle rectanglehandle,
 729                                                                  GHOST_TInt32 i);
 730
 731 /**
 732  * Does a union of the rectangle given and this rectangle.
 733  * The result is stored in this rectangle.
 734  * @param rectanglehandle The handle to the rectangle
 735  * @param       r       The rectangle that is input for the union operation.
 736  */
 737 extern void GHOST_UnionRectangle(GHOST_RectangleHandle rectanglehandle,
 738                                                                  GHOST_RectangleHandle anotherrectanglehandle);
 739
 740 /**
 741  * Grows the rectangle to included a point.
 742  * @param rectanglehandle The handle to the rectangle
 743  * @param       x       The x-coordinate of the point.
 744  * @param       y       The y-coordinate of the point.
 745  */
 746 extern void GHOST_UnionPointRectangle(GHOST_RectangleHandle rectanglehandle,
 747                                                                           GHOST_TInt32 x,
 748                                                                           GHOST_TInt32 y);
 749
 750 /**
 751  * Returns whether the point is inside this rectangle.
 752  * Point on the boundary is considered inside.
 753  * @param rectanglehandle The handle to the rectangle
 754  * @param x     x-coordinate of point to test.
 755  * @param y y-coordinate of point to test.
 756  * @return intean value (true if point is inside).
 757  */
 758 extern GHOST_TSuccess GHOST_IsInsideRectangle(GHOST_RectangleHandle rectanglehandle,
 759                                                                                           GHOST_TInt32 x,
 760                                                                                           GHOST_TInt32 y);
 761
 762 /**
 763  * Returns whether the rectangle is inside this rectangle.
 764  * @param rectanglehandle The handle to the rectangle
 765  * @param       r       rectangle to test.
 766  * @return      visibility (not, partially or fully visible).
 767  */
 768 extern GHOST_TVisibility GHOST_GetRectangleVisibility(GHOST_RectangleHandle rectanglehandle,
 769                                                                                                           GHOST_RectangleHandle anotherrectanglehandle);
 770
 771 /**
 772  * Sets rectangle members.
 773  * Sets rectangle members such that it is centered at the given location.
 774  * @param rectanglehandle The handle to the rectangle
 775  * @param       cx      requested center x-coordinate of the rectangle
 776  * @param       cy      requested center y-coordinate of the rectangle
 777  */
 778 extern void GHOST_SetCenterRectangle(GHOST_RectangleHandle rectanglehandle,
 779                                                                          GHOST_TInt32 cx,
 780                                                                          GHOST_TInt32 cy);
 781
 782 /**
 783  * Sets rectangle members.
 784  * Sets rectangle members such that it is centered at the given location,
 785  * with the width requested.
 786  * @param rectanglehandle The handle to the rectangle
 787  * @param       cx      requested center x-coordinate of the rectangle
 788  * @param       cy      requested center y-coordinate of the rectangle
 789  * @param       w       requested width of the rectangle
 790  * @param       h       requested height of the rectangle
 791  */
 792 extern void GHOST_SetRectangleCenter(GHOST_RectangleHandle rectanglehandle,
 793                                                                          GHOST_TInt32 cx,
 794                                                                          GHOST_TInt32 cy,
 795                                                                          GHOST_TInt32 w,
 796                                                                          GHOST_TInt32 h);
 797
 798 /**
 799  * Clips a rectangle.
 800  * Updates the rectangle given such that it will fit within this one.
 801  * This can result in an empty rectangle.
 802  * @param rectanglehandle The handle to the rectangle
 803  * @param       r       the rectangle to clip
 804  * @return      whether clipping has occurred
 805  */
 806 extern GHOST_TSuccess GHOST_ClipRectangle(GHOST_RectangleHandle rectanglehandle,
 807                                                                                   GHOST_RectangleHandle anotherrectanglehandle);
 808
 809 /**
 810  * Return the data from the clipboad
 811  * @param       return the selection instead, X11 only feature
 812  * @return      clipboard data
 813  */
 814 extern GHOST_TUns8* GHOST_getClipboard(int selection);
 815
 816 /**
 817  * Put data to the Clipboard
 818  * @param       set the selection instead, X11 only feature
 819  */
 820 extern void GHOST_putClipboard(GHOST_TInt8 *buffer, int selection);
 821
 822 #ifdef __cplusplus
 823 }
 824 #endif
 825
 826 #endif