| 1 |
<xml> |
| 2 |
<head> |
| 3 |
<title>ClanLib Input</title> |
| 4 |
<eyecolor>yellow</eyecolor> |
| 5 |
</head> |
| 6 |
<body> |
| 7 |
|
| 8 |
<h3>Handling input</h3> |
| 9 |
<p>Main classes: <codelink>CL_InputContext</codelink>, |
| 10 |
<codelink>CL_InputDevice</codelink>, <codelink>CL_InputEvent</codelink>, |
| 11 |
<codelink>CL_InputBuffer</codelink>.</p> |
| 12 |
|
| 13 |
<p>There are two ways to deal with input from the user; via events generated |
| 14 |
by the operating system, or by polling the input devices. Access to both |
| 15 |
polling and event handlers hookups is provided by the CL_InputContext |
| 16 |
class, available from CL_DisplayWindow::get_ic(), as shown earlier.</p> |
| 17 |
|
| 18 |
<p>The CL_InputContext class is a container for all the different types of |
| 19 |
input devices available from a window, categorized as either keyboards, mice |
| 20 |
or joysticks (game controllers). Here's an example of getting the input device for |
| 21 |
common devices:</p> |
| 22 |
|
| 23 |
<code> |
| 24 |
CL_DisplayWindow window("My ClanLib Window", 640, 480); |
| 25 |
CL_InputContext *ic = window.get_ic(); |
| 26 |
CL_InputDevice keyboard = ic->get_keyboard(); |
| 27 |
CL_InputDevice mouse = ic->get_mouse(); |
| 28 |
CL_InputDevice joystick = ic->get_joystick(); |
| 29 |
</code> |
| 30 |
|
| 31 |
<p>CL_InputDevice is an abstraction for any input device type. It has a set |
| 32 |
of polling functions for both keyboards, mice and joysticks:</p> |
| 33 |
|
| 34 |
<code> |
| 35 |
bool space_down = keyboard.get_keycode(CL_KEY_SPACE); |
| 36 |
std::string name_of_space = keyboard.get_key_name(CL_KEY_SPACE); |
| 37 |
int mouse_x = mouse.get_x(); |
| 38 |
int mouse_y = mouse.get_y(); |
| 39 |
float axis_x = joystick.get_axis(0); |
| 40 |
float axis_y = joystick.get_axis(1); |
| 41 |
</code> |
| 42 |
|
| 43 |
<p>In addition to the polling functions, CL_InputDevice also has a list of |
| 44 |
signals that are emitted when ClanLib receives input events for the specific |
| 45 |
device. When any of those events occur, a CL_InputEvent is passed along to |
| 46 |
any slot listening for that event. Here's an example of a handler routine listening |
| 47 |
for key down events from the keyboard:</p> |
| 48 |
|
| 49 |
<code> |
| 50 |
CL_Slot slot_key_down; |
| 51 |
|
| 52 |
void setup_slot(CL_InputContext *ic) |
| 53 |
{ |
| 54 |
CL_InputDevice keyboard = ic->get_keyboard(); |
| 55 |
slot_key_down = keyboard.sig_key_down().connect(&on_key_down); |
| 56 |
} |
| 57 |
|
| 58 |
void on_key_down(const CL_InputEvent &event) |
| 59 |
{ |
| 60 |
std::cout << "User pressed: " << event.str.c_str() << std::endl; |
| 61 |
} |
| 62 |
</code> |
| 63 |
|
| 64 |
<p><i>Note:</i> ClanLib only polls the operating system for new events when |
| 65 |
you call CL_System::keep_alive(), so make sure you call that at least once |
| 66 |
a frame.</p> |
| 67 |
|
| 68 |
<p>CL_InputBuffer is a class that helps you capture keyboard press events |
| 69 |
and convert them into a poll-able buffer. This is useful if you |
| 70 |
want to avoid setting up an event handler when you want the user to enter a |
| 71 |
string of text:</p> |
| 72 |
|
| 73 |
<code> |
| 74 |
CL_InputBuffer buffer(keyboard); |
| 75 |
bool quit = false; |
| 76 |
std::string text; |
| 77 |
while (!quit) |
| 78 |
{ |
| 79 |
while (buffer.keys_left() > 0) |
| 80 |
{ |
| 81 |
CL_InputEvent key = buffer.pop_key(); |
| 82 |
if (key.type != CL_InputEvent::pressed) continue; |
| 83 |
if (key.id == CL_KEY_ENTER) |
| 84 |
{ |
| 85 |
quit = true; |
| 86 |
break; |
| 87 |
} |
| 88 |
else |
| 89 |
{ |
| 90 |
text += key.str; |
| 91 |
} |
| 92 |
} |
| 93 |
|
| 94 |
draw_gfx(text); |
| 95 |
window.flip(); |
| 96 |
CL_System::keep_alive(); |
| 97 |
} |
| 98 |
std::cout << "User wrote: " << text.c_str() << std::endl; |
| 99 |
</code> |
| 100 |
|
| 101 |
<h3>Keycodes</h3> |
| 102 |
<p>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:</p> |
| 103 |
<table> |
| 104 |
<tr> <td> CL_MOUSE_LEFT </td> <td> CL_MOUSE_RIGHT </td> <td> CL_MOUSE_MIDDLE </td> <td> CL_MOUSE_WHEEL_UP </td> <td> CL_MOUSE_WHEEL_DOWN </td> </tr> |
| 105 |
<tr> <td> CL_MOUSE_XBUTTON1 </td> <td> CL_MOUSE_XBUTTON2 </td> <td> CL_KEY_BACKSPACE </td> <td> CL_KEY_TAB </td> <td> CL_KEY_CLEAR </td> </tr> |
| 106 |
<tr> <td> CL_KEY_RETURN </td> <td> CL_KEY_SHIFT </td> <td> CL_KEY_CONTROL </td> <td> CL_KEY_MENU </td> <td> CL_KEY_PAUSE </td> </tr> |
| 107 |
<tr> <td> CL_KEY_ESCAPE </td> <td> CL_KEY_SPACE </td> <td> CL_KEY_PRIOR </td> <td> CL_KEY_NEXT </td> <td> CL_KEY_END </td> </tr> |
| 108 |
<tr> <td> CL_KEY_HOME </td> <td> CL_KEY_LEFT </td> <td> CL_KEY_UP </td> <td> CL_KEY_RIGHT </td> <td> CL_KEY_DOWN </td> </tr> |
| 109 |
<tr> <td> CL_KEY_SELECT </td> <td> CL_KEY_PRINT </td> <td> CL_KEY_EXECUTE </td> <td> CL_KEY_INSERT </td> <td> CL_KEY_DELETE </td> </tr> |
| 110 |
<tr> <td> CL_KEY_HELP </td> <td> CL_KEY_0 </td> <td> CL_KEY_1 </td> <td> CL_KEY_2 </td> <td> CL_KEY_3 </td> </tr> |
| 111 |
<tr> <td> CL_KEY_4 </td> <td> CL_KEY_5 </td> <td> CL_KEY_6 </td> <td> CL_KEY_7 </td> <td> CL_KEY_8 </td> </tr> |
| 112 |
<tr> <td> CL_KEY_9 </td> <td> CL_KEY_A </td> <td> CL_KEY_B </td> <td> CL_KEY_C </td> <td> CL_KEY_D </td> </tr> |
| 113 |
<tr> <td> CL_KEY_E </td> <td> CL_KEY_F </td> <td> CL_KEY_G </td> <td> CL_KEY_H </td> <td> CL_KEY_I </td> </tr> |
| 114 |
<tr> <td> CL_KEY_J </td> <td> CL_KEY_K </td> <td> CL_KEY_L </td> <td> CL_KEY_M </td> <td> CL_KEY_N </td> </tr> |
| 115 |
<tr> <td> CL_KEY_O </td> <td> CL_KEY_P </td> <td> CL_KEY_Q </td> <td> CL_KEY_R </td> <td> CL_KEY_S </td> </tr> |
| 116 |
<tr> <td> CL_KEY_T </td> <td> CL_KEY_U </td> <td> CL_KEY_V </td> <td> CL_KEY_W </td> <td> CL_KEY_X </td> </tr> |
| 117 |
<tr> <td> CL_KEY_Y </td> <td> CL_KEY_Z </td> <td> CL_KEY_LWIN </td> <td> CL_KEY_RWIN </td> <td> CL_KEY_APPS </td> </tr> |
| 118 |
<tr> <td> CL_KEY_NUMPAD0 </td> <td> CL_KEY_NUMPAD1 </td> <td> CL_KEY_NUMPAD2 </td> <td> CL_KEY_NUMPAD3 </td> <td> CL_KEY_NUMPAD4 </td> </tr> |
| 119 |
<tr> <td> CL_KEY_NUMPAD5 </td> <td> CL_KEY_NUMPAD6 </td> <td> CL_KEY_NUMPAD7 </td> <td> CL_KEY_NUMPAD8 </td> <td> CL_KEY_NUMPAD9 </td> </tr> |
| 120 |
<tr> <td> CL_KEY_MULTIPLY </td> <td> CL_KEY_ADD </td> <td> CL_KEY_SEPARATOR </td> <td> CL_KEY_SUBTRACT </td> <td> CL_KEY_DECIMAL </td> </tr> |
| 121 |
<tr> <td> CL_KEY_DIVIDE </td> <td> CL_KEY_F1 </td> <td> CL_KEY_F2 </td> <td> CL_KEY_F3 </td> <td> CL_KEY_F4 </td> </tr> |
| 122 |
<tr> <td> CL_KEY_F5 </td> <td> CL_KEY_F6 </td> <td> CL_KEY_F7 </td> <td> CL_KEY_F8 </td> <td> CL_KEY_F9 </td> </tr> |
| 123 |
<tr> <td> CL_KEY_F10 </td> <td> CL_KEY_F11 </td> <td> CL_KEY_F12 </td> <td> CL_KEY_F13 </td> <td> CL_KEY_F14 </td> </tr> |
| 124 |
<tr> <td> CL_KEY_F15 </td> <td> CL_KEY_F16 </td> <td> CL_KEY_F17 </td> <td> CL_KEY_F18 </td> <td> CL_KEY_F19 </td> </tr> |
| 125 |
<tr> <td> CL_KEY_F20 </td> <td> CL_KEY_F21 </td> <td> CL_KEY_F22 </td> <td> CL_KEY_F23 </td> <td> CL_KEY_F24 </td> </tr> |
| 126 |
<tr> <td> CL_KEY_NUMLOCK </td> <td> CL_KEY_SCROLL </td> <td> CL_KEY_LSHIFT </td> <td> CL_KEY_RSHIFT </td> <td> CL_KEY_LCONTROL </td> </tr> |
| 127 |
<tr> <td> CL_KEY_RCONTROL </td> <td> CL_KEY_LMENU </td> <td> CL_KEY_RMENU </td> |
| 128 |
</table> |
| 129 |
|
| 130 |
</body> |
| 131 |
</xml> |