SDL_keysym(3)

✨ SDL_keysym ✨

okay bestie, welcome to the SDL API Reference, section 3 of the manual, and today's main character is literally the keysym struct 💅

---

🌸 NAME 🌸

SDL_keysym — the Keysym structure, aka the little bundle of joy that tells you which key got pressed 🎀

---

🦋 STRUCTURE DEFINITION 🦋

here's the whole fit, no notes:

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

---

💜 STRUCTURE DATA 💜

four fields, four besties, all of them iconic in their own way:

• scancode — the hardware specific scancode. lowkey the weird one.
• sym — the SDL virtual keysym. this is the one you're actually gonna be obsessed with.
• mod — the current key modifiers, as in "was shift held down or whatever".
• unicode — the translated character. the glow-up version of your keypress.

---

🌈 DESCRIPTION 🌈

so the SDL_keysym structure is what gets used when reporting key presses and releases, because it is literally a part of the SDL_KeyboardEvent. it's giving "I'm embedded in the event, I go where the event goes" 🫶

the scancode field should generally be left alone — it's the hardware dependent scancode returned by the keyboard, so it's not it, don't touch it, let it be. the sym field though? extremely useful. it's the SDL-defined value of the key (see SDL Key Syms), and it's the moment when you're 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, and it works exactly as explained in SDL_GetModState. and unicode? okay so unicode 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. and 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.
");
}

heads up bestie 🚨 UNICODE translation does have a slight overhead, so don't enable it unless it's needed. not everything needs to be turned on, we're not doing that today.

---

👑 SEE ALSO 👑

SDLKey

---

and that's the whole page fr fr 💖 this one came from SDL and it's dated Tue 11 Sep 2001, 23:00 — yes, that date, iconic in the most cursed way possible 😭 stay hydrated, read your manpages, and go press some keys. mwah 💅🎀🦋