Mercurial > sdl-ios-xcode
annotate docs/html/guideinputkeyboard.html @ 337:9154ec9ca3d2
Explicitly specify the SDL API calling convention (C by default)
| author | Sam Lantinga <slouken@libsdl.org> |
|---|---|
| date | Thu, 11 Apr 2002 14:35:16 +0000 |
| parents | 55f1f1b3e27d |
| children | 355632dca928 |
| rev | line source |
|---|---|
| 0 | 1 <HTML |
| 2 ><HEAD | |
| 3 ><TITLE | |
| 4 >Handling the Keyboard</TITLE | |
| 5 ><META | |
| 6 NAME="GENERATOR" | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.64 |
| 0 | 8 "><LINK |
| 9 REL="HOME" | |
| 10 TITLE="SDL Library Documentation" | |
| 11 HREF="index.html"><LINK | |
| 12 REL="UP" | |
| 13 TITLE="Input handling" | |
| 14 HREF="guideinput.html"><LINK | |
| 15 REL="PREVIOUS" | |
| 16 TITLE="Input handling" | |
| 17 HREF="guideinput.html"><LINK | |
| 18 REL="NEXT" | |
| 19 TITLE="Examples" | |
| 20 HREF="guideexamples.html"></HEAD | |
| 21 ><BODY | |
| 22 CLASS="SECT1" | |
| 23 BGCOLOR="#FFF8DC" | |
| 24 TEXT="#000000" | |
| 25 LINK="#0000ee" | |
| 26 VLINK="#551a8b" | |
| 27 ALINK="#ff0000" | |
| 28 ><DIV | |
| 29 CLASS="NAVHEADER" | |
| 30 ><TABLE | |
| 31 WIDTH="100%" | |
| 32 BORDER="0" | |
| 33 CELLPADDING="0" | |
| 34 CELLSPACING="0" | |
| 35 ><TR | |
| 36 ><TH | |
| 37 COLSPAN="3" | |
| 38 ALIGN="center" | |
| 39 >SDL Library Documentation</TH | |
| 40 ></TR | |
| 41 ><TR | |
| 42 ><TD | |
| 43 WIDTH="10%" | |
| 44 ALIGN="left" | |
| 45 VALIGN="bottom" | |
| 46 ><A | |
| 47 HREF="guideinput.html" | |
| 48 >Prev</A | |
| 49 ></TD | |
| 50 ><TD | |
| 51 WIDTH="80%" | |
| 52 ALIGN="center" | |
| 53 VALIGN="bottom" | |
| 54 >Chapter 3. Input handling</TD | |
| 55 ><TD | |
| 56 WIDTH="10%" | |
| 57 ALIGN="right" | |
| 58 VALIGN="bottom" | |
| 59 ><A | |
| 60 HREF="guideexamples.html" | |
| 61 >Next</A | |
| 62 ></TD | |
| 63 ></TR | |
| 64 ></TABLE | |
| 65 ><HR | |
| 66 ALIGN="LEFT" | |
| 67 WIDTH="100%"></DIV | |
| 68 ><DIV | |
| 69 CLASS="SECT1" | |
| 70 ><H1 | |
| 71 CLASS="SECT1" | |
| 72 ><A | |
| 73 NAME="GUIDEINPUTKEYBOARD" | |
| 74 >Handling the Keyboard</A | |
| 75 ></H1 | |
| 76 ><DIV | |
| 77 CLASS="SECT2" | |
| 78 ><H2 | |
| 79 CLASS="SECT2" | |
| 80 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
81 NAME="AEN271" |
| 0 | 82 >Keyboard Related Structures</A |
| 83 ></H2 | |
| 84 ><P | |
| 85 >It should make it a lot easier to understand this tutorial is you are familiar with the data types involved in keyboard access, so I'll explain them first.</P | |
| 86 ><DIV | |
| 87 CLASS="SECT3" | |
| 88 ><H3 | |
| 89 CLASS="SECT3" | |
| 90 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
91 NAME="AEN274" |
| 0 | 92 >SDLKey</A |
| 93 ></H3 | |
| 94 ><P | |
| 95 ><SPAN | |
| 96 CLASS="STRUCTNAME" | |
| 97 >SDLKey</SPAN | |
| 98 > is an enumerated type defined in SDL/include/SDL_keysym.h and detailed <A | |
| 99 HREF="sdlkey.html" | |
| 100 >here</A | |
| 101 >. Each <SPAN | |
| 102 CLASS="STRUCTNAME" | |
| 103 >SDLKey</SPAN | |
| 104 > symbol represents a key, <TT | |
| 105 CLASS="LITERAL" | |
| 106 >SDLK_a</TT | |
| 107 > corresponds to the 'a' key on a keyboard, <TT | |
| 108 CLASS="LITERAL" | |
| 109 >SDLK_SPACE</TT | |
| 110 > corresponds to the space bar, and so on.</P | |
| 111 ></DIV | |
| 112 ><DIV | |
| 113 CLASS="SECT3" | |
| 114 ><H3 | |
| 115 CLASS="SECT3" | |
| 116 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
117 NAME="AEN282" |
| 0 | 118 >SDLMod</A |
| 119 ></H3 | |
| 120 ><P | |
| 121 >SDLMod is an enumerated type, similar to <SPAN | |
| 122 CLASS="STRUCTNAME" | |
| 123 >SDLKey</SPAN | |
| 124 >, however it enumerates keyboard modifiers (Control, Alt, Shift). The full list of modifier symbols is <A | |
| 125 HREF="sdlkey.html#SDLMOD" | |
| 126 >here</A | |
| 127 >. <SPAN | |
| 128 CLASS="STRUCTNAME" | |
| 129 >SDLMod</SPAN | |
| 130 > values can be AND'd together to represent several modifiers.</P | |
| 131 ></DIV | |
| 132 ><DIV | |
| 133 CLASS="SECT3" | |
| 134 ><H3 | |
| 135 CLASS="SECT3" | |
| 136 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
137 NAME="AEN288" |
| 0 | 138 >SDL_keysym</A |
| 139 ></H3 | |
| 140 ><PRE | |
| 141 CLASS="PROGRAMLISTING" | |
| 142 >typedef struct{ | |
| 143 Uint8 scancode; | |
| 144 SDLKey sym; | |
| 145 SDLMod mod; | |
| 146 Uint16 unicode; | |
| 147 } SDL_keysym;</PRE | |
| 148 ><P | |
| 149 >The <SPAN | |
| 150 CLASS="STRUCTNAME" | |
| 151 >SDL_keysym</SPAN | |
| 152 > structure describes a key press or a key release. The <TT | |
| 153 CLASS="STRUCTFIELD" | |
| 154 ><I | |
| 155 >scancode</I | |
| 156 ></TT | |
| 157 > field is hardware specific and should be ignored unless you know what your doing. The <TT | |
| 158 CLASS="STRUCTFIELD" | |
| 159 ><I | |
| 160 >sym</I | |
| 161 ></TT | |
| 162 > field is the <SPAN | |
| 163 CLASS="STRUCTNAME" | |
| 164 >SDLKey</SPAN | |
| 165 > value of the key being pressed or released. The <TT | |
| 166 CLASS="STRUCTFIELD" | |
| 167 ><I | |
| 168 >mod</I | |
| 169 ></TT | |
| 170 > field describes the state of the keyboard modifiers at the time the key press or release occurred. So a value of <TT | |
| 171 CLASS="LITERAL" | |
| 172 >KMOD_NUM | KMOD_CAPS | KMOD_LSHIFT</TT | |
| 173 > would mean that Numlock, Capslock and the left shift key were all press (or enabled in the case of the lock keys). Finally, the <TT | |
| 174 CLASS="STRUCTFIELD" | |
| 175 ><I | |
| 176 >unicode</I | |
| 177 ></TT | |
| 178 > field stores the 16-bit unicode value of the key.</P | |
| 179 ><DIV | |
| 180 CLASS="NOTE" | |
| 181 ><BLOCKQUOTE | |
| 182 CLASS="NOTE" | |
| 183 ><P | |
| 184 ><B | |
| 185 >Note: </B | |
| 186 >It should be noted and understood that this field is only valid when the <SPAN | |
| 187 CLASS="STRUCTNAME" | |
| 188 >SDL_keysym</SPAN | |
| 189 > is describing a key press, not a key release. Unicode values only make sense on a key press because the unicode value describes an international character and only key presses produce characters. More information on Unicode can be found at <A | |
| 190 HREF="http://www.unicode.org" | |
| 191 TARGET="_top" | |
| 192 >www.unicode.org</A | |
| 193 ></P | |
| 194 ></BLOCKQUOTE | |
| 195 ></DIV | |
| 196 ><DIV | |
| 197 CLASS="NOTE" | |
| 198 ><BLOCKQUOTE | |
| 199 CLASS="NOTE" | |
| 200 ><P | |
| 201 ><B | |
| 202 >Note: </B | |
| 203 >Unicode translation must be enabled using the <A | |
| 204 HREF="sdlenableunicode.html" | |
| 205 ><TT | |
| 206 CLASS="FUNCTION" | |
| 207 >SDL_EnableUNICODE</TT | |
| 208 ></A | |
| 209 > function.</P | |
| 210 ></BLOCKQUOTE | |
| 211 ></DIV | |
| 212 ></DIV | |
| 213 ><DIV | |
| 214 CLASS="SECT3" | |
| 215 ><H3 | |
| 216 CLASS="SECT3" | |
| 217 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
218 NAME="AEN307" |
| 0 | 219 >SDL_KeyboardEvent</A |
| 220 ></H3 | |
| 221 ><PRE | |
| 222 CLASS="PROGRAMLISTING" | |
| 223 >typedef struct{ | |
| 224 Uint8 type; | |
| 225 Uint8 state; | |
| 226 SDL_keysym keysym; | |
| 227 } SDL_KeyboardEvent;</PRE | |
| 228 ><P | |
| 229 >The <SPAN | |
| 230 CLASS="STRUCTNAME" | |
| 231 >SDL_KeyboardEvent</SPAN | |
| 232 > describes a keyboard event (obviously). The <TT | |
| 233 CLASS="STRUCTFIELD" | |
| 234 ><I | |
| 235 >key</I | |
| 236 ></TT | |
| 237 > member of the <A | |
| 238 HREF="sdlevent.html" | |
| 239 ><SPAN | |
| 240 CLASS="STRUCTNAME" | |
| 241 >SDL_Event</SPAN | |
| 242 ></A | |
| 243 > union is a <SPAN | |
| 244 CLASS="STRUCTNAME" | |
| 245 >SDL_KeyboardEvent</SPAN | |
| 246 > structure. The <TT | |
| 247 CLASS="STRUCTFIELD" | |
| 248 ><I | |
| 249 >type</I | |
| 250 ></TT | |
| 251 > field specifies whether the event is a key release (<TT | |
| 252 CLASS="LITERAL" | |
| 253 >SDL_KEYUP</TT | |
| 254 >) or a key press (<TT | |
| 255 CLASS="LITERAL" | |
| 256 >SDL_KEYDOWN</TT | |
| 257 >) event. The <TT | |
| 258 CLASS="STRUCTFIELD" | |
| 259 ><I | |
| 260 >state</I | |
| 261 ></TT | |
| 262 > is largely redundant, it reports the same information as the <TT | |
| 263 CLASS="STRUCTFIELD" | |
| 264 ><I | |
| 265 >type</I | |
| 266 ></TT | |
| 267 > field but uses different values (<TT | |
| 268 CLASS="LITERAL" | |
| 269 >SDL_RELEASED</TT | |
| 270 > and <TT | |
| 271 CLASS="LITERAL" | |
| 272 >SDL_PRESSED</TT | |
| 273 >). The <TT | |
| 274 CLASS="STRUCTFIELD" | |
| 275 ><I | |
| 276 >keysym</I | |
| 277 ></TT | |
| 278 > contains information of the key press or release that this event represents (see above).</P | |
| 279 ></DIV | |
| 280 ></DIV | |
| 281 ><DIV | |
| 282 CLASS="SECT2" | |
| 283 ><H2 | |
| 284 CLASS="SECT2" | |
| 285 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
286 NAME="AEN324" |
| 0 | 287 >Reading Keyboard Events</A |
| 288 ></H2 | |
| 289 ><P | |
| 290 >Reading keybaord events from the event queue is quite simple (the event queue and using it is described <A | |
| 291 HREF="sdlevent.html" | |
| 292 >here</A | |
| 293 >). We read events using <A | |
| 294 HREF="sdlpollevent.html" | |
| 295 ><TT | |
| 296 CLASS="FUNCTION" | |
| 297 >SDL_PollEvent</TT | |
| 298 ></A | |
| 299 > in a <TT | |
| 300 CLASS="LITERAL" | |
| 301 >while()</TT | |
| 302 > loop and check for <TT | |
| 303 CLASS="LITERAL" | |
| 304 >SDL_KEYUP</TT | |
| 305 > and <TT | |
| 306 CLASS="LITERAL" | |
| 307 >SDL_KEYDOWN</TT | |
| 308 > events using a <TT | |
| 309 CLASS="LITERAL" | |
| 310 >switch</TT | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
311 > statement, like so:</P |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
312 ><DIV |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
313 CLASS="EXAMPLE" |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
314 ><A |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
315 NAME="AEN334" |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
316 ></A |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
317 ><P |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
318 ><B |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
319 >Example 3-10. Reading Keyboard Events</B |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
320 ></P |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
321 ><PRE |
| 0 | 322 CLASS="PROGRAMLISTING" |
| 323 > SDL_Event event; | |
| 324 . | |
| 325 . | |
| 326 /* Poll for events. SDL_PollEvent() returns 0 when there are no */ | |
| 327 /* more events on the event queue, our while loop will exit when */ | |
| 328 /* that occurs. */ | |
| 329 while( SDL_PollEvent( &event ) ){ | |
| 330 /* We are only worried about SDL_KEYDOWN and SDL_KEYUP events */ | |
| 331 switch( event.type ){ | |
| 332 case SDL_KEYDOWN: | |
| 333 printf( "Key press detected\n" ); | |
| 334 break; | |
| 335 | |
| 336 case SDL_KEYUP: | |
| 337 printf( "Key release detected\n" ); | |
| 338 break; | |
| 339 | |
| 340 default: | |
| 341 break; | |
| 342 } | |
| 343 } | |
| 344 . | |
| 345 .</PRE | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
346 ></DIV |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
347 ><P |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
348 >This is a very basic example. No information about the key press or release is interpreted. We will explore the other extreme out our first full example below - reporting all available information about a keyboard event.</P |
| 0 | 349 ></DIV |
| 350 ><DIV | |
| 351 CLASS="SECT2" | |
| 352 ><H2 | |
| 353 CLASS="SECT2" | |
| 354 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
355 NAME="AEN338" |
| 0 | 356 >A More Detailed Look</A |
| 357 ></H2 | |
| 358 ><P | |
| 359 >Before we can read events SDL must be initialised with <A | |
| 360 HREF="sdlinit.html" | |
| 361 ><TT | |
| 362 CLASS="FUNCTION" | |
| 363 >SDL_Init</TT | |
| 364 ></A | |
| 365 > and a video mode must be set using <A | |
| 366 HREF="sdlsetvideomode.html" | |
| 367 ><TT | |
| 368 CLASS="FUNCTION" | |
| 369 >SDL_SetVideoMode</TT | |
| 370 ></A | |
| 371 >. There are, however, two other functions we must use to obtain all the information required. We must enable unicode translation by calling <TT | |
| 372 CLASS="FUNCTION" | |
| 373 >SDL_EnableUNICODE(1)</TT | |
| 374 > and we must convert <SPAN | |
| 375 CLASS="STRUCTNAME" | |
| 376 >SDLKey</SPAN | |
| 377 > values into something printable, using <A | |
| 378 HREF="sdlgetkeyname.html" | |
| 379 ><TT | |
| 380 CLASS="FUNCTION" | |
| 381 >SDL_GetKeyName</TT | |
| 382 ></A | |
| 383 ></P | |
| 384 ><DIV | |
| 385 CLASS="NOTE" | |
| 386 ><BLOCKQUOTE | |
| 387 CLASS="NOTE" | |
| 388 ><P | |
| 389 ><B | |
| 390 >Note: </B | |
| 391 >It is useful to note that unicode values < 0x80 translate directly a characters ASCII value. THis is used in the example below</P | |
| 392 ></BLOCKQUOTE | |
| 393 ></DIV | |
| 394 ><DIV | |
| 395 CLASS="EXAMPLE" | |
| 396 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
397 NAME="AEN351" |
| 0 | 398 ></A |
| 399 ><P | |
| 400 ><B | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
401 >Example 3-11. Interpreting Key Event Information</B |
| 0 | 402 ></P |
| 403 ><PRE | |
| 404 CLASS="PROGRAMLISTING" | |
| 405 > #include "SDL.h" | |
| 406 | |
| 407 /* Function Prototypes */ | |
| 408 void PrintKeyInfo( SDL_KeyboardEvent *key ); | |
| 409 void PrintModifiers( SDLMod mod ); | |
| 410 | |
| 411 /* main */ | |
| 412 int main( int argc, char *argv[] ){ | |
| 413 | |
| 414 SDL_Event event; | |
| 415 int quit = 0; | |
| 416 | |
| 417 /* Initialise SDL */ | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
418 if( SDL_Init( SDL_INIT_VIDEO ) < 0){ |
| 0 | 419 fprintf( stderr, "Could not initialise SDL: %s\n", SDL_GetError() ); |
| 420 exit( -1 ); | |
| 421 } | |
| 422 | |
| 423 /* Set a video mode */ | |
| 424 if( !SDL_SetVideoMode( 320, 200, 0, 0 ) ){ | |
| 425 fprintf( stderr, "Could not set video mode: %s\n", SDL_GetError() ); | |
| 426 SDL_Quit(); | |
| 427 exit( -1 ); | |
| 428 } | |
| 429 | |
| 430 /* Enable Unicode translation */ | |
| 431 SDL_EnableUNICODE( 1 ); | |
| 432 | |
| 433 /* Loop until an SDL_QUIT event is found */ | |
| 434 while( !quit ){ | |
| 435 | |
| 436 /* Poll for events */ | |
| 437 while( SDL_PollEvent( &event ) ){ | |
| 438 | |
| 439 switch( event.type ){ | |
| 440 /* Keyboard event */ | |
| 441 /* Pass the event data onto PrintKeyInfo() */ | |
| 442 case SDL_KEYDOWN: | |
| 443 case SDL_KEYUP: | |
| 444 PrintKeyInfo( &event.key ); | |
| 445 break; | |
| 446 | |
| 447 /* SDL_QUIT event (window close) */ | |
| 448 case SDL_QUIT: | |
| 449 quit = 1; | |
| 450 break; | |
| 451 | |
| 452 default: | |
| 453 break; | |
| 454 } | |
| 455 | |
| 456 } | |
| 457 | |
| 458 } | |
| 459 | |
| 460 /* Clean up */ | |
| 461 SDL_Quit(); | |
| 462 exit( 0 ); | |
| 463 } | |
| 464 | |
| 465 /* Print all information about a key event */ | |
| 466 void PrintKeyInfo( SDL_KeyboardEvent *key ){ | |
| 467 /* Is it a release or a press? */ | |
| 468 if( key->type == SDL_KEYUP ) | |
| 469 printf( "Release:- " ); | |
| 470 else | |
| 471 printf( "Press:- " ); | |
| 472 | |
| 473 /* Print the hardware scancode first */ | |
| 474 printf( "Scancode: 0x%02X", key->keysym.scancode ); | |
| 475 /* Print the name of the key */ | |
| 476 printf( ", Name: %s", SDL_GetKeyName( key->keysym.sym ) ); | |
| 477 /* We want to print the unicode info, but we need to make */ | |
| 478 /* sure its a press event first (remember, release events */ | |
| 479 /* don't have unicode info */ | |
| 480 if( key->type == SDL_KEYDOWN ){ | |
| 481 /* If the Unicode value is less than 0x80 then the */ | |
| 482 /* unicode value can be used to get a printable */ | |
| 483 /* representation of the key, using (char)unicode. */ | |
| 484 printf(", Unicode: " ); | |
| 485 if( key->keysym.unicode < 0x80 && key->keysym.unicode > 0 ){ | |
| 486 printf( "%c (0x%04X)", (char)key->keysym.unicode, | |
| 487 key->keysym.unicode ); | |
| 488 } | |
| 489 else{ | |
| 490 printf( "? (0x%04X)", key->keysym.unicode ); | |
| 491 } | |
| 492 } | |
| 493 printf( "\n" ); | |
| 494 /* Print modifier info */ | |
| 495 PrintModifiers( key->keysym.mod ); | |
| 496 } | |
| 497 | |
| 498 /* Print modifier info */ | |
| 499 void PrintModifiers( SDLMod mod ){ | |
| 500 printf( "Modifers: " ); | |
| 501 | |
| 502 /* If there are none then say so and return */ | |
| 503 if( mod == KMOD_NONE ){ | |
| 504 printf( "None\n" ); | |
| 505 return; | |
| 506 } | |
| 507 | |
| 508 /* Check for the presence of each SDLMod value */ | |
| 509 /* This looks messy, but there really isn't */ | |
| 510 /* a clearer way. */ | |
| 511 if( mod & KMOD_NUM ) printf( "NUMLOCK " ); | |
| 512 if( mod & KMOD_CAPS ) printf( "CAPSLOCK " ); | |
| 513 if( mod & KMOD_LCTRL ) printf( "LCTRL " ); | |
| 514 if( mod & KMOD_RCTRL ) printf( "RCTRL " ); | |
| 515 if( mod & KMOD_RSHIFT ) printf( "RSHIFT " ); | |
| 516 if( mod & KMOD_LSHIFT ) printf( "LSHIFT " ); | |
| 517 if( mod & KMOD_RALT ) printf( "RALT " ); | |
| 518 if( mod & KMOD_LALT ) printf( "LALT " ); | |
| 519 if( mod & KMOD_CTRL ) printf( "CTRL " ); | |
| 520 if( mod & KMOD_SHIFT ) printf( "SHIFT " ); | |
| 521 if( mod & KMOD_ALT ) printf( "ALT " ); | |
| 522 printf( "\n" ); | |
| 523 }</PRE | |
| 524 ></DIV | |
| 525 ></DIV | |
| 526 ><DIV | |
| 527 CLASS="SECT2" | |
| 528 ><H2 | |
| 529 CLASS="SECT2" | |
| 530 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
531 NAME="AEN354" |
| 0 | 532 >Game-type Input</A |
| 533 ></H2 | |
| 534 ><P | |
| 535 >I have found that people using keyboard events for games and other interactive applications don't always understand one fundemental point.</P | |
| 536 ><A | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
537 NAME="AEN357" |
| 0 | 538 ></A |
| 539 ><BLOCKQUOTE | |
| 540 CLASS="BLOCKQUOTE" | |
| 541 ><P | |
| 542 >Keyboard events <I | |
| 543 CLASS="EMPHASIS" | |
| 544 >only</I | |
| 545 > take place when a keys state changes from being unpressed to pressed, and vice versa.</P | |
| 546 ></BLOCKQUOTE | |
| 547 ><P | |
| 548 >Imagine you have an image of an alien that you wish to move around using the cursor keys - when you pressed the left arrow key you want him to slide over to the left, when you press the down key you want him to slide down the screen. Examine the following code, it highlights and error that many people have made. | |
| 549 <PRE | |
| 550 CLASS="PROGRAMLISTING" | |
| 551 > /* Alien screen coordinates */ | |
| 552 int alien_x=0, alien_y=0; | |
| 553 . | |
| 554 . | |
| 555 /* Initialise SDL and video modes and all that */ | |
| 556 . | |
| 557 /* Main game loop */ | |
| 558 /* Check for events */ | |
| 559 while( SDL_PollEvent( &event ) ){ | |
| 560 switch( event.type ){ | |
| 561 /* Look for a keypress */ | |
| 562 case SDL_KEYDOWN: | |
| 563 /* Check the SDLKey values and move change the coords */ | |
| 564 switch( event.key.keysym.sym ){ | |
| 565 case SDLK_LEFT: | |
| 566 alien_x -= 1; | |
| 567 break; | |
| 568 case SDLK_RIGHT: | |
| 569 alien_x += 1; | |
| 570 break; | |
| 571 case SDLK_UP: | |
| 572 alien_y -= 1; | |
| 573 break; | |
| 574 case SDLK_DOWN: | |
| 575 alien_y += 1; | |
| 576 break; | |
| 577 default: | |
| 578 break; | |
| 579 } | |
| 580 } | |
| 581 } | |
| 582 } | |
| 583 . | |
| 584 .</PRE | |
| 585 > | |
| 586 At first glance you may think this is a perfectly reasonable piece of code for the task, but it isn't. Like I said keyboard events only occur when a key changes state, so the user would have to press and release the left cursor key 100 times to move the alien 100 pixels to the left.</P | |
| 587 ><P | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
588 >To get around this problem we must not use the events to change the position of the alien, we use the events to set flags which are then used in a seperate section of code to move the alien. Something like this:</P |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
589 ><DIV |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
590 CLASS="EXAMPLE" |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
591 ><A |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
592 NAME="AEN363" |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
593 ></A |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
594 ><P |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
595 ><B |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
596 >Example 3-12. Proper Game Movement</B |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
597 ></P |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
598 ><PRE |
| 0 | 599 CLASS="PROGRAMLISTING" |
| 600 > /* Alien screen coordinates */ | |
| 601 int alien_x=0, alien_y=0; | |
| 602 int alien_xvel=0, alien_yvel=0; | |
| 603 . | |
| 604 . | |
| 605 /* Initialise SDL and video modes and all that */ | |
| 606 . | |
| 607 /* Main game loop */ | |
| 608 /* Check for events */ | |
| 609 while( SDL_PollEvent( &event ) ){ | |
| 610 switch( event.type ){ | |
| 611 /* Look for a keypress */ | |
| 612 case SDL_KEYDOWN: | |
| 613 /* Check the SDLKey values and move change the coords */ | |
| 614 switch( event.key.keysym.sym ){ | |
| 615 case SDLK_LEFT: | |
| 616 alien_xvel = -1; | |
| 617 break; | |
| 618 case SDLK_RIGHT: | |
| 619 alien_xvel = 1; | |
| 620 break; | |
| 621 case SDLK_UP: | |
| 622 alien_yvel = -1; | |
| 623 break; | |
| 624 case SDLK_DOWN: | |
| 625 alien_yvel = 1; | |
| 626 break; | |
| 627 default: | |
| 628 break; | |
| 629 } | |
| 630 break; | |
| 631 /* We must also use the SDL_KEYUP events to zero the x */ | |
| 632 /* and y velocity variables. But we must also be */ | |
| 633 /* careful not to zero the velocities when we shouldn't*/ | |
| 634 case SDL_KEYUP: | |
| 635 switch( event.key.keysym.sym ){ | |
| 636 case SDLK_LEFT: | |
| 637 /* We check to make sure the alien is moving */ | |
| 638 /* to the left. If it is then we zero the */ | |
| 639 /* velocity. If the alien is moving to the */ | |
| 640 /* right then the right key is still press */ | |
| 641 /* so we don't tocuh the velocity */ | |
| 642 if( alien_xvel < 0 ) | |
| 643 alien_xvel = 0; | |
| 644 break; | |
| 645 case SDLK_RIGHT: | |
| 646 if( alien_xvel > 0 ) | |
| 647 alien_xvel = 0; | |
| 648 break; | |
| 649 case SDLK_UP: | |
| 650 if( alien_yvel < 0 ) | |
| 651 alien_yvel = 0; | |
| 652 break; | |
| 653 case SDLK_DOWN: | |
| 654 if( alien_yvel > 0 ) | |
| 655 alien_yvel = 0; | |
| 656 break; | |
| 657 default: | |
| 658 break; | |
| 659 } | |
| 660 break; | |
| 661 | |
| 662 default: | |
| 663 break; | |
| 664 } | |
| 665 } | |
| 666 . | |
| 667 . | |
| 668 /* Update the alien position */ | |
| 669 alien_x += alien_xvel; | |
| 670 alien_y += alien_yvel;</PRE | |
|
55
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
671 ></DIV |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
672 ><P |
|
55f1f1b3e27d
Added new docs for SDL 1.2.1
Sam Lantinga <slouken@lokigames.com>
parents:
0
diff
changeset
|
673 >As can be seen, we use two extra variables, alien_xvel and alien_yvel, which represent the motion of the ship, it is these variables that we update when we detect keypresses and releases.</P |
| 0 | 674 ></DIV |
| 675 ></DIV | |
| 676 ><DIV | |
| 677 CLASS="NAVFOOTER" | |
| 678 ><HR | |
| 679 ALIGN="LEFT" | |
| 680 WIDTH="100%"><TABLE | |
| 681 WIDTH="100%" | |
| 682 BORDER="0" | |
| 683 CELLPADDING="0" | |
| 684 CELLSPACING="0" | |
| 685 ><TR | |
| 686 ><TD | |
| 687 WIDTH="33%" | |
| 688 ALIGN="left" | |
| 689 VALIGN="top" | |
| 690 ><A | |
| 691 HREF="guideinput.html" | |
| 692 >Prev</A | |
| 693 ></TD | |
| 694 ><TD | |
| 695 WIDTH="34%" | |
| 696 ALIGN="center" | |
| 697 VALIGN="top" | |
| 698 ><A | |
| 699 HREF="index.html" | |
| 700 >Home</A | |
| 701 ></TD | |
| 702 ><TD | |
| 703 WIDTH="33%" | |
| 704 ALIGN="right" | |
| 705 VALIGN="top" | |
| 706 ><A | |
| 707 HREF="guideexamples.html" | |
| 708 >Next</A | |
| 709 ></TD | |
| 710 ></TR | |
| 711 ><TR | |
| 712 ><TD | |
| 713 WIDTH="33%" | |
| 714 ALIGN="left" | |
| 715 VALIGN="top" | |
| 716 >Input handling</TD | |
| 717 ><TD | |
| 718 WIDTH="34%" | |
| 719 ALIGN="center" | |
| 720 VALIGN="top" | |
| 721 ><A | |
| 722 HREF="guideinput.html" | |
| 723 >Up</A | |
| 724 ></TD | |
| 725 ><TD | |
| 726 WIDTH="33%" | |
| 727 ALIGN="right" | |
| 728 VALIGN="top" | |
| 729 >Examples</TD | |
| 730 ></TR | |
| 731 ></TABLE | |
| 732 ></DIV | |
| 733 ></BODY | |
| 734 ></HTML | |
| 735 > |