Mercurial > hg > pub > prymula > com

comparison DPF-Prymula-audioplugins/dpf/dgl/src/pugl-upstream/include/pugl/pugl.h @ 3:84e66ea83026

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
DPF-Prymula-audioplugins-0.231015-2
author prymula <prymula76@outlook.com>
date Mon, 16 Oct 2023 21:53:34 +0200
parents
children
comparison
equal deleted inserted replaced
2:cf2cb71d31dd 3:84e66ea83026
1 // Copyright 2012-2022 David Robillard <d@drobilla.net>
2 // SPDX-License-Identifier: ISC
3
4 #ifndef PUGL_PUGL_H
5 #define PUGL_PUGL_H
6
7 #include <stddef.h>
8 #include <stdint.h>
9
10 #ifndef __cplusplus
11 # include <stdbool.h>
12 #endif
13
14 #ifndef PUGL_API
15 # if defined(_WIN32) && !defined(PUGL_STATIC) && defined(PUGL_INTERNAL)
16 # define PUGL_API __declspec(dllexport)
17 # elif defined(_WIN32) && !defined(PUGL_STATIC)
18 # define PUGL_API __declspec(dllimport)
19 # elif defined(__GNUC__)
20 # define PUGL_API __attribute__((visibility("default")))
21 # else
22 # define PUGL_API
23 # endif
24 #endif
25
26 #ifndef PUGL_DISABLE_DEPRECATED
27 # if defined(__clang__)
28 # define PUGL_DEPRECATED_BY(rep) __attribute__((deprecated("", rep)))
29 # elif defined(__GNUC__)
30 # define PUGL_DEPRECATED_BY(rep) __attribute__((deprecated("Use " rep)))
31 # else
32 # define PUGL_DEPRECATED_BY(rep)
33 # endif
34 #endif
35
36 #if defined(__GNUC__)
37 # define PUGL_CONST_FUNC __attribute__((const))
38 #else
39 # define PUGL_CONST_FUNC
40 #endif
41
42 #define PUGL_CONST_API \
43 PUGL_API \
44 PUGL_CONST_FUNC
45
46 #define PUGL_BEGIN_DECLS
47 #define PUGL_END_DECLS
48
49 PUGL_BEGIN_DECLS
50
51 /**
52 @defgroup pugl Pugl C API
53 Pugl C API.
54 @{
55 */
56
57 /**
58 A pixel coordinate within/of a view.
59
60 This is relative to the top left corner of the view's parent, or to the top
61 left corner of the view itself, depending on the context.
62
63 There are platform-imposed limits on window positions. For portability,
64 applications should keep coordinates between -16000 and 16000. Note that
65 negative frame coordinates are possible, for example with multiple screens.
66 */
67 typedef int16_t PuglCoord;
68
69 /**
70 A pixel span (width or height) within/of a view.
71
72 Due to platform limits, the span of a view in either dimension should be
73 between 1 and 10000.
74 */
75 typedef uint16_t PuglSpan;
76
77 /**
78 A rectangle in a view or on the screen.
79
80 This type is used to describe two things: the position and size of a view
81 (for configuring), or a rectangle within a view (for exposing).
82
83 The coordinate (0, 0) represents the top-left pixel of the parent window (or
84 display if there isn't one), or the top-left pixel of the view,
85 respectively.
86 */
87 typedef struct {
88 PuglCoord x;
89 PuglCoord y;
90 PuglSpan width;
91 PuglSpan height;
92 } PuglRect;
93
94 /**
95 @defgroup events Events
96
97 All updates to the view happen via events, which are dispatched to the
98 view's event function. Most events map directly to one from the underlying
99 window system, but some are constructed by Pugl itself so there is not
100 necessarily a direct correspondence.
101
102 @{
103 */
104
105 /// Keyboard modifier flags
106 typedef enum {
107 PUGL_MOD_SHIFT = 1u << 0u, ///< Shift key
108 PUGL_MOD_CTRL = 1u << 1u, ///< Control key
109 PUGL_MOD_ALT = 1u << 2u, ///< Alt/Option key
110 PUGL_MOD_SUPER = 1u << 3u ///< Mod4/Command/Windows key
111 } PuglMod;
112
113 /// Bitwise OR of #PuglMod values
114 typedef uint32_t PuglMods;
115
116 /**
117 Keyboard key codepoints.
118
119 All keys are identified by a Unicode code point in PuglKeyEvent::key. This
120 enumeration defines constants for special keys that do not have a standard
121 code point, and some convenience constants for control characters. Note
122 that all keys are handled in the same way, this enumeration is just for
123 convenience when writing hard-coded key bindings.
124
125 Keys that do not have a standard code point use values in the Private Use
126 Area in the Basic Multilingual Plane (`U+E000` to `U+F8FF`). Applications
127 must take care to not interpret these values beyond key detection, the
128 mapping used here is arbitrary and specific to Pugl.
129 */
130 typedef enum {
131 // ASCII control codes
132 PUGL_KEY_BACKSPACE = 0x08,
133 PUGL_KEY_ESCAPE = 0x1B,
134 PUGL_KEY_DELETE = 0x7F,
135
136 // Unicode Private Use Area
137 PUGL_KEY_F1 = 0xE000,
138 PUGL_KEY_F2,
139 PUGL_KEY_F3,
140 PUGL_KEY_F4,
141 PUGL_KEY_F5,
142 PUGL_KEY_F6,
143 PUGL_KEY_F7,
144 PUGL_KEY_F8,
145 PUGL_KEY_F9,
146 PUGL_KEY_F10,
147 PUGL_KEY_F11,
148 PUGL_KEY_F12,
149 PUGL_KEY_LEFT,
150 PUGL_KEY_UP,
151 PUGL_KEY_RIGHT,
152 PUGL_KEY_DOWN,
153 PUGL_KEY_PAGE_UP,
154 PUGL_KEY_PAGE_DOWN,
155 PUGL_KEY_HOME,
156 PUGL_KEY_END,
157 PUGL_KEY_INSERT,
158 PUGL_KEY_SHIFT,
159 PUGL_KEY_SHIFT_L = PUGL_KEY_SHIFT,
160 PUGL_KEY_SHIFT_R,
161 PUGL_KEY_CTRL,
162 PUGL_KEY_CTRL_L = PUGL_KEY_CTRL,
163 PUGL_KEY_CTRL_R,
164 PUGL_KEY_ALT,
165 PUGL_KEY_ALT_L = PUGL_KEY_ALT,
166 PUGL_KEY_ALT_R,
167 PUGL_KEY_SUPER,
168 PUGL_KEY_SUPER_L = PUGL_KEY_SUPER,
169 PUGL_KEY_SUPER_R,
170 PUGL_KEY_MENU,
171 PUGL_KEY_CAPS_LOCK,
172 PUGL_KEY_SCROLL_LOCK,
173 PUGL_KEY_NUM_LOCK,
174 PUGL_KEY_PRINT_SCREEN,
175 PUGL_KEY_PAUSE
176 } PuglKey;
177
178 /// The type of a PuglEvent
179 typedef enum {
180 PUGL_NOTHING, ///< No event
181 PUGL_CREATE, ///< View created, a #PuglCreateEvent
182 PUGL_DESTROY, ///< View destroyed, a #PuglDestroyEvent
183 PUGL_CONFIGURE, ///< View moved/resized, a #PuglConfigureEvent
184 PUGL_MAP, ///< View made visible, a #PuglMapEvent
185 PUGL_UNMAP, ///< View made invisible, a #PuglUnmapEvent
186 PUGL_UPDATE, ///< View ready to draw, a #PuglUpdateEvent
187 PUGL_EXPOSE, ///< View must be drawn, a #PuglExposeEvent
188 PUGL_CLOSE, ///< View will be closed, a #PuglCloseEvent
189 PUGL_FOCUS_IN, ///< Keyboard focus entered view, a #PuglFocusEvent
190 PUGL_FOCUS_OUT, ///< Keyboard focus left view, a #PuglFocusEvent
191 PUGL_KEY_PRESS, ///< Key pressed, a #PuglKeyEvent
192 PUGL_KEY_RELEASE, ///< Key released, a #PuglKeyEvent
193 PUGL_TEXT, ///< Character entered, a #PuglTextEvent
194 PUGL_POINTER_IN, ///< Pointer entered view, a #PuglCrossingEvent
195 PUGL_POINTER_OUT, ///< Pointer left view, a #PuglCrossingEvent
196 PUGL_BUTTON_PRESS, ///< Mouse button pressed, a #PuglButtonEvent
197 PUGL_BUTTON_RELEASE, ///< Mouse button released, a #PuglButtonEvent
198 PUGL_MOTION, ///< Pointer moved, a #PuglMotionEvent
199 PUGL_SCROLL, ///< Scrolled, a #PuglScrollEvent
200 PUGL_CLIENT, ///< Custom client message, a #PuglClientEvent
201 PUGL_TIMER, ///< Timer triggered, a #PuglTimerEvent
202 PUGL_LOOP_ENTER, ///< Recursive loop entered, a #PuglLoopEnterEvent
203 PUGL_LOOP_LEAVE, ///< Recursive loop left, a #PuglLoopLeaveEvent
204 PUGL_DATA_OFFER, ///< Data offered from clipboard, a #PuglDataOfferEvent
205 PUGL_DATA, ///< Data available from clipboard, a #PuglDataEvent
206 } PuglEventType;
207
208 /// Common flags for all event types
209 typedef enum {
210 PUGL_IS_SEND_EVENT = 1, ///< Event is synthetic
211 PUGL_IS_HINT = 2 ///< Event is a hint (not direct user input)
212 } PuglEventFlag;
213
214 /// Bitwise OR of #PuglEventFlag values
215 typedef uint32_t PuglEventFlags;
216
217 /// Reason for a PuglCrossingEvent
218 typedef enum {
219 PUGL_CROSSING_NORMAL, ///< Crossing due to pointer motion
220 PUGL_CROSSING_GRAB, ///< Crossing due to a grab
221 PUGL_CROSSING_UNGRAB ///< Crossing due to a grab release
222 } PuglCrossingMode;
223
224 /**
225 Scroll direction.
226
227 Describes the direction of a #PuglScrollEvent along with whether the scroll
228 is a "smooth" scroll. The discrete directions are for devices like mouse
229 wheels with constrained axes, while a smooth scroll is for those with
230 arbitrary scroll direction freedom, like some touchpads.
231 */
232 typedef enum {
233 PUGL_SCROLL_UP, ///< Scroll up
234 PUGL_SCROLL_DOWN, ///< Scroll down
235 PUGL_SCROLL_LEFT, ///< Scroll left
236 PUGL_SCROLL_RIGHT, ///< Scroll right
237 PUGL_SCROLL_SMOOTH ///< Smooth scroll in any direction
238 } PuglScrollDirection;
239
240 /// Common header for all event structs
241 typedef struct {
242 PuglEventType type; ///< Event type
243 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
244 } PuglAnyEvent;
245
246 /**
247 View create event.
248
249 This event is sent when a view is realized before it is first displayed,
250 with the graphics context entered. This is typically used for setting up
251 the graphics system, for example by loading OpenGL extensions.
252
253 This event type has no extra fields.
254 */
255 typedef PuglAnyEvent PuglCreateEvent;
256
257 /**
258 View destroy event.
259
260 This event is the counterpart to #PuglCreateEvent, and it is sent when the
261 view is being destroyed. This is typically used for tearing down the
262 graphics system, or otherwise freeing any resources allocated when the
263 create event was handled.
264
265 This is the last event sent to any view, and immediately after it is
266 processed, the view is destroyed and may no longer be used.
267
268 This event type has no extra fields.
269 */
270 typedef PuglAnyEvent PuglDestroyEvent;
271
272 /**
273 View resize or move event.
274
275 A configure event is sent whenever the view is resized or moved. When a
276 configure event is received, the graphics context is active but not set up
277 for drawing. For example, it is valid to adjust the OpenGL viewport or
278 otherwise configure the context, but not to draw anything.
279 */
280 typedef struct {
281 PuglEventType type; ///< #PUGL_CONFIGURE
282 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
283 PuglCoord x; ///< Parent-relative X coordinate of view
284 PuglCoord y; ///< Parent-relative Y coordinate of view
285 PuglSpan width; ///< Width of view
286 PuglSpan height; ///< Height of view
287 } PuglConfigureEvent;
288
289 /**
290 View show event.
291
292 This event is sent when a view is mapped to the screen and made visible.
293
294 This event type has no extra fields.
295 */
296 typedef PuglAnyEvent PuglMapEvent;
297
298 /**
299 View hide event.
300
301 This event is sent when a view is unmapped from the screen and made
302 invisible.
303
304 This event type has no extra fields.
305 */
306 typedef PuglAnyEvent PuglUnmapEvent;
307
308 /**
309 View update event.
310
311 This event is sent to every view near the end of a main loop iteration when
312 any pending exposures are about to be redrawn. It is typically used to mark
313 regions to expose with puglPostRedisplay() or puglPostRedisplayRect(). For
314 example, to continuously animate, a view calls puglPostRedisplay() when an
315 update event is received, and it will then shortly receive an expose event.
316 */
317 typedef PuglAnyEvent PuglUpdateEvent;
318
319 /**
320 Expose event for when a region must be redrawn.
321
322 When an expose event is received, the graphics context is active, and the
323 view must draw the entire specified region. The contents of the region are
324 undefined, there is no preservation of anything drawn previously.
325 */
326 typedef struct {
327 PuglEventType type; ///< #PUGL_EXPOSE
328 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
329 PuglCoord x; ///< View-relative top-left X coordinate of region
330 PuglCoord y; ///< View-relative top-left Y coordinate of region
331 PuglSpan width; ///< Width of exposed region
332 PuglSpan height; ///< Height of exposed region
333 } PuglExposeEvent;
334
335 /**
336 View close event.
337
338 This event is sent when the view is to be closed, for example when the user
339 clicks the close button.
340
341 This event type has no extra fields.
342 */
343 typedef PuglAnyEvent PuglCloseEvent;
344
345 /**
346 Keyboard focus event.
347
348 This event is sent whenever the view gains or loses the keyboard focus. The
349 view with the keyboard focus will receive any key press or release events.
350 */
351 typedef struct {
352 PuglEventType type; ///< #PUGL_FOCUS_IN or #PUGL_FOCUS_OUT
353 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
354 PuglCrossingMode mode; ///< Reason for focus change
355 } PuglFocusEvent;
356
357 /**
358 Key press or release event.
359
360 This event represents low-level key presses and releases. This can be used
361 for "direct" keyboard handing like key bindings, but must not be interpreted
362 as text input.
363
364 Keys are represented portably as Unicode code points, using the "natural"
365 code point for the key where possible (see #PuglKey for details). The `key`
366 field is the code for the pressed key, without any modifiers applied. For
367 example, a press or release of the 'A' key will have `key` 97 ('a')
368 regardless of whether shift or control are being held.
369
370 Alternatively, the raw `keycode` can be used to work directly with physical
371 keys, but note that this value is not portable and differs between platforms
372 and hardware.
373 */
374 typedef struct {
375 PuglEventType type; ///< #PUGL_KEY_PRESS or #PUGL_KEY_RELEASE
376 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
377 double time; ///< Time in seconds
378 double x; ///< View-relative X coordinate
379 double y; ///< View-relative Y coordinate
380 double xRoot; ///< Root-relative X coordinate
381 double yRoot; ///< Root-relative Y coordinate
382 PuglMods state; ///< Bitwise OR of #PuglMod flags
383 uint32_t keycode; ///< Raw key code
384 uint32_t key; ///< Unshifted Unicode character code, or 0
385 } PuglKeyEvent;
386
387 /**
388 Character input event.
389
390 This event represents text input, usually as the result of a key press. The
391 text is given both as a Unicode character code and a UTF-8 string.
392
393 Note that this event is generated by the platform's input system, so there
394 is not necessarily a direct correspondence between text events and physical
395 key presses. For example, with some input methods a sequence of several key
396 presses will generate a single character.
397 */
398 typedef struct {
399 PuglEventType type; ///< #PUGL_TEXT
400 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
401 double time; ///< Time in seconds
402 double x; ///< View-relative X coordinate
403 double y; ///< View-relative Y coordinate
404 double xRoot; ///< Root-relative X coordinate
405 double yRoot; ///< Root-relative Y coordinate
406 PuglMods state; ///< Bitwise OR of #PuglMod flags
407 uint32_t keycode; ///< Raw key code
408 uint32_t character; ///< Unicode character code
409 char string[8]; ///< UTF-8 string
410 } PuglTextEvent;
411
412 /**
413 Pointer enter or leave event.
414
415 This event is sent when the pointer enters or leaves the view. This can
416 happen for several reasons (not just the user dragging the pointer over the
417 window edge), as described by the `mode` field.
418 */
419 typedef struct {
420 PuglEventType type; ///< #PUGL_POINTER_IN or #PUGL_POINTER_OUT
421 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
422 double time; ///< Time in seconds
423 double x; ///< View-relative X coordinate
424 double y; ///< View-relative Y coordinate
425 double xRoot; ///< Root-relative X coordinate
426 double yRoot; ///< Root-relative Y coordinate
427 PuglMods state; ///< Bitwise OR of #PuglMod flags
428 PuglCrossingMode mode; ///< Reason for crossing
429 } PuglCrossingEvent;
430
431 /**
432 Button press or release event.
433
434 Button numbers start from 0, and are ordered: primary, secondary, middle.
435 So, on a typical right-handed mouse, the button numbers are:
436
437 Left: 0
438 Right: 1
439 Middle (often a wheel): 2
440
441 Higher button numbers are reported in the same order they are represented on
442 the system. There is no universal standard here, but buttons 3 and 4 are
443 typically a pair of buttons or a rocker, which are usually bound to "back"
444 and "forward" operations.
445
446 Note that these numbers may differ from those used on the underlying
447 platform, since they are manipulated to provide a consistent portable API.
448 */
449 typedef struct {
450 PuglEventType type; ///< #PUGL_BUTTON_PRESS or #PUGL_BUTTON_RELEASE
451 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
452 double time; ///< Time in seconds
453 double x; ///< View-relative X coordinate
454 double y; ///< View-relative Y coordinate
455 double xRoot; ///< Root-relative X coordinate
456 double yRoot; ///< Root-relative Y coordinate
457 PuglMods state; ///< Bitwise OR of #PuglMod flags
458 uint32_t button; ///< Button number starting from 0
459 } PuglButtonEvent;
460
461 /**
462 Pointer motion event.
463 */
464 typedef struct {
465 PuglEventType type; ///< #PUGL_MOTION
466 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
467 double time; ///< Time in seconds
468 double x; ///< View-relative X coordinate
469 double y; ///< View-relative Y coordinate
470 double xRoot; ///< Root-relative X coordinate
471 double yRoot; ///< Root-relative Y coordinate
472 PuglMods state; ///< Bitwise OR of #PuglMod flags
473 } PuglMotionEvent;
474
475 /**
476 Scroll event.
477
478 The scroll distance is expressed in "lines", an arbitrary unit that
479 corresponds to a single tick of a detented mouse wheel. For example, `dy` =
480 1.0 scrolls 1 line up. Some systems and devices support finer resolution
481 and/or higher values for fast scrolls, so programs should handle any value
482 gracefully.
483 */
484 typedef struct {
485 PuglEventType type; ///< #PUGL_SCROLL
486 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
487 double time; ///< Time in seconds
488 double x; ///< View-relative X coordinate
489 double y; ///< View-relative Y coordinate
490 double xRoot; ///< Root-relative X coordinate
491 double yRoot; ///< Root-relative Y coordinate
492 PuglMods state; ///< Bitwise OR of #PuglMod flags
493 PuglScrollDirection direction; ///< Scroll direction
494 double dx; ///< Scroll X distance in lines
495 double dy; ///< Scroll Y distance in lines
496 } PuglScrollEvent;
497
498 /**
499 Custom client message event.
500
501 This can be used to send a custom message to a view, which is delivered via
502 the window system and processed in the event loop as usual. Among other
503 things, this makes it possible to wake up the event loop for any reason.
504 */
505 typedef struct {
506 PuglEventType type; ///< #PUGL_CLIENT
507 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
508 uintptr_t data1; ///< Client-specific data
509 uintptr_t data2; ///< Client-specific data
510 } PuglClientEvent;
511
512 /**
513 Timer event.
514
515 This event is sent at the regular interval specified in the call to
516 puglStartTimer() that activated it.
517
518 The `id` is the application-specific ID given to puglStartTimer() which
519 distinguishes this timer from others. It should always be checked in the
520 event handler, even in applications that register only one timer.
521 */
522 typedef struct {
523 PuglEventType type; ///< #PUGL_TIMER
524 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
525 uintptr_t id; ///< Timer ID
526 } PuglTimerEvent;
527
528 /**
529 Clipboard data offer event.
530
531 This event is sent when a clipboard has data present, possibly with several
532 datatypes. While handling this event, the types can be investigated with
533 puglGetClipboardType() to decide whether to accept the offer with
534 puglAcceptOffer().
535 */
536 typedef struct {
537 PuglEventType type; ///< #PUGL_DATA_OFFER
538 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
539 double time; ///< Time in seconds
540 } PuglDataOfferEvent;
541
542 /**
543 Clipboard data event.
544
545 This event is sent after accepting a data offer when the data has been
546 retrieved and converted. While handling this event, the data can be
547 accessed with puglGetClipboard().
548 */
549 typedef struct {
550 PuglEventType type; ///< #PUGL_DATA
551 PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
552 double time; ///< Time in seconds
553 uint32_t typeIndex; ///< Index of datatype
554 } PuglDataEvent;
555
556 /**
557 Recursive loop enter event.
558
559 This event is sent when the window system enters a recursive loop. The main
560 loop will be stalled and no expose events will be received while in the
561 recursive loop. To give the application full control, Pugl does not do any
562 special handling of this situation, but this event can be used to install a
563 timer to perform continuous actions (such as drawing) on platforms that do
564 this.
565
566 - MacOS: A recursive loop is entered while the window is being live resized.
567
568 - Windows: A recursive loop is entered while the window is being live
569 resized or the menu is shown.
570
571 - X11: A recursive loop is never entered and the event loop runs as usual
572 while the view is being resized.
573
574 This event type has no extra fields.
575 */
576 typedef PuglAnyEvent PuglLoopEnterEvent;
577
578 /**
579 Recursive loop leave event.
580
581 This event is sent after a loop enter event when the recursive loop is
582 finished and normal iteration will continue.
583
584 This event type has no extra fields.
585 */
586 typedef PuglAnyEvent PuglLoopLeaveEvent;
587
588 /**
589 View event.
590
591 This is a union of all event types. The type must be checked to determine
592 which fields are safe to access. A pointer to PuglEvent can either be cast
593 to the appropriate type, or the union members used.
594
595 The graphics system may only be accessed when handling certain events. The
596 graphics context is active for #PUGL_CREATE, #PUGL_DESTROY, #PUGL_CONFIGURE,
597 and #PUGL_EXPOSE, but only enabled for drawing for #PUGL_EXPOSE.
598 */
599 typedef union {
600 PuglAnyEvent any; ///< Valid for all event types
601 PuglEventType type; ///< Event type
602 PuglButtonEvent button; ///< #PUGL_BUTTON_PRESS, #PUGL_BUTTON_RELEASE
603 PuglConfigureEvent configure; ///< #PUGL_CONFIGURE
604 PuglExposeEvent expose; ///< #PUGL_EXPOSE
605 PuglKeyEvent key; ///< #PUGL_KEY_PRESS, #PUGL_KEY_RELEASE
606 PuglTextEvent text; ///< #PUGL_TEXT
607 PuglCrossingEvent crossing; ///< #PUGL_POINTER_IN, #PUGL_POINTER_OUT
608 PuglMotionEvent motion; ///< #PUGL_MOTION
609 PuglScrollEvent scroll; ///< #PUGL_SCROLL
610 PuglFocusEvent focus; ///< #PUGL_FOCUS_IN, #PUGL_FOCUS_OUT
611 PuglClientEvent client; ///< #PUGL_CLIENT
612 PuglTimerEvent timer; ///< #PUGL_TIMER
613 PuglDataOfferEvent offer; ///< #PUGL_DATA_OFFER
614 PuglDataEvent data; ///< #PUGL_DATA
615 } PuglEvent;
616
617 /**
618 @}
619 @defgroup status Status
620
621 Most functions return a status code which can be used to check for errors.
622
623 @{
624 */
625
626 /// Return status code
627 typedef enum {
628 PUGL_SUCCESS, ///< Success
629 PUGL_FAILURE, ///< Non-fatal failure
630 PUGL_UNKNOWN_ERROR, ///< Unknown system error
631 PUGL_BAD_BACKEND, ///< Invalid or missing backend
632 PUGL_BAD_CONFIGURATION, ///< Invalid view configuration
633 PUGL_BAD_PARAMETER, ///< Invalid parameter
634 PUGL_BACKEND_FAILED, ///< Backend initialization failed
635 PUGL_REGISTRATION_FAILED, ///< Class registration failed
636 PUGL_REALIZE_FAILED, ///< System view realization failed
637 PUGL_SET_FORMAT_FAILED, ///< Failed to set pixel format
638 PUGL_CREATE_CONTEXT_FAILED, ///< Failed to create drawing context
639 PUGL_UNSUPPORTED, ///< Unsupported operation
640 PUGL_NO_MEMORY, ///< Failed to allocate memory
641 } PuglStatus;
642
643 /// Return a string describing a status code
644 PUGL_CONST_API
645 const char*
646 puglStrerror(PuglStatus status);
647
648 /**
649 @}
650 @defgroup world World
651
652 The top-level context of a Pugl application or plugin.
653
654 The world contains all library-wide state. There is no static data in Pugl,
655 so it is safe to use multiple worlds in a single process. This is to
656 facilitate plugins or other situations where it is not possible to share a
657 world, but a single world should be shared for all views where possible.
658
659 @{
660 */
661
662 /**
663 The "world" of application state.
664
665 The world represents everything that is not associated with a particular
666 view. Several worlds can be created in a single process, but code using
667 different worlds must be isolated so they are never mixed. Views are
668 strongly associated with the world they were created in.
669 */
670 typedef struct PuglWorldImpl PuglWorld;
671
672 /// Handle for the world's opaque user data
673 typedef void* PuglWorldHandle;
674
675 /// The type of a World
676 typedef enum {
677 PUGL_PROGRAM, ///< Top-level application
678 PUGL_MODULE ///< Plugin or module within a larger application
679 } PuglWorldType;
680
681 /// World flags
682 typedef enum {
683 /**
684 Set up support for threads if necessary.
685
686 X11: Calls XInitThreads() which is required for some drivers.
687 */
688 PUGL_WORLD_THREADS = 1u << 0u
689 } PuglWorldFlag;
690
691 /// Bitwise OR of #PuglWorldFlag values
692 typedef uint32_t PuglWorldFlags;
693
694 /**
695 Create a new world.
696
697 @param type The type, which dictates what this world is responsible for.
698 @param flags Flags to control world features.
699 @return A new world, which must be later freed with puglFreeWorld().
700 */
701 PUGL_API
702 PuglWorld*
703 puglNewWorld(PuglWorldType type, PuglWorldFlags flags);
704
705 /// Free a world allocated with puglNewWorld()
706 PUGL_API
707 void
708 puglFreeWorld(PuglWorld* world);
709
710 /**
711 Set the user data for the world.
712
713 This is usually a pointer to a struct that contains all the state which must
714 be accessed by several views.
715
716 The handle is opaque to Pugl and is not interpreted in any way.
717 */
718 PUGL_API
719 void
720 puglSetWorldHandle(PuglWorld* world, PuglWorldHandle handle);
721
722 /// Get the user data for the world
723 PUGL_API
724 PuglWorldHandle
725 puglGetWorldHandle(PuglWorld* world);
726
727 /**
728 Return a pointer to the native handle of the world.
729
730 X11: Returns a pointer to the `Display`.
731
732 MacOS: Returns a pointer to the `NSApplication`.
733
734 Windows: Returns the `HMODULE` of the calling process.
735 */
736 PUGL_API
737 void*
738 puglGetNativeWorld(PuglWorld* world);
739
740 /**
741 Set the class name of the application.
742
743 This is a stable identifier for the application, used as the window
744 class/instance name on X11 and Windows. It is not displayed to the user,
745 but can be used in scripts and by window managers, so it should be the same
746 for every instance of the application, but different from other
747 applications.
748 */
749 PUGL_API
750 PuglStatus
751 puglSetClassName(PuglWorld* world, const char* name);
752
753 /// Get the class name of the application, or null
754 PUGL_API
755 const char*
756 puglGetClassName(const PuglWorld* world);
757
758 /**
759 Return the time in seconds.
760
761 This is a monotonically increasing clock with high resolution. The returned
762 time is only useful to compare against other times returned by this
763 function, its absolute value has no meaning.
764 */
765 PUGL_API
766 double
767 puglGetTime(const PuglWorld* world);
768
769 /**
770 Update by processing events from the window system.
771
772 This function is a single iteration of the main loop, and should be called
773 repeatedly to update all views.
774
775 If `timeout` is zero, then this function will not block. Plugins should
776 always use a timeout of zero to avoid blocking the host.
777
778 If a positive `timeout` is given, then events will be processed for that
779 amount of time, starting from when this function was called.
780
781 If a negative `timeout` is given, this function will block indefinitely
782 until an event occurs.
783
784 For continuously animating programs, a timeout that is a reasonable fraction
785 of the ideal frame period should be used, to minimize input latency by
786 ensuring that as many input events are consumed as possible before drawing.
787
788 @return #PUGL_SUCCESS if events are read, #PUGL_FAILURE if no events are
789 read, or an error.
790 */
791 PUGL_API
792 PuglStatus
793 puglUpdate(PuglWorld* world, double timeout);
794
795 /**
796 @}
797 @defgroup view View
798
799 A drawable region that receives events.
800
801 A view can be thought of as a window, but does not necessarily correspond to
802 a top-level window in a desktop environment. For example, a view can be
803 embedded in some other window, or represent an embedded system where there
804 is no concept of multiple windows at all.
805
806 @{
807 */
808
809 /// A drawable region that receives events
810 typedef struct PuglViewImpl PuglView;
811
812 /**
813 A graphics backend.
814
815 The backend dictates how graphics are set up for a view, and how drawing is
816 performed. A backend must be set by calling puglSetBackend() before
817 realising a view.
818
819 If you are using a local copy of Pugl, it is possible to implement a custom
820 backend. See the definition of `PuglBackendImpl` in the source code for
821 details.
822 */
823 typedef struct PuglBackendImpl PuglBackend;
824
825 /**
826 A native view handle.
827
828 X11: This is a `Window`.
829
830 MacOS: This is a pointer to an `NSView*`.
831
832 Windows: This is a `HWND`.
833 */
834 typedef uintptr_t PuglNativeView;
835
836 /// Handle for a view's opaque user data
837 typedef void* PuglHandle;
838
839 /// A hint for configuring a view
840 typedef enum {
841 PUGL_USE_COMPAT_PROFILE, ///< Use compatible (not core) OpenGL profile
842 PUGL_USE_DEBUG_CONTEXT, ///< True to use a debug OpenGL context
843 PUGL_CONTEXT_VERSION_MAJOR, ///< OpenGL context major version
844 PUGL_CONTEXT_VERSION_MINOR, ///< OpenGL context minor version
845 PUGL_RED_BITS, ///< Number of bits for red channel
846 PUGL_GREEN_BITS, ///< Number of bits for green channel
847 PUGL_BLUE_BITS, ///< Number of bits for blue channel
848 PUGL_ALPHA_BITS, ///< Number of bits for alpha channel
849 PUGL_DEPTH_BITS, ///< Number of bits for depth buffer
850 PUGL_STENCIL_BITS, ///< Number of bits for stencil buffer
851 PUGL_SAMPLES, ///< Number of samples per pixel (AA)
852 PUGL_DOUBLE_BUFFER, ///< True if double buffering should be used
853 PUGL_SWAP_INTERVAL, ///< Number of frames between buffer swaps
854 PUGL_RESIZABLE, ///< True if view should be resizable
855 PUGL_IGNORE_KEY_REPEAT, ///< True if key repeat events are ignored
856 PUGL_REFRESH_RATE, ///< Refresh rate in Hz
857 } PuglViewHint;
858
859 /// The number of #PuglViewHint values
860 #define PUGL_NUM_VIEW_HINTS ((unsigned)PUGL_REFRESH_RATE + 1u)
861
862 /// A special view hint value
863 typedef enum {
864 PUGL_DONT_CARE = -1, ///< Use best available value
865 PUGL_FALSE = 0, ///< Explicitly false
866 PUGL_TRUE = 1 ///< Explicitly true
867 } PuglViewHintValue;
868
869 /**
870 A hint for configuring/constraining the size of a view.
871
872 The system will attempt to make the view's window adhere to these, but they
873 are suggestions, not hard constraints. Applications should handle any view
874 size gracefully.
875 */
876 typedef enum {
877 PUGL_DEFAULT_SIZE, ///< Default size
878 PUGL_MIN_SIZE, ///< Minimum size
879 PUGL_MAX_SIZE, ///< Maximum size
880
881 /**
882 Fixed aspect ratio.
883
884 If set, the view's size should be constrained to this aspect ratio.
885 Mutually exclusive with #PUGL_MIN_ASPECT and #PUGL_MAX_ASPECT.
886 */
887 PUGL_FIXED_ASPECT,
888
889 /**
890 Minimum aspect ratio.
891
892 If set, the view's size should be constrained to an aspect ratio no lower
893 than this. Mutually exclusive with #PUGL_FIXED_ASPECT.
894 */
895 PUGL_MIN_ASPECT,
896
897 /**
898 Maximum aspect ratio.
899
900 If set, the view's size should be constrained to an aspect ratio no higher
901 than this. Mutually exclusive with #PUGL_FIXED_ASPECT.
902 */
903 PUGL_MAX_ASPECT
904 } PuglSizeHint;
905
906 /// The number of #PuglSizeHint values
907 #define PUGL_NUM_SIZE_HINTS ((unsigned)PUGL_MAX_ASPECT + 1u)
908
909 /// A function called when an event occurs
910 typedef PuglStatus (*PuglEventFunc)(PuglView* view, const PuglEvent* event);
911
912 /**
913 @defgroup setup Setup
914 Functions for creating and destroying a view.
915 @{
916 */
917
918 /**
919 Create a new view.
920
921 A newly created view does not correspond to a real system view or window.
922 It must first be configured, then the system view can be created with
923 puglRealize().
924 */
925 PUGL_API
926 PuglView*
927 puglNewView(PuglWorld* world);
928
929 /// Free a view created with puglNewView()
930 PUGL_API
931 void
932 puglFreeView(PuglView* view);
933
934 /// Return the world that `view` is a part of
935 PUGL_API
936 PuglWorld*
937 puglGetWorld(PuglView* view);
938
939 /**
940 Set the user data for a view.
941
942 This is usually a pointer to a struct that contains all the state which must
943 be accessed by a view. Everything needed to process events should be stored
944 here, not in static variables.
945
946 The handle is opaque to Pugl and is not interpreted in any way.
947 */
948 PUGL_API
949 void
950 puglSetHandle(PuglView* view, PuglHandle handle);
951
952 /// Get the user data for a view
953 PUGL_API
954 PuglHandle
955 puglGetHandle(PuglView* view);
956
957 /**
958 Set the graphics backend to use for a view.
959
960 This must be called once to set the graphics backend before calling
961 puglRealize().
962
963 Pugl includes the following backends:
964
965 - puglCairoBackend()
966 - puglGlBackend()
967 - puglVulkanBackend()
968
969 Note that backends are modular and not compiled into the main Pugl library
970 to avoid unnecessary dependencies. To use a particular backend,
971 applications must link against the appropriate backend library, or be sure
972 to compile in the appropriate code if using a local copy of Pugl.
973 */
974 PUGL_API
975 PuglStatus
976 puglSetBackend(PuglView* view, const PuglBackend* backend);
977
978 /// Return the graphics backend used by a view
979 const PuglBackend*
980 puglGetBackend(const PuglView* view);
981
982 /// Set the function to call when an event occurs
983 PUGL_API
984 PuglStatus
985 puglSetEventFunc(PuglView* view, PuglEventFunc eventFunc);
986
987 /**
988 Set a hint to configure view properties.
989
990 This only has an effect when called before puglRealize().
991 */
992 PUGL_API
993 PuglStatus
994 puglSetViewHint(PuglView* view, PuglViewHint hint, int value);
995
996 /**
997 Get the value for a view hint.
998
999 If the view has been realized, this can be used to get the actual value of a
1000 hint which was initially set to PUGL_DONT_CARE, or has been adjusted from
1001 the suggested value.
1002 */
1003 PUGL_API
1004 int
1005 puglGetViewHint(const PuglView* view, PuglViewHint hint);
1006
1007 /**
1008 Return the scale factor of the view.
1009
1010 This factor describe how large UI elements (especially text) should be
1011 compared to "normal". For example, 2.0 means the UI should be drawn twice
1012 as large.
1013
1014 "Normal" is loosely defined, but means a good size on a "standard DPI"
1015 display (around 96 DPI). In other words, the scale 1.0 should have text
1016 that is reasonably sized on a 96 DPI display, and the scale 2.0 should have
1017 text twice that large.
1018 */
1019 PUGL_API
1020 double
1021 puglGetScaleFactor(const PuglView* view);
1022
1023 /**
1024 @}
1025 @defgroup frame Frame
1026 Functions for working with the position and size of a view.
1027 @{
1028 */
1029
1030 /**
1031 Get the current position and size of the view.
1032
1033 The position is in screen coordinates with an upper left origin.
1034 */
1035 PUGL_API
1036 PuglRect
1037 puglGetFrame(const PuglView* view);
1038
1039 /**
1040 Set the current position and size of the view.
1041
1042 The position is in screen coordinates with an upper left origin.
1043
1044 @return #PUGL_UNKNOWN_ERROR on failure, in which case the view frame is
1045 unchanged.
1046 */
1047 PUGL_API
1048 PuglStatus
1049 puglSetFrame(PuglView* view, PuglRect frame);
1050
1051 /**
1052 Set the current position of the view.
1053
1054 @return #PUGL_UNKNOWN_ERROR on failure, in which case the view frame is
1055 unchanged.
1056 */
1057 PUGL_API
1058 PuglStatus
1059 puglSetPosition(PuglView* view, int x, int y);
1060
1061 /**
1062 Set the current size of the view.
1063
1064 @return #PUGL_UNKNOWN_ERROR on failure, in which case the view frame is
1065 unchanged.
1066 */
1067 PUGL_API
1068 PuglStatus
1069 puglSetSize(PuglView* view, unsigned width, unsigned height);
1070
1071 /**
1072 Set a size hint for the view.
1073
1074 This can be used to set the default, minimum, and maximum size of a view,
1075 as well as the supported range of aspect ratios.
1076
1077 This should be called before puglRealize() so the initial window for the
1078 view can be configured correctly.
1079
1080 @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is
1081 not yet realized.
1082 */
1083 PUGL_API
1084 PuglStatus
1085 puglSetSizeHint(PuglView* view,
1086 PuglSizeHint hint,
1087 PuglSpan width,
1088 PuglSpan height);
1089
1090 /**
1091 @}
1092 @defgroup window Window
1093 Functions to control the top-level window of a view.
1094 @{
1095 */
1096
1097 /**
1098 Set the title of the window.
1099
1100 This only makes sense for non-embedded views that will have a corresponding
1101 top-level window, and sets the title, typically displayed in the title bar
1102 or in window switchers.
1103 */
1104 PUGL_API
1105 PuglStatus
1106 puglSetWindowTitle(PuglView* view, const char* title);
1107
1108 /// Return the title of the window, or null
1109 PUGL_API
1110 const char*
1111 puglGetWindowTitle(const PuglView* view);
1112
1113 /**
1114 Set the parent window for embedding a view in an existing window.
1115
1116 This must be called before puglRealize(), reparenting is not supported.
1117 */
1118 PUGL_API
1119 PuglStatus
1120 puglSetParentWindow(PuglView* view, PuglNativeView parent);
1121
1122 /// Return the parent window this view is embedded in, or null
1123 PUGL_API
1124 PuglNativeView
1125 puglGetParentWindow(const PuglView* view);
1126
1127 /**
1128 Set the transient parent of the window.
1129
1130 Set this for transient children like dialogs, to have them properly
1131 associated with their parent window. This should be called before
1132 puglRealize().
1133
1134 A view can either have a parent (for embedding) or a transient parent (for
1135 top-level windows like dialogs), but not both.
1136 */
1137 PUGL_API
1138 PuglStatus
1139 puglSetTransientParent(PuglView* view, PuglNativeView parent);
1140
1141 /**
1142 Return the transient parent of the window.
1143
1144 @return The native handle to the window this view is a transient child of,
1145 or null.
1146 */
1147 PUGL_API
1148 PuglNativeView
1149 puglGetTransientParent(const PuglView* view);
1150
1151 /**
1152 Realize a view by creating a corresponding system view or window.
1153
1154 After this call, the (initially invisible) underlying system view exists and
1155 can be accessed with puglGetNativeView(). There is currently no
1156 corresponding unrealize function, the system view will be destroyed along
1157 with the view when puglFreeView() is called.
1158
1159 The view should be fully configured using the above functions before this is
1160 called. This function may only be called once per view.
1161 */
1162 PUGL_API
1163 PuglStatus
1164 puglRealize(PuglView* view);
1165
1166 /**
1167 Show the view.
1168
1169 If the view has not yet been realized, the first call to this function will
1170 do so automatically.
1171
1172 If the view is currently hidden, it will be shown and possibly raised to the
1173 top depending on the platform.
1174 */
1175 PUGL_API
1176 PuglStatus
1177 puglShow(PuglView* view);
1178
1179 /// Hide the current window
1180 PUGL_API
1181 PuglStatus
1182 puglHide(PuglView* view);
1183
1184 /// Return true iff the view is currently visible
1185 PUGL_API
1186 bool
1187 puglGetVisible(const PuglView* view);
1188
1189 /// Return the native window handle
1190 PUGL_API
1191 PuglNativeView
1192 puglGetNativeView(PuglView* view);
1193
1194 /**
1195 @}
1196 @defgroup graphics Graphics
1197 Functions for working with the graphics context and scheduling redisplays.
1198 @{
1199 */
1200
1201 /**
1202 Get the graphics context.
1203
1204 This is a backend-specific context used for drawing if the backend graphics
1205 API requires one. It is only available during an expose.
1206
1207 Cairo: Returns a pointer to a
1208 [cairo_t](http://www.cairographics.org/manual/cairo-cairo-t.html).
1209
1210 All other backends: returns null.
1211 */
1212 PUGL_API
1213 void*
1214 puglGetContext(PuglView* view);
1215
1216 /**
1217 Request a redisplay for the entire view.
1218
1219 This will cause an expose event to be dispatched later. If called from
1220 within the event handler, the expose should arrive at the end of the current
1221 event loop iteration, though this is not strictly guaranteed on all
1222 platforms. If called elsewhere, an expose will be enqueued to be processed
1223 in the next event loop iteration.
1224 */
1225 PUGL_API
1226 PuglStatus
1227 puglPostRedisplay(PuglView* view);
1228
1229 /**
1230 Request a redisplay of the given rectangle within the view.
1231
1232 This has the same semantics as puglPostRedisplay(), but allows giving a
1233 precise region for redrawing only a portion of the view.
1234 */
1235 PUGL_API
1236 PuglStatus
1237 puglPostRedisplayRect(PuglView* view, PuglRect rect);
1238
1239 /**
1240 @}
1241 @defgroup interaction Interaction
1242 Functions for interacting with the user and window system.
1243 @{
1244 */
1245
1246 /**
1247 A mouse cursor type.
1248
1249 This is a portable subset of mouse cursors that exist on X11, MacOS, and
1250 Windows.
1251 */
1252 typedef enum {
1253 PUGL_CURSOR_ARROW, ///< Default pointing arrow
1254 PUGL_CURSOR_CARET, ///< Caret (I-Beam) for text entry
1255 PUGL_CURSOR_CROSSHAIR, ///< Cross-hair
1256 PUGL_CURSOR_HAND, ///< Hand with a pointing finger
1257 PUGL_CURSOR_NO, ///< Operation not allowed
1258 PUGL_CURSOR_LEFT_RIGHT, ///< Left/right arrow for horizontal resize
1259 PUGL_CURSOR_UP_DOWN, ///< Up/down arrow for vertical resize
1260 PUGL_CURSOR_DIAGONAL, ///< Top-left to bottom-right arrow for diagonal resize
1261 PUGL_CURSOR_ANTI_DIAGONAL, ///< Bottom-left to top-right arrow for diagonal resize
1262 } PuglCursor;
1263
1264 /// The number of #PuglCursor values
1265 #define PUGL_NUM_CURSORS ((unsigned)PUGL_CURSOR_ANTI_DIAGONAL + 1u)
1266
1267 /**
1268 Grab the keyboard input focus.
1269
1270 Note that this will fail if the view is not mapped and so should not, for
1271 example, be called immediately after puglShow().
1272
1273 @return #PUGL_SUCCESS if the focus was successfully grabbed, or an error.
1274 */
1275 PUGL_API
1276 PuglStatus
1277 puglGrabFocus(PuglView* view);
1278
1279 /// Return whether `view` has the keyboard input focus
1280 PUGL_API
1281 bool
1282 puglHasFocus(const PuglView* view);
1283
1284 /**
1285 Request data from the general copy/paste clipboard.
1286
1287 A #PUGL_DATA_OFFER event will be sent if data is available.
1288 */
1289 PUGL_API
1290 PuglStatus
1291 puglPaste(PuglView* view);
1292
1293 /**
1294 Return the number of types available for the data in a clipboard.
1295
1296 Returns zero if the clipboard is empty.
1297 */
1298 PUGL_API
1299 uint32_t
1300 puglGetNumClipboardTypes(const PuglView* view);
1301
1302 /**
1303 Return the identifier of a type available in a clipboard.
1304
1305 This is usually a MIME type, but may also be another platform-specific type
1306 identifier. Applications must ignore any type they do not recognize.
1307
1308 Returns null if `typeIndex` is out of bounds according to
1309 puglGetNumClipboardTypes().
1310 */
1311 PUGL_API
1312 const char*
1313 puglGetClipboardType(const PuglView* view, uint32_t typeIndex);
1314
1315 /**
1316 Accept data offered from a clipboard.
1317
1318 To accept data, this must be called while handling a #PUGL_DATA_OFFER event.
1319 Doing so will request the data from the source as the specified type. When
1320 the data is available, a #PUGL_DATA event will be sent to the view which can
1321 then retrieve the data with puglGetClipboard().
1322
1323 @param view The view.
1324
1325 @param offer The data offer event.
1326
1327 @param typeIndex The index of the type that the view will accept. This is
1328 the `typeIndex` argument to the call of puglGetClipboardType() that returned
1329 the accepted type.
1330 */
1331 PUGL_API
1332 PuglStatus
1333 puglAcceptOffer(PuglView* view,
1334 const PuglDataOfferEvent* offer,
1335 uint32_t typeIndex);
1336
1337 /**
1338 Set the clipboard contents.
1339
1340 This sets the system clipboard contents, which can be retrieved with
1341 puglGetClipboard() or pasted into other applications.
1342
1343 @param view The view.
1344 @param type The MIME type of the data, "text/plain" is assumed if `NULL`.
1345 @param data The data to copy to the clipboard.
1346 @param len The length of data in bytes (including terminator if necessary).
1347 */
1348 PUGL_API
1349 PuglStatus
1350 puglSetClipboard(PuglView* view,
1351 const char* type,
1352 const void* data,
1353 size_t len);
1354
1355 /**
1356 Get the clipboard contents.
1357
1358 This gets the system clipboard contents, which may have been set with
1359 puglSetClipboard() or copied from another application.
1360
1361 @param view The view.
1362 @param typeIndex Index of the data type to get the item as.
1363 @param[out] len Set to the length of the data in bytes.
1364 @return The clipboard contents, or null.
1365 */
1366 PUGL_API
1367 const void*
1368 puglGetClipboard(PuglView* view, uint32_t typeIndex, size_t* len);
1369
1370 /**
1371 Set the mouse cursor.
1372
1373 This changes the system cursor that is displayed when the pointer is inside
1374 the view. May fail if setting the cursor is not supported on this system,
1375 for example if compiled on X11 without Xcursor support.
1376
1377 @return #PUGL_BAD_PARAMETER if the given cursor is invalid,
1378 #PUGL_FAILURE if the cursor is known but loading it system fails.
1379 */
1380 PUGL_API
1381 PuglStatus
1382 puglSetCursor(PuglView* view, PuglCursor cursor);
1383
1384 /**
1385 Request user attention.
1386
1387 This hints to the system that the window or application requires attention
1388 from the user. The exact effect depends on the platform, but is usually
1389 something like a flashing task bar entry or bouncing application icon.
1390 */
1391 PUGL_API
1392 PuglStatus
1393 puglRequestAttention(PuglView* view);
1394
1395 /**
1396 Activate a repeating timer event.
1397
1398 This starts a timer which will send a #PuglTimerEvent to `view` every
1399 `timeout` seconds. This can be used to perform some action in a view at a
1400 regular interval with relatively low frequency. Note that the frequency of
1401 timer events may be limited by how often puglUpdate() is called.
1402
1403 If the given timer already exists, it is replaced.
1404
1405 @param view The view to begin sending #PUGL_TIMER events to.
1406
1407 @param id The identifier for this timer. This is an application-specific ID
1408 that should be a low number, typically the value of a constant or `enum`
1409 that starts from 0. There is a platform-specific limit to the number of
1410 supported timers, and overhead associated with each, so applications should
1411 create only a few timers and perform several tasks in one if necessary.
1412
1413 @param timeout The period, in seconds, of this timer. This is not
1414 guaranteed to have a resolution better than 10ms (the maximum timer
1415 resolution on Windows) and may be rounded up if it is too short. On X11 and
1416 MacOS, a resolution of about 1ms can usually be relied on.
1417
1418 @return #PUGL_FAILURE if timers are not supported by the system,
1419 #PUGL_UNKNOWN_ERROR if setting the timer failed.
1420 */
1421 PUGL_API
1422 PuglStatus
1423 puglStartTimer(PuglView* view, uintptr_t id, double timeout);
1424
1425 /**
1426 Stop an active timer.
1427
1428 @param view The view that the timer is set for.
1429 @param id The ID previously passed to puglStartTimer().
1430
1431 @return #PUGL_FAILURE if timers are not supported by this system,
1432 #PUGL_UNKNOWN_ERROR if stopping the timer failed.
1433 */
1434 PUGL_API
1435 PuglStatus
1436 puglStopTimer(PuglView* view, uintptr_t id);
1437
1438 /**
1439 Send an event to a view via the window system.
1440
1441 If supported, the event will be delivered to the view via the event loop
1442 like other events. Note that this function only works for certain event
1443 types.
1444
1445 Currently, only #PUGL_CLIENT events are supported on all platforms.
1446
1447 X11: A #PUGL_EXPOSE event can be sent, which is similar to calling
1448 puglPostRedisplayRect(), but will always send a message to the X server,
1449 even when called in an event handler.
1450
1451 @return #PUGL_UNSUPPORTED if sending events of this type is not supported,
1452 #PUGL_UNKNOWN_ERROR if sending the event failed.
1453 */
1454 PUGL_API
1455 PuglStatus
1456 puglSendEvent(PuglView* view, const PuglEvent* event);
1457
1458 /**
1459 @}
1460 */
1461
1462 #ifndef PUGL_DISABLE_DEPRECATED
1463
1464 /**
1465 @}
1466 @defgroup deprecated Deprecated API
1467 @{
1468 */
1469
1470 PUGL_DEPRECATED_BY("PuglCreateEvent")
1471 typedef PuglCreateEvent PuglEventCreate;
1472
1473 PUGL_DEPRECATED_BY("PuglDestroyEvent")
1474 typedef PuglDestroyEvent PuglEventDestroy;
1475
1476 PUGL_DEPRECATED_BY("PuglConfigureEvent")
1477 typedef PuglConfigureEvent PuglEventConfigure;
1478
1479 PUGL_DEPRECATED_BY("PuglMapEvent")
1480 typedef PuglMapEvent PuglEventMap;
1481
1482 PUGL_DEPRECATED_BY("PuglUnmapEvent")
1483 typedef PuglUnmapEvent PuglEventUnmap;
1484
1485 PUGL_DEPRECATED_BY("PuglUpdateEvent")
1486 typedef PuglUpdateEvent PuglEventUpdate;
1487
1488 PUGL_DEPRECATED_BY("PuglExposeEvent")
1489 typedef PuglExposeEvent PuglEventExpose;
1490
1491 PUGL_DEPRECATED_BY("PuglCloseEvent")
1492 typedef PuglCloseEvent PuglEventClose;
1493
1494 PUGL_DEPRECATED_BY("PuglFocusEvent")
1495 typedef PuglFocusEvent PuglEventFocus;
1496
1497 PUGL_DEPRECATED_BY("PuglKeyEvent")
1498 typedef PuglKeyEvent PuglEventKey;
1499
1500 PUGL_DEPRECATED_BY("PuglTextEvent")
1501 typedef PuglTextEvent PuglEventText;
1502
1503 PUGL_DEPRECATED_BY("PuglCrossingEvent")
1504 typedef PuglCrossingEvent PuglEventCrossing;
1505
1506 PUGL_DEPRECATED_BY("PuglButtonEvent")
1507 typedef PuglButtonEvent PuglEventButton;
1508
1509 PUGL_DEPRECATED_BY("PuglMotionEvent")
1510 typedef PuglMotionEvent PuglEventMotion;
1511
1512 PUGL_DEPRECATED_BY("PuglScrollEvent")
1513 typedef PuglScrollEvent PuglEventScroll;
1514
1515 PUGL_DEPRECATED_BY("PuglClientEvent")
1516 typedef PuglClientEvent PuglEventClient;
1517
1518 PUGL_DEPRECATED_BY("PuglTimerEvent")
1519 typedef PuglTimerEvent PuglEventTimer;
1520
1521 PUGL_DEPRECATED_BY("PuglLoopEnterEvent")
1522 typedef PuglLoopEnterEvent PuglEventLoopEnter;
1523
1524 PUGL_DEPRECATED_BY("PuglLoopLeaveEvent")
1525 typedef PuglLoopLeaveEvent PuglEventLoopLeave;
1526
1527 /**
1528 A native window handle.
1529
1530 X11: This is a `Window`.
1531
1532 MacOS: This is a pointer to an `NSView*`.
1533
1534 Windows: This is a `HWND`.
1535 */
1536 PUGL_DEPRECATED_BY("PuglNativeView")
1537 typedef uintptr_t PuglNativeWindow;
1538
1539 /**
1540 Create a Pugl application and view.
1541
1542 To create a window, call the various puglInit* functions as necessary, then
1543 call puglRealize().
1544
1545 @deprecated Use puglNewApp() and puglNewView().
1546
1547 @param pargc Pointer to argument count (currently unused).
1548 @param argv Arguments (currently unused).
1549 @return A newly created view.
1550 */
1551 static inline PUGL_DEPRECATED_BY("puglNewView")
1552 PuglView*
1553 puglInit(const int* pargc, char** argv)
1554 {
1555 (void)pargc;
1556 (void)argv;
1557
1558 return puglNewView(puglNewWorld(PUGL_MODULE, 0));
1559 }
1560
1561 /**
1562 Destroy an app and view created with `puglInit()`.
1563
1564 @deprecated Use puglFreeApp() and puglFreeView().
1565 */
1566 static inline PUGL_DEPRECATED_BY("puglFreeView")
1567 void
1568 puglDestroy(PuglView* view)
1569 {
1570 PuglWorld* const world = puglGetWorld(view);
1571
1572 puglFreeView(view);
1573 puglFreeWorld(world);
1574 }
1575
1576 /**
1577 Set the window class name before creating a window.
1578 */
1579 static inline PUGL_DEPRECATED_BY("puglSetClassName")
1580 void
1581 puglInitWindowClass(PuglView* view, const char* name)
1582 {
1583 puglSetClassName(puglGetWorld(view), name);
1584 }
1585
1586 /**
1587 Set the window size before creating a window.
1588
1589 @deprecated Use puglSetFrame().
1590 */
1591 static inline PUGL_DEPRECATED_BY("puglSetFrame")
1592 void
1593 puglInitWindowSize(PuglView* view, int width, int height)
1594 {
1595 PuglRect frame = puglGetFrame(view);
1596
1597 frame.width = (PuglSpan)width;
1598 frame.height = (PuglSpan)height;
1599
1600 puglSetFrame(view, frame);
1601 }
1602
1603 /**
1604 Set the minimum window size before creating a window.
1605 */
1606 static inline PUGL_DEPRECATED_BY("puglSetMinSize")
1607 void
1608 puglInitWindowMinSize(PuglView* view, int width, int height)
1609 {
1610 puglSetSizeHint(view, PUGL_MIN_SIZE, (PuglSpan)width, (PuglSpan)height);
1611 }
1612
1613 /**
1614 Set the window aspect ratio range before creating a window.
1615
1616 The x and y values here represent a ratio of width to height. To set a
1617 fixed aspect ratio, set the minimum and maximum values to the same ratio.
1618
1619 Note that setting different minimum and maximum constraints does not
1620 currently work on MacOS (the minimum is used), so only setting a fixed
1621 aspect ratio works properly across all platforms.
1622 */
1623 static inline PUGL_DEPRECATED_BY("puglSetAspectRatio")
1624 void
1625 puglInitWindowAspectRatio(PuglView* view,
1626 int minX,
1627 int minY,
1628 int maxX,
1629 int maxY)
1630 {
1631 puglSetSizeHint(view, PUGL_MIN_ASPECT, (PuglSpan)minX, (PuglSpan)minY);
1632 puglSetSizeHint(view, PUGL_MAX_ASPECT, (PuglSpan)maxX, (PuglSpan)maxY);
1633 }
1634
1635 /**
1636 Set transient parent before creating a window.
1637
1638 On X11, parent must be a Window.
1639 On OSX, parent must be an NSView*.
1640 */
1641 static inline PUGL_DEPRECATED_BY("puglSetTransientParent")
1642 void
1643 puglInitTransientFor(PuglView* view, uintptr_t parent)
1644 {
1645 puglSetTransientParent(view, (PuglNativeWindow)parent);
1646 }
1647
1648 /**
1649 Set transient parent before creating a window.
1650
1651 @deprecated Use puglSetTransientParent().
1652 */
1653 static inline PUGL_DEPRECATED_BY("puglSetTransientParent")
1654 PuglStatus
1655 puglSetTransientFor(PuglView* view, uintptr_t parent)
1656 {
1657 return puglSetTransientParent(view, (PuglNativeWindow)parent);
1658 }
1659
1660 /**
1661 Enable or disable resizing before creating a window.
1662
1663 @deprecated Use puglSetViewHint() with #PUGL_RESIZABLE.
1664 */
1665 static inline PUGL_DEPRECATED_BY("puglSetViewHint")
1666 void
1667 puglInitResizable(PuglView* view, bool resizable)
1668 {
1669 puglSetViewHint(view, PUGL_RESIZABLE, resizable);
1670 }
1671
1672 /**
1673 Get the current size of the view.
1674
1675 @deprecated Use puglGetFrame().
1676
1677 */
1678 static inline PUGL_DEPRECATED_BY("puglGetFrame")
1679 void
1680 puglGetSize(PuglView* view, int* width, int* height)
1681 {
1682 const PuglRect frame = puglGetFrame(view);
1683
1684 *width = (int)frame.width;
1685 *height = (int)frame.height;
1686 }
1687
1688 /**
1689 Ignore synthetic repeated key events.
1690
1691 @deprecated Use puglSetViewHint() with #PUGL_IGNORE_KEY_REPEAT.
1692 */
1693 static inline PUGL_DEPRECATED_BY("puglSetViewHint")
1694 void
1695 puglIgnoreKeyRepeat(PuglView* view, bool ignore)
1696 {
1697 puglSetViewHint(view, PUGL_IGNORE_KEY_REPEAT, ignore);
1698 }
1699
1700 /**
1701 Set a hint before creating a window.
1702
1703 @deprecated Use puglSetWindowHint().
1704 */
1705 static inline PUGL_DEPRECATED_BY("puglSetViewHint")
1706 void
1707 puglInitWindowHint(PuglView* view, PuglViewHint hint, int value)
1708 {
1709 puglSetViewHint(view, hint, value);
1710 }
1711
1712 /**
1713 Set the parent window before creating a window (for embedding).
1714
1715 @deprecated Use puglSetWindowParent().
1716 */
1717 static inline PUGL_DEPRECATED_BY("puglSetParentWindow")
1718 void
1719 puglInitWindowParent(PuglView* view, PuglNativeWindow parent)
1720 {
1721 puglSetParentWindow(view, parent);
1722 }
1723
1724 /**
1725 Set the graphics backend to use.
1726
1727 @deprecated Use puglSetBackend().
1728 */
1729 static inline PUGL_DEPRECATED_BY("puglSetBackend")
1730 int
1731 puglInitBackend(PuglView* view, const PuglBackend* backend)
1732 {
1733 return (int)puglSetBackend(view, backend);
1734 }
1735
1736 /**
1737 Realize a view by creating a corresponding system view or window.
1738
1739 The view should be fully configured using the above functions before this is
1740 called. This function may only be called once per view.
1741
1742 @deprecated Use puglRealize(), or just show the view.
1743 */
1744 static inline PUGL_DEPRECATED_BY("puglRealize")
1745 PuglStatus
1746 puglCreateWindow(PuglView* view, const char* title)
1747 {
1748 puglSetWindowTitle(view, title);
1749 return puglRealize(view);
1750 }
1751
1752 /**
1753 Block and wait for an event to be ready.
1754
1755 This can be used in a loop to only process events via puglProcessEvents when
1756 necessary. This function will block indefinitely if no events are
1757 available, so is not appropriate for use in programs that need to perform
1758 regular updates (e.g. animation).
1759
1760 @deprecated Use puglPollEvents().
1761 */
1762 PUGL_API
1763 PUGL_DEPRECATED_BY("puglPollEvents")
1764 PuglStatus
1765 puglWaitForEvent(PuglView* view);
1766
1767 /**
1768 Process all pending window events.
1769
1770 This handles input events as well as rendering, so it should be called
1771 regularly and rapidly enough to keep the UI responsive. This function does
1772 not block if no events are pending.
1773
1774 @deprecated Use puglDispatchEvents().
1775 */
1776 PUGL_API
1777 PUGL_DEPRECATED_BY("puglDispatchEvents")
1778 PuglStatus
1779 puglProcessEvents(PuglView* view);
1780
1781 /**
1782 Poll for events that are ready to be processed.
1783
1784 This polls for events that are ready for any view in the world, potentially
1785 blocking depending on `timeout`.
1786
1787 @param world The world to poll for events.
1788
1789 @param timeout Maximum time to wait, in seconds. If zero, the call returns
1790 immediately, if negative, the call blocks indefinitely.
1791
1792 @return #PUGL_SUCCESS if events are read, #PUGL_FAILURE if not, or an error.
1793
1794 @deprecated Use puglUpdate().
1795 */
1796 static inline PUGL_DEPRECATED_BY("puglUpdate")
1797 PuglStatus
1798 puglPollEvents(PuglWorld* world, double timeout)
1799 {
1800 return puglUpdate(world, timeout);
1801 }
1802
1803 /**
1804 Dispatch any pending events to views.
1805
1806 This processes all pending events, dispatching them to the appropriate
1807 views. View event handlers will be called in the scope of this call. This
1808 function does not block, if no events are pending then it will return
1809 immediately.
1810
1811 @deprecated Use puglUpdate().
1812 */
1813 static inline PUGL_DEPRECATED_BY("puglUpdate")
1814 PuglStatus
1815 puglDispatchEvents(PuglWorld* world)
1816 {
1817 return puglUpdate(world, 0.0);
1818 }
1819
1820 static inline PUGL_DEPRECATED_BY("puglShow")
1821 PuglStatus
1822 puglShowWindow(PuglView* view)
1823 {
1824 return puglShow(view);
1825 }
1826
1827 static inline PUGL_DEPRECATED_BY("puglHide")
1828 PuglStatus
1829 puglHideWindow(PuglView* view)
1830 {
1831 return puglHide(view);
1832 }
1833
1834 /**
1835 Set the default size of the view.
1836
1837 This should be called before puglRealize() to set the default size of the
1838 view, which will be the initial size of the window if this is a top level
1839 view.
1840
1841 @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is
1842 not yet realized.
1843 */
1844 static inline PUGL_DEPRECATED_BY("puglSetSizeHint")
1845 PuglStatus
1846 puglSetDefaultSize(PuglView* view, int width, int height)
1847 {
1848 return puglSetSizeHint(
1849 view, PUGL_DEFAULT_SIZE, (PuglSpan)width, (PuglSpan)height);
1850 }
1851
1852 /**
1853 Set the minimum size of the view.
1854
1855 If an initial minimum size is known, this should be called before
1856 puglRealize() to avoid stutter, though it can be called afterwards as well.
1857
1858 @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is
1859 not yet realized.
1860 */
1861 static inline PUGL_DEPRECATED_BY("puglSetSizeHint")
1862 PuglStatus
1863 puglSetMinSize(PuglView* view, int width, int height)
1864 {
1865 return puglSetSizeHint(
1866 view, PUGL_MIN_SIZE, (PuglSpan)width, (PuglSpan)height);
1867 }
1868
1869 /**
1870 Set the maximum size of the view.
1871
1872 If an initial maximum size is known, this should be called before
1873 puglRealize() to avoid stutter, though it can be called afterwards as well.
1874
1875 @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is
1876 not yet realized.
1877 */
1878 static inline PUGL_DEPRECATED_BY("puglSetSizeHint")
1879 PuglStatus
1880 puglSetMaxSize(PuglView* view, int width, int height)
1881 {
1882 return puglSetSizeHint(
1883 view, PUGL_MAX_SIZE, (PuglSpan)width, (PuglSpan)height);
1884 }
1885
1886 /**
1887 Set the view aspect ratio range.
1888
1889 The x and y values here represent a ratio of width to height. To set a
1890 fixed aspect ratio, set the minimum and maximum values to the same ratio.
1891
1892 Note that setting different minimum and maximum constraints does not
1893 currently work on MacOS (the minimum is used), so only setting a fixed
1894 aspect ratio works properly across all platforms.
1895
1896 If an initial aspect ratio is known, this should be called before
1897 puglRealize() to avoid stutter, though it can be called afterwards as well.
1898
1899 @return #PUGL_UNKNOWN_ERROR on failure, but always succeeds if the view is
1900 not yet realized.
1901 */
1902 static inline PUGL_DEPRECATED_BY("puglSetSizeHint")
1903 PuglStatus
1904 puglSetAspectRatio(PuglView* view, int minX, int minY, int maxX, int maxY)
1905 {
1906 const PuglStatus st0 =
1907 puglSetSizeHint(view, PUGL_MIN_ASPECT, (PuglSpan)minX, (PuglSpan)minY);
1908
1909 const PuglStatus st1 =
1910 puglSetSizeHint(view, PUGL_MAX_ASPECT, (PuglSpan)maxX, (PuglSpan)maxY);
1911
1912 return st0 ? st0 : st1;
1913 }
1914
1915 /// Return the native window handle
1916 static inline PUGL_DEPRECATED_BY("puglGetNativeView")
1917 PuglNativeView
1918 puglGetNativeWindow(PuglView* view)
1919 {
1920 return puglGetNativeView(view);
1921 }
1922
1923 #endif // PUGL_DISABLE_DEPRECATED
1924
1925 /**
1926 @}
1927 @}
1928 */
1929
1930 PUGL_END_DECLS
1931
1932 #endif // PUGL_PUGL_H