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