SDL_SetWindowHitTest(3)

💅 SDL_SetWindowHitTest 💅

okay bestie, so this one lives in the SDL3 FUNCTIONS family, and honestly? it's giving main character energy for borderless windows. it's literally SDL_SetWindowHitTest from the SDL3 video squad, and it's about teaching your window which bits of itself are ~special~ 🎀

---

✨ NAME ✨

SDL_SetWindowHitTest — hand over a callback that decides whether a window region has special properties. yes, you're the one making the rules now. 👑

---

🌸 SYNOPSIS 🌸

#include <SDL3/SDL_video.h>

bool SDL_SetWindowHitTest(SDL_Window *window, SDL_HitTest callback, void *callback_data);

---

🦋 DESCRIPTION 🦋

so normally? windows get dragged and resized by the decorations the system window manager gives you — think title bar, borders, all that standard stuff. cute, classic, no notes. BUT 💖 some apps wanna drag their window from somewhere else entirely inside the window itself. like, maybe you've got a borderless window that should be draggable from literally any part of it, or you're simulating your own title bar, etc. etc. you get the vision.

this function is how you let the app hand over a callback that designates pieces of a given window as special. that callback gets run during event processing whenever we need to tell the OS to treat some region of the window specially. and the name for this whole little dance? "hit testing." periodt. 💅

⚠️ real talk though: mouse input may not be delivered to your application if it's inside a special area. the OS will often just take that input and use it for moving or resizing the window instead of passing it along to you. so like, don't be surprised. 🙈

passing NULL as the callback disables hit-testing. and fun fact, hit-testing is disabled by default anyway — it's an opt-in kind of situation, iykyk. 🌈

platforms that don't support this functionality will return false unconditionally — even if all you're trying to do is disable hit-testing. no cap. 💀

your callback may fire at any time, and its firing does not indicate any specific behavior. for example, on Windows this certainly might fire when the OS is deciding whether to drag your window — but it also fires for lots of other reasons too, some of them unrelated to anything you probably care about, _and when the mouse isn't actually at the location it is testing_. yeah. iconic chaos. 😭

and because it can fire at literally any moment, you should try to keep your callback efficient, devoid of allocations, etc. no heavy lifting in there bestie, it's a vibe check not a whole project. 🧚

---

🎀 FUNCTION PARAMETERS 🎀

• window — the window you're setting hit-testing on. the canvas. the moment. ✨
• callback — the function to call when doing a hit-test. this is your little agent of chaos.
• callback_data — an app-defined void pointer that gets passed to callback. put whatever you want in there, it's your bag. 👜

---

⭐ RETURN VALUE ⭐

returns true on success or false on failure — and if it's a fail, go call SDL_GetError() for more info, she'll tell you what's up. 🫶

---

🔥 THREAD SAFETY 🔥

this function should only be called on the main thread. that's it, that's the rule, don't fight it. 🚫🧵

---

🌈 AVAILABILITY 🌈

this function is available since SDL 3.2.0. so if you're on something older, sorry babe, it's not happening. 💜

---

okay that's the whole page, you ate it, you understood it, slay 💅✨

this little love letter comes from the Simple Directmedia Layer crew, SDL 3.4.18 era, and the page itself is SDL_SetWindowHitTest(3) — mwah, go make a draggable borderless window bestie 🎀🦋🌸