User Input

Input in ClanLib is accessed via a clan::InputContext object, which is usually acquired from a clan::DisplayWindow object. The input context interface is a container holding one or more clan::InputDevice objects, each acting as either a keyboard, mouse, joystick or tablet source. The input device interface provides access to various polling functions or signal callbacks, which are invoked when ClanLib receives these input messages.

The following example shows how to get the input devices for the first keyboard, mouse and joystick:

clan::DisplayWindow window(640, 480, "Hello Input");
clan::InputContext ic = window.get_ic();

Polling a device is fairly simple and straight forward (just call the appropriate functions), but the actual state of an input device does not always update immediately - in some cases they are updated based on input messages received from the underlying windowing system, which means that they will not update until you have made a call to clan::KeepAlive::process(). The following code correctly polls for hitting escape to quit the loop:

clan::DisplayWindow window(640, 480, "Hello Input");
clan::InputContext ic = window.get_ic();
while (true)
{
bool escape_down = keyboard.get_keycode(clan::KEY_ESCAPE);
if (escape_down)
break;
clan::KeepAlive::process();
window.get_gc().clear(clan::Color::white);
window.flip();
}

An alternative to polling input devices is to set up callback functions that get invoked whenever an input event occurs. To do this, simply connect a slot function to the signal you want to listen in on:

bool quit = false;
void my_callback(const clan::InputEvent &event, const clan::InputState &state)
{
if (event.id == clan::KEY_ESCAPE)
quit = true;
}
int main(int, char**)
{
try
{
clan::SetupCore setup_core;
clan::SetupDisplay setup_display;
clan::SetupGL setup_gl;
clan::DisplayWindow window(640, 480, "Hello Input");
clan::InputContext ic = window.get_ic();
clan::Slot slot = keyboard.sig_key_up().connect(&my_callback);
while (!quit)
{
clan::KeepAlive::process();
window.get_gc().clear(clan::Color::white);
window.flip();
}
}
catch(clan::Exception &exception)
{
// Create a console window for text-output if not available
clan::ConsoleWindow console("Console", 80, 160);
clan::Console::write_line("Exception caught: " + exception.get_message_and_stack_trace());
console.display_close_message();
return -1;
}
return 0;
}
bool get_keycode(int keycode) const
Returns true if the passed key code is down for this device. See keys.h for list of key codes.
Input event class.
Definition: input_event.h:44
InputDevice.
Definition: input_device.h:48
Text console window.
Definition: console_window.h:44
Signal< void(const InputEvent &)> & sig_key_up()
Signal emitted when key is released.
InputDevice & get_mouse(int mouse=0)
Returns the input device for the specified mouse.
InputContext.
Definition: input_context.h:45
static void sleep(int millis)
Sleep for 'millis' milliseconds.
Definition: signal.h:44
static void write_line(const std::string &text)
Writes text to the console window and then advances to a new line.
Definition: console.h:196
InputCode id
The exact input.
Definition: input_event.h:79
static Color white
Definition: color.h:568
InputDevice & get_joystick(int joystick=0)
Returns the input device for the specified joystick.
Top-level exception class.
Definition: exception.h:43
InputDevice & get_keyboard(int keyboard=0)
Returns the input device for the specified keyboard.
std::string get_message_and_stack_trace() const
Returns the message and call stack present when the exception object was created, formatted using new...
Top-level window class.
Definition: display_window.h:102