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.
main
Frank Praznik 2023-03-13 13:46:06 -04:00
parent f97b469184
commit 1f35fd6939
2 changed files with 20 additions and 10 deletions

View File

@ -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
* '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 valid for popup windows and will be ignored: -
* 'SDL_WINDOW_MINIMIZED' - 'SDL_WINDOW_MAXIMIZED' - 'SDL_WINDOW_FULLSCREEN' -
* `SDL_WINDOW_BORDERLESS` - `SDL_WINDOW_MOUSE_GRABBED`
* 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.
*

View File

@ -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);
}