From fbb5652d3ec5f04175c458442fc231857dab8e23 Mon Sep 17 00:00:00 2001 From: Frank Praznik Date: Sat, 6 Jul 2024 11:45:04 -0400 Subject: [PATCH] video: Document that SDL_RaiseWindow is a request and subject to window manager policy The result of SDL_RaiseWindow is ultimately subject to window manager policy, particularly if the request would result in stealing focus from another window. Document that this is only a request, and if successful, will result in a focus gained event along with the input focus flag being set on the window. --- include/SDL3/SDL_video.h | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/include/SDL3/SDL_video.h b/include/SDL3/SDL_video.h index d536396102..ee85f44ee7 100644 --- a/include/SDL3/SDL_video.h +++ b/include/SDL3/SDL_video.h @@ -1709,7 +1709,13 @@ extern SDL_DECLSPEC int SDLCALL SDL_ShowWindow(SDL_Window *window); extern SDL_DECLSPEC int SDLCALL SDL_HideWindow(SDL_Window *window); /** - * Raise a window above other windows and set the input focus. + * Request that a window be raised above other windows and gain the input focus. + * + * The result of this request is subject to desktop window manager policy, + * particularly if raising the requested window would result in stealing focus + * from another application. If the window is successfully raised and gains input + * focus, an SDL_EVENT_WINDOW_FOCUS_GAINED event will be emitted, and the window + * will have the SDL_WINDOW_INPUT_FOCUS flag set. * * \param window the window to raise. * \returns 0 on success or a negative error code on failure; call