Input guide

This guide introduces the input related functions of GLFW. For details on a specific function in this category, see the Input reference. There are also guides for the other areas of GLFW.

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, 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.

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 any windows and is normally done each frame after buffer swapping. Even when you have no windows, event polling needs to be done in order to receive monitor connection events.

There are two functions for processing pending events. glfwPollEvents, processes only those events that have already been received and then returns immediately.

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, glfwWaitEvents is a better choice.

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 you want to wait for events but have UI elements that need periodic updates, call glfwWaitEventsTimeout.

It puts the thread to sleep until at least one event has been received, or until the specified number of seconds have elapsed. It then processes any received events.

If the main thread is sleeping in glfwWaitEvents, you can wake it from another thread by posting an empty event to the event queue with glfwPostEmptyEvent.

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.

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.

Key input

If you wish to be notified when a physical key is pressed or released or when it repeats, set a key callback.

glfwSetKeyCallback(window, key_callback);

The callback function receives the keyboard key, platform-specific scancode, key action and modifier bits.

void key_callback(GLFWwindow* window, int key, int scancode, int action, int mods)
{
if (key == GLFW_KEY_E && action == GLFW_PRESS)
activate_airship();
}

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, for example E-mail and Play 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.

Key states for named keys are also saved in per-window state arrays that can be polled with glfwGetKey.

int state = glfwGetKey(window, GLFW_KEY_E);
if (state == GLFW_PRESS)
activate_airship();

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.

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 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.

Text input

GLFW supports text input in the form of a stream of Unicode code points, 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 dead keys. Once received, you can encode the code points into UTF-8 or any other encoding you prefer.

Because an unsigned int is 32 bits long on all platforms supported by GLFW, you can treat the code point argument as native endian UTF-32.

There are two callbacks for receiving Unicode code points. If you wish to offer regular text input, set a character callback.

glfwSetCharCallback(window, character_callback);

The callback function receives Unicode code points for key events that would have led to regular text input and generally behaves as a standard text field on that platform.

void character_callback(GLFWwindow* window, unsigned int codepoint)
{
}

If you wish to receive even those Unicode code points generated with modifier key combinations that a plain text field would ignore, or just want to know exactly what modifier keys were used, set a character with modifiers callback.

glfwSetCharModsCallback(window, charmods_callback);

The callback function receives Unicode code points and modifier bits.

void charmods_callback(GLFWwindow* window, unsigned int codepoint, int mods)
{
}

Key names

If you wish to refer to keys by name, you can query the keyboard layout dependent name of printable keys with glfwGetKeyName.

const char* key_name = glfwGetKeyName(GLFW_KEY_W, 0);
show_tutorial_hint("Press %s to move forward", key_name);

This function can handle both keys and scancodes. If the specified key is GLFW_KEY_UNKNOWN then the scancode is used, otherwise it is ignored. This matches the behavior of the key callback, meaning the callback arguments can always be passed unmodified to this function.

Mouse input

Mouse input comes in many forms, including cursor motion, button presses and scrolling offsets. The cursor appearance can also be changed, either to a custom image or a standard cursor shape from the system theme.

Cursor position

If you wish to be notified when the cursor moves over the window, set a cursor position callback.

glfwSetCursorPosCallback(window, cursor_pos_callback);

The callback functions receives the cursor position, measured in screen coordinates but relative to the top-left corner of the window client area. On platforms that provide it, the full sub-pixel cursor position is passed on.

static void cursor_position_callback(GLFWwindow* window, double xpos, double ypos)
{
}

The cursor position is also saved per-window and can be polled with glfwGetCursorPos.

double xpos, ypos;
glfwGetCursorPos(window, &xpos, &ypos);

Cursor modes

The GLFW_CURSOR input mode provides several cursor modes for special forms of mouse motion input. By default, the cursor mode is GLFW_CURSOR_NORMAL, meaning the regular arrow cursor (or another cursor set with glfwSetCursor) 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.

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 via both the cursor position callback and through polling.

Note
You should not implement your own version of this functionality using other features of GLFW. It is not supported and will not work as robustly as GLFW_CURSOR_DISABLED.

If you just wish the cursor to become hidden when it is over a window, set the cursor mode to GLFW_CURSOR_HIDDEN.

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.

Cursor objects

GLFW supports creating both custom and system theme cursor images, encapsulated as GLFWcursor objects. They are created with glfwCreateCursor or glfwCreateStandardCursor and destroyed with glfwDestroyCursor, or glfwTerminate, if any remain.

Custom cursor creation

A custom cursor is created with 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:

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);

If cursor creation fails, NULL will be returned, so it is necessary to check the return value.

The image data is 32-bit, little-endian, non-premultiplied RGBA, i.e. eight bits per channel. The pixels are arranged canonically as sequential rows, starting from the top-left corner.

Standard cursor creation

A cursor with a standard shape from the current system cursor theme can be can be created with glfwCreateStandardCursor.

These cursor objects behave in the exact same way as those created with glfwCreateCursor except that the system cursor theme provides the actual image.

Cursor destruction

When a cursor is no longer needed, destroy it with glfwDestroyCursor.

Cursor destruction always succeeds. All cursors remaining when glfwTerminate is called are destroyed as well.

Cursor setting

A cursor can be set as current for a window with glfwSetCursor.

glfwSetCursor(window, cursor);

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 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.

glfwSetCursor(window, NULL);

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.

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.

glfwSetCursorEnterCallback(window, cursor_enter_callback);

The callback function receives the new classification of the cursor.

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
}
}

Mouse button input

If you wish to be notified when a mouse button is pressed or released, set a mouse button callback.

glfwSetMouseButtonCallback(window, mouse_button_callback);

The callback function receives the mouse button, button action and modifier bits.

void mouse_button_callback(GLFWwindow* window, int button, int action, int mods)
{
if (button == GLFW_MOUSE_BUTTON_RIGHT && action == GLFW_PRESS)
popup_menu();
}

The action is one of GLFW_PRESS or GLFW_RELEASE.

Mouse button states for named buttons are also saved in per-window state arrays that can be polled with glfwGetMouseButton.

if (state == GLFW_PRESS)
upgrade_cow();

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.

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 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.

Scroll input

If you wish to be notified when the user scrolls, whether with a mouse wheel or touchpad gesture, set a scroll callback.

glfwSetScrollCallback(window, scroll_callback);

The callback function receives two-dimensional scroll offsets.

void scroll_callback(GLFWwindow* window, double xoffset, double yoffset)
{
}

A simple mouse wheel, being vertical, provides offsets along the Y-axis.

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 is present with glfwJoystickPresent.

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 glfwPollEvents or glfwWaitEvents to be called.

Joystick axis states

The positions of all axes of a joystick are returned by glfwGetJoystickAxes. See the reference documentation for the lifetime of the returned array.

int count;
const float* axes = glfwGetJoystickAxes(GLFW_JOYSTICK_1, &count);

Each element in the returned array is a value between -1.0 and 1.0.

Joystick button states

The states of all buttons of a joystick are returned by glfwGetJoystickButtons. See the reference documentation for the lifetime of the returned array.

int count;
const unsigned char* axes = glfwGetJoystickButtons(GLFW_JOYSTICK_1, &count);

Each element in the returned array is either GLFW_PRESS or GLFW_RELEASE.

Joystick name

The human-readable, UTF-8 encoded name of a joystick is returned by glfwGetJoystickName. See the reference documentation for the lifetime of the returned string.

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 is guaranteed to be unique, and only until that joystick is disconnected.

Joystick configuration changes

If you wish to be notified when a joystick is connected or disconnected, set a joystick callback.

glfwSetJoystickCallback(joystick_callback);

The callback function receives the ID of the joystick that has been connected and disconnected and the event that occurred.

void joystick_callback(int joy, int event)
{
if (event == GLFW_CONNECTED)
{
// The joystick was connected
}
else if (event == GLFW_DISCONNECTED)
{
// The joystick was disconnected
}
}

Time input

GLFW provides high-resolution time input, in seconds, with glfwGetTime.

double seconds = glfwGetTime();

It returns the number of seconds since the timer was started when the library was initialized with glfwInit. The platform-specific time sources used usually have micro- or nanosecond resolution.

You can modify the reference time with glfwSetTime.

This sets the timer to the specified time, in seconds.

You can also access the raw timer value, measured in 1 / frequency seconds, with glfwGetTimerValue.

uint64_t value = glfwGetTimerValue();

The frequency of the raw timer varies depending on what time sources are available on the machine. You can query its frequency, in Hz, with glfwGetTimerFrequency.

uint64_t freqency = glfwGetTimerFrequency();

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 glfwGetClipboardString. See the reference documentation for the lifetime of the returned string.

const char* text = glfwGetClipboardString(window);
if (text)
insert_text(text);

If the clipboard is empty or if its contents could not be converted, NULL is returned.

The contents of the system clipboard can be set to a UTF-8 encoded string with glfwSetClipboardString.

glfwSetClipboardString(window, "A string with words in it");

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.

Path drop input

If you wish to receive the paths of files and/or directories dropped on a window, set a file drop callback.

glfwSetDropCallback(window, drop_callback);

The callback function receives an array of paths encoded as UTF-8.

void drop_callback(GLFWwindow* window, int count, const char** paths)
{
int i;
for (i = 0; i < count; i++)
handle_dropped_file(paths[i]);
}

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.

glfwGetJoystickAxes
const float * glfwGetJoystickAxes(int joy, int *count)
Returns the values of all axes of the specified joystick.
GLFW_CURSOR_DISABLED
#define GLFW_CURSOR_DISABLED
Definition: glfw3.h:681
GLFW_CURSOR_NORMAL
#define GLFW_CURSOR_NORMAL
Definition: glfw3.h:679
GLFW_CURSOR
#define GLFW_CURSOR
Definition: glfw3.h:675
GLFW_CURSOR_HIDDEN
#define GLFW_CURSOR_HIDDEN
Definition: glfw3.h:680
GLFW_STICKY_KEYS
#define GLFW_STICKY_KEYS
Definition: glfw3.h:676
glfwGetTime
double glfwGetTime(void)
Returns the value of the GLFW timer.
glfwSetCursorPosCallback
GLFWcursorposfun glfwSetCursorPosCallback(GLFWwindow *window, GLFWcursorposfun cbfun)
Sets the cursor position callback.
glfwGetMouseButton
int glfwGetMouseButton(GLFWwindow *window, int button)
Returns the last reported state of a mouse button for the specified window.
glfwCreateCursor
GLFWcursor * glfwCreateCursor(const GLFWimage *image, int xhot, int yhot)
Creates a custom cursor.
GLFW_PRESS
#define GLFW_PRESS
The key or mouse button was pressed.
Definition: glfw3.h:268
glfwGetKeyName
const char * glfwGetKeyName(int key, int scancode)
Returns the localized name of the specified printable key.
GLFWimage::height
int height
Definition: glfw3.h:1200
glfwSetInputMode
void glfwSetInputMode(GLFWwindow *window, int mode, int value)
Sets an input option for the specified window.
GLFWwindow
struct GLFWwindow GLFWwindow
Opaque window object.
Definition: glfw3.h:789
GLFW_KEY_W
#define GLFW_KEY_W
Definition: glfw3.h:345
GLFW_KEY_E
#define GLFW_KEY_E
Definition: glfw3.h:327
glfwJoystickPresent
int glfwJoystickPresent(int joy)
Returns whether the specified joystick is present.
glfwGetJoystickName
const char * glfwGetJoystickName(int joy)
Returns the name of the specified joystick.
glfwSetJoystickCallback
GLFWjoystickfun glfwSetJoystickCallback(GLFWjoystickfun cbfun)
Sets the joystick configuration callback.
GLFW_JOYSTICK_1
#define GLFW_JOYSTICK_1
Definition: glfw3.h:480
glfwSetTime
void glfwSetTime(double time)
Sets the GLFW timer.
glfwGetCursorPos
void glfwGetCursorPos(GLFWwindow *window, double *xpos, double *ypos)
Retrieves the position of the cursor relative to the client area of the window.
glfwPollEvents
void glfwPollEvents(void)
Processes all pending events.
glfwWaitEvents
void glfwWaitEvents(void)
Waits until events are queued and processes them.
glfwDestroyCursor
void glfwDestroyCursor(GLFWcursor *cursor)
Destroys a cursor.
GLFW_STICKY_MOUSE_BUTTONS
#define GLFW_STICKY_MOUSE_BUTTONS
Definition: glfw3.h:677
glfwGetClipboardString
const char * glfwGetClipboardString(GLFWwindow *window)
Returns the contents of the clipboard as a string.
glfwSetCursor
void glfwSetCursor(GLFWwindow *window, GLFWcursor *cursor)
Sets the cursor for the window.
GLFWimage::pixels
unsigned char * pixels
Definition: glfw3.h:1203
glfwSetKeyCallback
GLFWkeyfun glfwSetKeyCallback(GLFWwindow *window, GLFWkeyfun cbfun)
Sets the key callback.
GLFW_DISCONNECTED
#define GLFW_DISCONNECTED
Definition: glfw3.h:730
glfwSetScrollCallback
GLFWscrollfun glfwSetScrollCallback(GLFWwindow *window, GLFWscrollfun cbfun)
Sets the scroll callback.
glfwSetDropCallback
GLFWdropfun glfwSetDropCallback(GLFWwindow *window, GLFWdropfun cbfun)
Sets the file drop callback.
glfwGetTimerValue
uint64_t glfwGetTimerValue(void)
Returns the current value of the raw timer.
glfwGetTimerFrequency
uint64_t glfwGetTimerFrequency(void)
Returns the frequency, in Hz, of the raw timer.
GLFW_MOUSE_BUTTON_LEFT
#define GLFW_MOUSE_BUTTON_LEFT
Definition: glfw3.h:469
glfwGetJoystickButtons
const unsigned char * glfwGetJoystickButtons(int joy, int *count)
Returns the state of all buttons of the specified joystick.
GLFWimage::width
int width
Definition: glfw3.h:1197
glfwSetMouseButtonCallback
GLFWmousebuttonfun glfwSetMouseButtonCallback(GLFWwindow *window, GLFWmousebuttonfun cbfun)
Sets the mouse button callback.
glfwWaitEventsTimeout
void glfwWaitEventsTimeout(double timeout)
Waits with timeout until events are queued and processes them.
glfwSetCursorEnterCallback
GLFWcursorenterfun glfwSetCursorEnterCallback(GLFWwindow *window, GLFWcursorenterfun cbfun)
Sets the cursor enter/exit callback.
GLFWcursor
struct GLFWcursor GLFWcursor
Opaque cursor object.
Definition: glfw3.h:801
glfwCreateStandardCursor
GLFWcursor * glfwCreateStandardCursor(int shape)
Creates a cursor with a standard shape.
GLFWimage
Image data.
Definition: glfw3.h:1194
GLFW_HRESIZE_CURSOR
#define GLFW_HRESIZE_CURSOR
The horizontal resize arrow shape.
Definition: glfw3.h:721
GLFW_CONNECTED
#define GLFW_CONNECTED
Definition: glfw3.h:729
GLFW_MOUSE_BUTTON_RIGHT
#define GLFW_MOUSE_BUTTON_RIGHT
Definition: glfw3.h:470
glfwPostEmptyEvent
void glfwPostEmptyEvent(void)
Posts an empty event to the event queue.
glfwGetKey
int glfwGetKey(GLFWwindow *window, int key)
Returns the last reported state of a keyboard key for the specified window.
glfwSetCharModsCallback
GLFWcharmodsfun glfwSetCharModsCallback(GLFWwindow *window, GLFWcharmodsfun cbfun)
Sets the Unicode character with modifiers callback.
glfwSetClipboardString
void glfwSetClipboardString(GLFWwindow *window, const char *string)
Sets the clipboard to the specified string.
glfwSetCharCallback
GLFWcharfun glfwSetCharCallback(GLFWwindow *window, GLFWcharfun cbfun)
Sets the Unicode character callback.