diff options
Diffstat (limited to 'pugl/pugl.h')
| -rw-r--r-- | pugl/pugl.h | 360 |
1 files changed, 339 insertions, 21 deletions
diff --git a/pugl/pugl.h b/pugl/pugl.h index b4c723b..1b22260 100644 --- a/pugl/pugl.h +++ b/pugl/pugl.h @@ -23,9 +23,6 @@ #include <stdint.h> -#include "pugl/common.h" -#include "pugl/event.h" - #ifdef PUGL_SHARED # ifdef _WIN32 # define PUGL_LIB_IMPORT __declspec(dllimport) @@ -56,9 +53,315 @@ extern "C" { */ /** - A function called when an event occurs. + A Pugl view. */ -typedef void (*PuglEventFunc)(PuglView* view, const PuglEvent* event); +typedef struct PuglViewImpl PuglView; + +/** + A native window handle. + + On X11, this is a Window. + On OSX, this is an NSView*. + On Windows, this is a HWND. +*/ +typedef intptr_t PuglNativeWindow; + +/** + Handle for opaque user data. +*/ +typedef void* PuglHandle; + +/** + Return status code. +*/ +typedef enum { + PUGL_SUCCESS = 0 +} PuglStatus; + +/** + Drawing context type. +*/ +typedef enum { + PUGL_GL = 0x1, + PUGL_CAIRO = 0x2, + PUGL_CAIRO_GL = 0x3 +} PuglContextType; + +/** + Convenience symbols for ASCII control characters. +*/ +typedef enum { + PUGL_CHAR_BACKSPACE = 0x08, + PUGL_CHAR_ESCAPE = 0x1B, + PUGL_CHAR_DELETE = 0x7F +} PuglChar; + +/** + Keyboard modifier flags. +*/ +typedef enum { + PUGL_MOD_SHIFT = 1, /**< Shift key */ + PUGL_MOD_CTRL = 1 << 1, /**< Control key */ + PUGL_MOD_ALT = 1 << 2, /**< Alt/Option key */ + PUGL_MOD_SUPER = 1 << 3 /**< Mod4/Command/Windows key */ +} PuglMod; + +/** + Special (non-Unicode) keyboard keys. + + The numerical values of these symbols occupy a reserved range of Unicode + points, so it is possible to express either a PuglKey value or a Unicode + character in the same variable. This is sometimes useful for interfacing + with APIs that do not make this distinction. +*/ +typedef enum { + PUGL_KEY_F1 = 0xE000, + PUGL_KEY_F2, + PUGL_KEY_F3, + PUGL_KEY_F4, + PUGL_KEY_F5, + PUGL_KEY_F6, + PUGL_KEY_F7, + PUGL_KEY_F8, + PUGL_KEY_F9, + PUGL_KEY_F10, + PUGL_KEY_F11, + PUGL_KEY_F12, + PUGL_KEY_LEFT, + PUGL_KEY_UP, + PUGL_KEY_RIGHT, + PUGL_KEY_DOWN, + PUGL_KEY_PAGE_UP, + PUGL_KEY_PAGE_DOWN, + PUGL_KEY_HOME, + PUGL_KEY_END, + PUGL_KEY_INSERT, + PUGL_KEY_SHIFT, + PUGL_KEY_CTRL, + PUGL_KEY_ALT, + PUGL_KEY_SUPER +} PuglKey; + +/** + The type of a PuglEvent. +*/ +typedef enum { + PUGL_NOTHING, /**< No event */ + PUGL_BUTTON_PRESS, /**< Mouse button press */ + PUGL_BUTTON_RELEASE, /**< Mouse button release */ + PUGL_CONFIGURE, /**< View moved and/or resized */ + PUGL_EXPOSE, /**< View exposed, redraw required */ + PUGL_CLOSE, /**< Close view */ + PUGL_KEY_PRESS, /**< Key press */ + PUGL_KEY_RELEASE, /**< Key release */ + PUGL_ENTER_NOTIFY, /**< Pointer entered view */ + PUGL_LEAVE_NOTIFY, /**< Pointer left view */ + PUGL_MOTION_NOTIFY, /**< Pointer motion */ + PUGL_SCROLL, /**< Scroll */ + PUGL_FOCUS_IN, /**< Keyboard focus entered view */ + PUGL_FOCUS_OUT /**< Keyboard focus left view */ +} PuglEventType; + +typedef enum { + PUGL_IS_SEND_EVENT = 1 +} PuglEventFlag; + +/** + Reason for a PuglEventCrossing. +*/ +typedef enum { + PUGL_CROSSING_NORMAL, /**< Crossing due to pointer motion. */ + PUGL_CROSSING_GRAB, /**< Crossing due to a grab. */ + PUGL_CROSSING_UNGRAB /**< Crossing due to a grab release. */ +} PuglCrossingMode; + +/** + Common header for all event structs. +*/ +typedef struct { + PuglEventType type; /**< Event type. */ + PuglView* view; /**< View that received this event. */ + uint32_t flags; /**< Bitwise OR of PuglEventFlag values. */ +} PuglEventAny; + +/** + Button press or release event. + + For event types PUGL_BUTTON_PRESS and PUGL_BUTTON_RELEASE. +*/ +typedef struct { + PuglEventType type; /**< PUGL_BUTTON_PRESS or PUGL_BUTTON_RELEASE. */ + PuglView* view; /**< View that received this event. */ + uint32_t flags; /**< Bitwise OR of PuglEventFlag values. */ + uint32_t time; /**< Time in milliseconds. */ + double x; /**< View-relative X coordinate. */ + double y; /**< View-relative Y coordinate. */ + double x_root; /**< Root-relative X coordinate. */ + double y_root; /**< Root-relative Y coordinate. */ + unsigned state; /**< Bitwise OR of PuglMod flags. */ + unsigned button; /**< 1-relative button number. */ +} PuglEventButton; + +/** + Configure event for when window size or position has changed. +*/ +typedef struct { + PuglEventType type; /**< PUGL_CONFIGURE. */ + PuglView* view; /**< View that received this event. */ + uint32_t flags; /**< Bitwise OR of PuglEventFlag values. */ + double x; /**< New parent-relative X coordinate. */ + double y; /**< New parent-relative Y coordinate. */ + double width; /**< New width. */ + double height; /**< New height. */ +} PuglEventConfigure; + +/** + Expose event for when a region must be redrawn. +*/ +typedef struct { + PuglEventType type; /**< PUGL_EXPOSE. */ + PuglView* view; /**< View that received this event. */ + uint32_t flags; /**< Bitwise OR of PuglEventFlag values. */ + double x; /**< View-relative X coordinate. */ + double y; /**< View-relative Y coordinate. */ + double width; /**< Width of exposed region. */ + double height; /**< Height of exposed region. */ + int count; /**< Number of expose events to follow. */ +} PuglEventExpose; + +/** + Window close event. +*/ +typedef struct { + PuglEventType type; /**< PUGL_CLOSE. */ + PuglView* view; /**< View that received this event. */ + uint32_t flags; /**< Bitwise OR of PuglEventFlag values. */ +} PuglEventClose; + +/** + Key press/release event. + + Keys that correspond to a Unicode character have `character` and `utf8` set. + Other keys will have `character` 0, but `special` may be set if this is a + known special key. + + A key press may be part of a multi-key sequence to generate a wide + character. If `filter` is set, this event is part of a multi-key sequence + and should be ignored if the application is reading textual input. + Following the series of filtered press events, a press event with + `character` and `utf8` (but `keycode` 0) will be sent. This event will have + no corresponding release event. + + Generally, an application should either work with raw keyboard press/release + events based on `keycode` (ignoring events with `keycode` 0), or + read textual input based on `character` or `utf8` (ignoring releases and + events with `filter` 1). Note that blindly appending `utf8` will yield + incorrect text, since press events are sent for both individually composed + keys and the resulting synthetic multi-byte press. +*/ +typedef struct { + PuglEventType type; /**< PUGL_KEY_PRESS or PUGL_KEY_RELEASE. */ + PuglView* view; /**< View that received this event. */ + uint32_t flags; /**< Bitwise OR of PuglEventFlag values. */ + uint32_t time; /**< Time in milliseconds. */ + double x; /**< View-relative X coordinate. */ + double y; /**< View-relative Y coordinate. */ + double x_root; /**< Root-relative X coordinate. */ + double y_root; /**< Root-relative Y coordinate. */ + unsigned state; /**< Bitwise OR of PuglMod flags. */ + unsigned keycode; /**< Raw key code. */ + uint32_t character; /**< Unicode character code, or 0. */ + PuglKey special; /**< Special key, or 0. */ + uint8_t utf8[8]; /**< UTF-8 string. */ + bool filter; /**< True if part of a multi-key sequence. */ +} PuglEventKey; + +/** + Pointer crossing event (enter and leave). +*/ +typedef struct { + PuglEventType type; /**< PUGL_ENTER_NOTIFY or PUGL_LEAVE_NOTIFY. */ + PuglView* view; /**< View that received this event. */ + uint32_t flags; /**< Bitwise OR of PuglEventFlag values. */ + uint32_t time; /**< Time in milliseconds. */ + double x; /**< View-relative X coordinate. */ + double y; /**< View-relative Y coordinate. */ + double x_root; /**< Root-relative X coordinate. */ + double y_root; /**< Root-relative Y coordinate. */ + unsigned state; /**< Bitwise OR of PuglMod flags. */ + PuglCrossingMode mode; /**< Reason for crossing. */ +} PuglEventCrossing; + +/** + Pointer motion event. +*/ +typedef struct { + PuglEventType type; /**< PUGL_MOTION_NOTIFY. */ + PuglView* view; /**< View that received this event. */ + uint32_t flags; /**< Bitwise OR of PuglEventFlag values. */ + uint32_t time; /**< Time in milliseconds. */ + double x; /**< View-relative X coordinate. */ + double y; /**< View-relative Y coordinate. */ + double x_root; /**< Root-relative X coordinate. */ + double y_root; /**< Root-relative Y coordinate. */ + unsigned state; /**< Bitwise OR of PuglMod flags. */ + bool is_hint; /**< True iff this event is a motion hint. */ + bool focus; /**< True iff this is the focused window. */ +} PuglEventMotion; + +/** + Scroll event. + + The scroll distance is expressed in "lines", an arbitrary unit that + corresponds to a single tick of a detented mouse wheel. For example, `dy` = + 1.0 scrolls 1 line up. Some systems and devices support finer resolution + and/or higher values for fast scrolls, so programs should handle any value + gracefully. + */ +typedef struct { + PuglEventType type; /**< PUGL_SCROLL. */ + PuglView* view; /**< View that received this event. */ + uint32_t flags; /**< Bitwise OR of PuglEventFlag values. */ + uint32_t time; /**< Time in milliseconds. */ + double x; /**< View-relative X coordinate. */ + double y; /**< View-relative Y coordinate. */ + double x_root; /**< Root-relative X coordinate. */ + double y_root; /**< Root-relative Y coordinate. */ + unsigned state; /**< Bitwise OR of PuglMod flags. */ + double dx; /**< Scroll X distance in lines. */ + double dy; /**< Scroll Y distance in lines. */ +} PuglEventScroll; + +/** + Keyboard focus event. +*/ +typedef struct { + PuglEventType type; /**< PUGL_FOCUS_IN or PUGL_FOCUS_OUT. */ + PuglView* view; /**< View that received this event. */ + uint32_t flags; /**< Bitwise OR of PuglEventFlag values. */ + bool grab; /**< True iff this is a grab/ungrab event. */ +} PuglEventFocus; + +/** + Interface event. + + This is a union of all event structs. The `type` must be checked to + determine which fields are safe to access. A pointer to PuglEvent can + either be cast to the appropriate type, or the union members used. +*/ +typedef union { + PuglEventType type; /**< Event type. */ + PuglEventAny any; /**< Valid for all event types. */ + PuglEventButton button; /**< PUGL_BUTTON_PRESS, PUGL_BUTTON_RELEASE. */ + PuglEventConfigure configure; /**< PUGL_CONFIGURE. */ + PuglEventExpose expose; /**< PUGL_EXPOSE. */ + PuglEventClose close; /**< PUGL_CLOSE. */ + PuglEventKey key; /**< PUGL_KEY_PRESS, PUGL_KEY_RELEASE. */ + PuglEventCrossing crossing; /**< PUGL_ENTER_NOTIFY, PUGL_LEAVE_NOTIFY. */ + PuglEventMotion motion; /**< PUGL_MOTION_NOTIFY. */ + PuglEventScroll scroll; /**< PUGL_SCROLL. */ + PuglEventFocus focus; /**< PUGL_FOCUS_IN, PUGL_FOCUS_OUT. */ +} PuglEvent; /** @name Initialization @@ -143,7 +446,7 @@ puglInitContextType(PuglView* view, PuglContextType type); /** @name Windows - Window management functions. + Functions for creating and managing a visible window for a view. @{ */ @@ -193,15 +496,6 @@ PUGL_API PuglHandle puglGetHandle(PuglView* view); /** - Get the drawing context. - - For PUGL_GL contexts, this is unused and returns NULL. - For PUGL_CAIRO contexts, this returns a pointer to a cairo_t. -*/ -PUGL_API void* -puglGetContext(PuglView* view); - -/** Return true iff the view is currently visible. */ PUGL_API bool @@ -214,10 +508,20 @@ PUGL_API void puglGetSize(PuglView* view, int* width, int* height); /** - Ignore synthetic repeated key events. + @name Context + Functions for accessing the drawing context. + @{ */ -PUGL_API void -puglIgnoreKeyRepeat(PuglView* view, bool ignore); + +/** + Get the drawing context. + + For PUGL_GL contexts, this is unused and returns NULL. + For PUGL_CAIRO contexts, this returns a pointer to a cairo_t. +*/ +PUGL_API void* +puglGetContext(PuglView* view); + /** Enter the drawing context. @@ -239,20 +543,30 @@ PUGL_API void puglLeaveContext(PuglView* view, bool flush); /** - @name Event Callbacks - Functions to set event callbacks for handling user input. + @} +*/ + +/** + @name Event Handling @{ */ /** + A function called when an event occurs. +*/ +typedef void (*PuglEventFunc)(PuglView* view, const PuglEvent* event); + +/** Set the function to call when an event occurs. */ PUGL_API void puglSetEventFunc(PuglView* view, PuglEventFunc eventFunc); /** - @} + Ignore synthetic repeated key events. */ +PUGL_API void +puglIgnoreKeyRepeat(PuglView* view, bool ignore); /** Grab the input focus. @@ -282,6 +596,10 @@ PUGL_API PuglStatus puglProcessEvents(PuglView* view); /** + @} +*/ + +/** Request a redisplay on the next call to puglProcessEvents(). */ PUGL_API void |