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