SDL_HINT_KEYCODE_OPTIONS(3)

💖 SDL_HINT_KEYCODE_OPTIONS(3) 💖

okay bestie, welcome to the SDL3 FUNCTIONS section of the manual, and today we're decoding the lil' string that decides how your keycodes get to glow up before they hit your event loop 🦋

---

✨ NAME ✨

SDL_HINT_KEYCODE_OPTIONS — a variable (yes, just a humble string) that controls how keycodes get represented in keyboard events 👑

---

✨ SYNOPSIS ✨

#include <SDL3/SDL_hints.h>

#define SDL_HINT_KEYCODE_OPTIONS "SDL_KEYCODE_OPTIONS"

like, that's it. that's the whole vibe. one #define, infinite power 💅

---

✨ DESCRIPTION ✨

So this variable is a comma separated set of options for translating keycodes in events. You feed it a string, it decides which flavor of keycode you get. no cap 🍓

Here's the menu, one bullet each, no skips:

• "none" — keycode options are cleared, and this overrides other options. like a reset button, or a "leave me alone" text. periodt.
• "hide_numpad" — the numpad keysyms get translated into their non-numpad versions based on the current NumLock state. For example, SDLK_KP_4 would become SDLK_4 if SDL_KMOD_NUM is set in the event modifiers, and SDLK_LEFT if it is unset. so numpad 4 is either a 4 or an arrow, depending on your NumLock mood swings 😭
• "french_numbers" — the number row on French keyboards is inverted, so pressing the 1 key would yield the keycode SDLK_1, or '1', instead of SDLK_AMPERSAND, or '&'. genuinely iconic, French keyboards said "we do it our way" 🇫🇷✨
• "latin_letters" — for keyboards using non-Latin letters, such as Russian or Thai, the letter keys generate keycodes as though it had an English QWERTY layout. e.g. pressing the key associated with SDL_SCANCODE_A on a Russian keyboard would yield 'a' instead of a Cyrillic letter. it's giving "translate me to QWERTY bestie" 🌈

The default value for this hint is "french_numbers,latin_letters" — so yeah, out of the box you already get the French numbers and the Latin letters. slay.

Some platforms like Emscripten only provide modified keycodes and the options are not used. so on those, this whole hint is lowkey just vibing in the background, unread 🙈

Also important, and I need you to hear this: these options do not affect the return value of SDL_GetKeyFromScancode() or SDL_GetScancodeFromKey(). They just apply to the keycode included in key events. So don't come for those two functions, they're innocent 💀

Oh and the good news: this hint can be set anytime. no setup window, no ceremony, just set it whenever. main character energy fr fr.

---

✨ AVAILABILITY ✨

This hint is available since SDL 3.2.0. if you're on something older, sorry babe, it's not there yet 😔

---

🎀 a lil sign-off 🎀

That's the whole page, bestie! This came to you from the Simple Directmedia Layer crew, version SDL 3.4.18, filed under SDL_HINT_KEYCODE_OPTIONS(3). go forth and set your hint string, and remember: "none" overrides everything, so don't say I didn't warn you 🫶💜