main

SDL assigns a virtual keysym to each key on the keyboard. These codes map at some level to the operating system's keyboard scancodes (which in turn map to the codes produced by the keyboard's hardware), but SDL takes care of the mapping behind the scenes. SDL provides a preprocessor symbol for each virtual keysym; for instance, the Escape key corresponds to the symbol SDLK_ESCAPE. You use these codes whenever you need to directly check the state (up or down) of a particular key, and SDL uses them to report key events. Virtual keysyms are represented by the SDLKey type.

What about the ``special'' keys on the keyboard, such as Ctrl, Alt, and Shift? These do in fact correspond to virtual keysyms, and they can be treated as ordinary keys (you can find their keysyms in SDL_keysym.h); however, they are also considered modifier keys. Each key event carries information about which modifiers were in effect when the key was pressed. Modifiers are represented by ORed bit flags; for instance, a combination of the left Ctrl and Alt keys would be flagged as (KMOD_LCTRL | KMOD_LALT). SDL provides the SDLMod enum for representing these combinations. Note that SDL makes a distinction between the left and right modifier keys.

The following example prints out information about SDL keyboard events. It prints the virtual keysym of each key, gives the key's symbolic name, and indicates whether the left Shift key was down when the key was pressed.

Code Listing 6.-9 (keyboard-events-sdl) ?

/* Example of simple keyboard input with SDL. */

#include 
#include 
#include 

int main()
{
    SDL_Surface *screen;
    SDL_Event event;

    /* Initialize SDL's video system and check for errors. */
    if (SDL_Init(SDL_INIT_VIDEO) != 0) {
        printf("Unable to initialize SDL: %s\n", SDL_GetError());
        return 1;
    }

    /* Make sure SDL_Quit gets called when the program exits! */
    atexit(SDL_Quit);

    /* Attempt to set a 256x256 hicolor (16-bit) video mode. */
    screen = SDL_SetVideoMode(256, 256, 16, 0);
    if (screen == NULL) {
        printf("Unable to set video mode: %s\n", SDL_GetError());
        return 1;
    }

    printf("Press 'Q' to quit.\n");

    /* Start the event loop. Keep reading events until there
       is an error, or the user presses a mouse button. */
    while (SDL_WaitEvent(&event) != 0) {
        SDL_keysym keysym;

        /* SDL_WaitEvent has filled in our event structure
           with the next event. We check its type field to
           find out what happened. */
        switch (event.type) {

        case SDL_KEYDOWN:
            printf("Key pressed. ");
            keysym = event.key.keysym;
            printf("SDL keysym is %i. ", keysym.sym);
            printf("(%s) ", SDL_GetKeyName(keysym.sym));

            /* Report the left shift modifier. */
            if (event.key.keysym.mod & KMOD_LSHIFT)
                printf("Left Shift is down.\n");
            else
                printf("Left Shift is up.\n");

            /* Did the user press Q? */
            if (keysym.sym == SDLK_q) {
                printf("'Q' pressed, exiting.\n");
                exit(0);
            }

            break;

        case SDL_KEYUP:
            printf("Key released. ");
            printf("SDL keysym is %i. ", keysym.sym);
            printf("(%s) ", SDL_GetKeyName(keysym.sym));

            if (event.key.keysym.mod & KMOD_LSHIFT)
                printf("Left Shift is down.\n");
            else
                printf("Left Shift is up.\n");

            break;

        case SDL_QUIT:
            printf("Quit event. Bye.\n");
            exit(0);
        }
    }

    return 0;
}

It is important to note that a keystroke generates only one event, regardless of how long a key is held down. Games generally use the keyboard as a set of control buttons, not as character input devices, and so the normal key repeat feature is most often of no use to them. However, you can enable key repeat with the SDL_EnableKeyRepeat function. This might be useful for implementing text fields in dialog boxes, for instance.

As with the mouse, it is possible to read the keyboard's state directly, bypassing the event interface. There is no function for directly obtaining the state of an individual key, but a program can obtain a snapshot of the entire keyboard in the form of an array. The SDL_GetKeyState function returns a pointer to SDL's internal keyboard state array, which is indexed with the SDLK_ keysym constants. Each entry in the array is a simple Uint8 flag indicating whether that key is currently down. Remember to call SDL_PumpEvents before reading the keyboard's state array, or the array's data will not be valid.