Keyboard, mouse and joystick

Introduction

This tutorial explains how to access global inputs: keyboard, mouse and joysticks. This must not be confused with events: real-time inputs allow you to query the global state of keyboard, mouse and joysticks at any time ("is this button currently pressed?", "where is the mouse?") while events notify you when something happens ("this button was pressed", "the mouse has moved").

Keyboard

The class that gives access to the keyboard state is sf::Keyboard. It contains only one function, isKeyPressed, which checks the current state of a key (pressed or released). It is a static function, so you don't need to instanciate sf::Keyboard to use it.

This function directly reads the keyboard state, ignoring the focus state of your window. This means that isKeyPressed may return true even if your window is inactive.

if (sf::Keyboard::isKeyPressed(sf::Keyboard::Left))
{
    // left key is pressed: move our character
    character.move(1, 0);
}

Key codes are defined in the sf::Keyboard::Key enum.

Some key codes may be missing, or interpreted incorrectly depending on your OS and keyboard layout. This is something that will be improved in a future version of SFML.

Mouse

The class that gives access to the mouse state is sf::Mouse. Like its friend sf::Keyboard, sf::Mouse contains only static functions and is not meant to be instanciated (SFML only handles a single mouse for the time being).

You can check if buttons are pressed:

if (sf::Mouse::isButtonPressed(sf::Mouse::Left))
{
    // left mouse button is pressed: shoot
    gun.fire();
}

Mouse button codes are defined in the sf::Mouse::Button enum. SFML supports up to 5 buttons: left, right, middle (wheel), plus two extra buttons whatever they are.

You can also get and set the current position of the mouse, either relatively to the desktop or to a window:

// get the global mouse position (relatively to the desktop)
sf::Vector2i globalPosition = sf::Mouse::getPosition();

// get the local mouse position (relatively to a window)
sf::Vector2i localPosition = sf::Mouse::getPosition(window); // window is a sf::Window
// set the mouse position globally (relatively to the desktop)
sf::Mouse::setPosition(sf::Vector2i(10, 50));

// set the mouse position localy (relatively to a window)
sf::Mouse::setPosition(sf::Vector2i(10, 50), window); // window is a sf::Window

There's no function for reading the current state of the mouse wheel. Indeed, the wheel can only be moved relatively, and has no absolute state. By looking at a key you can tell whether it's pressed or released ; by looking at the mouse cursor you can tell where it is located on the screen ; but by looking at the mouse wheel you can't tell which "tick" it is on. You can only be notified when it moves (MouseWheelMoved event).

Joystick

The class that gives access to the joysticks state is sf::Joystick. Like the other classes of this tutorial, it contains static functions only.

Joysticks are identified by their index (0 to 7, since SFML supports up to 8 joysticks). Therefore, the first argument of every function of sf::Joystick is the index of the joystick that you want to query.

You can check whether a joystick is connected or not:

if (sf::Joystick::isConnected(0))
{
    // joystick number 0 is connected
    ...
}

You can also get the capabilities of a connected joystick:

// check how many buttons joystick number 0 has
unsigned int buttonCount = sf::Joystick::getButtonCount(0);

// check if joystick number 0 has a Z axis
bool hasZ = sf::Joystick::hasAxis(0, sf::Joystick::Z);

Joystick axes are defined in the sf::Joystick::Axis enum. Since they have no special meaning, buttons are simply numbered from 0 to 31.

Finally, you can of course query the state of a joystick's axes and buttons:

// is button 1 of joystick number 0 pressed?
if (sf::Joystick::isButtonPressed(0, 1))
{
    // yes: shoot!
    gun.fire();
}

// what's the current position of the X and Y axes of joystick number 0?
float x = sf::Joystick::getAxisPosition(0, sf::Joystick::X);
float y = sf::Joystick::getAxisPosition(0, sf::Joystick::Y);
character.move(x, y);

Joystick states are automatically updated by the event loop. If you don't have one, or need to read a joystick state (for example, check which joysticks are connected) before starting your game loop, you'll have to call the sf::Joystick::update() function to make sure that the joystick states are up to date.