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