mirror of
https://github.com/glfw/glfw.git
synced 2026-08-28 10:25:53 +02:00
Documentation work.
This commit is contained in:
Camilla Berglund
554
docs/input.dox
554
docs/input.dox
@@ -1,13 +1,563 @@
|
||||
/*!
|
||||
|
||||
@page input Input handling guide
|
||||
@page input Input guide
|
||||
|
||||
@tableofcontents
|
||||
|
||||
@section input_key Keyboard input
|
||||
This guide introduces the input related functions of GLFW. There are also
|
||||
guides for the other areas of GLFW.
|
||||
|
||||
- @ref intro
|
||||
- @ref window
|
||||
- @ref context
|
||||
- @ref monitor
|
||||
|
||||
GLFW provides many kinds of input. While some can only be polled, like time, or
|
||||
only received via callbacks, like scrolling, there are those that provide both
|
||||
callbacks and polling. Where a callback is provided, that is the recommended
|
||||
way to receive that kind of input. The more you can use callbacks the less time
|
||||
your users' machines will need to spend polling.
|
||||
|
||||
All input callbacks receive a window handle. By using the
|
||||
[window user pointer](@ref window_userptr), you can access non-global structures
|
||||
or objects from your callbacks.
|
||||
|
||||
To get a better feel for how the various events callbacks behave, run the
|
||||
`events` test program. It register every callback supported by GLFW and prints
|
||||
out all arguments provided for every event, along with time and sequence
|
||||
information.
|
||||
|
||||
|
||||
@section input_event Event processing
|
||||
|
||||
GLFW needs to communicate regularly with the window system both in order to
|
||||
receive events and to show that the application hasn't locked up. Event
|
||||
processing must be done regularly while you have visible windows and is normally
|
||||
done each frame after [buffer swapping](@ref window_swap).
|
||||
|
||||
There are two functions for processing pending events. @ref glfwPollEvents,
|
||||
processes only those events that have already been received and then returns
|
||||
immediately.
|
||||
|
||||
@code
|
||||
glfwPollEvents();
|
||||
@endcode
|
||||
|
||||
This is the best choice when rendering continually, like most games do.
|
||||
|
||||
If you only need to update the contents of the window when you receive new
|
||||
input, @ref glfwWaitEvents is a better choice.
|
||||
|
||||
@code
|
||||
glfwWaitEvents();
|
||||
@endcode
|
||||
|
||||
It puts the thread to sleep until at least one event has been received and then
|
||||
processes all received events. This saves a great deal of CPU cycles and is
|
||||
useful for, for example, editing tools. There must be at least one GLFW window
|
||||
for this function to sleep.
|
||||
|
||||
If the main thread is sleeping in @ref glfwWaitEvents, you can wake it from
|
||||
another thread by posting an empty event to the event queue with @ref
|
||||
glfwPostEmptyEvent.
|
||||
|
||||
@code
|
||||
glfwPostEmptyEvent();
|
||||
@endcode
|
||||
|
||||
Do not assume that callbacks will *only* be called through either of the above
|
||||
functions. While it is necessary to process events in the event queue, some
|
||||
window systems will send some events directly to the application, which in turn
|
||||
causes callbacks to be called outside of regular event processing.
|
||||
|
||||
|
||||
@section input_keyboard Keyboard input
|
||||
|
||||
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.
|
||||
|
||||
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
|
||||
may not be the case on your machine, but your users are likely not all using the
|
||||
same keyboard layout, input method or even operating system as you.
|
||||
|
||||
|
||||
@subsection input_key Key input
|
||||
|
||||
If you wish to be notified when a physical key is pressed or released or when it
|
||||
repeats, set a key callback with @ref glfwSetKeyCallback.
|
||||
|
||||
@code
|
||||
glfwSetKeyCallback(window, key_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the [keyboard key](@ref keys), platform-specific
|
||||
scancode, key action and [modifier bits](@ref mods).
|
||||
|
||||
@code
|
||||
void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
|
||||
{
|
||||
if (key == GLFW_KEY_E && action == GLFW_PRESS)
|
||||
activate_airship();
|
||||
}
|
||||
@endcode
|
||||
|
||||
The action is one of `GLFW_PRESS`, `GLFW_REPEAT` or `GLFW_RELEASE`. The key
|
||||
will be `GLFW_KEY_UNKNOWN` if GLFW lacks a key token for it. These keys still
|
||||
have unique, if platform-specific scancodes.
|
||||
|
||||
The scancode is unique for every key but is platform-specific, so a scancode
|
||||
will map to different keys on different platforms.
|
||||
|
||||
The key will be `GLFW_KEY_UNKNOWN` for special keys like *E-mail* or *Play* that
|
||||
don't have a key token. Those keys will still have unique, if platform-specific
|
||||
scancodes.
|
||||
|
||||
Key states for [named keys](@ref keys) are also saved in per-window state arrays
|
||||
that can be polled with @ref glfwGetKey.
|
||||
|
||||
@code
|
||||
int state = glfwGetKey(window, GLFW_KEY_E);
|
||||
if (state == GLFW_PRESS)
|
||||
activate_airship();
|
||||
@endcode
|
||||
|
||||
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 state of the key.
|
||||
|
||||
Whenever you poll state, you risk missing the state change you are looking for.
|
||||
If a pressed key is released again before you poll its state, you will have
|
||||
missed the key press. The recommended solution for this is to use a
|
||||
key callback, but there is also the `GLFW_STICKY_KEYS` input mode.
|
||||
|
||||
@code
|
||||
glfwSetInputMode(window, GLFW_STICKY_KEYS, 1);
|
||||
@endcode
|
||||
|
||||
When sticky keys mode is enabled, the pollable state of a key will remain
|
||||
`GLFW_PRESS` until the state of that key is polled with @ref glfwGetKey. Once
|
||||
it has been polled, if a key release event had been processed in the meantime,
|
||||
the state will reset to `GLFW_RELEASE`, otherwise it will remain `GLFW_PRESS`.
|
||||
|
||||
The `GLFW_KEY_LAST` constant holds the highest value of any
|
||||
[named key](@ref keys).
|
||||
|
||||
|
||||
@subsection input_char Unicode character input
|
||||
|
||||
If you wish to receive Unicode code point input, set a character callback with
|
||||
@ref glfwSetCharCallback.
|
||||
|
||||
@code
|
||||
glfwSetCharCallback(window, character_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives Unicode code points for key events that would
|
||||
have led to regular text input on that platform.
|
||||
|
||||
@code
|
||||
void character_callback(GLFWwindow* window, unsigned int codepoint)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
If you wish to receive all Unicode code point events generated by the system, or
|
||||
just want to know exactly what modifier keys were used, set a character with
|
||||
modifiers callback with @ref glfwSetCharModsCallback.
|
||||
|
||||
@code
|
||||
glfwSetCharCallback(window, charmods_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives Unicode code points and
|
||||
[modifier bits](@ref mods).
|
||||
|
||||
@code
|
||||
void charmods_callback(GLFWwindow* window, unsigned int codepoint, int mods)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
|
||||
@section input_mouse Mouse input
|
||||
|
||||
Mouse input comes in many forms, including of mouse motion and button presses,
|
||||
system cursor appearance and behavior, and two-dimensional scrolling. All of
|
||||
these are supported by GLFW.
|
||||
|
||||
|
||||
@subsection input_cursor_pos Cursor position
|
||||
|
||||
If you wish to be notified when the system cursor moves over the window, set
|
||||
a cursor position callback with @ref glfwSetCursorPosCallback.
|
||||
|
||||
@code
|
||||
glfwSetCursorPosCallback(window, cursor_pos_callback);
|
||||
@endcode
|
||||
|
||||
The callback functions receives the cursor position. On platforms that provide
|
||||
it, the full sub-pixel cursor position is passed on.
|
||||
|
||||
@code
|
||||
static void cursor_position_callback(GLFWwindow* window, double xpos, double ypos)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
The cursor position is also saved per-window and can be polled with @ref
|
||||
glfwGetCursorPos.
|
||||
|
||||
@code
|
||||
double xpos, ypos;
|
||||
glfwGetCursorPos(window, &xpos, &ypos);
|
||||
@endcode
|
||||
|
||||
This function only returns cached cursor positions. It does not poll the
|
||||
system for the current position. Whenever you poll state, you risk missing the
|
||||
state change you are looking for.
|
||||
|
||||
|
||||
@subsection input_cursor_mode Cursor modes
|
||||
|
||||
The `GLFW_CURSOR` input mode provides several cursor modes for special forms of
|
||||
mouse motion input. By default, the `GLFW_CURSOR_NORMAL` cursor mode is used,
|
||||
meaning the regular arrow cursor or a [custom cursor](@ref input_cursor) is used
|
||||
and cursor motion is not limited.
|
||||
|
||||
If you wish to implement mouse motion based camera controls or other input
|
||||
schemes that require unlimited mouse movement, set the cursor mode to
|
||||
`GLFW_CURSOR_DISABLED`.
|
||||
|
||||
@code
|
||||
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_DISABLED);
|
||||
@endcode
|
||||
|
||||
This will hide the cursor and lock it to the specified window. GLFW will then
|
||||
take care of all the details of cursor re-centering and offset calculation and
|
||||
providing the application with a virtual cursor position. This virtual position
|
||||
is provided normally, both via the cursor position callback and via position
|
||||
polling.
|
||||
|
||||
@note You should not implement your own version of this functionality using
|
||||
other features of GLFW. It will not work as robustly as `GLFW_CURSOR_DISABLED`,
|
||||
as those features are not intended for this purpose.
|
||||
|
||||
If you just wish the cursor to become hidden when it is over a window, set
|
||||
the cursor mode to `GLFW_CURSOR_HIDDEN`.
|
||||
|
||||
@code
|
||||
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_HIDDEN);
|
||||
@endcode
|
||||
|
||||
This mode puts no limit on the motion of the cursor.
|
||||
|
||||
To exit out of either of these special modes, restore the `GLFW_CURSOR_NORMAL`
|
||||
cursor mode.
|
||||
|
||||
@code
|
||||
glfwSetInputMode(window, GLFW_CURSOR, GLFW_CURSOR_NORMAL);
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection input_cursor Cursor objects
|
||||
|
||||
GLFW supports creating custom system cursor images, encapsulated as @ref
|
||||
GLFWcursor objects. They are created with @ref glfwCreateCursor and destroyed
|
||||
with @ref glfwDestroyCursor (or @ref glfwTerminate, if any remain).
|
||||
|
||||
|
||||
@subsubsection input_cursor_creation Cursor creation
|
||||
|
||||
A cursor is created with @ref glfwCreateCursor, which returns a handle to the
|
||||
created cursor object. For example, this creates a 16x16 white square cursor
|
||||
with the hot-spot in the upper-left corner:
|
||||
|
||||
@code
|
||||
unsigned char pixels[16 * 16 * 4];
|
||||
memset(pixels, 0xff, sizeof(pixels));
|
||||
|
||||
GLFWimage image;
|
||||
image.width = 16;
|
||||
image.height = 16;
|
||||
image.pixels = pixels;
|
||||
|
||||
GLFWcursor* cursor = glfwCreateCursor(&image, 0, 0);
|
||||
@endcode
|
||||
|
||||
The image data is 32-bit RGBA, i.e. eight bits per channel. The pixels are
|
||||
arranged canonically as sequental rows, starting from the top-left corner.
|
||||
|
||||
|
||||
@subsubsection input_cursor_destruction Cursor destruction
|
||||
|
||||
When a cursor is no longer needed, destroy it with @ref glfwDestroyCursor.
|
||||
|
||||
@code
|
||||
glfwDestroyCursor(cursor);
|
||||
@endcode
|
||||
|
||||
Cursor destruction always succeeds. All cursors remaining at the time of @ref
|
||||
glfwTerminate is called are destroyed as well.
|
||||
|
||||
|
||||
@subsubsection input_cursor_set Cursor setting
|
||||
|
||||
A cursor can be set as current for a window with @ref glfwSetCursor.
|
||||
|
||||
@code
|
||||
glfwSetCursor(window, cursor);
|
||||
@endcode
|
||||
|
||||
Once set, the cursor image will be used as long as the system cursor is over the
|
||||
client area of the window and the [cursor mode](@ref input_cursor_mode) is set
|
||||
to `GLFW_CURSOR_NORMAL`.
|
||||
|
||||
A single cursor may be set for any number of windows.
|
||||
|
||||
To remove a cursor from a window, set the cursor of that window to `NULL`.
|
||||
|
||||
@code
|
||||
glfwSetCursor(window, NULL);
|
||||
@endcode
|
||||
|
||||
When a cursor is destroyed, it is removed from any window where it is set. This
|
||||
does not affect the cursor modes of those windows.
|
||||
|
||||
|
||||
@subsection input_cursor_enter Cursor enter/leave events
|
||||
|
||||
If you wish to be notified when the cursor enters or leaves the client area of
|
||||
a window, set a cursor enter/leave callback with @ref glfwSetCursorEnterCallback.
|
||||
|
||||
@code
|
||||
glfwSetCursorEnterCallback(window, cursor_enter_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the new classification of the cursor.
|
||||
|
||||
@code
|
||||
void cursor_enter_callback(GLFWwindow* window, int entered)
|
||||
{
|
||||
if (entered)
|
||||
{
|
||||
// The cursor entered the client area of the window
|
||||
}
|
||||
else
|
||||
{
|
||||
// The cursor left the client area of the window
|
||||
}
|
||||
}
|
||||
@endcode
|
||||
|
||||
|
||||
@subsection input_mouse_button Mouse button input
|
||||
|
||||
If you wish to be notified when a mouse button is pressed or released, set
|
||||
a mouse button callback with @ref glfwSetMouseButtonCallback.
|
||||
|
||||
@code
|
||||
glfwSetMouseButtonCallback(window, mouse_button_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives the [mouse button](@ref buttons), button action
|
||||
and [modifier bits](@ref mods).
|
||||
|
||||
@code
|
||||
void mouse_button_callback(GLFWwindow* window, int button, int action, int mods)
|
||||
{
|
||||
if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS)
|
||||
popup_menu();
|
||||
}
|
||||
@endcode
|
||||
|
||||
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.
|
||||
|
||||
@code
|
||||
int state = glfwGetMouseButton(window, GLFW_MOUSE_BUTTON_LEFT);
|
||||
if (state == GLFW_PRESS)
|
||||
upgrade_cow();
|
||||
@endcode
|
||||
|
||||
The returned state is one of `GLFW_PRESS` or `GLFW_RELEASE`.
|
||||
|
||||
This function only returns cached mouse button event state. It does not poll
|
||||
the system for the current state of the mouse button.
|
||||
|
||||
Whenever you poll state, you risk missing the state change you are looking for.
|
||||
If a pressed mouse button is released again before you poll its state, you will have
|
||||
missed the button press. The recommended solution for this is to use a
|
||||
mouse button callback, but there is also the `GLFW_STICKY_MOUSE_BUTTONS`
|
||||
input mode.
|
||||
|
||||
@code
|
||||
glfwSetInputMode(window, GLFW_STICKY_MOUSE_BUTTONS, 1);
|
||||
@endcode
|
||||
|
||||
When sticky mouse buttons mode is enabled, the pollable state of a mouse button
|
||||
will remain `GLFW_PRESS` until the state of that button is polled with @ref
|
||||
glfwGetMouseButton. Once it has been polled, if a mouse button release event
|
||||
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).
|
||||
|
||||
|
||||
@subsection input_scroll Scroll input
|
||||
|
||||
If you wish to be notified when the user scrolls, whether with a mouse wheel or
|
||||
touchpad gesture, set a scroll callback with @ref glfwSetScrollCallback.
|
||||
|
||||
@code
|
||||
glfwSetScrollCallback(window, scroll_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives two-dimensional scroll offsets.
|
||||
|
||||
@code
|
||||
void scroll_callback(GLFWwindow* window, double xoffset, double yoffset)
|
||||
{
|
||||
}
|
||||
@endcode
|
||||
|
||||
A simple mouse wheel, being vertical, provides offsets along the Y-axis.
|
||||
|
||||
|
||||
@section input_joy Joystick input
|
||||
|
||||
The joystick functions expose connected joysticks and controllers, with both
|
||||
referred to as joysticks. It supports up to sixteen joysticks, ranging from
|
||||
`GLFW_JOYSTICK_1`, `GLFW_JOYSTICK_2` up to `GLFW_JOYSTICK_LAST`. You can test
|
||||
whether a [joystick](@ref joysticks) is present with @ref glfwJoystickPresent.
|
||||
|
||||
@code
|
||||
int present = glfwJoystickPresent(GLFW_JOYSTICK_1);
|
||||
@endcode
|
||||
|
||||
When GLFW is initialized, detected joysticks are added to to the beginning of
|
||||
the array, starting with `GLFW_JOYSTICK_1`. Once a joystick is detected, it
|
||||
keeps its assigned index until it is disconnected, so as joysticks are connected
|
||||
and disconnected, they will become spread out.
|
||||
|
||||
Joystick state is updated as needed when a joystick function is called and does
|
||||
not require a window to be created or @ref glfwPollEvents or @ref glfwWaitEvents
|
||||
to be called.
|
||||
|
||||
|
||||
@subsection input_joy_axis Joystick axis states
|
||||
|
||||
The positions of all axes of a joystick are returned by @ref
|
||||
glfwGetJoystickAxes. See the reference documentation for the lifetime of the
|
||||
returned array.
|
||||
|
||||
@code
|
||||
int count;
|
||||
const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_1, &count);
|
||||
@endcode
|
||||
|
||||
Each element in the returned array is a value between -1.0 and 1.0.
|
||||
|
||||
|
||||
@subsection input_joy_button Joystick button states
|
||||
|
||||
The states of all buttons of a joystick are returned by @ref
|
||||
glfwGetJoystickButtons. See the reference documentation for the lifetime of the
|
||||
returned array.
|
||||
|
||||
@code
|
||||
int count;
|
||||
const unsigned char* axes = glfwGetJoystickButtons(GLFW_JOYSTICK_1, &count);
|
||||
@endcode
|
||||
|
||||
Each element in the returned array is either `GLFW_PRESS` or `GLFW_RELEASE`.
|
||||
|
||||
|
||||
@subsection input_joy_name Joystick name
|
||||
|
||||
The human-readable, UTF-8 encoded name of a joystick is returned by @ref
|
||||
glfwGetJoystickName. See the reference documentation for the lifetime of the
|
||||
returned string.
|
||||
|
||||
@code
|
||||
const char* name = glfwGetJoystickName(GLFW_JOYSTICK_1);
|
||||
@endcode
|
||||
|
||||
Joystick names are not guaranteed to be unique. Two joysticks of the same model
|
||||
and make may have the same name. Only the [joystick token](@ref joysticks) is
|
||||
guaranteed to be unique, and only until that joystick is disconnected.
|
||||
|
||||
|
||||
@section input_time Time input
|
||||
|
||||
GLFW provides high-resolution time input, in seconds, with @ref glfwGetTime.
|
||||
|
||||
@code
|
||||
double seconds = glfwGetTime();
|
||||
@endcode
|
||||
|
||||
It returns the number of seconds since the timer was started when the library
|
||||
was initialized with @ref glfwInit. The platform-specific time sources used
|
||||
usually have micro- or nanosecond resolution.
|
||||
|
||||
You can modify the reference time with @ref glfwSetTime.
|
||||
|
||||
@code
|
||||
glfwSetTime(4.0);
|
||||
@endcode
|
||||
|
||||
This sets the timer to the specified time, in seconds.
|
||||
|
||||
|
||||
@section input_clipboard Clipboard input and output
|
||||
|
||||
If the system clipboard contains a UTF-8 encoded string or if it can be
|
||||
converted to one, you can retrieve it with @ref glfwGetClipboardString. See the
|
||||
reference documentation for the lifetime of the returned string.
|
||||
|
||||
@code
|
||||
const char* clipboard = glfwGetClipboardString(window);
|
||||
@endcode
|
||||
|
||||
The contents of the system clipboard can be set to a UTF-8 encoded string with
|
||||
@ref glfwSetClipboardString.
|
||||
|
||||
@code
|
||||
glfwSetClipboardString(window, "A string with words in it");
|
||||
@endcode
|
||||
|
||||
The clipboard functions take a window handle argument because some window
|
||||
systems require a window to communicate with the system clipboard. Any valid
|
||||
window may be used.
|
||||
|
||||
|
||||
@section input_drop Path drop input
|
||||
|
||||
If you wish to receive the paths of files and/or directories dropped on
|
||||
a window, set a file drop callback with @ref glfwSetDropCallback.
|
||||
|
||||
@code
|
||||
glfwSetDropCallback(window, drop_callback);
|
||||
@endcode
|
||||
|
||||
The callback function receives an array of paths encoded as UTF-8.
|
||||
|
||||
@code
|
||||
void drop_callback(GLFWwindow* window, int count, const char** paths)
|
||||
{
|
||||
int i;
|
||||
for (i = 0; i < count; i++)
|
||||
handle_dropped_file(paths[i]);
|
||||
}
|
||||
@endcode
|
||||
|
||||
The path array and its strings are only valid until the file drop callback
|
||||
returns, as they may have been generated specifically for that event. You need
|
||||
to make a deep copy of the array if you want to keep the paths.
|
||||
|
||||
*/
|
||||
|
||||
Reference in New Issue
Block a user