From 1f35fd69395aa4dc1a663ebf99ece832593a1969 Mon Sep 17 00:00:00 2001
From: Frank Praznik <[EMAIL REDACTED]>
Date: Mon, 13 Mar 2023 13:46:06 -0400
Subject: [PATCH] video: Update the popup window creation documentation and
disallowed flags
Update the popup window creation documentation with additional info, remove the SDL_WINDOW_MOUSE_GRABBED flag check since it isn't a valid window creation flag and will be removed automatically elsewhere, and check for and remove the explicit skip taskbar and borderless flags since they are implicit for popup windows.
---
include/SDL3/SDL_video.h | 30 ++++++++++++++++++++----------
src/video/SDL_video.c | 2 +-
2 files changed, 21 insertions(+), 11 deletions(-)
diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h
index d27ab37d9519..e1d56e97587e 100644
--- a/include/SDL3/SDL_video.h
+++ b/include/SDL3/SDL_video.h
@@ -667,20 +667,29 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindow(const char *title, int w, i
/**
* Create a child popup window of the specified parent window.
*
- * 'flags' **must** contain exactly one of the following: -
- * 'SDL_WINDOW_TOOLTIP': The popup window is a tooltip and will not pass any
- * input events - 'SDL_WINDOW_POPUP_MENU': The popup window is a popup menu
- *
- * The following flags are not valid for popup windows and will be ignored: -
- * 'SDL_WINDOW_MINIMIZED' - 'SDL_WINDOW_MAXIMIZED' - 'SDL_WINDOW_FULLSCREEN' -
- * `SDL_WINDOW_BORDERLESS` - `SDL_WINDOW_MOUSE_GRABBED`
+ * 'flags' **must** contain exactly one of the following:
+ * - 'SDL_WINDOW_TOOLTIP': The popup window is a tooltip and will not pass any
+ * input events.
+ * - 'SDL_WINDOW_POPUP_MENU': The popup window is a popup menu. The topmost
+ * popup menu will implicitly gain the keyboard focus.
+ *
+ * The following flags are not relevant to popup window creation and will be ignored:
+ * - 'SDL_WINDOW_MINIMIZED'
+ * - 'SDL_WINDOW_MAXIMIZED'
+ * - 'SDL_WINDOW_FULLSCREEN'
+ * - 'SDL_WINDOW_BORDERLESS'
+ * - 'SDL_WINDOW_SKIP_TASKBAR'
*
* The parent parameter **must** be non-null and a valid window. The parent of
* a popup window can be either a regular, toplevel window, or another popup
* window.
*
- * Popup windows cannot be minimized, maximized, made fullscreen, or grab the
- * mouse. Attempts to do so will fail.
+ * Popup windows cannot be minimized, maximized, made fullscreen, raised, flash,
+ * be made a modal window, be the parent of a modal window, or grab the mouse
+ * and/or keyboard. Attempts to do so will fail.
+ *
+ * Popup windows implicitly do not have a border/decorations and do not appear
+ * on the taskbar/dock or in lists of windows such as alt-tab menus.
*
* If a parent window is hidden, any child popup windows will be recursively
* hidden as well. Child popup windows not explicitly hidden will be restored
@@ -696,7 +705,8 @@ extern DECLSPEC SDL_Window *SDLCALL SDL_CreateWindow(const char *title, int w, i
* of the parent window, in screen coordinates
* \param w the width of the window, in screen coordinates
* \param h the height of the window, in screen coordinates
- * \param flags 0, or one or more SDL_WindowFlags OR'd together
+ * \param flags SDL_WINDOW_TOOLTIP or SDL_WINDOW_POPUP MENU, and zero or more
+ * additional SDL_WindowFlags OR'd together.
* \returns the window that was created or NULL on failure; call
* SDL_GetError() for more information.
*
diff --git a/src/video/SDL_video.c b/src/video/SDL_video.c
index 9e7d354717de..ea1cf6ccead3 100644
--- a/src/video/SDL_video.c
+++ b/src/video/SDL_video.c
@@ -1953,7 +1953,7 @@ SDL_Window *SDL_CreatePopupWindow(SDL_Window *parent, int offset_x, int offset_y
}
/* Remove invalid flags */
- flags &= ~(SDL_WINDOW_MINIMIZED | SDL_WINDOW_MAXIMIZED | SDL_WINDOW_FULLSCREEN | SDL_WINDOW_MOUSE_GRABBED);
+ flags &= ~(SDL_WINDOW_MINIMIZED | SDL_WINDOW_MAXIMIZED | SDL_WINDOW_FULLSCREEN | SDL_WINDOW_BORDERLESS | SDL_WINDOW_SKIP_TASKBAR);
return SDL_CreateWindowInternal(NULL, offset_x, offset_y, w, h, parent, flags);
}