Change glfwInitHintString to glfwWindowHintString

Fixes #1139.

README.md

@@ -147,7 +147,8 @@ information on what to include when reporting a bug.
 - Added `glfwSetWindowAttrib` function for changing window attributes (#537)
 - Added `glfwGetJoystickHats` function for querying joystick hats
   (#889,#906,#934)
-- Added `glfwInitHint` and `glfwInitHintString` for setting initialization hints
+- Added `glfwInitHint` for setting initialization hints
+- Added `glfwWindowHintString` for setting string type window hints (#893,#1139)
 - Added `glfwGetWindowOpacity` and `glfwSetWindowOpacity` for controlling whole
   window transparency (#1089)
 - Added `glfwGetX11SelectionString` and `glfwSetX11SelectionString`
@@ -165,8 +166,8 @@ information on what to include when reporting a bug.
 - Added macOS specific `GLFW_COCOA_GRAPHICS_SWITCHING` window hint (#377,#935)
 - Added macOS specific `GLFW_COCOA_CHDIR_RESOURCES` init hint
 - Added macOS specific `GLFW_COCOA_MENUBAR` init hint
-- Added X11 specific `GLFW_X11_WM_CLASS_NAME` and `GLFW_X11_WM_CLASS_CLASS` init
-  hints (#893)
+- Added X11 specific `GLFW_X11_CLASS_NAME` and `GLFW_X11_INSTANCE_NAME` window
+  hints (#893,#1139)
 - Added `GLFW_INCLUDE_ES32` for including the OpenGL ES 3.2 header
 - Added `GLFW_OSMESA_CONTEXT_API` for creating OpenGL contexts with
   [OSMesa](https://www.mesa3d.org/osmesa.html) (#281)

docs/intro.dox

@@ -33,7 +33,6 @@ successfully initialized, and only from the main thread.
  - @ref glfwGetError
  - @ref glfwSetErrorCallback
  - @ref glfwInitHint
- - @ref glfwInitHintString
  - @ref glfwInit
  - @ref glfwTerminate
 
@@ -67,8 +66,7 @@ settings and these might not be restored without termination.
 @subsection init_hints Initialization hints
 
 Initialization hints are set before @ref glfwInit and affect how the library
-behaves until termination.  Integer type hints are set with @ref glfwInitHint
-and string type hints with @ref glfwInitHintString.
+behaves until termination.  Hints are set with @ref glfwInitHint.
 
 @code
 glfwInitHint(GLFW_JOYSTICK_HAT_BUTTONS, GLFW_FALSE);
@@ -104,15 +102,6 @@ a nib or manually, when the first window is created, which is when AppKit is
 initialized.  Set this with @ref glfwInitHint.
 
 
-@subsubsection init_hints_x11 X11 specific init hints
-
-@anchor GLFW_X11_WM_CLASS_NAME
-@anchor GLFW_X11_WM_CLASS_CLASS
-__GLFW_X11_WM_CLASS_NAME__ and __GLFW_X11_WM_CLASS_CLASS__ specifies the desired
-ASCII encoded name and class parts of the ICCCM `WM_CLASS` hint for all windows.
-Set this with @ref glfwInitHintString.
-
-
 @subsubsection init_hints_values Supported and default values
 
 Initialization hint             | Default value | Supported values
@@ -120,8 +109,6 @@ Initialization hint             | Default value | Supported values
 @ref GLFW_JOYSTICK_HAT_BUTTONS  | `GLFW_TRUE`   | `GLFW_TRUE` or `GLFW_FALSE`
 @ref GLFW_COCOA_CHDIR_RESOURCES | `GLFW_TRUE`   | `GLFW_TRUE` or `GLFW_FALSE`
 @ref GLFW_COCOA_MENUBAR         | `GLFW_TRUE`   | `GLFW_TRUE` or `GLFW_FALSE`
-@ref GLFW_X11_WM_CLASS_NAME     | `""`          | An ASCII encoded `WM_CLASS` name
-@ref GLFW_X11_WM_CLASS_CLASS    | `""`          | An ASCII encoded `WM_CLASS` class
 
 
 @subsection intro_init_terminate Terminating GLFW

docs/news.dox

@@ -69,9 +69,8 @@ glfwGetWindowContentScale and @ref glfwGetMonitorContentScale.
 
 @subsection news_33_inithint Support for initialization hints
 
-GLFW now supports setting library initialization hints with @ref glfwInitHint
-or @ref glfwInitHintString.  These must be set before initialization to take
-effect.
+GLFW now supports setting library initialization hints with @ref glfwInitHint.
+These must be set before initialization to take effect.
 
 @see @ref init_hints
 

docs/window.dox

@@ -146,16 +146,18 @@ is restored, but the gamma ramp is left untouched.
 There are a number of hints that can be set before the creation of a window and
 context.  Some affect the window itself, others affect the framebuffer or
 context.  These hints are set to their default values each time the library is
-initialized with @ref glfwInit, can be set individually with @ref glfwWindowHint
-and reset all at once to their defaults with @ref glfwDefaultWindowHints.
+initialized with @ref glfwInit.  Integer value hints can be set individually
+with @ref glfwWindowHint and string value hints with @ref glfwWindowHintString.
+You can reset all at once to their defaults with @ref glfwDefaultWindowHints.
 
 Some hints are platform specific.  These are always valid to set on any
 platform but they will only affect their specific platform.  Other platforms
 will ignore them.  Setting these hints requires no platform specific headers or
 calls.
 
-Note that hints need to be set _before_ the creation of the window and context
-you wish to have the specified attributes.
+@note Window hints need to be set before the creation of the window and context
+you wish to have the specified attributes.  They function as additional
+arguments to @ref glfwCreateWindow.
 
 
 @subsubsection window_hints_hard Hard and soft constraints
@@ -465,6 +467,15 @@ should also declare this in its `Info.plist` by setting the
 `NSSupportsAutomaticGraphicsSwitching` key to `true`.
 
 
+@subsubsection window_hints_x11 X11 specific window hints
+
+@anchor GLFW_X11_CLASS_NAME
+@anchor GLFW_X11_INSTANCE_NAME
+__GLFW_X11_CLASS_NAME__ and __GLFW_X11_INSTANCE_NAME__ specifies the desired
+ASCII encoded class and instance parts of the ICCCM `WM_CLASS` window property.
+These are set with @ref glfwWindowHintString.
+
+
 @subsubsection window_hints_values Supported and default values
 
 Window hint                   | Default value               | Supported values
@@ -506,6 +517,8 @@ GLFW_OPENGL_PROFILE           | `GLFW_OPENGL_ANY_PROFILE`   | `GLFW_OPENGL_ANY_P
 GLFW_COCOA_RETINA_FRAMEBUFFER | `GLFW_TRUE`                 | `GLFW_TRUE` or `GLFW_FALSE`
 GLFW_COCOA_FRAME_AUTOSAVE     | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
 GLFW_COCOA_GRAPHICS_SWITCHING | `GLFW_FALSE`                | `GLFW_TRUE` or `GLFW_FALSE`
+GLFW_X11_CLASS_NAME           | `""`                        | An ASCII encoded `WM_CLASS` class name
+GLFW_X11_INSTANCE_NAME        | `""`                        | An ASCII encoded `WM_CLASS` instance name
 
 
 @section window_events Window event processing

include/GLFW/glfw3.h

@@ -966,6 +966,9 @@ extern "C" {
 #define GLFW_COCOA_RETINA_FRAMEBUFFER 0x00023001
 #define GLFW_COCOA_FRAME_AUTOSAVE     0x00023002
 #define GLFW_COCOA_GRAPHICS_SWITCHING 0x00023003
+
+#define GLFW_X11_CLASS_NAME         0x00024001
+#define GLFW_X11_INSTANCE_NAME      0x00024002
 /*! @} */
 
 #define GLFW_NO_API                          0
@@ -1046,9 +1049,6 @@ extern "C" {
 
 #define GLFW_COCOA_CHDIR_RESOURCES  0x00051001
 #define GLFW_COCOA_MENUBAR          0x00051002
-
-#define GLFW_X11_WM_CLASS_NAME      0x00052001
-#define GLFW_X11_WM_CLASS_CLASS     0x00052002
 /*! @} */
 
 #define GLFW_DONT_CARE              -1
@@ -1644,8 +1644,7 @@ GLFWAPI void glfwTerminate(void);
 
 /*! @brief Sets the specified init hint to the desired value.
  *
- *  This function sets hints for the next initialization of GLFW.  Only integer
- *  type hints can be set with this function.
+ *  This function sets hints for the next initialization of GLFW.
  *
  *  The values you set hints to are never reset by GLFW, but they only take
  *  effect during initialization.  Once GLFW has been initialized, any values
@@ -1668,7 +1667,6 @@ GLFWAPI void glfwTerminate(void);
  *
  *  @sa init_hints
  *  @sa glfwInit
- *  @sa glfwInitHintString
  *
  *  @since Added in version 3.3.
  *
@@ -1676,40 +1674,6 @@ GLFWAPI void glfwTerminate(void);
  */
 GLFWAPI void glfwInitHint(int hint, int value);
 
-/*! @brief Sets the specified init hint to the desired value.
- *
- *  This function sets hints for the next initialization of GLFW.  Only string
- *  type hints can be set with this function.
- *
- *  The values you set hints to are never reset by GLFW, but they only take
- *  effect during initialization.  Once GLFW has been initialized, any values
- *  you set will be ignored until the library is terminated and initialized
- *  again.
- *
- *  Some hints are platform specific.  These may be set on any platform but they
- *  will only affect their specific platform.  Other platforms will ignore them.
- *  Setting these hints requires no platform specific headers or functions.
- *
- *  @param[in] hint The [init hint](@ref init_hints) to set.
- *  @param[in] value The new value of the init hint.
- *
- *  @errors Possible errors include @ref GLFW_INVALID_ENUM and @ref
- *  GLFW_INVALID_VALUE.
- *
- *  @remarks This function may be called before @ref glfwInit.
- *
- *  @thread_safety This function must only be called from the main thread.
- *
- *  @sa init_hints
- *  @sa glfwInit
- *  @sa glfwInitHint
- *
- *  @since Added in version 3.3.
- *
- *  @ingroup init
- */
-GLFWAPI void glfwInitHintString(int hint, const char* value);
-
 /*! @brief Retrieves the version of the GLFW library.
  *
  *  This function retrieves the major, minor and revision numbers of the GLFW
@@ -2205,6 +2169,7 @@ GLFWAPI void glfwSetGammaRamp(GLFWmonitor* monitor, const GLFWgammaramp* ramp);
  *
  *  @sa @ref window_hints
  *  @sa @ref glfwWindowHint
+ *  @sa @ref glfwWindowHintString
  *
  *  @since Added in version 3.0.
  *
@@ -2215,14 +2180,20 @@ GLFWAPI void glfwDefaultWindowHints(void);
 /*! @brief Sets the specified window hint to the desired value.
  *
  *  This function sets hints for the next call to @ref glfwCreateWindow.  The
- *  hints, once set, retain their values until changed by a call to @ref
- *  glfwWindowHint or @ref glfwDefaultWindowHints, or until the library is
- *  terminated.
+ *  hints, once set, retain their values until changed by a call to this
+ *  function or @ref glfwDefaultWindowHints, or until the library is terminated.
+ *
+ *  Only integer value hints can be set with this function.  String value hints
+ *  are set with @ref glfwWindowHintString.
  *
  *  This function does not check whether the specified hint values are valid.
  *  If you set hints to invalid values this will instead be reported by the next
  *  call to @ref glfwCreateWindow.
  *
+ *  Some hints are platform specific.  These may be set on any platform but they
+ *  will only affect their specific platform.  Other platforms will ignore them.
+ *  Setting these hints requires no platform specific headers or functions.
+ *
  *  @param[in] hint The [window hint](@ref window_hints) to set.
  *  @param[in] value The new value of the window hint.
  *
@@ -2232,6 +2203,7 @@ GLFWAPI void glfwDefaultWindowHints(void);
  *  @thread_safety This function must only be called from the main thread.
  *
  *  @sa @ref window_hints
+ *  @sa @ref glfwWindowHintString
  *  @sa @ref glfwDefaultWindowHints
  *
  *  @since Added in version 3.0.  Replaces `glfwOpenWindowHint`.
@@ -2240,6 +2212,44 @@ GLFWAPI void glfwDefaultWindowHints(void);
  */
 GLFWAPI void glfwWindowHint(int hint, int value);
 
+/*! @brief Sets the specified window hint to the desired value.
+ *
+ *  This function sets hints for the next call to @ref glfwCreateWindow.  The
+ *  hints, once set, retain their values until changed by a call to this
+ *  function or @ref glfwDefaultWindowHints, or until the library is terminated.
+ *
+ *  Only string type hints can be set with this function.  Integer value hints
+ *  are set with @ref glfwWindowHint.
+ *
+ *  This function does not check whether the specified hint values are valid.
+ *  If you set hints to invalid values this will instead be reported by the next
+ *  call to @ref glfwCreateWindow.
+ *
+ *  Some hints are platform specific.  These may be set on any platform but they
+ *  will only affect their specific platform.  Other platforms will ignore them.
+ *  Setting these hints requires no platform specific headers or functions.
+ *
+ *  @param[in] hint The [window hint](@ref window_hints) to set.
+ *  @param[in] value The new value of the window hint.
+ *
+ *  @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
+ *  GLFW_INVALID_ENUM.
+ *
+ *  @pointer_lifetime The specified string is copied before this function
+ *  returns.
+ *
+ *  @thread_safety This function must only be called from the main thread.
+ *
+ *  @sa @ref window_hints
+ *  @sa @ref glfwWindowHint
+ *  @sa @ref glfwDefaultWindowHints
+ *
+ *  @since Added in version 3.3.
+ *
+ *  @ingroup window
+ */
+GLFWAPI void glfwWindowHintString(int hint, const char* value);
+
 /*! @brief Creates a window and its associated context.
  *
  *  This function creates a window and its associated OpenGL or OpenGL ES
@@ -2362,10 +2372,12 @@ GLFWAPI void glfwWindowHint(int hint, int value);
  *  query the final size, position or other attributes directly after window
  *  creation.
  *
- *  @remark @x11 The name and class of the `WM_CLASS` window property will by
- *  default be set to the window title passed to this function.  Set the @ref
- *  GLFW_X11_WM_CLASS_NAME and @ref GLFW_X11_WM_CLASS_CLASS init hints before
- *  initialization to override this.
+ *  @remark @x11 The class part of the `WM_CLASS` window property will by
+ *  default be set to the window title passed to this function.  The instance
+ *  part will use the contents of the `RESOURCE_NAME` environment variable, if
+ *  present and not empty, or fall back to the window title.  Set the @ref
+ *  GLFW_X11_CLASS_NAME and @ref GLFW_X11_INSTANCE_NAME window hints to override
+ *  this.
  *
  *  @remark @wayland The window frame is currently unimplemented, as if
  *  [GLFW_DECORATED](@ref GLFW_DECORATED_hint) was always set to `GLFW_FALSE`.

src/init.c

@@ -53,10 +53,6 @@ static _GLFWinitconfig _glfwInitHints =
     {
         GLFW_TRUE,  // macOS menu bar
         GLFW_TRUE   // macOS bundle chdir
-    },
-    {
-        "",         // X11 WM_CLASS name
-        ""          // X11 WM_CLASS class
     }
 };
 
@@ -260,27 +256,7 @@ GLFWAPI void glfwInitHint(int hint, int value)
     }
 
     _glfwInputError(GLFW_INVALID_ENUM,
-                    "Invalid integer type init hint 0x%08X", hint);
-}
-
-GLFWAPI void glfwInitHintString(int hint, const char* value)
-{
-    assert(value != NULL);
-
-    switch (hint)
-    {
-        case GLFW_X11_WM_CLASS_NAME:
-            strncpy(_glfwInitHints.x11.className, value,
-                    sizeof(_glfwInitHints.x11.className) - 1);
-            return;
-        case GLFW_X11_WM_CLASS_CLASS:
-            strncpy(_glfwInitHints.x11.classClass, value,
-                    sizeof(_glfwInitHints.x11.classClass) - 1);
-            return;
-    }
-
-    _glfwInputError(GLFW_INVALID_ENUM,
-                    "Invalid string type init hint 0x%08X", hint);
+                    "Invalid init hint 0x%08X", hint);
 }
 
 GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev)

src/internal.h

@@ -281,10 +281,6 @@ struct _GLFWinitconfig
         GLFWbool  menubar;
         GLFWbool  chdir;
     } ns;
-    struct {
-        char      className[256];
-        char      classClass[256];
-    } x11;
 };
 
 /*! @brief Window configuration.
@@ -310,6 +306,10 @@ struct _GLFWwndconfig
         GLFWbool  retina;
         GLFWbool  frame;
     } ns;
+    struct {
+        char      className[256];
+        char      instanceName[256];
+    } x11;
 };
 
 /*! @brief Context configuration.

src/window.c

@@ -396,6 +396,27 @@ GLFWAPI void glfwWindowHint(int hint, int value)
     _glfwInputError(GLFW_INVALID_ENUM, "Invalid window hint 0x%08X", hint);
 }
 
+GLFWAPI void glfwWindowHintString(int hint, const char* value)
+{
+    assert(value != NULL);
+
+    _GLFW_REQUIRE_INIT();
+
+    switch (hint)
+    {
+        case GLFW_X11_CLASS_NAME:
+            strncpy(_glfw.hints.window.x11.className, value,
+                    sizeof(_glfw.hints.window.x11.className) - 1);
+            return;
+        case GLFW_X11_INSTANCE_NAME:
+            strncpy(_glfw.hints.window.x11.instanceName, value,
+                    sizeof(_glfw.hints.window.x11.instanceName) - 1);
+            return;
+    }
+
+    _glfwInputError(GLFW_INVALID_ENUM, "Invalid window hint string 0x%08X", hint);
+}
+
 GLFWAPI void glfwDestroyWindow(GLFWwindow* handle)
 {
     _GLFWwindow* window = (_GLFWwindow*) handle;

src/x11_window.c

@@ -711,21 +711,26 @@ static GLFWbool createNativeWindow(_GLFWwindow* window,
     {
         XClassHint* hint = XAllocClassHint();
 
-        if (strlen(_glfw.hints.init.x11.className) &&
-            strlen(_glfw.hints.init.x11.classClass))
+        if (strlen(wndconfig->x11.instanceName) &&
+            strlen(wndconfig->x11.className))
         {
-            hint->res_name = (char*) _glfw.hints.init.x11.className;
-            hint->res_class = (char*) _glfw.hints.init.x11.classClass;
-        }
-        else if (strlen(wndconfig->title))
-        {
-            hint->res_name = (char*) wndconfig->title;
-            hint->res_class = (char*) wndconfig->title;
+            hint->res_name = (char*) wndconfig->x11.instanceName;
+            hint->res_class = (char*) wndconfig->x11.className;
         }
         else
         {
-            hint->res_name = (char*) "glfw-application";
-            hint->res_class = (char*) "GLFW-Application";
+            const char* resourceName = getenv("RESOURCE_NAME");
+            if (resourceName && strlen(resourceName))
+                hint->res_name = (char*) resourceName;
+            else if (strlen(wndconfig->title))
+                hint->res_name = (char*) wndconfig->title;
+            else
+                hint->res_name = (char*) "glfw-application";
+
+            if (strlen(wndconfig->title))
+                hint->res_class = (char*) wndconfig->title;
+            else
+                hint->res_class = (char*) "GLFW-Application";
         }
 
         XSetClassHint(_glfw.x11.display, window->x11.handle, hint);