SDL_CreatePopupWindow(3)

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

💖 SDL_CreatePopupWindow — the manual page, but make it bestie 💖

okay so you're here for SDL_CreatePopupWindow(3), which lives in the SDL3 FUNCTIONS section of the SDL3 manual, and honestly? it's giving "make a lil baby window that hangs off your main window." Let's get into it. ✨

🌸 NAME 🌸

SDL_CreatePopupWindow — Create a child popup window of the specified parent window.

like. a window. that pops. off its parent. the vibes are immaculate. 🫶

🎀 SYNOPSIS 🎀

#include <SDL3/SDL_video.h>

SDL_Window * SDL_CreatePopupWindow(SDL_Window *parent, int offset_x, int offset_y, int w, int h, SDL_WindowFlags flags);

✨ DESCRIPTION ✨

okay bestie, first thing first: the window size is a request. it is not a promise. it is a wish. it is you asking the universe (the desktop layout + window manager policies) very politely, and the universe going "hmm, maybe." 😭 So your app must be prepared to handle a window of any size. no cap.

The flags parameter must contain at least one of these two:

  • SDL_WINDOW_TOOLTIP — the popup window is a tooltip, and it will not pass any input events. it's just vibes and pixels, no clicks.
  • SDL_WINDOW_POPUP_MENU — the popup window is a popup menu. the topmost popup menu will implicitly gain the keyboard focus. main character energy, honestly. 👑

🙈 flags that get ignored 🙈

these ones are just not relevant to popup window creation, so they get ignored. they show up to the party and nobody talks to them:

  • SDL_WINDOW_MINIMIZED
  • SDL_WINDOW_MAXIMIZED
  • SDL_WINDOW_FULLSCREEN
  • SDL_WINDOW_BORDERLESS

💀 flags that will straight up fail 💀

these are incompatible with popup window creation and will cause it to fail. not "be ignored," not "be sad," fail. periodt.

  • SDL_WINDOW_UTILITY
  • SDL_WINDOW_MODAL

🦋 the rules, bestie 🦋

The parent parameter must be non-null and a valid window. and the parent of a popup window can be either a regular, toplevel window, or another popup window. popups all the way down, iykyk. 🌀

Popup windows cannot be:

  • minimized
  • maximized
  • made fullscreen
  • raised
  • flashed
  • made a modal window
  • be the parent of a toplevel window
  • grab the mouse and/or keyboard

and if you try any of those? they will fail. attempts to do so will fail. the window said no. 🙅♀️

Also, popup windows implicitly do not have a border/decorations, and they do not appear on the taskbar/dock or in lists of windows such as alt-tab menus. they're stealth mode. they're the invisible girlies of the windowing world. 🌫️

⭐ the defaults (and how to override them) ⭐

By default, popup window positions will automatically be constrained to keep the entire window within display bounds. You can override this with the SDL_PROP_WINDOW_CREATE_CONSTRAIN_POPUP_BOOLEAN property. ✨

By default, popup menus will automatically grab keyboard focus from the parent when shown. This behavior can be overridden by:

  • setting the SDL_WINDOW_NOT_FOCUSABLE flag,
  • setting the SDL_PROP_WINDOW_CREATE_FOCUSABLE_BOOLEAN property to false,
  • or toggling it after creation via the SDL_SetWindowFocusable() function.

🌈 parent/child lore 🌈

If a parent window is hidden or destroyed, any child popup windows will be recursively hidden or destroyed as well. and child popup windows that were not explicitly hidden will be restored when the parent is shown. it's a whole family system. the popups are ride-or-die fr fr. 🥹

💜 FUNCTION PARAMETERS 💜

  • parent — the parent of the window, must not be NULL.
  • offset_x — the x position of the popup window relative to the origin of the parent.
  • offset_y — the y position of the popup window relative to the origin of the parent window.
  • w — the width of the window.
  • h — the height of the window.
  • flags — SDL_WINDOW_TOOLTIP or SDL_WINDOW_POPUP_MENU, and zero or more additional SDL_WindowFlags OR'd together.

🔥 RETURN VALUE 🔥

Returns the window that was created, or NULL on failure. if it's NULL, call SDL_GetError() for more information. that's your girl, she'll tell you what went wrong. 😭

🧚 THREAD SAFETY 🧚

This function should only be called on the main thread. do not be out here on a worker thread trying to make windows, bestie. main thread only. 💅

👑 AVAILABILITY 👑

This function is available since SDL 3.2.0. so if you're on something older, no popups for you. 🙈

🌟 SEE ALSO 🌟

and that's the whole page, bestie!! 🎀 go forth and make your lil popup windows, and remember: size is a request, main thread only, and SDL_WINDOW_TOOLTIP / SDL_WINDOW_POPUP_MENU — pick at least one. slay. 💖

this has been Simple Directmedia Layer, SDL 3.4.18, from the SDL_CreatePopupWindow(3) page — mwah, love u, bye!! 💅✨🌸
📦 where this page comes from