#

## ClanLib Input

### Handling input

Main classes: CL_InputContext, CL_InputDevice, CL_InputEvent, CL_InputBuffer.

There are two ways to deal with input from the user; via events generated by the operating system, or by polling the input devices. Access to both polling and event handlers hookups is provided by the CL_InputContext class, available from CL_DisplayWindow::get_ic(), as shown earlier.

The CL_InputContext class is a container for all the different types of input devices available from a window, categorized as either keyboards, mice or joysticks (game controllers). Here's an example of getting the input device for common devices:

    	CL_DisplayWindow window("My ClanLib Window", 640, 480);
    	CL_InputContext *ic = window.get_ic();
    	CL_InputDevice keyboard = ic->get_keyboard();
    	CL_InputDevice mouse = ic->get_mouse();
    	CL_InputDevice joystick = ic->get_joystick();

CL_InputDevice is an abstraction for any input device type. It has a set of polling functions for both keyboards, mice and joysticks:

    	bool space_down = keyboard.get_keycode(CL_KEY_SPACE);
    	std::string name_of_space = keyboard.get_key_name(CL_KEY_SPACE);
    	int mouse_x = mouse.get_x();
    	int mouse_y = mouse.get_y();
    	float axis_x = joystick.get_axis(0);
    	float axis_y = joystick.get_axis(1);

In addition to the polling functions, CL_InputDevice also has a list of signals that are emitted when ClanLib receives input events for the specific device. When any of those events occur, a CL_InputEvent is passed along to any slot listening for that event. Here's an example of a handler routine listening for key down events from the keyboard:

    	CL_Slot slot_key_down;

    	void setup_slot(CL_InputContext *ic)
    	{
    		CL_InputDevice keyboard = ic->get_keyboard();
    		slot_key_down = keyboard.sig_key_down().connect(&on_key_down);
    	}

    	void on_key_down(const CL_InputEvent &event)
    	{
    		std::cout << "User pressed: " << event.str.c_str() << std::endl;
    	}

Note: ClanLib only polls the operating system for new events when you call CL_System::keep_alive(), so make sure you call that at least once a frame.

CL_InputBuffer is a class that helps you capture keyboard press events and convert them into a poll-able buffer. This is useful if you want to avoid setting up an event handler when you want the user to enter a string of text:

    	CL_InputBuffer buffer(keyboard);
    	bool quit = false;
    	std::string text;
    	while (!quit)
    	{
    		while (buffer.keys_left() > 0)
    		{
    			CL_InputEvent key = buffer.pop_key();
    			if (key.type != CL_InputEvent::pressed) continue;
    			if (key.id == CL_KEY_ENTER)
    			{
    				quit = true;
    				break;
    			}
    			else
    			{
    				text += key.str;
    			}
    		}

    		draw_gfx(text);
    		window.flip();
    		CL_System::keep_alive();
    	}
    	std::cout << "User wrote: " << text.c_str() << std::endl;

### Keycodes

The following table shows the keycodes available for ClanLib. Codes that start with CL_KEY are for use with the CL_Keyboard class, and codes that start with CL_MOUSE are for use with the CL_Mouse class:

CL_MOUSE_LEFT | CL_MOUSE_RIGHT | CL_MOUSE_MIDDLE | CL_MOUSE_WHEEL_UP | CL_MOUSE_WHEEL_DOWN
CL_MOUSE_XBUTTON1 | CL_MOUSE_XBUTTON2 | CL_KEY_BACKSPACE | CL_KEY_TAB | CL_KEY_CLEAR
CL_KEY_RETURN | CL_KEY_SHIFT | CL_KEY_CONTROL | CL_KEY_MENU | CL_KEY_PAUSE
CL_KEY_ESCAPE | CL_KEY_SPACE | CL_KEY_PRIOR | CL_KEY_NEXT | CL_KEY_END
CL_KEY_HOME | CL_KEY_LEFT | CL_KEY_UP | CL_KEY_RIGHT | CL_KEY_DOWN
CL_KEY_SELECT | CL_KEY_PRINT | CL_KEY_EXECUTE | CL_KEY_INSERT | CL_KEY_DELETE
CL_KEY_HELP | CL_KEY_0 | CL_KEY_1 | CL_KEY_2 | CL_KEY_3
CL_KEY_4 | CL_KEY_5 | CL_KEY_6 | CL_KEY_7 | CL_KEY_8
CL_KEY_9 | CL_KEY_A | CL_KEY_B | CL_KEY_C | CL_KEY_D
CL_KEY_E | CL_KEY_F | CL_KEY_G | CL_KEY_H | CL_KEY_I
CL_KEY_J | CL_KEY_K | CL_KEY_L | CL_KEY_M | CL_KEY_N
CL_KEY_O | CL_KEY_P | CL_KEY_Q | CL_KEY_R | CL_KEY_S
CL_KEY_T | CL_KEY_U | CL_KEY_V | CL_KEY_W | CL_KEY_X
CL_KEY_Y | CL_KEY_Z | CL_KEY_LWIN | CL_KEY_RWIN | CL_KEY_APPS
CL_KEY_NUMPAD0 | CL_KEY_NUMPAD1 | CL_KEY_NUMPAD2 | CL_KEY_NUMPAD3 | CL_KEY_NUMPAD4
CL_KEY_NUMPAD5 | CL_KEY_NUMPAD6 | CL_KEY_NUMPAD7 | CL_KEY_NUMPAD8 | CL_KEY_NUMPAD9
CL_KEY_MULTIPLY | CL_KEY_ADD | CL_KEY_SEPARATOR | CL_KEY_SUBTRACT | CL_KEY_DECIMAL
CL_KEY_DIVIDE | CL_KEY_F1 | CL_KEY_F2 | CL_KEY_F3 | CL_KEY_F4
CL_KEY_F5 | CL_KEY_F6 | CL_KEY_F7 | CL_KEY_F8 | CL_KEY_F9
CL_KEY_F10 | CL_KEY_F11 | CL_KEY_F12 | CL_KEY_F13 | CL_KEY_F14
CL_KEY_F15 | CL_KEY_F16 | CL_KEY_F17 | CL_KEY_F18 | CL_KEY_F19
CL_KEY_F20 | CL_KEY_F21 | CL_KEY_F22 | CL_KEY_F23 | CL_KEY_F24
CL_KEY_NUMLOCK | CL_KEY_SCROLL | CL_KEY_LSHIFT | CL_KEY_RSHIFT | CL_KEY_LCONTROL
CL_KEY_RCONTROL | CL_KEY_LMENU | CL_KEY_RMENU

Questions or comments, write to the ClanLib mailing list.