Move entire API to pugl.h

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