GLFW provides many kinds of input. While some can only be polled, like time, or only received via callbacks, like scrolling, many provide both callbacks and polling. Callbacks are more work to use than polling but is less CPU intensive and guarantees that you do not miss state changes.

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 poll the window system for events both to provide input to the application and to prove to the window system that the application hasn't locked up. Event processing 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 and joystick connection events.

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

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 or other tasks that need periodic updates, glfwWaitEventsTimeout lets you specify a timeout.

Do not assume that callbacks will only be called in response to the above functions. While it is necessary to process events in one or more of the ways above, window systems that require GLFW to register callbacks of its own can pass events to GLFW in response to many window system function calls. GLFW will pass those events on to the application callbacks before returning.

For example, on Windows the system function that glfwSetWindowSize is implemented with will send window size events directly to the event callback that every window has and that GLFW implements for its windows. If you have set a window size callback GLFW will call it in turn with the new size before everything returns back out of the glfwSetWindowSize call.

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.

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. You can query the scancode for any named key on the current platform with glfwGetKeyScancode.

This function only returns cached key event state. It does not poll the system for the current physical 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.

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.

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

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.

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.

Cursor mode

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 only wish the cursor to become hidden when it is over a window but still want it to behave normally, set the cursor mode to GLFW_CURSOR_HIDDEN.

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 with the red channel first. The pixels are arranged canonically as sequential rows, starting from the top-left corner.

Cursor destruction

Cursor destruction always succeeds. If the cursor is current for any window, that window will revert to the default cursor. This does not affect the cursor mode. All remaining cursors remaining are destroyed when glfwTerminate is called.

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.

A normal 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 and including GLFW_JOYSTICK_16 or 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. Once a joystick is detected, it keeps its assigned ID until it is disconnected or the library is terminated, so as joysticks are connected and disconnected, there may appear gaps in the IDs.

Joystick axis, button and hat state is updated when polled and does not require a window to be created or events to be processed. However, if you want joystick connection and disconnection events reliably delivered to the joystick callback then you must process events.

To see all the properties of all connected joysticks in real-time, run the joysticks test program.

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.

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

For backward compatibility with earlier versions that did not have glfwGetJoystickHats, the button array by default also includes all hats. See the reference documentation for glfwGetJoystickButtons for details.

Joystick hat states

The states of all hats are returned by glfwGetJoystickHats. See the reference documentation for the lifetime of the returned array.

For backward compatibility with earlier versions that did not have glfwGetJoystickHats, all hats are by default also included in the button array. See the reference documentation for glfwGetJoystickButtons for details.

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.

For joystick connection and disconnection events to be delivered on all platforms, you need to call one of the event processing functions. Joystick disconnection may also be detected and the callback called by joystick functions. The function will then return whatever it returns for a disconnected joystick.

Gamepad input

The joystick functions provide unlabeled axes, buttons and hats, with no indication of where they are located on the device. Their order may also vary between platforms even with the same device.

To solve this problem the SDL community crowdsourced the SDL_GameControllerDB project, a database of mappings from many different devices to an Xbox-like gamepad.

GLFW supports this mapping format and contains a copy of the mappings available at the time of release. See Gamepad mappings for how to update this at runtime. Mappings will be assigned to joysticks automatically any time a joystick is connected or the mappings are updated.

The GLFWgamepadstate struct has two arrays; one for button states and one for axis states. The values for each button and axis are the same as for the glfwGetJoystickButtons and glfwGetJoystickAxes functions, i.e. GLFW_PRESS or GLFW_RELEASE for buttons and -1.0 to 1.0 inclusive for axes.

The sizes of the arrays and the positions within each array are fixed.

For those who prefer, there are also the GLFW_GAMEPAD_BUTTON_CROSS, GLFW_GAMEPAD_BUTTON_CIRCLE, GLFW_GAMEPAD_BUTTON_SQUARE and GLFW_GAMEPAD_BUTTON_TRIANGLE aliases for the A, B, X and Y button indices.

This function supports everything from single lines up to and including the unmodified contents of the whole gamecontrollerdb.txt file.

Below is a description of the mapping format. Please keep in mind that this description is not authoritative. The format is defined by the SDL and SDL_GameControllerDB projects and their documentation and code takes precedence.

Each mapping is a single line of comma-separated values describing the GUID, name and layout of the gamepad. Lines that do not begin with a hexadecimal digit are ignored.

The first value is always the gamepad GUID, a 32 character long hexadecimal string that typically identifies its make, model, revision and the type of connection to the computer. When this information is not available, the GUID is generated using the gamepad name. GLFW uses the SDL 2.0.5+ GUID format but can convert from the older formats.

The second value is always the human-readable name of the gamepad.

All subsequent values are in the form <field>:<value> and describe the layout of the mapping. These fields may not all be present and may occur in any order.

The value of an axis or button field can be a joystick button, a joystick axis, a hat bitmask or empty. Joystick buttons are specified as bN, for example b2 for the third button. Joystick axes are specified as aN, for example a7 for the eighth button. Joystick hat bit masks are specified as hN.N, for example h0.8 for left on the first hat. More than one bit may be set in the mask.

There is also the special platform field that specifies which platform the mapping is valid for. Possible values are Windows, Mac OS X and Linux.

Below is an example of what a gamepad mapping might look like. It is the one built into GLFW for Xbox controllers accessed via the XInput API on Windows. This example has been broken into several lines to fit on the page, but real gamepad mappings must be a single line.

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.

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.