Events¶

All updates to the view happen via events, which are dispatched to the view’s event function.

Most events map directly to one from the underlying window system, but some are constructed by Pugl itself so there is not necessarily a direct correspondence.

struct PuglAnyEvent¶

Common header for all event structs.

PuglEventType type¶: Event type.

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

struct PuglConfigureEvent¶

View resize or move event.

A configure event is sent whenever the view is resized or moved. When a configure event is received, the graphics context is active but not set up for drawing. For example, it is valid to adjust the OpenGL viewport or otherwise configure the context, but not to draw anything.

PuglEventType type¶: PuglEventType.PUGL_CONFIGURE

PuglEventFlags 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.

struct PuglExposeEvent¶

Expose event for when a region must be redrawn.

When an expose event is received, the graphics context is active, and the view must draw the entire specified region. The contents of the region are undefined, there is no preservation of anything drawn previously.

PuglEventType type¶: PuglEventType.PUGL_EXPOSE

PuglEventFlags 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.

struct PuglFocusEvent¶

Keyboard focus event.

This event is sent whenever the view gains or loses the keyboard focus. The view with the keyboard focus will receive any key press or release events.

PuglEventType type¶: PuglEventType.PUGL_FOCUS_IN or PuglEventType.PUGL_FOCUS_OUT

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

PuglCrossingMode mode¶: Reason for focus change.

struct PuglKeyEvent¶

Key press or release event.

This event represents low-level key presses and releases. This can be used for “direct” keyboard handing like key bindings, but must not be interpreted as text input.

Keys are represented portably as Unicode code points, using the “natural” code point for the key where possible (see PuglKey for details). The key field is the code for the pressed key, without any modifiers applied. For example, a press or release of the ‘A’ key will have key 97 (‘a’) regardless of whether shift or control are being held.

Alternatively, the raw keycode can be used to work directly with physical keys, but note that this value is not portable and differs between platforms and hardware.

PuglEventType type¶: PuglEventType.PUGL_KEY_PRESS or PuglEventType.PUGL_KEY_RELEASE

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

double time¶: Time in seconds.

double x¶: View-relative X coordinate.

double y¶: View-relative Y coordinate.

double xRoot¶: Root-relative X coordinate.

double yRoot¶: Root-relative Y coordinate.

PuglMods state¶: Bitwise OR of PuglMod flags.

uint32_t keycode¶: Raw key code.

uint32_t key¶: Unshifted Unicode character code, or 0.

struct PuglTextEvent¶

Character input event.

This event represents text input, usually as the result of a key press. The text is given both as a Unicode character code and a UTF-8 string.

Note that this event is generated by the platform’s input system, so there is not necessarily a direct correspondence between text events and physical key presses. For example, with some input methods a sequence of several key presses will generate a single character.

PuglEventType type¶: PuglEventType.PUGL_TEXT

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

double time¶: Time in seconds.

double x¶: View-relative X coordinate.

double y¶: View-relative Y coordinate.

double xRoot¶: Root-relative X coordinate.

double yRoot¶: Root-relative Y coordinate.

PuglMods state¶: Bitwise OR of PuglMod flags.

uint32_t keycode¶: Raw key code.

uint32_t character¶: Unicode character code.

char string¶: UTF-8 string.

struct PuglCrossingEvent¶

Pointer enter or leave event.

This event is sent when the pointer enters or leaves the view. This can happen for several reasons (not just the user dragging the pointer over the window edge), as described by the mode field.

PuglEventType type¶: PuglEventType.PUGL_POINTER_IN or PuglEventType.PUGL_POINTER_OUT

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

double time¶: Time in seconds.

double x¶: View-relative X coordinate.

double y¶: View-relative Y coordinate.

double xRoot¶: Root-relative X coordinate.

double yRoot¶: Root-relative Y coordinate.

PuglMods state¶: Bitwise OR of PuglMod flags.

PuglCrossingMode mode¶: Reason for crossing.

struct PuglButtonEvent¶

Button press or release event.

PuglEventType type¶: PuglEventType.PUGL_BUTTON_PRESS or PuglEventType.PUGL_BUTTON_RELEASE

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

double time¶: Time in seconds.

double x¶: View-relative X coordinate.

double y¶: View-relative Y coordinate.

double xRoot¶: Root-relative X coordinate.

double yRoot¶: Root-relative Y coordinate.

PuglMods state¶: Bitwise OR of PuglMod flags.

uint32_t button¶: Button number starting from 1.

struct PuglMotionEvent¶

Pointer motion event.

PuglEventType type¶: PuglEventType.PUGL_MOTION

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

double time¶: Time in seconds.

double x¶: View-relative X coordinate.

double y¶: View-relative Y coordinate.

double xRoot¶: Root-relative X coordinate.

double yRoot¶: Root-relative Y coordinate.

PuglMods state¶: Bitwise OR of PuglMod flags.

struct PuglScrollEvent¶

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.

PuglEventType type¶: PuglEventType.PUGL_SCROLL

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

double time¶: Time in seconds.

double x¶: View-relative X coordinate.

double y¶: View-relative Y coordinate.

double xRoot¶: Root-relative X coordinate.

double yRoot¶: Root-relative Y coordinate.

PuglMods state¶: Bitwise OR of PuglMod flags.

PuglScrollDirection direction¶: Scroll direction.

double dx¶: Scroll X distance in lines.

double dy¶: Scroll Y distance in lines.

struct PuglClientEvent¶

Custom client message event.

This can be used to send a custom message to a view, which is delivered via the window system and processed in the event loop as usual. Among other things, this makes it possible to wake up the event loop for any reason.

PuglEventType type¶: PuglEventType.PUGL_CLIENT

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

uintptr_t data1¶: Client-specific data.

uintptr_t data2¶: Client-specific data.

struct PuglTimerEvent¶

Timer event.

This event is sent at the regular interval specified in the call to puglStartTimer() that activated it.

The id is the application-specific ID given to puglStartTimer() which distinguishes this timer from others. It should always be checked in the event handler, even in applications that register only one timer.

PuglEventType type¶: PuglEventType.PUGL_TIMER

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

uintptr_t id¶: Timer ID.

struct PuglDataOfferEvent¶

Clipboard data offer event.

This event is sent when a clipboard has data present, possibly with several datatypes. While handling this event, the types can be investigated with puglGetClipboardType() to decide whether to accept the offer with puglAcceptOffer().

PuglEventType type¶: PuglEventType.PUGL_DATA_OFFER

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

double time¶: Time in seconds.

double x¶: View-relative X coordinate.

double y¶: View-relative Y coordinate.

double xRoot¶: Root-relative X coordinate.

double yRoot¶: Root-relative Y coordinate.

PuglClipboard clipboard¶: Clipboard with available data.

struct PuglDataEvent¶

Paste or drop event.

This event is sent after accepting a PuglEventType.PUGL_DATA_OFFER when the data has been retrieved and converted. While handling this event, the data can be accessed with puglGetClipboard().

PuglEventType type¶: PuglEventType.PUGL_DATA

PuglEventFlags flags¶: Bitwise OR of PuglEventFlag values.

double time¶: Time in seconds.

double x¶: View-relative X coordinate.

double y¶: View-relative Y coordinate.

double xRoot¶: Root-relative X coordinate.

double yRoot¶: Root-relative Y coordinate.

PuglClipboard clipboard¶: Clipboard with available data.

uint32_t typeIndex¶: Index of datatype.

union PuglEvent¶

View event.

This is a union of all event types. 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.

The graphics system may only be accessed when handling certain events. The graphics context is active for PuglEventType.PUGL_CREATE, PuglEventType.PUGL_DESTROY, PuglEventType.PUGL_CONFIGURE, and PuglEventType.PUGL_EXPOSE, but only enabled for drawing for PuglEventType.PUGL_EXPOSE.

PuglAnyEvent any¶: Valid for all event types.

PuglEventType type¶: Event type.

PuglButtonEvent button¶: PuglEventType.PUGL_BUTTON_PRESS, PuglEventType.PUGL_BUTTON_RELEASE

PuglConfigureEvent configure¶: PuglEventType.PUGL_CONFIGURE

PuglExposeEvent expose¶: PuglEventType.PUGL_EXPOSE

PuglKeyEvent key¶: PuglEventType.PUGL_KEY_PRESS, PuglEventType.PUGL_KEY_RELEASE

PuglTextEvent text¶: PuglEventType.PUGL_TEXT

PuglCrossingEvent crossing¶: PuglEventType.PUGL_POINTER_IN, PuglEventType.PUGL_POINTER_OUT

PuglMotionEvent motion¶: PuglEventType.PUGL_MOTION

PuglScrollEvent scroll¶: PuglEventType.PUGL_SCROLL

PuglFocusEvent focus¶: PuglEventType.PUGL_FOCUS_IN, PuglEventType.PUGL_FOCUS_OUT

PuglClientEvent client¶: PuglEventType.PUGL_CLIENT

PuglTimerEvent timer¶: PuglEventType.PUGL_TIMER

PuglDataOfferEvent offer¶: PuglEventType.PUGL_DATA_OFFER

PuglDataEvent data¶: PuglEventType.PUGL_DATA

enum PuglMod¶

Keyboard modifier flags.

enumerator PUGL_MOD_SHIFT¶: Shift key.

enumerator PUGL_MOD_CTRL¶: Control key.

enumerator PUGL_MOD_ALT¶: Alt/Option key.

enumerator PUGL_MOD_SUPER¶: Mod4/Command/Windows key.

enum PuglKey¶

Keyboard key codepoints.

All keys are identified by a Unicode code point in PuglKeyEvent.key. This enumeration defines constants for special keys that do not have a standard code point, and some convenience constants for control characters. Note that all keys are handled in the same way, this enumeration is just for convenience when writing hard-coded key bindings.

Keys that do not have a standard code point use values in the Private Use Area in the Basic Multilingual Plane (U+E000 to U+F8FF). Applications must take care to not interpret these values beyond key detection, the mapping used here is arbitrary and specific to Pugl.

enumerator PUGL_KEY_BACKSPACE¶

enumerator PUGL_KEY_ESCAPE¶

enumerator PUGL_KEY_DELETE¶

enumerator PUGL_KEY_F1¶

enumerator PUGL_KEY_F2¶

enumerator PUGL_KEY_F3¶

enumerator PUGL_KEY_F4¶

enumerator PUGL_KEY_F5¶

enumerator PUGL_KEY_F6¶

enumerator PUGL_KEY_F7¶

enumerator PUGL_KEY_F8¶

enumerator PUGL_KEY_F9¶

enumerator PUGL_KEY_F10¶

enumerator PUGL_KEY_F11¶

enumerator PUGL_KEY_F12¶

enumerator PUGL_KEY_LEFT¶

enumerator PUGL_KEY_UP¶

enumerator PUGL_KEY_RIGHT¶

enumerator PUGL_KEY_DOWN¶

enumerator PUGL_KEY_PAGE_UP¶

enumerator PUGL_KEY_PAGE_DOWN¶

enumerator PUGL_KEY_HOME¶

enumerator PUGL_KEY_END¶

enumerator PUGL_KEY_INSERT¶

enumerator PUGL_KEY_SHIFT¶

enumerator PUGL_KEY_SHIFT_L¶

enumerator PUGL_KEY_SHIFT_R¶

enumerator PUGL_KEY_CTRL¶

enumerator PUGL_KEY_CTRL_L¶

enumerator PUGL_KEY_CTRL_R¶

enumerator PUGL_KEY_ALT¶

enumerator PUGL_KEY_ALT_L¶

enumerator PUGL_KEY_ALT_R¶

enumerator PUGL_KEY_SUPER¶

enumerator PUGL_KEY_SUPER_L¶

enumerator PUGL_KEY_SUPER_R¶

enumerator PUGL_KEY_MENU¶

enumerator PUGL_KEY_CAPS_LOCK¶

enumerator PUGL_KEY_SCROLL_LOCK¶

enumerator PUGL_KEY_NUM_LOCK¶

enumerator PUGL_KEY_PRINT_SCREEN¶

enumerator PUGL_KEY_PAUSE¶

enum PuglEventType¶

The type of a PuglEvent.

enumerator PUGL_NOTHING¶: No event.

enumerator PUGL_CREATE¶: View created, a PuglCreateEvent.

enumerator PUGL_DESTROY¶: View destroyed, a PuglDestroyEvent.

enumerator PUGL_CONFIGURE¶: View moved/resized, a PuglConfigureEvent.

enumerator PUGL_MAP¶: View made visible, a PuglMapEvent.

enumerator PUGL_UNMAP¶: View made invisible, a PuglUnmapEvent.

enumerator PUGL_UPDATE¶: View ready to draw, a PuglUpdateEvent.

enumerator PUGL_EXPOSE¶: View must be drawn, a PuglExposeEvent.

enumerator PUGL_CLOSE¶: View will be closed, a PuglCloseEvent.

enumerator PUGL_FOCUS_IN¶: Keyboard focus entered view, a PuglFocusEvent.

enumerator PUGL_FOCUS_OUT¶: Keyboard focus left view, a PuglFocusEvent.

enumerator PUGL_KEY_PRESS¶: Key pressed, a PuglKeyEvent.

enumerator PUGL_KEY_RELEASE¶: Key released, a PuglKeyEvent.

enumerator PUGL_TEXT¶: Character entered, a PuglTextEvent.

enumerator PUGL_POINTER_IN¶: Pointer entered view, a PuglCrossingEvent.

enumerator PUGL_POINTER_OUT¶: Pointer left view, a PuglCrossingEvent.

enumerator PUGL_BUTTON_PRESS¶: Mouse button pressed, a PuglButtonEvent.

enumerator PUGL_BUTTON_RELEASE¶: Mouse button released, a PuglButtonEvent.

enumerator PUGL_MOTION¶: Pointer moved, a PuglMotionEvent.

enumerator PUGL_SCROLL¶: Scrolled, a PuglScrollEvent.

enumerator PUGL_CLIENT¶: Custom client message, a PuglClientEvent.

enumerator PUGL_TIMER¶: Timer triggered, a PuglTimerEvent.

enumerator PUGL_LOOP_ENTER¶: Recursive loop entered, a PuglLoopEnterEvent.

enumerator PUGL_LOOP_LEAVE¶: Recursive loop left, a PuglLoopLeaveEvent.

enumerator PUGL_DATA_OFFER¶: Data offered from clipboard, a PuglDataOfferEvent.

enumerator PUGL_DATA¶: Data pasted or dropped, a PuglDataEvent.

enum PuglEventFlag¶

Common flags for all event types.

enumerator PUGL_IS_SEND_EVENT¶: Event is synthetic.

enumerator PUGL_IS_HINT¶: Event is a hint (not direct user input)

enum PuglCrossingMode¶

Reason for a PuglCrossingEvent.

enumerator PUGL_CROSSING_NORMAL¶: Crossing due to pointer motion.

enumerator PUGL_CROSSING_GRAB¶: Crossing due to a grab.

enumerator PUGL_CROSSING_UNGRAB¶: Crossing due to a grab release.

enum PuglScrollDirection¶

Scroll direction.

Describes the direction of a PuglScrollEvent along with whether the scroll is a “smooth” scroll. The discrete directions are for devices like mouse wheels with constrained axes, while a smooth scroll is for those with arbitrary scroll direction freedom, like some touchpads.

enumerator PUGL_SCROLL_UP¶: Scroll up.

enumerator PUGL_SCROLL_DOWN¶: Scroll down.

enumerator PUGL_SCROLL_LEFT¶: Scroll left.

enumerator PUGL_SCROLL_RIGHT¶: Scroll right.

enumerator PUGL_SCROLL_SMOOTH¶: Smooth scroll in any direction.

enum PuglClipboard¶

A system clipboard.

A clipboard provides a unified interface for drag-and-drop and copy-and-paste interactions.

enumerator PUGL_CLIPBOARD_GENERAL¶: General clipboard for copy/pasted data.

enumerator PUGL_CLIPBOARD_DRAG¶: Drag clipboard for drag and drop data.

enum PuglAction¶

An action that can be performed on data from a clipboard.

This is used to provide feedback to the user during drag-and-drop.

enumerator PUGL_ACTION_COPY¶: Data will be copied.

enumerator PUGL_ACTION_LINK¶: Data will be linked to.

enumerator PUGL_ACTION_MOVE¶: Data will be moved.

enumerator PUGL_ACTION_PRIVATE¶: Unspecified private action.

typedef uint32_t PuglMods¶: Bitwise OR of PuglMod values.

typedef uint32_t PuglEventFlags¶: Bitwise OR of PuglEventFlag values.

typedef PuglAnyEvent PuglCreateEvent¶

View create event.

This event is sent when a view is realized before it is first displayed, with the graphics context entered. This is typically used for setting up the graphics system, for example by loading OpenGL extensions.

This event type has no extra fields.

typedef PuglAnyEvent PuglDestroyEvent¶

View destroy event.

This event is the counterpart to PuglCreateEvent, and it is sent when the view is being destroyed. This is typically used for tearing down the graphics system, or otherwise freeing any resources allocated when the create event was handled.

This is the last event sent to any view, and immediately after it is processed, the view is destroyed and may no longer be used.

This event type has no extra fields.

typedef PuglAnyEvent PuglMapEvent¶

View show event.

This event is sent when a view is mapped to the screen and made visible.

This event type has no extra fields.

typedef PuglAnyEvent PuglUnmapEvent¶

View hide event.

This event is sent when a view is unmapped from the screen and made invisible.

This event type has no extra fields.

typedef PuglAnyEvent PuglUpdateEvent¶

View update event.

This event is sent to every view near the end of a main loop iteration when any pending exposures are about to be redrawn. It is typically used to mark regions to expose with puglPostRedisplay() or puglPostRedisplayRect(). For example, to continuously animate, a view calls puglPostRedisplay() when an update event is received, and it will then shortly receive an expose event.

typedef PuglAnyEvent PuglCloseEvent¶

View close event.

This event is sent when the view is to be closed, for example when the user clicks the close button.

This event type has no extra fields.

typedef PuglAnyEvent PuglLoopEnterEvent¶

Recursive loop enter event.

This event is sent when the window system enters a recursive loop. The main loop will be stalled and no expose events will be received while in the recursive loop. To give the application full control, Pugl does not do any special handling of this situation, but this event can be used to install a timer to perform continuous actions (such as drawing) on platforms that do this.

MacOS: A recursive loop is entered while the window is being live resized.
Windows: A recursive loop is entered while the window is being live resized or the menu is shown.
X11: A recursive loop is never entered and the event loop runs as usual while the view is being resized.

This event type has no extra fields.

typedef PuglAnyEvent PuglLoopLeaveEvent¶

Recursive loop leave event.

This event is sent after a loop enter event when the recursive loop is finished and normal iteration will continue.

This event type has no extra fields.