From 00e0a5f2ce568f56cbfebed1a7eef4ced5ef09eb Mon Sep 17 00:00:00 2001 From: David Robillard Date: Wed, 1 Apr 2020 19:36:01 +0200 Subject: 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. --- pugl/detail/implementation.c | 8 ++++---- pugl/detail/mac.m | 4 ++-- pugl/detail/types.h | 4 ++-- pugl/detail/win.c | 4 ++-- pugl/detail/win.h | 4 ++-- pugl/detail/x11.c | 6 +++--- pugl/pugl.h | 41 ++++++++++++++++++++++++++--------------- 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); /** @@ -1139,6 +1139,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. -- cgit v1.2.1