From 2f1dd9fdf59307d2ef5e9cf58bcad77e07a27de7 Mon Sep 17 00:00:00 2001
From: David Robillard <d@drobilla.net>
Date: Wed, 1 Apr 2020 21:52:19 +0200
Subject: Add types and documentation for all event types
These are not necessary since they are just aliases for PuglEventAny, but
provide a place to put the documentation, and can make code clearer where a
specific event type is known.
---
pugl/pugl.h | 78 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++-----
1 file changed, 72 insertions(+), 6 deletions(-)
diff --git a/pugl/pugl.h b/pugl/pugl.h
index b958e1a..c8807f1 100644
--- a/pugl/pugl.h
+++ b/pugl/pugl.h
@@ -176,14 +176,14 @@ typedef enum {
*/
typedef enum {
PUGL_NOTHING, ///< No event
- PUGL_CREATE, ///< View created, a #PuglEventAny
- PUGL_DESTROY, ///< View destroyed, a #PuglEventAny
+ PUGL_CREATE, ///< View created, a #PuglEventCreate
+ PUGL_DESTROY, ///< View destroyed, a #PuglEventDestroy
PUGL_CONFIGURE, ///< View moved/resized, a #PuglEventConfigure
- PUGL_MAP, ///< View made visible, a #PuglEventAny
- PUGL_UNMAP, ///< View made invisible, a #PuglEventAny
- PUGL_UPDATE, ///< View ready to draw, a #PuglEventAny
+ PUGL_MAP, ///< View made visible, a #PuglEventMap
+ PUGL_UNMAP, ///< View made invisible, a #PuglEventUnmap
+ PUGL_UPDATE, ///< View ready to draw, a #PuglEventUpdate
PUGL_EXPOSE, ///< View must be drawn, a #PuglEventExpose
- PUGL_CLOSE, ///< View will be closed, a #PuglEventAny
+ PUGL_CLOSE, ///< View will be closed, a #PuglEventClose
PUGL_FOCUS_IN, ///< Keyboard focus entered view, a #PuglEventFocus
PUGL_FOCUS_OUT, ///< Keyboard focus left view, a #PuglEventFocus
PUGL_KEY_PRESS, ///< Key pressed, a #PuglEventKey
@@ -235,6 +235,32 @@ typedef struct {
PuglEventFlags flags; ///< Bitwise OR of #PuglEventFlag values
} PuglEventAny;
+/**
+ 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 PuglEventAny PuglEventCreate;
+
+/**
+ View destroy event.
+
+ This event is the counterpart to #PuglEventCreate, 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 PuglEventAny PuglEventDestroy;
+
/**
View resize or move event.
@@ -252,6 +278,36 @@ typedef struct {
double height; ///< New height
} PuglEventConfigure;
+/**
+ 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 PuglEventAny PuglEventMap;
+
+/**
+ 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 PuglEventAny PuglEventUnmap;
+
+/**
+ 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 PuglEventAny PuglEventUpdate;
+
/**
Expose event for when a region must be redrawn.
@@ -269,6 +325,16 @@ typedef struct {
int count; ///< Number of expose events to follow
} PuglEventExpose;
+/**
+ 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 PuglEventAny PuglEventClose;
+
/**
Keyboard focus event.
--
cgit v1.2.3