intern/ghost/GHOST_C-api.h

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