Consistently use "view" terminology in API

The sloppy use of "window" caused quite a bit of confusion, since views only
correspond to top-level windows in some cases, and on MacOS, a non-top-level
view is not a "window" at all.

7 files changed, 41 insertions, 30 deletions

diff --git a/pugl/detail/implementation.c b/pugl/detail/implementation.c
index 1454899..6bb019d 100644
--- a/pugl/detail/implementation.c
+++ b/pugl/detail/implementation.c
@@ -62,8 +62,8 @@ puglStrerror(const PuglStatus status)
 	case PUGL_BAD_BACKEND:           return "Invalid or missing backend";
 	case PUGL_BAD_PARAMETER:         return "Invalid parameter";
 	case PUGL_BACKEND_FAILED:        return "Backend initialisation failed";
-	case PUGL_REGISTRATION_FAILED:   return "Window class registration failed";
-	case PUGL_CREATE_WINDOW_FAILED:  return "Window creation failed";
+	case PUGL_REGISTRATION_FAILED:   return "Class registration failed";
+	case PUGL_REALIZE_FAILED:        return "View creation failed";
 	case PUGL_SET_FORMAT_FAILED:     return "Failed to set pixel format";
 	case PUGL_CREATE_CONTEXT_FAILED: return "Failed to create drawing context";
 	case PUGL_UNSUPPORTED_TYPE:      return "Unsupported data type";
@@ -237,7 +237,7 @@ puglGetWorld(PuglView* view)
 PuglStatus
 puglSetViewHint(PuglView* view, PuglViewHint hint, int value)
 {
-	if (hint < PUGL_NUM_WINDOW_HINTS) {
+	if (hint < PUGL_NUM_VIEW_HINTS) {
 		view->hints[hint] = value;
 		return PUGL_SUCCESS;
 	}
@@ -246,7 +246,7 @@ puglSetViewHint(PuglView* view, PuglViewHint hint, int value)
 }
 
 PuglStatus
-puglSetParentWindow(PuglView* view, PuglNativeWindow parent)
+puglSetParentWindow(PuglView* view, PuglNativeView parent)
 {
 	view->parent = parent;
 	return PUGL_SUCCESS;
diff --git a/pugl/detail/mac.m b/pugl/detail/mac.m
index 43dca9e..c495ee4 100644
--- a/pugl/detail/mac.m
+++ b/pugl/detail/mac.m
@@ -1072,10 +1072,10 @@ puglPostRedisplayRect(PuglView* view, const PuglRect rect)
 	return PUGL_SUCCESS;
 }
 
-PuglNativeWindow
+PuglNativeView
 puglGetNativeWindow(PuglView* view)
 {
-	return (PuglNativeWindow)view->impl->wrapperView;
+	return (PuglNativeView)view->impl->wrapperView;
 }
 
 PuglStatus
diff --git a/pugl/detail/types.h b/pugl/detail/types.h
index e750ca1..eb450e1 100644
--- a/pugl/detail/types.h
+++ b/pugl/detail/types.h
@@ -43,7 +43,7 @@ typedef struct PuglWorldInternalsImpl PuglWorldInternals;
 typedef struct PuglInternalsImpl PuglInternals;
 
 /** View hints. */
-typedef int PuglHints[PUGL_NUM_WINDOW_HINTS];
+typedef int PuglHints[PUGL_NUM_VIEW_HINTS];
 
 /** Blob of arbitrary data. */
 typedef struct {
@@ -60,7 +60,7 @@ struct PuglViewImpl {
 	PuglEventFunc      eventFunc;
 	char*              title;
 	PuglBlob           clipboard;
-	PuglNativeWindow   parent;
+	PuglNativeView     parent;
 	uintptr_t          transientParent;
 	PuglHints          hints;
 	PuglRect           frame;
diff --git a/pugl/detail/win.c b/pugl/detail/win.c
index 6d8a99e..44ba6cd 100644
--- a/pugl/detail/win.c
+++ b/pugl/detail/win.c
@@ -906,10 +906,10 @@ puglPostRedisplayRect(PuglView* view, const PuglRect rect)
 	return PUGL_SUCCESS;
 }
 
-PuglNativeWindow
+PuglNativeView
 puglGetNativeWindow(PuglView* view)
 {
-	return (PuglNativeWindow)view->impl->hwnd;
+	return (PuglNativeView)view->impl->hwnd;
 }
 
 PuglStatus
diff --git a/pugl/detail/win.h b/pugl/detail/win.h
index 283f39e..949fa90 100644
--- a/pugl/detail/win.h
+++ b/pugl/detail/win.h
@@ -106,11 +106,11 @@ puglWinCreateWindow(const PuglView* const view,
 	                             CW_USEDEFAULT, CW_USEDEFAULT,
 	                             wr.right-wr.left, wr.bottom-wr.top,
 	                             (HWND)view->parent, NULL, NULL, NULL))) {
-		return PUGL_CREATE_WINDOW_FAILED;
+		return PUGL_REALIZE_FAILED;
 	} else if (!(*hdc = GetDC(*hwnd))) {
 		DestroyWindow(*hwnd);
 		*hwnd = NULL;
-		return PUGL_CREATE_WINDOW_FAILED;
+		return PUGL_REALIZE_FAILED;
 	}
 
 	return PUGL_SUCCESS;
diff --git a/pugl/detail/x11.c b/pugl/detail/x11.c
index 59850c5..d959dbf 100644
--- a/pugl/detail/x11.c
+++ b/pugl/detail/x11.c
@@ -1061,10 +1061,10 @@ puglPostRedisplayRect(PuglView* view, PuglRect rect)
 	return PUGL_SUCCESS;
 }
 
-PuglNativeWindow
+PuglNativeView
 puglGetNativeWindow(PuglView* view)
 {
-	return (PuglNativeWindow)view->impl->win;
+	return (PuglNativeView)view->impl->win;
 }
 
 PuglStatus
@@ -1139,7 +1139,7 @@ puglSetAspectRatio(PuglView* const view,
 }
 
 PuglStatus
-puglSetTransientFor(PuglView* view, PuglNativeWindow parent)
+puglSetTransientFor(PuglView* view, PuglNativeView parent)
 {
 	Display* display = view->world->impl->display;
 
diff --git a/pugl/pugl.h b/pugl/pugl.h
index 8d0039e..b958e1a 100644
--- a/pugl/pugl.h
+++ b/pugl/pugl.h
@@ -236,9 +236,9 @@ typedef struct {
 } PuglEventAny;
 
 /**
-   Window resize or move event.
+   View resize or move event.
 
-   A configure event is sent whenever the window is resized or moved.  When a
+   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.
@@ -383,7 +383,7 @@ typedef struct {
 	double         yRoot;  ///< Root-relative Y coordinate
 	PuglMods       state;  ///< Bitwise OR of #PuglMod flags
 	bool           isHint; ///< True iff this event is a motion hint
-	bool           focus;  ///< True iff this is the focused window
+	bool           focus;  ///< True iff this is the focused view
 } PuglEventMotion;
 
 /**
@@ -484,8 +484,8 @@ typedef enum {
 	PUGL_BAD_BACKEND,           ///< Invalid or missing backend
 	PUGL_BAD_PARAMETER,         ///< Invalid parameter
 	PUGL_BACKEND_FAILED,        ///< Backend initialisation failed
-	PUGL_REGISTRATION_FAILED,   ///< Window class registration failed
-	PUGL_CREATE_WINDOW_FAILED,  ///< Window creation failed
+	PUGL_REGISTRATION_FAILED,   ///< Class registration failed
+	PUGL_REALIZE_FAILED,        ///< System view realization failed
 	PUGL_SET_FORMAT_FAILED,     ///< Failed to set pixel format
 	PUGL_CREATE_CONTEXT_FAILED, ///< Failed to create drawing context
 	PUGL_UNSUPPORTED_TYPE,      ///< Unsupported data type
@@ -715,7 +715,7 @@ typedef struct PuglViewImpl PuglView;
 typedef struct PuglBackendImpl PuglBackend;
 
 /**
-   A native window handle.
+   A native view handle.
 
    X11: This is a `Window`.
 
@@ -723,7 +723,7 @@ typedef struct PuglBackendImpl PuglBackend;
 
    Windows: This is a `HWND`.
 */
-typedef uintptr_t PuglNativeWindow;
+typedef uintptr_t PuglNativeView;
 
 /**
    Handle for a view's opaque user data.
@@ -747,10 +747,10 @@ typedef enum {
 	PUGL_SAMPLES,               ///< Number of samples per pixel (AA)
 	PUGL_DOUBLE_BUFFER,         ///< True if double buffering should be used
 	PUGL_SWAP_INTERVAL,         ///< Number of frames between buffer swaps
-	PUGL_RESIZABLE,             ///< True if window should be resizable
+	PUGL_RESIZABLE,             ///< True if view should be resizable
 	PUGL_IGNORE_KEY_REPEAT,     ///< True if key repeat events are ignored
 
-	PUGL_NUM_WINDOW_HINTS
+	PUGL_NUM_VIEW_HINTS
 } PuglViewHint;
 
 /**
@@ -839,7 +839,7 @@ PUGL_API PuglStatus
 puglSetEventFunc(PuglView* view, PuglEventFunc eventFunc);
 
 /**
-   Set a hint to configure window properties.
+   Set a hint to configure view properties.
 
    This only has an effect when called before puglRealize().
 */
@@ -880,7 +880,7 @@ PUGL_API PuglStatus
 puglSetMinSize(PuglView* view, int width, int height);
 
 /**
-   Set the window aspect ratio range.
+   Set the view aspect ratio range.
 
    The x and y values here represent a ratio of width to height.  To set a
    fixed aspect ratio, set the minimum and maximum values to the same ratio.
@@ -898,7 +898,7 @@ puglSetAspectRatio(PuglView* view, int minX, int minY, int maxX, int maxY);
 /**
    @}
    @name Windows
-   Functions for working with top-level windows.
+   Functions for working with system views and the window hierarchy.
    @{
 */
 
@@ -918,7 +918,7 @@ puglSetWindowTitle(PuglView* view, const char* title);
    This must be called before puglRealize(), reparenting is not supported.
 */
 PUGL_API PuglStatus
-puglSetParentWindow(PuglView* view, PuglNativeWindow parent);
+puglSetParentWindow(PuglView* view, PuglNativeView parent);
 
 /**
    Set the transient parent of the window.
@@ -928,7 +928,7 @@ puglSetParentWindow(PuglView* view, PuglNativeWindow parent);
    puglRealize().
 */
 PUGL_API PuglStatus
-puglSetTransientFor(PuglView* view, PuglNativeWindow parent);
+puglSetTransientFor(PuglView* view, PuglNativeView parent);
 
 /**
    Realise a view by creating a corresponding system view or window.
@@ -971,7 +971,7 @@ puglGetVisible(PuglView* view);
 /**
    Return the native window handle.
 */
-PUGL_API PuglNativeWindow
+PUGL_API PuglNativeView
 puglGetNativeWindow(PuglView* view);
 
 /**
@@ -1140,6 +1140,17 @@ puglSendEvent(PuglView* view, const PuglEvent* event);
 */
 
 /**
+   A native window handle.
+
+   X11: This is a `Window`.
+
+   MacOS: This is a pointer to an `NSView*`.
+
+   Windows: This is a `HWND`.
+*/
+typedef uintptr_t PuglNativeWindow;
+
+/**
    Create a Pugl application and view.
 
    To create a window, call the various puglInit* functions as necessary, then