Navy.gif/glfw
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Improve documentation relating to key tokens

Browse Source 
Shifted the documentation away from the term 'named keys' as something
different than keys that glfwGetKeyName will return a name for.  The
already existing term 'key token' should now be used to refer to the
GLFW_KEY_* constants.

The associated term 'named mouse button' was also replaced with
'supported mouse button'.

The parts explaining which key tokens will return a valid scancode from
glfwGetKeyScancode have hopefully been clarified.  This issue was
reported in #2055.

The GLFW_KEY_UNKNOWN constant has been moved out of the list of key
tokens to simplify and hopefully clarify the related documentation.

Various other keyboard key related edits were made, hopefully resulting
in improvements.

Related to #2055
This commit is contained in:
Camilla Löwy 2023-12-04 20:06:10 +01:00
parent 557a633b2d
commit 9959dc69ca
2 changed files with 38 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
docs/input.dox
View File

@ -95,7 +95,7 @@ new size before everything returns back out of the @ref glfwSetWindowSize call.
GLFW divides keyboard input into two categories; key events and character
events. Key events relate to actual physical keyboard keys, whereas character
events relate to the Unicode code points generated by pressing some of them.
events relate to the text that is generated by pressing some of them.
Keys and characters do not map 1:1. A single key press may produce several
characters, and a single character may require several keys to produce. This
@ -127,6 +127,10 @@ The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`. Events with
`GLFW_PRESS` and `GLFW_RELEASE` actions are emitted for every key press. Most
keys will also emit events with `GLFW_REPEAT` actions while a key is held down.
Note that many keyboards have a limit on how many keys being simultaneous held
down that they can detect. This limit is called
[key rollover](https://en.wikipedia.org/wiki/Key_rollover).
Key events with `GLFW_REPEAT` actions are intended for text input. They are
emitted at the rate set in the user's keyboard settings. At most one key is
repeated even if several keys are held down. `GLFW_REPEAT` actions should not
@ -142,16 +146,16 @@ keys.
The scancode is unique for every key, regardless of whether it has a key token.
Scancodes are platform-specific but consistent over time, so keys will have
different scancodes depending on the platform but they are safe to save to disk.
You can query the scancode for any [named key](@ref keys) on the current
platform with @ref glfwGetKeyScancode.
You can query the scancode for any [key token](@ref keys) supported on the
current platform with @ref glfwGetKeyScancode.
@code
const int scancode = glfwGetKeyScancode(GLFW_KEY_X);
set_key_mapping(scancode, swap_weapons);
@endcode
The last reported state for every [named key](@ref keys) is also saved in
per-window state arrays that can be polled with @ref glfwGetKey.
The last reported state for every physical key with a [key token](@ref keys) is
also saved in per-window state arrays that can be polled with @ref glfwGetKey.
@code
int state = glfwGetKey(window, GLFW_KEY_E);
@ -164,7 +168,8 @@ if (state == GLFW_PRESS)
The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
This function only returns cached key event state. It does not poll the
system for the current physical state of the key.
system for the current state of the physical key. It also does not provide any
key repeat information.
@anchor GLFW_STICKY_KEYS
Whenever you poll state, you risk missing the state change you are looking for.
@ -195,15 +200,15 @@ Lock was on when the event occurred and the @ref GLFW_MOD_NUM_LOCK bit set if
Num Lock was on.
The `GLFW_KEY_LAST` constant holds the highest value of any
[named key](@ref keys).
[key token](@ref keys).
@subsection input_char Text input
GLFW supports text input in the form of a stream of
[Unicode code points](https://en.wikipedia.org/wiki/Unicode), as produced by the
operating system text input system. Unlike key input, text input obeys keyboard
layouts and modifier keys and supports composing characters using
operating system text input system. Unlike key input, text input is affected by
keyboard layouts and modifier keys and supports composing characters using
[dead keys](https://en.wikipedia.org/wiki/Dead_key). Once received, you can
encode the code points into UTF-8 or any other encoding you prefer.
@ -502,8 +507,9 @@ void mouse_button_callback(GLFWwindow* window, int button, int action, int mods)
The action is one of `GLFW_PRESS` or `GLFW_RELEASE`.
Mouse button states for [named buttons](@ref buttons) are also saved in
per-window state arrays that can be polled with @ref glfwGetMouseButton.
The last reported state for every [supported mouse button](@ref buttons) is also
saved in per-window state arrays that can be polled with @ref
glfwGetMouseButton.
@code
int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT);
@ -536,7 +542,7 @@ had been processed in the meantime, the state will reset to `GLFW_RELEASE`,
otherwise it will remain `GLFW_PRESS`.
The `GLFW_MOUSE_BUTTON_LAST` constant holds the highest value of any
[named button](@ref buttons).
[supported mouse button](@ref buttons).
@subsection scrolling Scroll input

35
include/GLFW/glfw3.h
View File

@ -361,10 +361,15 @@ extern "C" {
#define GLFW_HAT_RIGHT_DOWN (GLFW_HAT_RIGHT | GLFW_HAT_DOWN)
#define GLFW_HAT_LEFT_UP (GLFW_HAT_LEFT | GLFW_HAT_UP)
#define GLFW_HAT_LEFT_DOWN (GLFW_HAT_LEFT | GLFW_HAT_DOWN)
/*! @ingroup input
*/
#define GLFW_KEY_UNKNOWN -1
/*! @} */
/*! @defgroup keys Keyboard keys
* @brief Keyboard key IDs.
/*! @defgroup keys Keyboard key tokens
* @brief Keyboard key tokens.
*
* See [key input](@ref input_key) for how these are used.
*
@ -387,9 +392,6 @@ extern "C" {
* @{
*/
/* The unknown key */
#define GLFW_KEY_UNKNOWN -1
/* Printable keys */
#define GLFW_KEY_SPACE 32
#define GLFW_KEY_APOSTROPHE 39 /* ' */
@ -4741,15 +4743,18 @@ GLFWAPI const char* glfwGetKeyName(int key, int scancode);
*
* This function returns the platform-specific scancode of the specified key.
*
* If the key is `GLFW_KEY_UNKNOWN` or does not exist on the keyboard this
* method will return `-1`.
* If the specified [key token](@ref keys) corresponds to a physical key not
* supported on the current platform then this method will return `-1`.
* Calling this function with anything other than a key token will return `-1`
* and generate a @ref GLFW_INVALID_ENUM error.
*
* @param[in] key Any [named key](@ref keys).
* @return The platform-specific scancode for the key, or `-1` if an
* [error](@ref error_handling) occurred.
* @param[in] key Any [key token](@ref keys).
* @return The platform-specific scancode for the key, or `-1` if the key is
* not supported on the current platform or an [error](@ref error_handling)
* occurred.
*
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED, @ref
* GLFW_INVALID_ENUM and @ref GLFW_PLATFORM_ERROR.
* @errors Possible errors include @ref GLFW_NOT_INITIALIZED and @ref
* GLFW_INVALID_ENUM.
*
* @thread_safety This function may be called from any thread.
*
@ -5058,9 +5063,9 @@ GLFWAPI void glfwSetCursor(GLFWwindow* window, GLFWcursor* cursor);
* [character callback](@ref glfwSetCharCallback) instead.
*
* When a window loses input focus, it will generate synthetic key release
* events for all pressed named keys. You can tell these events from
* user-generated events by the fact that the synthetic ones are generated
* after the focus loss event has been processed, i.e. after the
* events for all pressed keys with associated key tokens. You can tell these
* events from user-generated events by the fact that the synthetic ones are
* generated after the focus loss event has been processed, i.e. after the
* [window focus callback](@ref glfwSetWindowFocusCallback) has been called.
*
* The scancode of a key is specific to that platform or sometimes even to that