Handle to a non owned window. More...

Inheritance diagram for SDL::WindowRef:

[legend]

Public Member Functions
constexpr	WindowRef (const WindowRef &other)
	Copy constructor.

constexpr	WindowRef (WindowRef &&other)
	Move constructor.

constexpr	~WindowRef ()=default
	Default constructor.

WindowRef &	operator= (WindowRef other)
	Assignment operator.

void	reset (SDL_Window *newResource={})
	Destroy a window.

	WindowBase (StringParam title, SDL_Point size, WindowFlags flags=0)
	Create a window with the specified dimensions and flags.

	WindowBase (WindowBase &parent, SDL_Point offset, SDL_Point size, WindowFlags flags=0)
	Create a child popup window of the specified parent window.

	WindowBase (PropertiesBase &props)
	Create a window with the specified properties.

Public Member Functions inherited from SDL::WindowBase
	WindowBase (StringParam title, SDL_Point size, WindowFlags flags=0)
	Create a window with the specified dimensions and flags.

	WindowBase (WindowBase &parent, SDL_Point offset, SDL_Point size, WindowFlags flags=0)
	Create a child popup window of the specified parent window.

	WindowBase (PropertiesBase &props)
	Create a window with the specified properties.

Display	GetDisplay () const
	Get the display associated with a window.

float	GetPixelDensity () const
	Get the pixel density of a window.

float	GetDisplayScale () const
	Get the content display scale relative to a window's pixel size.

void	SetFullscreenMode (OptionalRef< const DisplayMode > mode)
	Set the display mode to use when a window is visible and fullscreen.

const DisplayMode *	GetFullscreenMode () const
	Query the display mode to use when a window is visible at fullscreen.

OwnPtr< void >	GetICCProfile (size_t *size) const
	Get the raw ICC profile data for the screen the window is currently on.

PixelFormat	GetPixelFormat () const
	Get the pixel format associated with the window.

WindowID	GetID () const
	Get the numeric ID of a window.

WindowRef	GetParent () const
	Get parent of a window.

PropertiesRef	GetProperties () const
	Get the properties associated with a window.

WindowFlags	GetFlags () const
	Get the window flags.

void	SetTitle (StringParam title)
	Set the title of a window.

const char *	GetTitle () const
	Get the title of a window.

void	SetIcon (SurfaceBase &icon)
	Set the icon for a window.

void	SetRect (Rect rect)
	Request the window's position and size to be set.

Rect	GetRect () const
	Get the position and client size of a window.

void	SetPosition (SDL_Point p)
	Request that the window's position be set.

Point	GetPosition () const
	Get the position of a window.

void	GetPosition (int x, int y) const
	Get the position of a window.

void	SetSize (SDL_Point p)
	Request that the size of a window's client area be set.

Point	GetSize () const
	Get the size of a window's client area.

void	GetSize (int w, int h) const
	Get the size of a window's client area.

Rect	GetSafeArea () const
	Get the safe area for this window.

void	SetAspectRatio (float min_aspect, float max_aspect)
	Request that the aspect ratio of a window's client area be set.

void	GetAspectRatio (float min_aspect, float max_aspect) const
	Get the size of a window's client area.

void	GetBordersSize (int top, int left, int bottom, int right) const
	Get the size of a window's borders (decorations) around the client area.

Point	GetSizeInPixels () const
	Get the size of a window's client area, in pixels.

void	GetSizeInPixels (int w, int h) const
	Get the size of a window's client area, in pixels.

void	SetMinimumSize (SDL_Point p)
	Set the minimum size of a window's client area.

void	GetMinimumSize (int w, int h) const
	Get the minimum size of a window's client area.

void	SetMaximumSize (SDL_Point p)
	Set the maximum size of a window's client area.

void	GetMaximumSize (int w, int h) const
	Get the maximum size of a window's client area.

void	SetBordered (bool bordered)
	Set the border state of a window.

void	SetResizable (bool resizable)
	Set the user-resizable state of a window.

void	SetAlwaysOnTop (bool on_top)
	Set the window to always be above the others.

void	Show ()
	Show a window.

void	Hide ()
	Hide a window.

void	Raise ()
	Request that a window be raised above other windows and gain the input focus.

void	Maximize ()
	Request that the window be made as large as possible.

void	Minimize ()
	Request that the window be minimized to an iconic representation.

void	Restore ()
	Request that the size and position of a minimized or maximized window be restored.

void	SetFullscreen (bool fullscreen)
	Request that the window's fullscreen state be changed.

void	Sync ()
	Block until any pending window state is finalized.

bool	HasSurface () const
	Return whether the window has a surface associated with it.

SurfaceRef	GetSurface ()
	Get the SDL surface associated with the window.

void	SetSurfaceVSync (int vsync)
	Toggle VSync for the window surface.

int	GetSurfaceVSync () const
	Get VSync for the window surface.

void	UpdateSurface ()
	Copy the window surface to the screen.

void	UpdateSurfaceRects (SpanRef< const SDL_Rect > rects)
	Copy areas of the window surface to the screen.

void	DestroySurface ()
	Destroy the surface associated with the window.

void	SetKeyboardGrab (bool grabbed)
	Set a window's keyboard grab mode.

void	SetMouseGrab (bool grabbed)
	Set a window's mouse grab mode.

bool	GetKeyboardGrab () const
	Get a window's keyboard grab mode.

bool	GetMouseGrab () const
	Get a window's mouse grab mode.

void	SetMouseRect (const SDL_Rect &rect)
	Confines the cursor to the specified area of a window.

const SDL_Rect *	GetMouseRect () const
	Get the mouse confinement rectangle of a window.

void	SetOpacity (float opacity)
	Set the opacity for a window.

float	GetOpacity () const
	Get the opacity of a window.

void	SetParent (OptionalWindow parent)
	Set the window as a child of a parent window.

void	SetModal (bool modal)
	Toggle the state of the window as modal.

void	SetFocusable (bool focusable)
	Set whether the window may have input focus.

void	ShowSystemMenu (SDL_Point p)
	Display the system-level window menu.

void	SetHitTest (HitTestCB callback)
	Provide a callback that decides if a window region has special properties.

void	SetHitTest (HitTest callback, void *callback_data)
	Provide a callback that decides if a window region has special properties.

void	SetShape (SurfaceBase &shape)
	Set the shape of a transparent window.

void	Flash (FlashOperation operation)
	Request a window to demand attention from the user.

RendererRef	GetRenderer () const
	Get the renderer associated with a window.

void	StartTextInput ()
	Start accepting Unicode text input events in a window.

void	StartTextInput (PropertiesBase &props)
	Start accepting Unicode text input events in a window, with properties describing the input.

bool	IsTextInputActive () const
	Check whether or not Unicode text input events are enabled for a window.

void	StopTextInput ()
	Stop receiving any text input events in a window.

void	ClearComposition ()
	Dismiss the composition window/IME without disabling the subsystem.

void	SetTextInputArea (const SDL_Rect &rect, int cursor)
	Set the area used to type Unicode text input.

void	GetTextInputArea (Rect rect, int cursor)
	Get the area used to type Unicode text input.

bool	IsScreenKeyboardShown () const
	Check whether the screen keyboard is shown for given window.

void	WarpMouse (float x, float y)
	Move the mouse cursor to the given position within the window.

void	SetRelativeMouseMode (bool enabled)
	Set relative mouse mode for a window.

bool	GetRelativeMouseMode () const
	Query whether relative mouse mode is enabled for a window.

constexpr	Resource (T resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Public Member Functions inherited from SDL::Resource< SDL_Window * >
constexpr	Resource (SDL_Window * resource={})
	Constructs the underlying resource.

constexpr	Resource (std::nullptr_t)
	Equivalent to default ctor.

constexpr	Resource (std::nullopt_t)
	Equivalent to default ctor.

	Resource (const Resource &other)=delete

	Resource (Resource &&other)=delete

Resource &	operator= (const Resource &other)=delete

Resource &	operator= (Resource &&other)=delete

constexpr	operator bool () const
	True if contains a valid resource.

constexpr bool	operator== (const Resource &other) const=default
	Comparison.

constexpr bool	operator== (std::nullopt_t) const
	Comparison.

constexpr bool	operator== (std::nullptr_t) const
	Comparison.

constexpr SDL_Window *	get () const
	Return contained resource;.

constexpr SDL_Window *	release (SDL_Window * newResource={})
	Return contained resource and empties or replace value.

constexpr const SDL_Window *	operator-> () const
	Access to fields.

constexpr SDL_Window *	operator-> ()
	Access to fields.

Static Public Member Functions
static WindowRef	FromID (WindowID id)
	Get a window from a stored ID.

static WindowRef	GetGrabbed ()
	Get the window that currently has an input grab enabled.

Detailed Description

Category:: Resource

See also: WindowBase; Window

Member Function Documentation

◆ reset()

void SDL::WindowRef::reset ( SDL_Window * newResource = {} )

inline

Any child windows owned by the window will be recursively destroyed as well.

Note that on some platforms, the visible window may not actually be removed from the screen until the SDL event loop is pumped again, even though the WindowBase is no longer valid after this call.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

◆ WindowBase() [1/3]

SDL::WindowBase::WindowBase ( PropertiesBase & props )

inline

The window size is a request and may be different than expected based on the desktop layout and window manager policies. Your application should be prepared to handle a window of any size.

These are the supported properties:

prop::Window.CREATE_ALWAYS_ON_TOP_BOOLEAN: true if the window should be always on top
prop::Window.CREATE_BORDERLESS_BOOLEAN: true if the window has no window decoration
prop::Window.CREATE_EXTERNAL_GRAPHICS_CONTEXT_BOOLEAN: true if the window will be used with an externally managed graphics context.
prop::Window.CREATE_FOCUSABLE_BOOLEAN: true if the window should accept keyboard input (defaults true)
prop::Window.CREATE_FULLSCREEN_BOOLEAN: true if the window should start in fullscreen mode at desktop resolution
prop::Window.CREATE_HEIGHT_NUMBER: the height of the window
prop::Window.CREATE_HIDDEN_BOOLEAN: true if the window should start hidden
prop::Window.CREATE_HIGH_PIXEL_DENSITY_BOOLEAN: true if the window uses a high pixel density buffer if possible
prop::Window.CREATE_MAXIMIZED_BOOLEAN: true if the window should start maximized
prop::Window.CREATE_MENU_BOOLEAN: true if the window is a popup menu
prop::Window.CREATE_METAL_BOOLEAN: true if the window will be used with Metal rendering
prop::Window.CREATE_MINIMIZED_BOOLEAN: true if the window should start minimized
prop::Window.CREATE_MODAL_BOOLEAN: true if the window is modal to its parent
prop::Window.CREATE_MOUSE_GRABBED_BOOLEAN: true if the window starts with grabbed mouse focus
prop::Window.CREATE_OPENGL_BOOLEAN: true if the window will be used with OpenGL rendering
prop::Window.CREATE_PARENT_POINTER: an WindowBase that will be the parent of this window, required for windows with the "tooltip", "menu", and "modal" properties
prop::Window.CREATE_RESIZABLE_BOOLEAN: true if the window should be resizable
prop::Window.CREATE_TITLE_STRING: the title of the window, in UTF-8 encoding
prop::Window.CREATE_TRANSPARENT_BOOLEAN: true if the window show transparent in the areas with alpha of 0
prop::Window.CREATE_TOOLTIP_BOOLEAN: true if the window is a tooltip
prop::Window.CREATE_UTILITY_BOOLEAN: true if the window is a utility window, not showing in the task bar and window list
prop::Window.CREATE_VULKAN_BOOLEAN: true if the window will be used with Vulkan rendering
prop::Window.CREATE_WIDTH_NUMBER: the width of the window
prop::Window.CREATE_X_NUMBER: the x position of the window, or SDL_WINDOWPOS_CENTERED, defaults to SDL_WINDOWPOS_UNDEFINED. This is relative to the parent for windows with the "tooltip" or "menu" property set.
prop::Window.CREATE_Y_NUMBER: the y position of the window, or SDL_WINDOWPOS_CENTERED, defaults to SDL_WINDOWPOS_UNDEFINED. This is relative to the parent for windows with the "tooltip" or "menu" property set.

These are additional supported properties on macOS:

prop::Window.CREATE_COCOA_WINDOW_POINTER: the (__unsafe_unretained) NSWindow associated with the window, if you want to wrap an existing window.
prop::Window.CREATE_COCOA_VIEW_POINTER: the (__unsafe_unretained) NSView associated with the window, defaults to [window contentView]

These are additional supported properties on Wayland:

prop::Window.CREATE_WAYLAND_SURFACE_ROLE_CUSTOM_BOOLEAN - true if the application wants to use the Wayland surface for a custom role and does not want it attached to an XDG toplevel window. See README/wayland for more information on using custom surfaces.
prop::Window.CREATE_WAYLAND_CREATE_EGL_WINDOW_BOOLEAN - true if the application wants an associated wl_egl_window object to be created and attached to the window, even if the window does not have the OpenGL property or WINDOW_OPENGL flag set.
prop::Window.CREATE_WAYLAND_WL_SURFACE_POINTER - the wl_surface associated with the window, if you want to wrap an existing window. See README/wayland for more information.

These are additional supported properties on Windows:

prop::Window.CREATE_WIN32_HWND_POINTER: the HWND associated with the window, if you want to wrap an existing window.
prop::Window.CREATE_WIN32_PIXEL_FORMAT_HWND_POINTER: optional, another window to share pixel format with, useful for OpenGL windows

These are additional supported properties with X11:

prop::Window.CREATE_X11_WINDOW_NUMBER: the X11 Window associated with the window, if you want to wrap an existing window.

The window is implicitly shown if the "hidden" property is not set.

Windows with the "tooltip" and "menu" properties are popup windows and have the behaviors and guidelines outlined in WindowBase.WindowBase().

If this window is being created to be used with an RendererBase, you should not add a graphics API specific property (prop::Window.CREATE_OPENGL_BOOLEAN, etc), as SDL will handle that internally when it chooses a renderer. However, SDL might need to recreate your window at that point, which may cause the window to appear briefly, and then flicker as it is recreated. The correct approach to this is to create the window with the prop::Window.CREATE_HIDDEN_BOOLEAN property set to true, then create the renderer, then show the window with WindowBase.Show().

Parameters

props the properties to use.

Postcondition: the window that was created.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: Properties.Properties

◆ WindowBase() [2/3]

SDL::WindowBase::WindowBase	(	StringParam	title,
		SDL_Point	size,
		WindowFlags	flags = `0`
	)

inline

The window size is a request and may be different than expected based on the desktop layout and window manager policies. Your application should be prepared to handle a window of any size.

flags may be any of the following OR'd together:

WINDOW_FULLSCREEN: fullscreen window at desktop resolution
WINDOW_OPENGL: window usable with an OpenGL context
WINDOW_OCCLUDED: window partially or completely obscured by another window
WINDOW_HIDDEN: window is not visible
WINDOW_BORDERLESS: no window decoration
WINDOW_RESIZABLE: window can be resized
WINDOW_MINIMIZED: window is minimized
WINDOW_MAXIMIZED: window is maximized
WINDOW_MOUSE_GRABBED: window has grabbed mouse focus
WINDOW_INPUT_FOCUS: window has input focus
WINDOW_MOUSE_FOCUS: window has mouse focus
WINDOW_EXTERNAL: window not created by SDL
WINDOW_MODAL: window is modal
WINDOW_HIGH_PIXEL_DENSITY: window uses high pixel density back buffer if possible
WINDOW_MOUSE_CAPTURE: window has mouse captured (unrelated to MOUSE_GRABBED)
WINDOW_ALWAYS_ON_TOP: window should always be above others
WINDOW_UTILITY: window should be treated as a utility window, not showing in the task bar and window list
WINDOW_TOOLTIP: window should be treated as a tooltip and does not get mouse or keyboard focus, requires a parent window
WINDOW_POPUP_MENU: window should be treated as a popup menu, requires a parent window
WINDOW_KEYBOARD_GRABBED: window has grabbed keyboard input
WINDOW_VULKAN: window usable with a Vulkan instance
WINDOW_METAL: window usable with a Metal instance
WINDOW_TRANSPARENT: window with transparent buffer
WINDOW_NOT_FOCUSABLE: window should not be focusable

The WindowBase is implicitly shown if WINDOW_HIDDEN is not set.

On Apple's macOS, you must set the NSHighResolutionCapable Info.plist property to YES, otherwise you will not receive a High-DPI OpenGL canvas.

The window pixel size may differ from its window coordinate size if the window is on a high pixel density display. Use WindowBase.GetSize() to query the client area's size in window coordinates, and WindowBase.GetSizeInPixels() or RendererBase.GetOutputSize() to query the drawable size in pixels. Note that the drawable size can vary after the window is created and should be queried again if you get an EVENT_WINDOW_PIXEL_SIZE_CHANGED event.

If the window is created with any of the WINDOW_OPENGL or WINDOW_VULKAN flags, then the corresponding LoadLibrary function (GL_LoadLibrary or SDL_Vulkan_LoadLibrary) is called and the corresponding UnloadLibrary function is called by WindowRef.reset().

If WINDOW_VULKAN is specified and there isn't a working Vulkan driver, WindowBase.WindowBase() will fail, because SDL_Vulkan_LoadLibrary() will fail.

If WINDOW_METAL is specified on an OS that does not support Metal, WindowBase.WindowBase() will fail.

If you intend to use this window with an RendererBase, you should use CreateWindowAndRenderer() instead of this function, to avoid window flicker.

On non-Apple devices, SDL requires you to either not link to the Vulkan loader or link to a dynamic library version. This limitation may be removed in a future version of SDL.

Parameters

title	the title of the window, in UTF-8 encoding.
size	the width and height of the window.
flags	0, or one or more WindowFlags OR'd together.

Postcondition: the window that was created.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: CreateWindowAndRenderer()

◆ WindowBase() [3/3]

SDL::WindowBase::WindowBase	(	WindowBase &	parent,
		SDL_Point	offset,
		SDL_Point	size,
		WindowFlags	flags = `0`
	)

inline

The window size is a request and may be different than expected based on the desktop layout and window manager policies. Your application should be prepared to handle a window of any size.

The flags parameter must contain at least one of the following:

WINDOW_TOOLTIP: The popup window is a tooltip and will not pass any input events.
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:

WINDOW_MINIMIZED
WINDOW_MAXIMIZED
WINDOW_FULLSCREEN
WINDOW_BORDERLESS

The following flags are incompatible with popup window creation and will cause it to fail:

WINDOW_UTILITY
WINDOW_MODAL

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, raised, flash, be made a modal window, be the parent of a toplevel 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 or destroyed, any child popup windows will be recursively hidden or destroyed as well. Child popup windows not explicitly hidden will be restored when the parent is shown.

Parameters

parent	the parent of the window, must not be nullptr.
offset	the x, y position of the popup window relative to the origin of the parent.
size	the width and height of the window.
flags	WINDOW_TOOLTIP or WINDOW_POPUP_MENU, and zero or more additional WindowFlags OR'd together.

Postcondition: the window that was created.

Exceptions

Error on failure.

Thread safety:: This function should only be called on the main thread.

Since: This function is available since SDL 3.2.0.

See also: WindowBase.GetParent

The documentation for this struct was generated from the following file:

SDL3pp/SDL3pp_video.h

Public Member Functions

Static Public Member Functions

Detailed Description

Member Function Documentation

◆ reset()

◆ WindowBase() [1/3]

◆ WindowBase() [2/3]

◆ WindowBase() [3/3]