SDL3pp
A slim C++ wrapper for SDL3
|
The struct used as an opaque handle to a window. More...
Public Member Functions | |
constexpr | Window ()=default |
Default ctor. | |
constexpr | Window (const WindowRaw resource) |
Constructs from WindowParam. More... | |
constexpr | Window (const Window &other)=delete |
Copy constructor. | |
constexpr | Window (Window &&other) |
Move constructor. | |
constexpr | Window (const WindowRef &other)=delete |
constexpr | Window (WindowRef &&other)=delete |
Window (StringParam title, const PointRaw &size, WindowFlags flags=0) | |
Create a window with the specified dimensions and flags. More... | |
Window (WindowParam parent, const PointRaw &offset, const PointRaw &size, WindowFlags flags=0) | |
Create a child popup window of the specified parent window. More... | |
Window (PropertiesParam props) | |
Create a window with the specified properties. More... | |
~Window () | |
Destructor. | |
Window & | operator= (Window other) |
Assignment operator. | |
constexpr WindowRaw | get () const |
Retrieves underlying WindowRaw. | |
constexpr WindowRaw | release () |
Retrieves underlying WindowRaw and clear this. | |
constexpr auto | operator<=> (const Window &other) const =default |
Comparison. | |
constexpr bool | operator== (std::nullptr_t _) const |
Comparison. | |
constexpr | operator bool () const |
Converts to bool. | |
constexpr | operator WindowParam () const |
Converts to WindowParam. | |
void | Destroy () |
Destroy a window. More... | |
Display | GetDisplay () const |
Get the display associated with a window. More... | |
float | GetPixelDensity () const |
Get the pixel density of a window. More... | |
float | GetDisplayScale () const |
Get the content display scale relative to a window's pixel size. More... | |
void | SetFullscreenMode (OptionalRef< const DisplayMode > mode) |
Set the display mode to use when a window is visible and fullscreen. More... | |
const DisplayMode & | GetFullscreenMode () const |
Query the display mode to use when a window is visible at fullscreen. More... | |
OwnPtr< void > | GetICCProfile () const |
Get the raw ICC profile data for the screen the window is currently on. More... | |
PixelFormat | GetPixelFormat () const |
Get the pixel format associated with the window. More... | |
WindowID | GetID () const |
Get the numeric ID of a window. More... | |
WindowRef | GetParent () const |
Get parent of a window. More... | |
PropertiesRef | GetProperties () const |
Get the properties associated with a window. More... | |
WindowFlags | GetFlags () const |
Get the window flags. More... | |
void | SetTitle (StringParam title) |
Set the title of a window. More... | |
const char * | GetTitle () const |
Get the title of a window. More... | |
void | SetIcon (SurfaceParam icon) |
Set the icon for a window. More... | |
void | SetRect (Rect rect) |
Request the window's position and size to be set. More... | |
Rect | GetRect () const |
Get the position and client size of a window. More... | |
void | SetPosition (const PointRaw &p) |
Request that the window's position be set. More... | |
Point | GetPosition () const |
Get the position of a window. More... | |
void | GetPosition (int *x, int *y) const |
Get the position of a window. More... | |
void | SetSize (const PointRaw &p) |
Request that the size of a window's client area be set. More... | |
Point | GetSize () const |
Get the size of a window's client area. More... | |
void | GetSize (int *w, int *h) const |
Get the size of a window's client area. More... | |
Rect | GetSafeArea () const |
Get the safe area for this window. More... | |
void | SetAspectRatio (float min_aspect, float max_aspect) |
Request that the aspect ratio of a window's client area be set. More... | |
void | GetAspectRatio (float *min_aspect, float *max_aspect) const |
Get the size of a window's client area. More... | |
void | GetBordersSize (int *top, int *left, int *bottom, int *right) const |
Get the size of a window's borders (decorations) around the client area. More... | |
Point | GetSizeInPixels () const |
Get the size of a window's client area, in pixels. More... | |
void | GetSizeInPixels (int *w, int *h) const |
Get the size of a window's client area, in pixels. More... | |
void | SetMinimumSize (const PointRaw &p) |
Set the minimum size of a window's client area. More... | |
void | GetMinimumSize (int *w, int *h) const |
Get the minimum size of a window's client area. More... | |
void | SetMaximumSize (const PointRaw &p) |
Set the maximum size of a window's client area. More... | |
void | GetMaximumSize (int *w, int *h) const |
Get the maximum size of a window's client area. More... | |
void | SetBordered (bool bordered) |
Set the border state of a window. More... | |
void | SetResizable (bool resizable) |
Set the user-resizable state of a window. More... | |
void | SetAlwaysOnTop (bool on_top) |
Set the window to always be above the others. More... | |
void | Show () |
Show a window. More... | |
void | Hide () |
Hide a window. More... | |
void | Raise () |
Request that a window be raised above other windows and gain the input focus. More... | |
void | Maximize () |
Request that the window be made as large as possible. More... | |
void | Minimize () |
Request that the window be minimized to an iconic representation. More... | |
void | Restore () |
Request that the size and position of a minimized or maximized window be restored. More... | |
void | SetFullscreen (bool fullscreen) |
Request that the window's fullscreen state be changed. More... | |
void | Sync () |
Block until any pending window state is finalized. More... | |
bool | HasSurface () const |
Return whether the window has a surface associated with it. More... | |
Surface | GetSurface () |
Get the SDL surface associated with the window. More... | |
void | SetSurfaceVSync (int vsync) |
Toggle VSync for the window surface. More... | |
int | GetSurfaceVSync () const |
Get VSync for the window surface. More... | |
void | UpdateSurface () |
Copy the window surface to the screen. More... | |
void | UpdateSurfaceRects (SpanRef< const RectRaw > rects) |
Copy areas of the window surface to the screen. More... | |
void | DestroySurface () |
Destroy the surface associated with the window. More... | |
void | SetKeyboardGrab (bool grabbed) |
Set a window's keyboard grab mode. More... | |
void | SetMouseGrab (bool grabbed) |
Set a window's mouse grab mode. More... | |
bool | GetKeyboardGrab () const |
Get a window's keyboard grab mode. More... | |
bool | GetMouseGrab () const |
Get a window's mouse grab mode. More... | |
void | SetMouseRect (const RectRaw &rect) |
Confines the cursor to the specified area of a window. More... | |
const RectRaw * | GetMouseRect () const |
Get the mouse confinement rectangle of a window. More... | |
void | SetOpacity (float opacity) |
Set the opacity for a window. More... | |
float | GetOpacity () const |
Get the opacity of a window. More... | |
void | SetParent (WindowParam parent) |
Set the window as a child of a parent window. More... | |
void | SetModal (bool modal) |
Toggle the state of the window as modal. More... | |
void | SetFocusable (bool focusable) |
Set whether the window may have input focus. More... | |
void | ShowSystemMenu (const PointRaw &p) |
Display the system-level window menu. More... | |
void | SetHitTest (HitTestCB callback) |
Provide a callback that decides if a window region has special properties. More... | |
void | SetHitTest (HitTest callback, void *callback_data) |
Provide a callback that decides if a window region has special properties. More... | |
void | SetShape (SurfaceParam shape) |
Set the shape of a transparent window. More... | |
void | Flash (FlashOperation operation) |
Request a window to demand attention from the user. More... | |
void | StartTextInput () |
Start accepting Unicode text input events in a window. More... | |
void | StartTextInput (PropertiesParam props) |
Start accepting Unicode text input events in a window, with properties describing the input. More... | |
bool | IsTextInputActive () const |
Check whether or not Unicode text input events are enabled for a window. More... | |
void | StopTextInput () |
Stop receiving any text input events in a window. More... | |
void | ClearComposition () |
Dismiss the composition window/IME without disabling the subsystem. More... | |
void | SetTextInputArea (const RectRaw &rect, int cursor) |
Set the area used to type Unicode text input. More... | |
void | GetTextInputArea (RectRaw *rect, int *cursor) |
Get the area used to type Unicode text input. More... | |
bool | IsScreenKeyboardShown () const |
Check whether the screen keyboard is shown for given window. More... | |
void | WarpMouse (const FPointRaw &p) |
Move the mouse cursor to the given position within the window. More... | |
void | SetRelativeMouseMode (bool enabled) |
Set relative mouse mode for a window. More... | |
bool | GetRelativeMouseMode () const |
Query whether relative mouse mode is enabled for a window. More... | |
RendererRef | GetRenderer () const |
Get the renderer associated with a window. More... | |
Static Public Member Functions | |
static WindowRef | FromID (WindowID id) |
Get a window from a stored ID. More... | |
static WindowRef | GetGrabbed () |
Get the window that currently has an input grab enabled. More... | |
|
inlineexplicitconstexpr |
resource | a WindowRaw to be wrapped. |
This assumes the ownership, call release() if you need to take back.
|
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 resolutionWINDOW_OPENGL
: window usable with an OpenGL contextWINDOW_OCCLUDED
: window partially or completely obscured by another windowWINDOW_HIDDEN
: window is not visibleWINDOW_BORDERLESS
: no window decorationWINDOW_RESIZABLE
: window can be resizedWINDOW_MINIMIZED
: window is minimizedWINDOW_MAXIMIZED
: window is maximizedWINDOW_MOUSE_GRABBED
: window has grabbed mouse focusWINDOW_INPUT_FOCUS
: window has input focusWINDOW_MOUSE_FOCUS
: window has mouse focusWINDOW_EXTERNAL
: window not created by SDLWINDOW_MODAL
: window is modalWINDOW_HIGH_PIXEL_DENSITY
: window uses high pixel density back buffer if possibleWINDOW_MOUSE_CAPTURE
: window has mouse captured (unrelated to MOUSE_GRABBED)WINDOW_ALWAYS_ON_TOP
: window should always be above othersWINDOW_UTILITY
: window should be treated as a utility window, not showing in the task bar and window listWINDOW_TOOLTIP
: window should be treated as a tooltip and does not get mouse or keyboard focus, requires a parent windowWINDOW_POPUP_MENU
: window should be treated as a popup menu, requires a parent windowWINDOW_KEYBOARD_GRABBED
: window has grabbed keyboard inputWINDOW_VULKAN
: window usable with a Vulkan instanceWINDOW_METAL
: window usable with a Metal instanceWINDOW_TRANSPARENT
: window with transparent bufferWINDOW_NOT_FOCUSABLE
: window should not be focusableThe Window 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 Window.GetSize() to query the client area's size in window coordinates, and Window.GetSizeInPixels() or Renderer.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 Vulkan_LoadLibrary) is called and the corresponding UnloadLibrary function is called by Window.Destroy().
If WINDOW_VULKAN is specified and there isn't a working Vulkan driver, Window.Window() will fail, because Vulkan_LoadLibrary() will fail.
If WINDOW_METAL is specified on an OS that does not support Metal, Window.Window() will fail.
If you intend to use this window with an Renderer, 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.
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. |
|
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.
By default, popup window positions will automatically be constrained to keep the entire window within display bounds. This can be overridden with the 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 WINDOW_NOT_FOCUSABLE
flag, setting the prop::Window.CREATE_FOCUSABLE_BOOLEAN
property to false, or toggling it after creation via the Window.SetFocusable()
function.
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.
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. |
|
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 topprop::Window.CREATE_BORDERLESS_BOOLEAN
: true if the window has no window decorationprop::Window.CREATE_CONSTRAIN_POPUP_BOOLEAN
: true if the "tooltip" and "menu" window types should be automatically constrained to be entirely within display bounds (default), false if no constraints on the position are desired.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 resolutionprop::Window.CREATE_HEIGHT_NUMBER
: the height of the windowprop::Window.CREATE_HIDDEN_BOOLEAN
: true if the window should start hiddenprop::Window.CREATE_HIGH_PIXEL_DENSITY_BOOLEAN
: true if the window uses a high pixel density buffer if possibleprop::Window.CREATE_MAXIMIZED_BOOLEAN
: true if the window should start maximizedprop::Window.CREATE_MENU_BOOLEAN
: true if the window is a popup menuprop::Window.CREATE_METAL_BOOLEAN
: true if the window will be used with Metal renderingprop::Window.CREATE_MINIMIZED_BOOLEAN
: true if the window should start minimizedprop::Window.CREATE_MODAL_BOOLEAN
: true if the window is modal to its parentprop::Window.CREATE_MOUSE_GRABBED_BOOLEAN
: true if the window starts with grabbed mouse focusprop::Window.CREATE_OPENGL_BOOLEAN
: true if the window will be used with OpenGL renderingprop::Window.CREATE_PARENT_POINTER
: an Window that will be the parent of this window, required for windows with the "tooltip", "menu", and "modal" propertiesprop::Window.CREATE_RESIZABLE_BOOLEAN
: true if the window should be resizableprop::Window.CREATE_TITLE_STRING
: the title of the window, in UTF-8 encodingprop::Window.CREATE_TRANSPARENT_BOOLEAN
: true if the window show transparent in the areas with alpha of 0prop::Window.CREATE_TOOLTIP_BOOLEAN
: true if the window is a tooltipprop::Window.CREATE_UTILITY_BOOLEAN
: true if the window is a utility window, not showing in the task bar and window listprop::Window.CREATE_VULKAN_BOOLEAN
: true if the window will be used with Vulkan renderingprop::Window.CREATE_WIDTH_NUMBER
: the width of the windowprop::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 windowsThese 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 Window.Window().
If this window is being created to be used with an Renderer, 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 Window.Show().
props | the properties to use. |
|
inline |
This is the current position of the window as last reported by the windowing system.
Error | on failure. |
|
inline |
This is the current position of the window as last reported by the windowing system.
The window pixel size may differ from its window coordinate size if the window is on a high pixel density display. Use Window.GetSizeInPixels() or RendererRef.GetOutputSize() to get the real client area size in pixels.
Error | on failure. |
|
inline |
The window pixel size may differ from its window coordinate size if the window is on a high pixel density display. Use GetSizeInPixels() or Renderer.GetOutputSize() to get the real client area size in pixels.
|
inline |
void SDL::Window::SetHitTest | ( | HitTest | callback, |
void * | callback_data | ||
) |
Normally windows are dragged and resized by decorations provided by the system window manager (a title bar, borders, etc), but for some apps, it makes sense to drag them from somewhere else inside the window itself; for example, one might have a borderless window that wants to be draggable from any part, or simulate its own title bar, etc.
This function lets the app provide a callback that designates pieces of a given window as special. This callback is run during event processing if we need to tell the OS to treat a region of the window specially; the use of this callback is known as "hit testing."
Mouse input may not be delivered to your application if it is within a special area; the OS will often apply that input to moving the window or resizing the window and not deliver it to the application.
Specifying nullptr for a callback disables hit-testing. Hit-testing is disabled by default.
Platforms that don't support this functionality will return false unconditionally, even if you're attempting to disable hit-testing.
Your callback may fire at any time, and its firing does not indicate any specific behavior (for example, on Windows, this certainly might fire when the OS is deciding whether to drag your window, but it fires for lots of other reasons, too, some unrelated to anything you probably care about and when the mouse isn't actually at the location it is testing). Since this can fire at any time, you should try to keep your callback efficient, devoid of allocations, etc.
callback | the function to call when doing a hit-test. |
callback_data | an app-defined void pointer passed to callback. |
Error | on failure. |
|
inline |
Normally windows are dragged and resized by decorations provided by the system window manager (a title bar, borders, etc), but for some apps, it makes sense to drag them from somewhere else inside the window itself; for example, one might have a borderless window that wants to be draggable from any part, or simulate its own title bar, etc.
This function lets the app provide a callback that designates pieces of a given window as special. This callback is run during event processing if we need to tell the OS to treat a region of the window specially; the use of this callback is known as "hit testing."
Mouse input may not be delivered to your application if it is within a special area; the OS will often apply that input to moving the window or resizing the window and not deliver it to the application.
Specifying nullptr for a callback disables hit-testing. Hit-testing is disabled by default.
Platforms that don't support this functionality will return false unconditionally, even if you're attempting to disable hit-testing.
Your callback may fire at any time, and its firing does not indicate any specific behavior (for example, on Windows, this certainly might fire when the OS is deciding whether to drag your window, but it fires for lots of other reasons, too, some unrelated to anything you probably care about and when the mouse isn't actually at the location it is testing). Since this can fire at any time, you should try to keep your callback efficient, devoid of allocations, etc.
callback | the function to call when doing a hit-test. |
Error | on failure. |
|
inline |
rect | the rect containing the new coordinates |
Error | on failure. |