X11: Fix potential crash in puglGrabFocus()

This is really a mistake in user code, but things shouldn't crash in general.
So, this commit fixes the crash and adds some documentation so that developers
hopefully don't try to grab focus before it makes sense.

The case that was previously a crash will now gracefully fail, that is, the
focus will not be (and can not be) grabbed.

1 files changed, 8 insertions, 1 deletions

diff --git a/include/pugl/pugl.h b/include/pugl/pugl.h
index 6e783e7..59b8847 100644
--- a/include/pugl/pugl.h
+++ b/include/pugl/pugl.h
@@ -1137,7 +1137,14 @@ typedef enum {
   PUGL_CURSOR_UP_DOWN,    ///< Up/down arrow for vertical resize
 } PuglCursor;
 
-/// Grab the keyboard input focus
+/**
+   Grab the keyboard input focus.
+
+   Note that this will fail if the view is not mapped and so should not, for
+   example, be called immediately after puglShow().
+
+   @return #PUGL_SUCCESS if the focus was successfully grabbed, or an error.
+*/
 PUGL_API
 PuglStatus
 puglGrabFocus(PuglView* view);