SDL_SetWindowKeyboardGrab(3)

📦
version 3.4.18 · 9 versions
, in fedora 43, fedora 44

✨ SDL_SetWindowKeyboardGrab(3) ✨

okay bestie, welcome to the SDL3 FUNCTIONS corner of the man pages 💖 this one is SDL_SetWindowKeyboardGrab and it's giving keyboard grab mode, no cap.

🎀 NAME 🎀

SDL_SetWindowKeyboardGrab — set a window's keyboard grab mode. literally that's the whole job. slay.

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_video.h>

bool SDL_SetWindowKeyboardGrab(SDL_Window *window, bool grabbed);

🦋 DESCRIPTION 🦋

so, keyboard grab? it enables capture of system keyboard shortcuts like Alt+Tab or the Meta/Super key. yes, the ones your OS is usually gatekeeping. 😭

but lowkey, not all system keyboard shortcuts can be captured by applications — one example is Ctrl+Alt+Del on Windows. some of those are just untouchable, periodt. 💀

this is primarily intended for specialized applications such as VNC clients or VM frontends. normal games should not use keyboard grab — like, fr fr, don't do it, that's not your vibe. 🙈

when keyboard grab is enabled, SDL will continue to handle Alt+Tab when the window is full-screen, to ensure the user is not trapped in your application. very considerate of SDL, honestly. if you have a custom keyboard shortcut to exit fullscreen mode, you may suppress this behavior with SDL_HINT_ALLOW_ALT_TAB_WHILE_GRABBED.

and here's the plot twist 👑: if the caller enables a grab while another window is currently grabbed, the other window loses its grab in favor of the caller's window. main character energy, but make it window management. it's giving "there can only be one." 💅

🍓 FUNCTION PARAMETERS 🍓

  • window — the window for which the keyboard grab mode should be set. the one getting the glow-up.
  • grabbed — this is true to grab keyboard, and false to release. binary queen. ✨

⭐ RETURN VALUE ⭐

Returns true on success or false on failure; call SDL_GetError() for more information. so if it flops, SDL_GetError() will tell you why — always check, bestie, don't just sit there wondering. 😭

🧚 THREAD SAFETY 🧚

This function should only be called on the main thread. no side-quests on other threads, okay? 🫶

🌈 AVAILABILITY 🌈

This function is available since SDL 3.2.0. if your SDL is older than that, it's simply not going to happen, sorry babe. 💜

👑 SEE ALSO 👑

Simple Directmedia Layer said hi, this is SDL 3.4.18, and the whole keyboard-grab saga lives under SDL_SetWindowKeyboardGrab(3). k bye, go grab responsibly 💖✨🎀🦋🌸💅

📦 where this page comes from