Replace puglShowWindow() with puglRealize()

4 files changed, 81 insertions, 44 deletions

diff --git a/pugl/detail/mac.m b/pugl/detail/mac.m
index f8ab084..43dca9e 100644
--- a/pugl/detail/mac.m
+++ b/pugl/detail/mac.m
@@ -753,7 +753,7 @@ puglConstraint(id item, NSLayoutAttribute attribute, float constant)
 }
 
 PuglStatus
-puglCreateWindow(PuglView* view, const char* title)
+puglRealize(PuglView* view)
 {
 	PuglInternals* impl = view->impl;
 
@@ -788,11 +788,6 @@ puglCreateWindow(PuglView* view, const char* title)
 		[impl->drawView setHidden:NO];
 		[[impl->drawView window] makeFirstResponder:impl->wrapperView];
 	} else {
-		NSString* titleString = [[NSString alloc]
-			                        initWithBytes:title
-			                               length:strlen(title)
-			                             encoding:NSUTF8StringEncoding];
-
 		const NSRect frame = rectToScreen(
 			NSMakeRect(view->frame.x, view->frame.y,
 			           view->minWidth, view->minHeight));
@@ -811,13 +806,21 @@ puglCreateWindow(PuglView* view, const char* title)
 			              defer:NO
 		              ] retain];
 		[window setPuglview:view];
-		[window setTitle:titleString];
+
+		if (view->title) {
+			NSString* titleString = [[NSString alloc]
+				                        initWithBytes:view->title
+				                               length:strlen(view->title)
+				                             encoding:NSUTF8StringEncoding];
+
+			[window setTitle:titleString];
+		}
+
 		if (view->minWidth || view->minHeight) {
 			[window setContentMinSize:NSMakeSize(view->minWidth,
 			                                     view->minHeight)];
 		}
 		impl->window = window;
-		puglSetWindowTitle(view, title);
 
 		((NSWindow*)window).delegate = [[PuglWindowDelegate alloc]
 			                  initWithPuglWindow:window];
@@ -1080,12 +1083,12 @@ puglSetWindowTitle(PuglView* view, const char* title)
 {
 	puglSetString(&view->title, title);
 
-	NSString* titleString = [[NSString alloc]
-		                        initWithBytes:title
-		                               length:strlen(title)
-		                             encoding:NSUTF8StringEncoding];
-
 	if (view->impl->window) {
+		NSString* titleString = [[NSString alloc]
+		    initWithBytes:title
+		           length:strlen(title)
+		         encoding:NSUTF8StringEncoding];
+
 		[view->impl->window setTitle:titleString];
 	}
 
diff --git a/pugl/detail/win.c b/pugl/detail/win.c
index 4606d60..6d8a99e 100644
--- a/pugl/detail/win.c
+++ b/pugl/detail/win.c
@@ -160,12 +160,10 @@ puglPollWinEvents(PuglWorld* world, const double timeout)
 }
 
 PuglStatus
-puglCreateWindow(PuglView* view, const char* title)
+puglRealize(PuglView* view)
 {
 	PuglInternals* impl = view->impl;
 
-	title = title ? title : view->world->className;
-
 	// Get refresh rate for resize draw timer
 	DEVMODEA devMode = {0};
 	EnumDisplaySettingsA(NULL, ENUM_CURRENT_SETTINGS, &devMode);
@@ -187,8 +185,8 @@ puglCreateWindow(PuglView* view, const char* title)
 		return PUGL_CREATE_CONTEXT_FAILED;
 	}
 
-	if (title) {
-		puglSetWindowTitle(view, title);
+	if (view->title) {
+		puglSetWindowTitle(view, view->title);
 	}
 
 	puglSetFrame(view, view->frame);
@@ -919,10 +917,12 @@ puglSetWindowTitle(PuglView* view, const char* title)
 {
 	puglSetString(&view->title, title);
 
-	wchar_t* wtitle = puglUtf8ToWideChar(title);
-	if (wtitle) {
-		SetWindowTextW(view->impl->hwnd, wtitle);
-		free(wtitle);
+	if (view->impl->hwnd) {
+		wchar_t* wtitle = puglUtf8ToWideChar(title);
+		if (wtitle) {
+			SetWindowTextW(view->impl->hwnd, wtitle);
+			free(wtitle);
+		}
 	}
 
 	return PUGL_SUCCESS;
diff --git a/pugl/detail/x11.c b/pugl/detail/x11.c
index 3f43a8f..59850c5 100644
--- a/pugl/detail/x11.c
+++ b/pugl/detail/x11.c
@@ -221,7 +221,7 @@ getSizeHints(const PuglView* view)
 }
 
 PuglStatus
-puglCreateWindow(PuglView* view, const char* title)
+puglRealize(PuglView* view)
 {
 	PuglInternals* const impl    = view->impl;
 	PuglWorld* const     world   = view->world;
@@ -268,8 +268,8 @@ puglCreateWindow(PuglView* view, const char* title)
 	XClassHint classHint = { world->className, world->className };
 	XSetClassHint(display, win, &classHint);
 
-	if (title) {
-		puglSetWindowTitle(view, title);
+	if (view->title) {
+		puglSetWindowTitle(view, view->title);
 	}
 
 	if (!view->parent) {
@@ -300,9 +300,18 @@ puglCreateWindow(PuglView* view, const char* title)
 PuglStatus
 puglShowWindow(PuglView* view)
 {
+	PuglStatus st = PUGL_SUCCESS;
+
+	if (!view->impl->win) {
+		if ((st = puglRealize(view))) {
+			return st;
+		}
+	}
+
 	XMapRaised(view->impl->display, view->impl->win);
 	puglPostRedisplay(view);
-	return PUGL_SUCCESS;
+
+	return st;
 }
 
 PuglStatus
@@ -1065,10 +1074,13 @@ puglSetWindowTitle(PuglView* view, const char* title)
 	const PuglX11Atoms* const atoms   = &view->world->impl->atoms;
 
 	puglSetString(&view->title, title);
-	XStoreName(display, view->impl->win, title);
-	XChangeProperty(display, view->impl->win, atoms->NET_WM_NAME,
-	                atoms->UTF8_STRING, 8, PropModeReplace,
-	                (const uint8_t*)title, (int)strlen(title));
+
+	if (view->impl->win) {
+		XStoreName(display, view->impl->win, title);
+		XChangeProperty(display, view->impl->win, atoms->NET_WM_NAME,
+		                atoms->UTF8_STRING, 8, PropModeReplace,
+		                (const uint8_t*)title, (int)strlen(title));
+	}
 
 	return PUGL_SUCCESS;
 }
diff --git a/pugl/pugl.h b/pugl/pugl.h
index f1ddfdb..b09d883 100644
--- a/pugl/pugl.h
+++ b/pugl/pugl.h
@@ -776,7 +776,8 @@ typedef PuglStatus (*PuglEventFunc)(PuglView* view, const PuglEvent* event);
    Create a new view.
 
    A newly created view does not correspond to a real system view or window.
-   It must first be configured, then be realised by calling puglCreateWindow().
+   It must first be configured, then the system view can be created with
+   puglRealize().
 */
 PUGL_API PuglView*
 puglNewView(PuglWorld* world);
@@ -815,7 +816,7 @@ puglGetHandle(PuglView* view);
    Set the graphics backend to use for a view.
 
    This must be called once to set the graphics backend before calling
-   puglCreateWindow().
+   puglRealize().
 
    Pugl includes the following backends:
 
@@ -839,7 +840,7 @@ puglSetEventFunc(PuglView* view, PuglEventFunc eventFunc);
 /**
    Set a hint to configure window properties.
 
-   This only has an effect when called before puglCreateWindow().
+   This only has an effect when called before puglRealize().
 */
 PUGL_API PuglStatus
 puglSetViewHint(PuglView* view, PuglViewHint hint, int value);
@@ -872,8 +873,7 @@ puglSetFrame(PuglView* view, PuglRect frame);
    Set the minimum size of the view.
 
    If an initial minimum size is known, this should be called before
-   puglCreateWindow() to avoid stutter, though it can be called afterwards as
-   well.
+   puglRealize() to avoid stutter, though it can be called afterwards as well.
 */
 PUGL_API PuglStatus
 puglSetMinSize(PuglView* view, int width, int height);
@@ -889,8 +889,7 @@ puglSetMinSize(PuglView* view, int width, int height);
    ratio works properly across all platforms.
 
    If an initial aspect ratio is known, this should be called before
-   puglCreateWindow() to avoid stutter, though it can be called afterwards as
-   well.
+   puglRealize() to avoid stutter, though it can be called afterwards as well.
 */
 PUGL_API PuglStatus
 puglSetAspectRatio(PuglView* view, int minX, int minY, int maxX, int maxY);
@@ -915,7 +914,7 @@ puglSetWindowTitle(PuglView* view, const char* title);
 /**
    Set the parent window for embedding a view in an existing window.
 
-   This must be called before puglCreateWindow(), reparenting is not supported.
+   This must be called before puglRealize(), reparenting is not supported.
 */
 PUGL_API PuglStatus
 puglSetParentWindow(PuglView* view, PuglNativeWindow parent);
@@ -925,7 +924,7 @@ puglSetParentWindow(PuglView* view, PuglNativeWindow parent);
 
    Set this for transient children like dialogs, to have them properly
    associated with their parent window.  This should be called before
-   puglCreateWindow().
+   puglRealize().
 */
 PUGL_API PuglStatus
 puglSetTransientFor(PuglView* view, PuglNativeWindow parent);
@@ -933,17 +932,25 @@ puglSetTransientFor(PuglView* view, PuglNativeWindow parent);
 /**
    Realise a view by creating a corresponding system view or window.
 
+   After this call, the (initially invisible) underlying system view exists and
+   can be accessed with puglGetNativeWindow().  There is currently no
+   corresponding unrealize function, the system view will be destroyed along
+   with the view when puglFreeView() is called.
+
    The view should be fully configured using the above functions before this is
    called.  This function may only be called once per view.
 */
 PUGL_API PuglStatus
-puglCreateWindow(PuglView* view, const char* title);
+puglRealize(PuglView* view);
 
 /**
-   Show the current window.
+   Show the view.
+
+   If the view has not yet been realized, the first call to this function will
+   do so automatically.
 
-   If the window is currently hidden, it will be shown and possibly raised to
-   the top depending on the platform.
+   If the view is currently hidden, it will be shown and possibly raised to the
+   top depending on the platform.
 */
 PUGL_API PuglStatus
 puglShowWindow(PuglView* view);
@@ -1135,7 +1142,7 @@ puglSendEvent(PuglView* view, const PuglEvent* event);
    Create a Pugl application and view.
 
    To create a window, call the various puglInit* functions as necessary, then
-   call puglCreateWindow().
+   call puglRealize().
 
    @deprecated Use puglNewApp() and puglNewView().
 
@@ -1303,6 +1310,21 @@ puglInitBackend(PuglView* view, const PuglBackend* backend)
 }
 
 /**
+   Realise a view by creating a corresponding system view or window.
+
+   The view should be fully configured using the above functions before this is
+   called.  This function may only be called once per view.
+
+   @deprecated Use puglRealize(), or just show the view.
+*/
+static inline PUGL_DEPRECATED_BY("puglRealize") PuglStatus
+puglCreateWindow(PuglView* view, const char* title)
+{
+	puglSetWindowTitle(view, title);
+	return puglRealize(view);
+}
+
+/**
    Block and wait for an event to be ready.
 
    This can be used in a loop to only process events via puglProcessEvents when