SDL_keysym

Name

SDL_keysym -- Keysym structure

Structure Definition

typedef struct{
  Uint8 scancode;
  SDLKey sym;
  SDLMod mod;
  Uint16 unicode;
} SDL_keysym;

Structure Data

`scancode`	Hardware specific scancode
`sym`	SDL virtual keysym
`mod`	Current key modifiers
`unicode`	Translated character

Description

The SDL_keysym structure is used to report key presses and releases. It is part of the SDL_KeyboardEvent.

The scancode field should generally be left alone, it is the hardware-dependent scancode returned by the keyboard. The sym field is extremely useful. It is the SDL-defined value of the key (see the keysym definitions in SDLKey). This field is very useful when you are checking for certain key presses, like so:

.
.
while(SDL_PollEvent(&event)){
  switch(event.type){
    case SDL_KEYDOWN:
      if(event.key.keysym.sym==SDLK_LEFT)
        move_left();
      break;
    .
    .
    .
  }
}
.
.

mod stores the current state of the keyboard modifiers as explained in SDL_GetModState.

The unicode field is only used when UNICODE translation is enabled with SDL_EnableUNICODE. If unicode is non-zero then this is the UNICODE character corresponding to the keypress. If the high 9 bits of the character are 0, then this maps to the equivalent ASCII character:

char ch;
if ( (keysym.unicode & 0xFF80) == 0 ) {
  ch = keysym.unicode & 0x7F;
}
else {
  printf("An International Character.\n");
}

UNICODE translation does create a slight overhead so don't enable it unless its needed.

NOTE: Key release events (SDL_KEYUP) won't necessarily (ever?) contain unicode information. See http://lists.libsdl.org/pipermail/sdl-libsdl.org/2005-January/048355.html

Discussion

There's no comment on whether or not shift is taken into account either for sym or unicode. It would be nice to not have to manage keymaps as well.