Debian Codegraph @

Documentation/Overview/input.xml

raw
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>