Events

Classes
struct	PuglAnyEvent
	Common header for all event structs. More...
struct	PuglConfigureEvent
struct	PuglExposeEvent
struct	PuglFocusEvent
struct	PuglKeyEvent
struct	PuglTextEvent
struct	PuglCrossingEvent
struct	PuglButtonEvent
struct	PuglMotionEvent
struct	PuglScrollEvent
struct	PuglClientEvent
struct	PuglTimerEvent
struct	PuglDataOfferEvent
struct	PuglDataEvent
union	PuglEvent

Typedefs
typedef uint32_t	PuglMods
	Bitwise OR of PuglMod values.
typedef uint32_t	PuglEventFlags
	Bitwise OR of PuglEventFlag values.
typedef PuglAnyEvent	PuglCreateEvent
typedef PuglAnyEvent	PuglDestroyEvent
typedef PuglAnyEvent	PuglMapEvent
typedef PuglAnyEvent	PuglUnmapEvent
typedef PuglAnyEvent	PuglUpdateEvent
typedef PuglAnyEvent	PuglCloseEvent
typedef PuglAnyEvent	PuglLoopEnterEvent
typedef PuglAnyEvent	PuglLoopLeaveEvent

Enumerations
enum	PuglMod { PUGL_MOD_SHIFT = 1u << 0u , PUGL_MOD_CTRL = 1u << 1u , PUGL_MOD_ALT = 1u << 2u , PUGL_MOD_SUPER = 1u << 3u }
	Keyboard modifier flags. More...
enum	PuglKey {   PUGL_KEY_BACKSPACE = 0x08 , PUGL_KEY_ESCAPE = 0x1B , PUGL_KEY_DELETE = 0x7F , 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_SHIFT_L = PUGL_KEY_SHIFT , PUGL_KEY_SHIFT_R , PUGL_KEY_CTRL ,   PUGL_KEY_CTRL_L = PUGL_KEY_CTRL , PUGL_KEY_CTRL_R , PUGL_KEY_ALT , PUGL_KEY_ALT_L = PUGL_KEY_ALT ,   PUGL_KEY_ALT_R , PUGL_KEY_SUPER , PUGL_KEY_SUPER_L = PUGL_KEY_SUPER , PUGL_KEY_SUPER_R ,   PUGL_KEY_MENU , PUGL_KEY_CAPS_LOCK , PUGL_KEY_SCROLL_LOCK , PUGL_KEY_NUM_LOCK ,   PUGL_KEY_PRINT_SCREEN , PUGL_KEY_PAUSE }
enum	PuglEventType {   PUGL_NOTHING , PUGL_CREATE , PUGL_DESTROY , PUGL_CONFIGURE ,   PUGL_MAP , PUGL_UNMAP , PUGL_UPDATE , PUGL_EXPOSE ,   PUGL_CLOSE , PUGL_FOCUS_IN , PUGL_FOCUS_OUT , PUGL_KEY_PRESS ,   PUGL_KEY_RELEASE , PUGL_TEXT , PUGL_POINTER_IN , PUGL_POINTER_OUT ,   PUGL_BUTTON_PRESS , PUGL_BUTTON_RELEASE , PUGL_MOTION , PUGL_SCROLL ,   PUGL_CLIENT , PUGL_TIMER , PUGL_LOOP_ENTER , PUGL_LOOP_LEAVE ,   PUGL_DATA_OFFER , PUGL_DATA }
	The type of a PuglEvent. More...
enum	PuglEventFlag { PUGL_IS_SEND_EVENT = 1 , PUGL_IS_HINT = 2 }
	Common flags for all event types. More...
enum	PuglCrossingMode { PUGL_CROSSING_NORMAL , PUGL_CROSSING_GRAB , PUGL_CROSSING_UNGRAB }
	Reason for a PuglCrossingEvent. More...
enum	PuglScrollDirection {   PUGL_SCROLL_UP , PUGL_SCROLL_DOWN , PUGL_SCROLL_LEFT , PUGL_SCROLL_RIGHT ,   PUGL_SCROLL_SMOOTH }

Detailed Description

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.

Typedef Documentation

PuglCloseEvent

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.

PuglCreateEvent

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.

PuglDestroyEvent

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.

PuglEventFlags

typedef uint32_t PuglEventFlags

Bitwise OR of PuglEventFlag values.

PuglLoopEnterEvent

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.

PuglLoopLeaveEvent

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.

PuglMapEvent

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.

PuglMods

typedef uint32_t PuglMods

Bitwise OR of PuglMod values.

PuglUnmapEvent

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.

PuglUpdateEvent

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.

Enumeration Type Documentation

PuglCrossingMode

enum PuglCrossingMode

Reason for a PuglCrossingEvent.

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

PuglEventFlag

enum PuglEventFlag

Common flags for all event types.

Enumerator
PUGL_IS_SEND_EVENT	Event is synthetic.
PUGL_IS_HINT	Event is a hint (not direct user input).

PuglEventType

enum PuglEventType

The type of a PuglEvent.

Enumerator
PUGL_NOTHING	No event.
PUGL_CREATE	View created, a PuglCreateEvent.
PUGL_DESTROY	View destroyed, a PuglDestroyEvent.
PUGL_CONFIGURE	View moved/resized, a PuglConfigureEvent.
PUGL_MAP	View made visible, a PuglMapEvent.
PUGL_UNMAP	View made invisible, a PuglUnmapEvent.
PUGL_UPDATE	View ready to draw, a PuglUpdateEvent.
PUGL_EXPOSE	View must be drawn, a PuglExposeEvent.
PUGL_CLOSE	View will be closed, a PuglCloseEvent.
PUGL_FOCUS_IN	Keyboard focus entered view, a PuglFocusEvent.
PUGL_FOCUS_OUT	Keyboard focus left view, a PuglFocusEvent.
PUGL_KEY_PRESS	Key pressed, a PuglKeyEvent.
PUGL_KEY_RELEASE	Key released, a PuglKeyEvent.
PUGL_TEXT	Character entered, a PuglTextEvent.
PUGL_POINTER_IN	Pointer entered view, a PuglCrossingEvent.
PUGL_POINTER_OUT	Pointer left view, a PuglCrossingEvent.
PUGL_BUTTON_PRESS	Mouse button pressed, a PuglButtonEvent.
PUGL_BUTTON_RELEASE	Mouse button released, a PuglButtonEvent.
PUGL_MOTION	Pointer moved, a PuglMotionEvent.
PUGL_SCROLL	Scrolled, a PuglScrollEvent.
PUGL_CLIENT	Custom client message, a PuglClientEvent.
PUGL_TIMER	Timer triggered, a PuglTimerEvent.
PUGL_LOOP_ENTER	Recursive loop entered, a PuglLoopEnterEvent.
PUGL_LOOP_LEAVE	Recursive loop left, a PuglLoopLeaveEvent.
PUGL_DATA_OFFER	Data offered from clipboard, a PuglDataOfferEvent.
PUGL_DATA	Data available from clipboard, a PuglDataEvent.

PuglKey

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
PUGL_KEY_ESCAPE
PUGL_KEY_DELETE
PUGL_KEY_F1
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_SHIFT_L
PUGL_KEY_SHIFT_R
PUGL_KEY_CTRL
PUGL_KEY_CTRL_L
PUGL_KEY_CTRL_R
PUGL_KEY_ALT
PUGL_KEY_ALT_L
PUGL_KEY_ALT_R
PUGL_KEY_SUPER
PUGL_KEY_SUPER_L
PUGL_KEY_SUPER_R
PUGL_KEY_MENU
PUGL_KEY_CAPS_LOCK
PUGL_KEY_SCROLL_LOCK
PUGL_KEY_NUM_LOCK
PUGL_KEY_PRINT_SCREEN
PUGL_KEY_PAUSE

PuglMod

enum PuglMod

Keyboard modifier flags.

Enumerator
PUGL_MOD_SHIFT	Shift key.
PUGL_MOD_CTRL	Control key.
PUGL_MOD_ALT	Alt/Option key.
PUGL_MOD_SUPER	Mod4/Command/Windows key.

PuglScrollDirection

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.
PUGL_SCROLL_DOWN	Scroll down.
PUGL_SCROLL_LEFT	Scroll left.
PUGL_SCROLL_RIGHT	Scroll right.
PUGL_SCROLL_SMOOTH	Smooth scroll in any direction.