Add glfwInitHintString

Adds string type init hints.  Adds X11 specific init hints for WM_CLASS
components.  Documentation work.

Fixes #893.
This commit is contained in:
Camilla Löwy 2017-07-25 01:55:08 +02:00
parent 00d2efb9ab
commit 213dd2d0d6
7 changed files with 139 additions and 34 deletions

View File

@ -143,7 +143,7 @@ information on what to include when reporting a bug.
- Added `glfwSetWindowAttrib` function for changing window attributes (#537) - Added `glfwSetWindowAttrib` function for changing window attributes (#537)
- Added `glfwGetJoystickHats` function for querying joystick hats - Added `glfwGetJoystickHats` function for querying joystick hats
(#889,#906,#934) (#889,#906,#934)
- Added `glfwInitHint` function for setting library initialization hints - Added `glfwInitHint` and `glfwInitHintString` for setting initialization hints
- Added headless [OSMesa](http://mesa3d.org/osmesa.html) backend (#850) - Added headless [OSMesa](http://mesa3d.org/osmesa.html) backend (#850)
- Added definition of `GLAPIENTRY` to public header - Added definition of `GLAPIENTRY` to public header
- Added `GLFW_CENTER_CURSOR` window hint for controlling cursor centering - Added `GLFW_CENTER_CURSOR` window hint for controlling cursor centering
@ -154,6 +154,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_GRAPHICS_SWITCHING` window hint (#377,#935)
- Added macOS specific `GLFW_COCOA_CHDIR_RESOURCES` init hint - Added macOS specific `GLFW_COCOA_CHDIR_RESOURCES` init hint
- Added macOS specific `GLFW_COCOA_MENUBAR` 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 `GLFW_INCLUDE_ES32` for including the OpenGL ES 3.2 header - Added `GLFW_INCLUDE_ES32` for including the OpenGL ES 3.2 header
- Added `GLFW_OSMESA_CONTEXT_API` for creating OpenGL contexts with - Added `GLFW_OSMESA_CONTEXT_API` for creating OpenGL contexts with
[OSMesa](https://www.mesa3d.org/osmesa.html) (#281) [OSMesa](https://www.mesa3d.org/osmesa.html) (#281)

View File

@ -33,6 +33,7 @@ successfully initialized, and only from the main thread.
- @ref glfwGetError - @ref glfwGetError
- @ref glfwSetErrorCallback - @ref glfwSetErrorCallback
- @ref glfwInitHint - @ref glfwInitHint
- @ref glfwInitHintString
- @ref glfwInit - @ref glfwInit
- @ref glfwTerminate - @ref glfwTerminate
@ -65,23 +66,26 @@ system settings and these might not be restored without termination.
@subsection init_hints Initialization hints @subsection init_hints Initialization hints
There are a number of hints that can be set before initialization, that affect Initialization hints are set before @ref glfwInit and affect how the library
how the library behaves. behaves until termination. Integer type hints are set with @ref glfwInitHint
and string type hints with @ref glfwInitHintString.
The values you set are not affected by initialization or termination, but they @code
are only read during initialization. Once GLFW has been initialized, setting glfwInitHint(GLFW_JOYSTICK_HAT_BUTTONS, GLFW_FALSE);
new hint values will not affect behavior until the next time it is terminated @endcode
and initialized.
Some hints are platform specific. These are always valid to set on any The values you set hints to are never reset by GLFW, but they only take effect
platform but they will only affect their specific platform. Other platforms during initialization. Once GLFW has been initialized, any values you set will
will simply ignore them. Setting these hints requires no platform specific be ignored until the library is terminated and initialized again.
headers or calls.
Some hints are platform specific. These may be set on any platform but they
will only affect their specific platform. Other platforms will simply ignore
them. Setting these hints requires no platform specific headers or functions.
@anchor GLFW_JOYSTICK_HAT_BUTTONS @anchor GLFW_JOYSTICK_HAT_BUTTONS
__GLFW_JOYSTICK_HAT_BUTTONS__ specifies whether to also expose joystick hats as __GLFW_JOYSTICK_HAT_BUTTONS__ specifies whether to also expose joystick hats as
buttons, for compatibility with earlier versions of GLFW that did not have @ref buttons, for compatibility with earlier versions of GLFW that did not have @ref
glfwGetJoystickHats. glfwGetJoystickHats. Set this with @ref glfwInitHint.
@subsubsection init_hints_osx macOS specific init hints @subsubsection init_hints_osx macOS specific init hints
@ -89,12 +93,21 @@ glfwGetJoystickHats.
@anchor GLFW_COCOA_CHDIR_RESOURCES @anchor GLFW_COCOA_CHDIR_RESOURCES
__GLFW_COCOA_CHDIR_RESOURCES__ specifies whether to set the current directory to __GLFW_COCOA_CHDIR_RESOURCES__ specifies whether to set the current directory to
the application to the `Contents/Resources` subdirectory of the application's the application to the `Contents/Resources` subdirectory of the application's
bundle, if present. bundle, if present. Set this with @ref glfwInitHint.
@anchor GLFW_COCOA_MENUBAR @anchor GLFW_COCOA_MENUBAR
__GLFW_COCOA_MENUBAR__ specifies whether to create a basic menu bar, either from __GLFW_COCOA_MENUBAR__ specifies whether to create a basic menu bar, either from
a nib or manually, when the first window is created, which is when AppKit is a nib or manually, when the first window is created, which is when AppKit is
initialized. 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 @subsubsection init_hints_values Supported and default values
@ -104,6 +117,8 @@ Init hint | Default value | Supported values
@ref GLFW_JOYSTICK_HAT_BUTTONS | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE` @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_CHDIR_RESOURCES | `GLFW_TRUE` | `GLFW_TRUE` or `GLFW_FALSE`
@ref GLFW_COCOA_MENUBAR | `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 @subsection intro_init_terminate Terminating GLFW

View File

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

View File

@ -1016,6 +1016,9 @@ extern "C" {
#define GLFW_COCOA_CHDIR_RESOURCES 0x00051001 #define GLFW_COCOA_CHDIR_RESOURCES 0x00051001
#define GLFW_COCOA_MENUBAR 0x00051002 #define GLFW_COCOA_MENUBAR 0x00051002
#define GLFW_X11_WM_CLASS_NAME 0x00052001
#define GLFW_X11_WM_CLASS_CLASS 0x00052002
/*! @} */ /*! @} */
#define GLFW_DONT_CARE -1 #define GLFW_DONT_CARE -1
@ -1609,17 +1612,18 @@ GLFWAPI void glfwTerminate(void);
/*! @brief Sets the specified init hint to the desired value. /*! @brief Sets the specified init hint to the desired value.
* *
* This function sets hints for the next initialization of GLFW. * This function sets hints for the next initialization of GLFW. Only integer
* type hints can be set with this function.
* *
* The values you set are not affected by initialization or termination, but * The values you set hints to are never reset by GLFW, but they only take
* they are only read during initialization. Once GLFW has been initialized, * effect during initialization. Once GLFW has been initialized, any values
* setting new hint values will not affect behavior until the next time the * you set will be ignored until the library is terminated and initialized
* library is terminated and initialized. * again.
* *
* Some hints are platform specific. These are always valid to set on any * Some hints are platform specific. These may be set on any platform but they
* platform but they will only affect their specific platform. Other platforms * will only affect their specific platform. Other platforms will simply
* will simply ignore them. Setting these hints requires no platform specific * ignore them. Setting these hints requires no platform specific headers or
* headers or calls. * functions.
* *
* @param[in] hint The [init hint](@ref init_hints) to set. * @param[in] hint The [init hint](@ref init_hints) to set.
* @param[in] value The new value of the init hint. * @param[in] value The new value of the init hint.
@ -1633,6 +1637,7 @@ GLFWAPI void glfwTerminate(void);
* *
* @sa init_hints * @sa init_hints
* @sa glfwInit * @sa glfwInit
* @sa glfwInitHintString
* *
* @since Added in version 3.3. * @since Added in version 3.3.
* *
@ -1640,6 +1645,41 @@ GLFWAPI void glfwTerminate(void);
*/ */
GLFWAPI void glfwInitHint(int hint, int value); 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 simply
* 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. /*! @brief Retrieves the version of the GLFW library.
* *
* This function retrieves the major, minor and revision numbers of the GLFW * This function retrieves the major, minor and revision numbers of the GLFW
@ -2261,6 +2301,11 @@ GLFWAPI void glfwWindowHint(int hint, int value);
* query the final size, position or other attributes directly after window * query the final size, position or other attributes directly after window
* creation. * 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 @wayland The window frame is currently unimplemented, as if * @remark @wayland The window frame is currently unimplemented, as if
* [GLFW_DECORATED](@ref GLFW_DECORATED_hint) was always set to `GLFW_FALSE`. * [GLFW_DECORATED](@ref GLFW_DECORATED_hint) was always set to `GLFW_FALSE`.
* A compositor can still emit close, resize or maximize events, using for * A compositor can still emit close, resize or maximize events, using for

View File

@ -32,6 +32,7 @@
#include <stdlib.h> #include <stdlib.h>
#include <stdio.h> #include <stdio.h>
#include <stdarg.h> #include <stdarg.h>
#include <assert.h>
// The global variables below comprise all global data in GLFW. // The global variables below comprise all global data in GLFW.
@ -48,10 +49,14 @@ static _GLFWerror _glfwMainThreadError;
static GLFWerrorfun _glfwErrorCallback; static GLFWerrorfun _glfwErrorCallback;
static _GLFWinitconfig _glfwInitHints = static _GLFWinitconfig _glfwInitHints =
{ {
GLFW_TRUE, // hat buttons GLFW_TRUE, // hat buttons
{ {
GLFW_TRUE, // menubar GLFW_TRUE, // macOS menu bar
GLFW_TRUE // chdir GLFW_TRUE // macOS bundle chdir
},
{
"", // X11 WM_CLASS name
"" // X11 WM_CLASS class
} }
}; };
@ -243,7 +248,28 @@ GLFWAPI void glfwInitHint(int hint, int value)
return; return;
} }
_glfwInputError(GLFW_INVALID_ENUM, "Invalid init hint 0x%08X", hint); _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);
break;
case GLFW_X11_WM_CLASS_CLASS:
strncpy(_glfwInitHints.x11.classClass, value,
sizeof(_glfwInitHints.x11.classClass) - 1);
break;
}
_glfwInputError(GLFW_INVALID_ENUM,
"Invalid string type init hint 0x%08X", hint);
} }
GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev) GLFWAPI void glfwGetVersion(int* major, int* minor, int* rev)

View File

@ -277,6 +277,10 @@ struct _GLFWinitconfig
GLFWbool menubar; GLFWbool menubar;
GLFWbool chdir; GLFWbool chdir;
} ns; } ns;
struct {
char className[256];
char classClass[256];
} x11;
}; };
/*! @brief Window configuration. /*! @brief Window configuration.

View File

@ -614,13 +614,25 @@ static GLFWbool createNativeWindow(_GLFWwindow* window,
updateNormalHints(window, wndconfig->width, wndconfig->height); updateNormalHints(window, wndconfig->width, wndconfig->height);
// Set ICCCM WM_CLASS property // Set ICCCM WM_CLASS property
// HACK: Until a mechanism for specifying the application name is added, the
// initial window title is used as the window class name
if (strlen(wndconfig->title))
{ {
XClassHint* hint = XAllocClassHint(); XClassHint* hint = XAllocClassHint();
hint->res_name = (char*) wndconfig->title;
hint->res_class = (char*) wndconfig->title; if (strlen(_glfw.hints.init.x11.className) &&
strlen(_glfw.hints.init.x11.classClass))
{
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;
}
else
{
hint->res_name = (char*) "glfw-application";
hint->res_class = (char*) "GLFW-Application";
}
XSetClassHint(_glfw.x11.display, window->x11.handle, hint); XSetClassHint(_glfw.x11.display, window->x11.handle, hint);
XFree(hint); XFree(hint);