Class Window

Namespace: Sdl3Sharp.Video.Windowing

Assembly: Sdl3Sharp.dll

Represents a window

public abstract class Window : IDisposable

Inheritance: object

Window

Implements: IDisposable

Derived: Window<TDriver>

Inherited Members: object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

A window is used to display content on the screen and receive input from the user.

To display content in a window, you can either use a Renderer, constructed from any of the TryCreateRenderer* methods (e.g. TryCreateRenderer(out Renderer?, params ReadOnlySpan<string>) or from the TryCreateWithRenderer(string, int, int, out Window?, out Renderer?, WindowFlags) methods, or use the Surface property to get a WindowSurface you can draw on. Using either one mutually excludes the other.

If you use a Renderer in conjunction with a Window, please make sure that you don't use it after the window has been disposed. The recommended approach is to dispose the renderer before the window.

Windows can be either top-level or be children of other windows. To make a window a child of another window, you just need to set its Parent property.

Special rules apply for child windows: they will be hidden with their parent and will be destroyed when their parent gets destroyed.

You can create new windows using any of the TryCreate* methods (e.g. TryCreate(string, int, int, out Window?, WindowFlags)) or create new popup windows using the TryCreatePopup(int, int, int, int, out Window?, WindowFlags) method. The latter will create the new window as a child window of the window the method was called on.

For the most part Windows are not thread-safe, and most of their properties and methods should only be accessed from the main thread!

Windows are not driver-agnostic! Most of the time instance of this abstract class are of the concrete Window<TDriver> type with a specific windowing driver as the type argument. However, the Window type exists as a common abstraction.

To specify a concrete window type, use Window<TDriver> with a windowing driver that implements the IWindowingDriver interface (e.g. Window<Windows>).

Properties

AllWindows

Gets a collection of all currently valid windows

public static Window[] AllWindows { get; }

Property Value

Window[]: A collection of all currently valid windows

Exceptions

SdlException: Couldn't get the list of windows

AspectRatio

Gets or sets the range of aspect ratios for the window's client area

public (float Minimum, float Maximum) AspectRatio { get; set; }

Property Value

(float Integer, float Fractional): The range of aspect ratios for the window's client area. The minimum is the lower limit of the aspect ratio, or 0 for no lower limit set. The maximum is the upper limit of the aspect ratio, or 0 for no upper limit set.

Remarks

The aspect ratio is the ratio of width divided by height, e.g. 2560 by 1600 would be 1.6. Larger aspect ratios are wider and smaller aspect ratios are narrower.

If the window is in a fixed-size state, such as maximized or fullscreen, when setting this property, the request will be deferred until the window exits that state and becomes resizable again.

On some windowing backends, a request to change this setting is asynchronous and the new window aspect ratio may not have have been applied immediately upon setting this property. If an immediate change is required, you can call TrySync() to block until the changes have taken effect.

When the window size changes, an WindowResized event will be emitted with the new window dimensions. Note that the new dimensions may not match the exact aspect ratio requested, as some windowing backends can restrict the window size in certain scenarios (e.g. constraining the size of the content area to remain within the usable desktop bounds). Additionally, windowing backends can also deny the request to change this setting altogether.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information)

BordersSize

Gets the size of the window's borders (decorations) around the client area

public (int Top, int Left, int Bottom, int Right) BordersSize { get; }

Property Value

(int Top, int Left, int Bottom, int Right): The size of the window's borders (decorations) around the client area, in pixels

Remarks

Note that if this property fails to retrieve the borders size, the size values will be initialized to (0, 0, 0, 0) instead.

This property can fail to retrieve the borders size on platforms where the window has not yet been decorated by the display server (for example, immediately after creating the Window). It is recommended that you wait at least until the window has been presented and composited, so that the window backend has a chance to decorate the window and provide the border dimensions to SDL.

This property can also fail to retrieve the borders size if getting that information is not supported.

This property should only be accessed from the main thread.

Display

Gets the display associated with the window

public Display Display { get; }

Property Value

Display: The display associated with the window, which is the display containing the center of the window

Remarks

The value of the property sometimes reports the primary display instead, if SDL couldn't determine the actual display the window is on.

Accessing this property can also throw an SdlException under some rare circumstances, for example if there are no connected displays at all.

This property should only be accessed from the main thread.

Exceptions

SdlException: Couldn't get the display for the window (check TryGet(out string?) for more information)

DisplayScale

Gets the content display scale relative to the window's pixel size

public float DisplayScale { get; }

Property Value

float: The content display scale relative to the window's pixel size

Remarks

The value of this property is a combination of the window pixel density and the display content scale, and is the expected scale for displaying content in this window. For example, if a 3840 by 2160 window had a display scale of 2.0, the user expects the content to take twice as many pixels and be the same physical size as if it were being displayed in a 1920 by 1080 window with a display scale of 1.0.

Conceptually this value corresponds to the scale display setting, and is updated when that setting is changed, or the window moves to a display with a different scale setting.

This property should only be accessed from the main thread.

Flags

Gets the flags associated with the window

public WindowFlags Flags { get; }

Property Value

WindowFlags: The flags associated with the window

Remarks

This property should only be accessed from the main thread.

FullscreenMode

Gets or sets the DisplayMode to use when the window is visible at fullscreen

public DisplayMode? FullscreenMode { get; set; }

Property Value

DisplayMode: The DisplayMode to use when the window is visible at fullscreen, or null for borderless fullscreen desktop mode

Remarks

This property only effects the display mode used when the window is in fullscreen mode. To change the window's size when it's not in fullscreen mode, use the Size property instead.

If the window is currently in the fullscreen state, a request to change this setting is asynchronous and the new display mode may not have have been applied immediately upon setting this property. If an immediate change is required, you can call TrySync() to block until the changes have taken effect.

When the new display mode takes effect, an WindowResized and/or an WindowPixelSizeChanged event will be emitted with the new display mode's dimensions.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

GrabbedWindow

Gets the window that currently has the input grab, if any

public static Window? GrabbedWindow { get; }

Property Value

Window: The window that currently has the input grab, or null if there's no such window

Remarks

This property should only be accessed from the main thread.

HasKeyboardGrab

Gets or sets a value indicating whether the window has grabbed keyboard input

public bool HasKeyboardGrab { get; set; }

Property Value

bool: A value indicating whether the window has grabbed keyboard input

Remarks

Keyboard grab enables capture of system keyboard shortcuts like Alt+Tab or the Meta/Super key. Note that not all system keyboard shortcuts can be captured by applications (one notable example is Ctrl+Alt+Del on Windows).

This property is primarily intended for use by specialized applications such as VNC clients or VM frontends. Normal games should not use keyboard grab.

When keyboard grab is enabled, SDL will continue to handle Alt+Tab when the window is fullscreen to ensure the user is not trapped in your application. If you have a custom keyboard shortcut to exit fullscreen mode, you may suppress this behavior with a setting of AllowAltTabWhileGrabbed.

If the keyboard grab is enabled on a window while another window currently has the keyboard grab, the other window loses its grab in favor of the window where the grab was just enabled.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

HasMouseGrab

Gets or sets a value indicating whether the window has grabbed mouse input

public bool HasMouseGrab { get; set; }

Property Value

bool: A value indicating whether the window has grabbed mouse input

Remarks

Mouse grab confines the mouse cursor to the area of the window.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

HasSurface

Gets a value indicating whether the window currently has a Surface associated with it

public bool HasSurface { get; }

Property Value

bool: A value indicating whether the window currently has a Surface associated with it

Remarks

If the value of this property is true, you can access the Surface property and get the existing associated surface, otherwise, if the value is false, accessing the Surface property will create a new surface and associate it with the window.

This property should only be accessed from the main thread.

HdrHeadroom

Gets the additional high dynamic range that can be displayed, in terms of the SDR white level

public float HdrHeadroom { get; }

Property Value

float: The additional high dynamic range that can be displayed, in terms of the SDR white level

Remarks

The value of this property will be 1.0 when HDR is not enabled.

The value of this property can change dynamically at runtime when a WindowHdrStateChanged event is sent.

HitTest

Gets or sets the custom hit test deciding whether a window region has special properties

public HitTest? HitTest { get; set; }

Property Value

HitTest: The custom hit test deciding whether a window region has special properties, or null if no custom hit test is set for the window

Remarks

Normally windows are dragged and resized by decorations provided by the system window manager (a title bar, borders, etc), but for some applications, it makes sense to drag them from somewhere else inside the window itself. For example, you might want to create a borderless window that the user can drag from any part, or you to simulate your own title bar, etc.

This property lets the application provide a delegate that's called to determine whether certain regions of the window are special. This delegate is run during event processing when SDL needs to tell the operating system to treat a region of the window specially. This process is called "hit testing."

Mouse input may not be delivered to your application if it is within a special area. The operating system will often apply that input to moving the window or resizing the window and not deliver it to the application.

Specifying null for this property disables hit testing. Hit testing is disabled by default.

Some platforms may not support this functionality and will throw a SdlException when you attempt to set this property, even if you attempt to set it to null to disable hit testing.

The provided delegate may be called at any time, and it being called does not indicate any specific behavior. For example, on Windows, the delegate certainly might called when the operating system is trying to decide whether to drag your window. But it will be called for lot of other reasons too, some of which might be unrelated to anything you probably care about and even when the mouse isn't actually at the location it is testing. Since the delegate can be called at any time, you should try to keep it as efficient as possible and try to avoid doing any heavy or potentially time-consuming/blocking work in it.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

Id

Gets the numeric ID of the window

public uint Id { get; }

Property Value

uint: The numeric ID of the window, or 0 on failure (check TryGet(out string?) for more information)

Remarks

This the ID that SDL uses to identify windows in WindowEvents and some other events. It's a necessity in order to map such events to their corresponding Window instances using TryGetFromId(uint, out Window?).

This property should only be accessed from the main thread.

IsAlwaysOnTop

Gets or sets a value indicating whether the window should always be above other windows

public bool IsAlwaysOnTop { get; set; }

Property Value

bool: A value indicating whether the window should always be above other windows

Remarks

Setting this property to true will bring the window to the front and keep it above other windows.

The value of this property is reflected as the AlwaysOnTop flag in the Flags property of the window.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

IsBordered

Gets or sets a value indicating whether the window has a border (decorations) around the client area

public bool IsBordered { get; set; }

Property Value

bool: A value indicating whether the window has a border (decorations) around the client area

Remarks

Changing this property will add or remove the window's border (decorations) around the client area. It's a no-op if the window's border state already matches the given value.

You can't change the border state of a fullscreen window!

The inverse value of this property is reflected as the Borderless flag in the Flags property of the window.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

IsFocusable

Gets or sets a value indicating whether the window may have input focus

public bool IsFocusable { get; set; }

Property Value

bool: A value indicating whether the window may have input focus

Remarks

The inverse value of this property is reflected as the NotFocusable flag in the Flags property of the window.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

IsFullscreen

Gets or sets a value indicating whether the window is currently in fullscreen mode

public bool IsFullscreen { get; set; }

Property Value

bool: A value indicating whether the window is currently in fullscreen mode

Remarks

By default a window in fullscreen mode uses borderless fullscreen desktop mode, but you can specify an exclusive display mode using the FullscreenMode property.

On some windowing backends, a request to change this setting is asynchronous and the new fullscreen state may not have have been applied immediately upon setting this property. If an immediate change is required, you can call TrySync() to block until the changes have taken effect.

When the fullscreen state changed, an WindowEnterFullscreen or an WindowLeaveFullscreen event will be emitted. Windowing backends can also deny the request to change this setting altogether.

The value of this property is reflected as the Fullscreen flag in the Flags property of the window.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

IsHdrEnabled

Gets a value indicating whether the window has HDR headroom above the SDR white level

public bool IsHdrEnabled { get; }

Property Value

bool: A value indicating whether the window has HDR headroom above the SDR white level

Remarks

The value of this property can change dynamically at runtime when a WindowHdrStateChanged event is sent.

IsModal

Gets or sets a value indicating whether the window is modal

public bool IsModal { get; set; }

Property Value

bool: A value indicating whether the window is modal

Remarks

To enable the modal state for a window, the window must be a child of another window, or else this property will throw a SdlException when you attempt to set it to true. You can set the parent of a window using the Parent property.

The value of this property is reflected as the Modal flag in the Flags property of the window.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

IsResizable

Gets or sets a value indicating whether the window is resizable by the user

public bool IsResizable { get; set; }

Property Value

bool: A value indicating whether the window is resizable by the user

Remarks

Changing this property will allow or disallow the user from resizing the window. It's a no-op if the window's resizable state already matches the given value.

The value of this property is reflected as the Resizable flag in the Flags property of the window.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

IsValid

Gets a value indicating whether the window is valid

public bool IsValid { get; }

Property Value

bool: A value indicating whether the window is valid

Remarks

A Window instance can become invalid after it's been disposed, or it's associated native window has been destroyed.

The latter can be the case, for example, for child windows that become invalid when their parent window is disposed/destroyed. You need to be careful when handling the lifetime of child windows in relation to their parent windows. It's the best to dispose child windows before their parent windows, or resetting their parent to something else (or null) before their parent windows are disposed/destroyed. You can check if a window has a parent or change their parent using the Parent property.

MaximumSize

Gets or sets the maximum size of the window's client area

public (int Width, int Height) MaximumSize { get; set; }

Property Value

(int Width, int Height): A value indicating the maximum size of the window's client area, or 0 individually for the width or height component to indicate no maximum limit set for that component

Remarks

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information)

MinimumSize

Gets or sets the minimum size of the window's client area

public (int Width, int Height) MinimumSize { get; set; }

Property Value

(int Width, int Height): A value indicating the minimum size of the window's client area, or 0 individually for the width or height component to indicate no minimum limit set for that component

Remarks

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information)

MouseRect

Gets or sets the area of the window the mouse cursor is confined to

public Rect<int>? MouseRect { get; set; }

Property Value

Rect<int>?: The area of the window the mouse cursor is confined to, or null if the mouse cursor is not confined

Remarks

Note that setting the value of this property to some non-null area, does not grab the cursor, it only defines the area the mouse cursor is restricted to when the window has mouse focus. If you want to grab the cursor, you can use the HasMouseGrab property for that.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

Opacity

Gets or sets the opacity of the window

public float Opacity { get; set; }

Property Value

float: The opacity of the window, where 1.0 is fully opaque, 0.0 is fully transparent, and -1.0 indicates an error when getting the value (check TryGet(out string?) for more information)

Remarks

The value set will be clamped to the range of 0.0 to 1.0.

If transparency isn't supported on the current platform, the value of this property will be 1.0 (as opposed to -1.0 to indicate an error) when getting it, but this property will still throw an SdlException when you attempt to set it.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

Parent

Gets or sets the parent of the window, if any

public Window? Parent { get; set; }

Property Value

Window: The parent of the window, or null if the window has no parent

Remarks

Setting the value of this property to a non-null window will make the current window a child of that window, and setting it to null will make the current window a top-level window. If the window is already the child of an existing window, it will be reparented to the new parent window.

If a parent window is hidden or disposed/destroyed, this will also be recursively applied to all child windows.

Child windows that weren't explicitly hidden (e.g. via TryHide()) but were only hidden because their parent was hidden, will be automatically shown again when their parent is shown again.

You need to be careful when handling the lifetime of child windows in relation to their parent windows. It's the best to dispose child windows before their parent windows, or resetting their parent to something else (or null) before their parent windows are disposed/destroyed.

Attempting to set the parent of a window that is currently in the modal state will throw a SdlException. You can use the IsModal property to check if a window is currently in the modal state, and set it to false to disable the modal state before attempting to change the parent.

Additionally, popup windows cannot change parents and attempts to do so will throw a SdlException.

Setting a parent window that is currently the sibling or descendent of the child window results in undefined behavior. Please try to avoid doing that.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

PixelDensity

Gets the pixel density of the window

public float PixelDensity { get; }

Property Value

float: The pixel density of the window, or 0.0 on failure (check TryGet(out string?) for more information)

Remarks

The pixel density is the ratio of pixel size to window size. For example, if the window is 1920 by 1080 and it has a high density back buffer of 3840 by 2160 pixels, it would have a pixel density of 2.0.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

PixelFormat

Gets the pixel format associated with the window

public PixelFormat PixelFormat { get; }

Property Value

PixelFormat: The pixel format associated with the window, or Unknown on failure (check TryGet(out string?) for more information)

Remarks

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

Position

Gets the position of the window

public (int X, int Y) Position { get; }

Property Value

(int Width, int Height): The position of the window

Remarks

The value of this property is the position of the window as it was last reported by the windowing backend.

If you want to set the position of the window, you can use the TrySetPosition(WindowPosition, WindowPosition) method instead.

This property should only be accessed from the main thread.

Exceptions

SdlException: When getting this property, SDL failed with an error (check TryGet(out string?) for more information)

ProgressState

Gets or sets the state of the progress bar displayed for the window's taskbar entry

public ProgressState ProgressState { get; set; }

Property Value

ProgressState: The state of the progress bar displayed for the window's taskbar entry, or Invalid on failure (check TryGet(out string?) for more information)

Remarks

You can use this property in conjunction with the ProgressValue property to display a progress bar with a certain value in the taskbar entry for the window.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

ProgressValue

Gets or sets the value of the progress bar displayed for the window's taskbar entry

public float ProgressValue { get; set; }

Property Value

float: The value of the progress bar displayed for the window's taskbar entry, where 0.0 is no progress, 1.0 is full progress

Remarks

The value set will be clamped to the range of 0.0 to 1.0.

You can use this property in conjunction with the ProgressState property to display a progress bar with a certain value in the taskbar entry for the window.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

Properties

Gets the properties associated with the window

public Properties? Properties { get; }

Property Value

Properties: The properties associated with the window, or null if the properties could not be retrieved successfully (check TryGet(out string?) for more information)

Remarks

This property should only be accessed from the main thread.

Renderer

Gets the renderer associated with the window, if any

public Renderer? Renderer { get; }

Property Value

Renderer: The renderer associated with the window, or null if the window has no renderer or the renderer couldn't be retrieved successfully (check TryGet(out string?) for more information)

Remarks

Initially, a window can have no renderer associated with it if it was created without one (e.g. it was created with TryCreate(string, int, int, out Window?, WindowFlags) instead of TryCreateWithRenderer(string, int, int, out Window?, out Renderer?, WindowFlags)). The value of this property will be null in that case, as long as no renderer has been associated with the window yet.

The value of this property can also be null if the renderer couldn't be retrieved successfully. You should check TryGet(out string?) for more information and to see if that's the case.

You can set a renderer for a window by using any of the TryCreateRenderer* methods (e.g. TryCreateRenderer(out Renderer?, params ReadOnlySpan<string>)) on the window instance, but only once. Once a renderer is successfully associated with the window, it can't be replaced and subsequently calls to any of the TryCreateRenderer* methods will fail.

SafeArea

Gets the safe area of the window

public Rect<int> SafeArea { get; }

Property Value

Rect<int>: The safe area of the window

Remarks

Some devices have portions of the screen which are partially obscured or not interactive, possibly due to on-screen controls, curved edges, camera notches, TV overscan, etc. This property provides the area of the current viewport which is safe to have interactible content. You should continue rendering into the rest of the window, but it should not contain visually important or interactible content.

This property should only be accessed from the main thread.

SdrWhiteLevel

Gets the value of SDR white in the Srgb color space for the window

public float SdrWhiteLevel { get; }

Property Value

float: The value of SDR white in the Srgb color space for the window

Remarks

On Windows the value of this property corresponds to the SDR white level in scRGB color space, and on Apple platform this is always 1.0 for EDR content.

The value of this property can change dynamically at runtime when a WindowHdrStateChanged event is sent.

Shape

Gets or sets the shape associated with the window, if any

public Surface? Shape { get; set; }

Property Value

Surface: The shape associated with the window, or null if the window has no associated shape

Remarks

The alpha channel of the shape associated with the transparent window is used to determine the shape "visible" to the mouse cursor. Fully transparent areas of the shape are also transparent to mouse clicks.

If you are using something else besides SDL to render the window, then you are responsible for drawing the alpha channel of the window to match the shape's alpha channel to get consistent cross-platform results.

The given Surface when setting this property is copied, so you can safely dispose of it after setting the property if you don't need it anymore. This also means that changes to the given surface after setting this property won't affect the shape of the window and you'd need to set this property again with the updated surface to change the shape of the window.

Setting this property is an expensive operation and should be done sparingly.

The window must have been created with the Transparent flag to be able to associate a shape with it. Attempting to set a shape for a window that wasn't created with the Transparent flag will throw a SdlException.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting this property, SDL failed with an error (check TryGet(out string?) for more information)

Size

Gets or sets the size of the window's client area

public (int Width, int Height) Size { get; set; }

Property Value

(int Width, int Height): The size of the window's client area

Remarks

The size of the window's client area reported by this property might be different from the size in pixels of the window's client area. This is especially the case if the window is on a display with a high pixel density. To get the real client area size in pixels, you can use the SizeInPixels property or the OutputSize property (on the associated Renderer) instead.

Setting the size of a window when the window is in fullscreen mode or maximized has no effect. To change the size of a window in fullscreen mode, you can use the FullscreenMode property instead.

On some windowing backends, a request to change this setting is asynchronous and the new window size may not have have been applied immediately upon setting this property. If an immediate change is required, you can call TrySync() to block until the changes have taken effect.

When the window size changes, an WindowResized event will be emitted with the new window dimensions. Note that the new dimensions may not match the exact size requested, as some windowing backends can restrict the window size in certain scenarios (e.g. constraining the size of the content area to remain within the usable desktop bounds). Additionally, windowing backends can also deny the request to change this setting altogether.

This property should only be accessed from the main thread.

Exceptions

SdlException: When setting or getting this property, SDL failed with an error (check TryGet(out string?) for more information)

SizeInPixels

Gets the size in pixels of the window's client area

public (int Width, int Height) SizeInPixels { get; }

Property Value

(int Width, int Height): The size in pixels of the window's client area

Remarks

The size in pixels of the window's client area reported by this property might be different from the size of the window's client area reported by the Size property. This is especially the case if the window is on a display with a high pixel density.

If you want to set the size of the window's client area, you must use the Size property instead, but keep in mind that the sizes might differ.

This property should only be accessed from the main thread.

Exceptions

SdlException: When getting this property, SDL failed with an error (check TryGet(out string?) for more information)

Surface

Gets the WindowSurface associated with the window

public WindowSurface Surface { get; }

Property Value

WindowSurface: The WindowSurface associated with the window

Remarks

If necessary, a new surface will be created with the optimal format for the window. While you don't need to dispose of the surface manually, doing so will invalidate the surface and a new one will be created the next time you access this property.

You can check the HasSurface to determine whether the window currently has a valid surface associated with it. If the value of the HasSurface property is true, you can access the Surface property and get the existing associated surface, otherwise, if the value is false, accessing the Surface property will create a new surface and associate it with the window. If you don't want to create a new surface unnecessarily, you should check the HasSurface property before accessing the Surface property!

WindowSurfaces can be used as an alternative to using a Renderer on the window.

To reflect changes made to the surface, you need to call either the TryUpdate() or TryUpdateRects(ReadOnlySpan<Rect<int>>) method on the surface, in order for the surface to be copied to screen and displayed as the window's content. Changes to the surface won't be displayed until you call one of those methods.

Do not attempt to use a WindowSurface together with a Renderer on the same Window! They are meant to be used mutually exclusively for the same Window.

The surface associated with the window will be invalidated if the window is resized. After resizing a window you need to access this property again to get a new valid surface.

This property is affected by the FrameBufferAcceleration hint.

This property should only be accessed from the main thread.

Title

Gets or sets the title of the window

public string Title { get; set; }

Property Value

string: The title of the window

Remarks

Depending on the platform and windowing backend, Unicode characters may be allowed in the window title.

Methods

Dispose()

Disposes the window

public void Dispose()

Remarks

After disposing a Window, it becomes invalid and all of its associated resources (e.g. Renderer, Surface, etc.) will be invalidated as well. Do not attempt to access or use any of those resources after the window has been disposed.

This method should only be called from the main thread.

~Window()

protected ~Window()

TryCreate(out Window?, bool?, bool?, bool?, bool?, WindowFlags?, bool?, bool?, int?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, Window?, bool?, string?, bool?, bool?, bool?, bool?, int?, WindowPosition?, WindowPosition?, Properties?)

Tries to create a new Window with the specified parameters

public static bool TryCreate(out Window? window, bool? alwaysOnTop = null, bool? bordered = null, bool? constrainPopup = null, bool? externalGraphicsContext = null, WindowFlags? flags = null, bool? focusable = null, bool? fullscreen = null, int? height = null, bool? hidden = null, bool? highPixelDensity = null, bool? maximized = null, bool? menu = null, bool? metal = null, bool? minimized = null, bool? modal = null, bool? mouseGrabbed = null, bool? openGL = null, Window? parent = null, bool? resizable = null, string? title = null, bool? transparent = null, bool? tooltip = null, bool? utility = null, bool? vulkan = null, int? width = null, WindowPosition? x = null, WindowPosition? y = null, Properties? properties = null)

Parameters

window Window: The resulting Window, if this method returns true; otherwise, null
alwaysOnTop bool?: A value indicating whether the window should always be above others
bordered bool?: A value indicating whether the window should have a border (decorations)
constrainPopup bool?: A value indicating whether a "tooltip" or "menu" popup window should be automatically constrained to the bounds of the display. If this parameter is null (the default), the default behavior is to constrain popup windows.
externalGraphicsContext bool?: A value indicating whether the window will be used with an externally managed graphics context
flags WindowFlags?: The flags the window should be created with
focusable bool?: A value indicating whether the window should accept input focus. If this parameter is null (the default), the default behavior is to accept input focus.
fullscreen bool?: A value indicating whether the window should be created initially in fullscreen mode at desktop resolution
height int?: The height of the window
hidden bool?: A value indicating whether the window should be created initially hidden
highPixelDensity bool?: A value indicating whether the window should be created with a high pixel density buffer, if possible
maximized bool?: A value indicating whether the window should be created initially maximized
menu bool?: A value indicating whether the window should be created as a "menu" popup window. If this parameter is set to true, you must specify a parent window for the window to be created.
metal bool?: A value indicating whether the window will be used with Metal rendering
minimized bool?: A value indicating whether the window should be created initially minimized
modal bool?: A value indicating whether the window should be created as modal to its parent window. If this parameter is set to true, you must specify a parent window for the window to be created.
mouseGrabbed bool?: A value indicating whether the window should be created initially with the mouse grabbed
openGL bool?: A value indicating whether the window will be used with OpenGL rendering
parent Window: The parent Window of the window to be created. You must specify a non-null window when you want to create a "tooltip" or "menu" popup window or a window that should be modal to its parent window.
resizable bool?: A value indicating whether the window should be resizable by the user
title string: The title of the window. Depending on the platform and windowing backend, Unicode characters may be allowed in the window title.
transparent bool?: A value indicating whether the window should be created with a transparent buffer. The value of this parameter will determine whether the window will be shown transparent in areas where the alpha channel value of the window's buffer is equal to 0.
tooltip bool?: A value indicating whether the window should be created as a "tooltip" popup window
utility bool?: A value indicating whether the window should be created as a utility window (e.g. not showing in the task bar and window list)
vulkan bool?: A value indicating whether the window will be used with Vulkan rendering
width int?: The width of the window
x WindowPosition?: The X coordinate of the window, Centered, Undefined, or a value obtained from using the CenteredOn(Display) or UndefinedOn(Display) methods. You can either specify definitive coordinates as the value for this parameter, or you can use Centered, Undefined, CenteredOn(Display), or UndefinedOn(Display) to specify some special window positions to be determined in relation to the primary display or a specific display.
y WindowPosition?: The Y coordinate of the window, Centered, Undefined, or a value obtained from using the CenteredOn(Display) or UndefinedOn(Display) methods. You can either specify definitive coordinates as the value for this parameter, or you can use Centered, Undefined, CenteredOn(Display), or UndefinedOn(Display) to specify some special window positions to be determined in relation to the primary display or a specific display.
properties Properties: Additional properties to use when creating the window

Returns

bool: true, if the window was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The actual size of the created window may differ from the specified size, based on the desktop layout and window manager's policies. You should be prepared to handle windows of any size.

The resulting window will be immediately shown if the hidden parameter isn't set to true, otherwise it will be created hidden and you can show it later using the TryShow() method.

If this window is intended to being be used with a Renderer, you should not use a graphics API specific parameter (openGL, vulkan, etc), as SDL will handle that internally when it chooses a renderer, while creating the renderer with any of the TryCreateRenderer* methods. 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 hidden parameter set to true, then create the renderer, then show the window with TryShow().

You can see the TryCreate(string, int, int, out Window?, WindowFlags) method for more in-depth information about creating windows and the available flags.

You can see the TryCreatePopup(int, int, int, int, out Window?, WindowFlags) method for more in-depth information about creating popup windows and how "tooltip" and "menu" popup windows work.

This method should only be called from the main thread.

TryCreate(string, int, int, out Window?, WindowFlags)

Tries to create a new Window with the specified title, size, and flags

public static bool TryCreate(string title, int width, int height, out Window? window, WindowFlags flags = WindowFlags.None)

Parameters

title string: The title of the window. Depending on the platform and windowing backend, Unicode characters may be allowed in the window title.
width int: The width of the window
height int: The height of the window
window Window: The resulting Window, if this method returns true; otherwise, null
flags WindowFlags: The flags the window should be created with

Returns

bool: true, if the window was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The actual size of the created window may differ from the specified size, based on the desktop layout and window manager's policies. You should be prepared to handle windows of any size.

The resulting window will be immediately shown if the Hidden flag isn't specified, otherwise it will be created hidden and you can show it later using the TryShow() method.

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

The window's size in pixels may differ from its window's coordinate size if the window is on a high pixel density display. You can use the Size property to get the window's coordinate size and the SizeInPixels property or the OutputSize property on the associated Renderer to get the window's drawable size in pixels. Note that the drawable size of a window can vary after the window is created and should be checked again after an WindowPixelSizeChanged event is received.

If the window is created with any of the OpenGL or Vulkan flags, then the corresponding library ( or ) will be loaded upon creation, if necessary. Afterwards, when the window is disposed/destroyed the corresponding library will be unloaded again.

If the Vulkan flag is specified and there isn't a working Vulkan driver SDL can use, this method will fail.

If the Metal flag is specified and the platform doesn't support Metal, this method will fail.

If you intend to use the newly created window with a Renderer, you can use the TryCreateWithRenderer(string, int, int, out Window?, out Renderer?, WindowFlags) method instead, to avoid window flicker. Otherwise, you can create a Renderer for the window later using any of its TryCreateRenderer* methods (e.g. TryCreateRenderer(out Renderer?, params ReadOnlySpan<string>)).

This method should only be called from the main thread.

TryCreatePopup(int, int, int, int, out Window?, WindowFlags)

Tries to create a new popup Window as a child of the window with the specified position, size and flags.

public bool TryCreatePopup(int x, int y, int width, int height, out Window? popupWindow, WindowFlags flags = WindowFlags.Tooltip)

Parameters

x int: The X coordinate of the popup window relative to the parent window
y int: The Y coordinate of the popup window relative to the parent window
width int: The width of the popup window
height int: The height of the popup window
popupWindow Window: The resulting popup Window, if the method returns true; otherwise, null
flags WindowFlags: The flags the window should be created with

Returns

bool: true, if the popup window was created successfully; otherwise, false

Remarks

The actual size of the created window may differ from the specified size, based on the desktop layout and window manager's policies. You should be prepared to handle windows of any size.

The given flags argument must contain at least one of the following flags:

TooltipThe newly create popup window is a tooltip and will not pass any input events
PopupMenuThe newly create popup window is a popup menu. The topmost popup menu will implicitly gain the keyboard focus

The flags parameter defaults to Tooltip if not specified.

The following flags will be ignored if specified in the flags argument:

The given flags argument must not contain any of the following flags:

If the flags argument contains any of the above flags, this method will fail.

The parent of a popup window can be either a regular, toplevel window, or another popup window.

Popup windows cannot be minimized, be maximized, be made fullscreen, raised, be made 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 borders or 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. If you want to create an unconstrained popup window, you must manually construct it using the TryCreate(out Window?, bool?, bool?, bool?, bool?, WindowFlags?, bool?, bool?, int?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, Window?, bool?, string?, bool?, bool?, bool?, bool?, int?, WindowPosition?, WindowPosition?, Properties?) method with the constrainPopup parameter set to false.

By default, popup menus will automatically grab keyboard focus from the parent when shown. This behavior can be overridden by specifying the NotFocusable flag, by constructing the popup menu using the TryCreate(out Window?, bool?, bool?, bool?, bool?, WindowFlags?, bool?, bool?, int?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, Window?, bool?, string?, bool?, bool?, bool?, bool?, int?, WindowPosition?, WindowPosition?, Properties?) method with the focusable parameter set to false, or by setting the IsFocusable property to false after creating the popup menu.

If a parent window is hidden or disposed/destroyed, this will also be recursively applied to all child windows.

Child windows that weren't explicitly hidden (e.g. via TryHide()) but were only hidden because their parent was hidden, will be automatically shown again when their parent is shown again.

This method should only be called from the main thread.

TryCreateRenderer(out Renderer?, params ReadOnlySpan<string>)

Tries to create a new Renderer for this window

public bool TryCreateRenderer(out Renderer? renderer, params ReadOnlySpan<string> driverNames)

Parameters

renderer Renderer: The resulting Renderer, if the method returns true; otherwise, null
driverNames ReadOnlySpan<string>: An optional list of driver names to try, in order of preference. An empty list (the default) lets SDL automatically choose the best available driver for you.

Returns

bool: true, if the renderer was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

If you want to try specific rendering drivers, you can provide their names for the driverNames parameter. You can use the Name property of the pre-defined drivers for this (e.g. Name), or you can get the list of all available drivers at runtime using AvailableDriverNames property.

SDL will attempt to create a renderer using each of the specified driver names in order, and will return the first one that succeeds.

Leaving the driverNames parameter empty (the default) lets SDL automatically choose the best available driver for you, which is usually what you want unless you have specific requirements or want to test multiple drivers.

The default renderering size of the resulting renderer will match the size of the window in pixels, but you can change the content size and scaling later using the LogicalPresentation property if needed.

The resulting renderer will be of the Renderer<TDriver> type with a specific rendering driver as the type argument. If you need driver-specific functionality, you can type check and cast the resulting renderer to the appropriate Renderer<TDriver> type later or you can use the TryCreateRenderer<TDriver>(out Renderer<TDriver>?) method alternatively.

This method should only be called from the main thread.

TryCreateRenderer(out Renderer?, string?, ColorSpace?, RendererVSync?, Properties?)

Tries to create a new Renderer for this window

public bool TryCreateRenderer(out Renderer? renderer, string? driverName = null, ColorSpace? outputColorSpace = null, RendererVSync? presentVSync = null, Properties? properties = null)

Parameters

renderer Renderer: The resulting Renderer, if the method returns true; otherwise, null
driverName string: The name of the rendering driver to use, or null to let SDL automatically choose the best available driver for you
outputColorSpace ColorSpace?: The color space to be used by renderer for presenting to the output display. The Direct3D 11, Direct3D 12, and Metal renderers support SrgbLinear, which is a linear color space and supports HDR output. In that case, drawing still uses the sRGB color space, but individual values can go beyond 1.0 and floating point textures can be used for HDR content. If this parameter is null (the default), the output color space defaults to Srgb.
presentVSync RendererVSync?: The vertical synchronization (VSync) mode or interval to be used by the renderer. Can be specified to be Disabled to disable VSync, Adaptive to enable late swap tearing (adaptive VSync) if supported, or the result of the Interval(int) method to specify a custom VSync interval. You can specify a custom interval of 1 to synchronize to present of the renderer with every vertical refresh, 2 to synchronize it with every second vertical refresh, and so on. If this parameter is null (the default), the VSync mode defaults to Disabled.
properties Properties: Additional properties to use when creating the renderer

Returns

bool: true, if the renderer was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method should only be called from the main thread.

TryCreateRenderer(out Renderer<Gpu>?, GpuDevice?)

Tries to create a new GPU renderer for this window

public bool TryCreateRenderer(out Renderer<Gpu>? renderer, GpuDevice? gpuDevice = null)

Parameters

renderer Renderer<Gpu>: The resulting renderer, if this method returns true; otherwise, null
gpuDevice GpuDevice: The GpuDevice to use with the renderer, or null to let SDL select or create a suitable GPU device automatically

Returns

bool: true, if the renderer was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

If the gpuDevice is null, SDL will automatically select or create a suitable GPU device for you. The GpuDevice can be later retrieved from the renderer using the get_GpuDevice(Renderer<Gpu>) property.

If this method is called with a non-null GpuDevice, it should be called on the thread that created the device. And it should be definitely be called on the thread that created the window.

TryCreateRenderer(out Renderer<Gpu>?, ColorSpace?, RendererVSync?, GpuDevice?, bool?, bool?, bool?, Properties?)

Tries to create a new GPU renderer for this window

public bool TryCreateRenderer(out Renderer<Gpu>? renderer, ColorSpace? outputColorSpace = null, RendererVSync? presentVSync = null, GpuDevice? gpuDevice = null, bool? gpuShadersSpirV = null, bool? gpuShadersDxil = null, bool? gpuShadersMsl = null, Properties? properties = null)

Parameters

renderer Renderer<Gpu>: The resulting Renderer<TDriver>, if the method returns true; otherwise, null
outputColorSpace ColorSpace?: The color space to be used by renderer for presenting to the output display. The Direct3D 11, Direct3D 12, and Metal renderers support SrgbLinear, which is a linear color space and supports HDR output. In that case, drawing still uses the sRGB color space, but individual values can go beyond 1.0 and floating point textures can be used for HDR content. If this parameter is null (the default), the output color space defaults to Srgb.
presentVSync RendererVSync?: The vertical synchronization (VSync) mode or interval to be used by the renderer. Can be specified to be Disabled to disable VSync, Adaptive to enable late swap tearing (adaptive VSync) if supported, or the result of the Interval(int) method to specify a custom VSync interval. You can specify a custom interval of 1 to synchronize to present of the renderer with every vertical refresh, 2 to synchronize it with every second vertical refresh, and so on. If this parameter is null (the default), the VSync mode defaults to Disabled.
gpuDevice GpuDevice: The GpuDevice to use with the renderer, or null (the default) to let SDL select or create a suitable GPU device automatically
gpuShadersSpirV bool?: An optional value indicating whether the application is able to provide SPIR-V shaders to the renderer
gpuShadersDxil bool?: An optional value indicating whether the application is able to provide DXIL shaders to the renderer
gpuShadersMsl bool?: An optional value indicating whether the application is able to provide MSL shaders to the renderer
properties Properties: Additional properties to use when creating the renderer

Returns

bool: true, if the renderer was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The resulting renderer will be of the Renderer<TDriver> type with the specified TDriver as the type argument.

This method should only be called from the main thread.

TryCreateRenderer(out Renderer<Vulkan>?, ColorSpace?, RendererVSync?, nint?, ulong?, nint?, nint?, uint?, uint?, Properties?)

Tries to create a new Vulkan renderer for this window

public bool TryCreateRenderer(out Renderer<Vulkan>? renderer, ColorSpace? outputColorSpace = null, RendererVSync? presentVSync = null, nint? vulkanInstance = null, ulong? vulkanSurface = null, nint? vulkanPhysicalDevice = null, nint? vulkanDevice = null, uint? vulkanGraphicsQueueFamilyIndex = null, uint? vulkanPresentQueueFamilyIndex = null, Properties? properties = null)

Parameters

renderer Renderer<Vulkan>: The resulting Renderer<TDriver>, if the method returns true; otherwise, null
outputColorSpace ColorSpace?: The color space to be used by renderer for presenting to the output display. The Direct3D 11, Direct3D 12, and Metal renderers support SrgbLinear, which is a linear color space and supports HDR output. In that case, drawing still uses the sRGB color space, but individual values can go beyond 1.0 and floating point textures can be used for HDR content. If this parameter is null (the default), the output color space defaults to Srgb.
presentVSync RendererVSync?: The vertical synchronization (VSync) mode or interval to be used by the renderer. Can be specified to be Disabled to disable VSync, Adaptive to enable late swap tearing (adaptive VSync) if supported, or the result of the Interval(int) method to specify a custom VSync interval. You can specify a custom interval of 1 to synchronize to present of the renderer with every vertical refresh, 2 to synchronize it with every second vertical refresh, and so on. If this parameter is null (the default), the VSync mode defaults to Disabled.
vulkanInstance nint?: The https://docs.vulkan.org/refpages/latest/refpages/source/VkInstance.htmlVkInstance to use with the renderer. Must be directly cast to an nint from an https://docs.vulkan.org/refpages/latest/refpages/source/VkInstance.htmlVkInstance handle.
vulkanSurface ulong?: The https://docs.vulkan.org/refpages/latest/refpages/source/VkSurfaceKHR.htmlVkSurfaceKHR to use with the renderer. Must be directly cast to an ulong from a https://docs.vulkan.org/refpages/latest/refpages/source/VkSurfaceKHR.htmlVkSurfaceKHR handle.
vulkanPhysicalDevice nint?: The https://docs.vulkan.org/refpages/latest/refpages/source/VkPhysicalDevice.htmlVkPhysicalDevice to use with the renderer. Must be directly cast to an nint from a https://docs.vulkan.org/refpages/latest/refpages/source/VkPhysicalDevice.htmlVkPhysicalDevice handle.
vulkanDevice nint?: The https://docs.vulkan.org/refpages/latest/refpages/source/VkDevice.htmlVkDevice to use with the renderer. Must be directly cast to an nint from a https://docs.vulkan.org/refpages/latest/refpages/source/VkDevice.htmlVkDevice handle.
vulkanGraphicsQueueFamilyIndex uint?: The queue family index used for rendering
vulkanPresentQueueFamilyIndex uint?: The queue family index used for presentation
properties Properties: Additional properties to use when creating the renderer

Returns

bool: true, if the renderer was created successfully; otherwise, false (check TryGet(out string?) for more information)

Remarks

The resulting renderer will be of the Renderer<TDriver> type with the specified TDriver as the type argument.

This method should only be called from the main thread.

TryCreateRenderer<TDriver>(out Renderer<TDriver>?)

Tries to create a new Renderer<TDriver> for this window

public bool TryCreateRenderer<TDriver>(out Renderer<TDriver>? renderer) where TDriver : notnull, IRenderingDriver

Parameters

renderer Renderer<TDriver>: The resulting Renderer<TDriver>, if the method returns true; otherwise, null

Returns

bool: true, if the renderer was created successfully; otherwise, false (check TryGet(out string?) for more information)

Type Parameters

TDriver: The rendering driver type associated with the resulting renderer

Remarks

The resulting renderer will be of the Renderer<TDriver> type with the specified TDriver as the type argument.

This method should only be called from the main thread.

TryCreateRenderer<TDriver>(out Renderer<TDriver>?, ColorSpace?, RendererVSync?, Properties?)

Tries to create a new Renderer<TDriver> for this window

public bool TryCreateRenderer<TDriver>(out Renderer<TDriver>? renderer, ColorSpace? outputColorSpace = null, RendererVSync? presentVSync = null, Properties? properties = null) where TDriver : notnull, IRenderingDriver

Parameters

renderer Renderer<TDriver>: The resulting Renderer<TDriver>, if the method returns true; otherwise, null
outputColorSpace ColorSpace?: The color space to be used by renderer for presenting to the output display. The Direct3D 11, Direct3D 12, and Metal renderers support SrgbLinear, which is a linear color space and supports HDR output. In that case, drawing still uses the sRGB color space, but individual values can go beyond 1.0 and floating point textures can be used for HDR content. If this parameter is null (the default), the output color space defaults to Srgb.
presentVSync RendererVSync?: The vertical synchronization (VSync) mode or interval to be used by the renderer. Can be specified to be Disabled to disable VSync, Adaptive to enable late swap tearing (adaptive VSync) if supported, or the result of the Interval(int) method to specify a custom VSync interval. You can specify a custom interval of 1 to synchronize to present of the renderer with every vertical refresh, 2 to synchronize it with every second vertical refresh, and so on. If this parameter is null (the default), the VSync mode defaults to Disabled.
properties Properties: Additional properties to use when creating the renderer

Returns

bool: true, if the renderer was created successfully; otherwise, false (check TryGet(out string?) for more information)

Type Parameters

TDriver: The rendering driver type associated with the resulting renderer

Remarks

The resulting renderer will be of the Renderer<TDriver> type with the specified TDriver as the type argument.

This method should only be called from the main thread.

TryCreateWithRenderer(string, int, int, out Window?, out Renderer?, WindowFlags)

Tries to create a new Window with the specified title, size and flags, and an associated default Renderer

public static bool TryCreateWithRenderer(string title, int width, int height, out Window? window, out Renderer? renderer, WindowFlags flags = WindowFlags.None)

Parameters

title string: The title of the window. Depending on the platform and windowing backend, Unicode characters may be allowed in the window title.
width int: The width of the window
height int: The height of the window
window Window: The resulting Window, if this method returns true; otherwise, null
renderer Renderer: The resulting default Renderer, if this method returns true; otherwise, null
flags WindowFlags: The flags the window should be created with

Returns

bool: true if the window and renderer were successfully created; otherwise, false

Remarks

You can also access the created Renderer later using the Renderer property of the resulting window.

If a window is created with an associated Renderer, don't try to create another renderer for the same window.

You can see the TryCreate(string, int, int, out Window?, WindowFlags) method for more in-depth information about creating windows and the available flags.

This method should only be called from the main thread.

TryCreate<TDriver>(out Window<TDriver>?, bool?, bool?, bool?, bool?, WindowFlags?, bool?, bool?, int?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, bool?, Window?, bool?, string?, bool?, bool?, bool?, bool?, int?, WindowPosition?, WindowPosition?, Properties?)

Tries to create a new Window with the specified parameters

public static bool TryCreate<TDriver>(out Window<TDriver>? window, bool? alwaysOnTop = null, bool? bordered = null, bool? constrainPopup = null, bool? externalGraphicsContext = null, WindowFlags? flags = null, bool? focusable = null, bool? fullscreen = null, int? height = null, bool? hidden = null, bool? highPixelDensity = null, bool? maximized = null, bool? menu = null, bool? metal = null, bool? minimized = null, bool? modal = null, bool? mouseGrabbed = null, bool? openGL = null, Window? parent = null, bool? resizable = null, string? title = null, bool? transparent = null, bool? tooltip = null, bool? utility = null, bool? vulkan = null, int? width = null, WindowPosition? x = null, WindowPosition? y = null, Properties? properties = null) where TDriver : notnull, IWindowingDriver

Parameters

window Window<TDriver>: The resulting Window, if this method returns true; otherwise, null
alwaysOnTop bool?: A value indicating whether the window should always be above others
bordered bool?: A value indicating whether the window should have a border (decorations)
constrainPopup bool?: A value indicating whether a "tooltip" or "menu" popup window should be automatically constrained to the bounds of the display. If this parameter is null (the default), the default behavior is to constrain popup windows.
externalGraphicsContext bool?: A value indicating whether the window will be used with an externally managed graphics context
flags WindowFlags?: The flags the window should be created with
focusable bool?: A value indicating whether the window should accept input focus. If this parameter is null (the default), the default behavior is to accept input focus.
fullscreen bool?: A value indicating whether the window should be created initially in fullscreen mode at desktop resolution
height int?: The height of the window
hidden bool?: A value indicating whether the window should be created initially hidden
highPixelDensity bool?: A value indicating whether the window should be created with a high pixel density buffer, if possible
maximized bool?: A value indicating whether the window should be created initially maximized
menu bool?: A value indicating whether the window should be created as a "menu" popup window. If this parameter is set to true, you must specify a parent window for the window to be created.
metal bool?: A value indicating whether the window will be used with Metal rendering
minimized bool?: A value indicating whether the window should be created initially minimized
modal bool?: A value indicating whether the window should be created as modal to its parent window. If this parameter is set to true, you must specify a parent window for the window to be created.
mouseGrabbed bool?: A value indicating whether the window should be created initially with the mouse grabbed
openGL bool?: A value indicating whether the window will be used with OpenGL rendering
parent Window: The parent Window of the window to be created. You must specify a non-null window when you want to create a "tooltip" or "menu" popup window or a window that should be modal to its parent window.
resizable bool?: A value indicating whether the window should be resizable by the user
title string: The title of the window. Depending on the platform and windowing backend, Unicode characters may be allowed in the window title.
transparent bool?: A value indicating whether the window should be created with a transparent buffer. The value of this parameter will determine whether the window will be shown transparent in areas where the alpha channel value of the window's buffer is equal to 0.
tooltip bool?: A value indicating whether the window should be created as a "tooltip" popup window
utility bool?: A value indicating whether the window should be created as a utility window (e.g. not showing in the task bar and window list)
vulkan bool?: A value indicating whether the window will be used with Vulkan rendering
width int?: The width of the window
x WindowPosition?: The X coordinate of the window, Centered, Undefined, or a value obtained from using the CenteredOn(Display) or UndefinedOn(Display) methods. You can either specify definitive coordinates as the value for this parameter, or you can use Centered, Undefined, CenteredOn(Display), or UndefinedOn(Display) to specify some special window positions to be determined in relation to the primary display or a specific display.
y WindowPosition?: The Y coordinate of the window, Centered, Undefined, or a value obtained from using the CenteredOn(Display) or UndefinedOn(Display) methods. You can either specify definitive coordinates as the value for this parameter, or you can use Centered, Undefined, CenteredOn(Display), or UndefinedOn(Display) to specify some special window positions to be determined in relation to the primary display or a specific display.
properties Properties: Additional properties to use when creating the window

Returns

bool: true, if the window was created successfully; otherwise, false (check TryGet(out string?) for more information)

Type Parameters

TDriver: The windowing driver type associated with the resulting window. Note that this method will fail if the currently active windowing driver does not match the specified TDriver type.

Remarks

The actual size of the created window may differ from the specified size, based on the desktop layout and window manager's policies. You should be prepared to handle windows of any size.

The resulting window will be immediately shown if the hidden parameter isn't set to true, otherwise it will be created hidden and you can show it later using the TryShow() method.

You can see the TryCreate(string, int, int, out Window?, WindowFlags) method for more in-depth information about creating windows and the available flags.

You can see the TryCreatePopup(int, int, int, int, out Window?, WindowFlags) method for more in-depth information about creating popup windows and how "tooltip" and "menu" popup windows work.

This method should only be called from the main thread.

TryFlash(FlashOperation)

Tries to make the window flash in order to demand the user's attention

public bool TryFlash(FlashOperation operation)

Parameters

operation FlashOperation: The flash operation to perform

Returns

bool: true, if the flash operation was successfully initiated or canceled; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method should only be called from the main thread.

TryGetFromId(uint, out Window?)

Tries to get an existing Window by its numeric ID

public static bool TryGetFromId(uint id, out Window? result)

Parameters

id uint: The numeric ID of the window
result Window: The existing Window associated with the specified id, if the method returns true; otherwise, null

Returns

bool: true, if a window with the specified id exists; otherwise, false

Remarks

This method makes use of the ID that SDL uses to identify windows in WindowEvents and some other events and maps such events to their corresponding Window instances using their Id.

This method should only be called from the main thread.

TryGetICCProfileData(out NativeMemoryManager?)

Tries to get the raw ICC profile data associated with the screen the window is currently displayed on

public bool TryGetICCProfileData(out NativeMemoryManager? iccProfileData)

Parameters

iccProfileData NativeMemoryManager: The raw ICC profile data associated with the screen the window is currently displayed on, if the method returns true; otherwise, null

Returns

bool: true, if the ICC profile data was successfully retrieved; otherwise, false (check TryGet(out string?) for more information)

Remarks

Please remember to dispose the resulting iccProfileData when you don't need it anymore to release the underlying unmanaged resources.

This method should only be called from the main thread.

TryHide()

Tries to hide the window

public bool TryHide()

Returns

bool: true, if the window was successfully hidden; otherwise, false (check TryGet(out string?) for more information)

Remarks

To show a hidden window again, you can use the TryShow() method.

This method recursively hides all child windows of this window as well.

This method should only be called from the main thread.

TryMaximize()

Tries to maximize the window (e.g. make it as large as possible)

public bool TryMaximize()

Returns

bool: true, if the window was successfully maximized; otherwise, false (check TryGet(out string?) for more information)

Remarks

Non-resizable windows can't be maximized. The window must have the Resizable flag set, or a call to this method will have no effect.

On some windowing backends, a request to maximize a window is asynchronous and the new window state may not have have been applied immediately after calling this method. If an immediate change is required, you can call TrySync() to block until the changes have taken effect.

When the window state changes, an WindowMaximized event will be emitted. Windowing backends can also deny the request to change this setting altogether.

When maximizing a window, whether the constraints set via MaximumSize are honored depends on the policy of the window manager. On Windows and macOS, the constraints are enforced when maximizing, while X11 and Wayland window managers may vary.

This method should only be called from the main thread.

TryMinimize()

Tries to minimize the window (e.g. bring it to an iconic representation)

public bool TryMinimize()

Returns

bool: true, if the window was successfully minimized; otherwise, false (check TryGet(out string?) for more information)

Remarks

If the window is in fullscreen mode, a call to this method has no direct effect, but it may alter the state the window is returned to when leaving fullscreen.

On some windowing backends, a request to minimize a window is asynchronous and the new window state may not have have been applied immediately after calling this method. If an immediate change is required, you can call TrySync() to block until the changes have taken effect.

When the window state changes, an WindowMinimized event will be emitted. Windowing backends can also deny the request to change this setting altogether.

This method should only be called from the main thread.

TryRaise()

Tries to raise the window above other windows and to let it gain the input focus

public bool TryRaise()

Returns

bool: true, if the window was successfully raised; otherwise, false (check TryGet(out string?) for more information)

Remarks

The result of a request to raise a window 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 WindowFocusGained event will be emitted, and the window will have the InputFocus flag set.

This method should only be called from the main thread.

TryRestore()

Tries to restore the size and position of the previously minimized or maximized window

public bool TryRestore()

Returns

bool: true, if the window was successfully restored; otherwise, false (check TryGet(out string?) for more information)

Remarks

If the window is in fullscreen mode, a call to this method has no direct effect, but it may alter the state the window is returned to when leaving fullscreen.

On some windowing backends, a request to restore a window is asynchronous and the new window state may not have have been applied immediately after calling this method. If an immediate change is required, you can call TrySync() to block until the changes have taken effect.

When the window state changes, an WindowRestored event will be emitted. Windowing backends can also deny the request to change this setting altogether.

This method should only be called from the main thread.

TrySetIcon(Surface)

Tries to set the icon for the window

public bool TrySetIcon(Surface icon)

Parameters

icon Surface: The icon to set for the window

Returns

bool: true, if the icon was successfully set; otherwise, false (check TryGet(out string?) for more information)

Remarks

If the given icon is a surface with alternate representations, the surface will be interpreted as the content to be used for 100% display scale, and the alternate representations will be used for high DPI situations. For example, if the original surface is 32 by 32, then on a 2x macOS display or 200% display scale on Windows, a 64 by 64 version of the image will be used, if available.

If a matching version of the image isn't available, the closest larger size image will be downscaled to the appropriate size and be used instead, if available. Otherwise, the closest smaller image will be upscaled and be used instead.

The given icon as well as all of its alternate representations will be copied, so you can safely dispose of it after passing it if you don't need it anymore.

This method should only be called from the main thread.

TrySetPosition(WindowPosition, WindowPosition)

Tries to set the position of the window

public bool TrySetPosition(WindowPosition x, WindowPosition y)

Parameters

x WindowPosition: The new X coordinate of the window, Centered, Undefined, or a value obtained from using the CenteredOn(Display) or UndefinedOn(Display) methods.
y WindowPosition: The new Y coordinate of the window, Centered, Undefined, or a value obtained from using the CenteredOn(Display) or UndefinedOn(Display) methods.

Returns

bool: true, if the position was successfully set; otherwise, false (check TryGet(out string?) for more information)

Remarks

You can either specify definitive coordinates for the new window position, or you can use Centered, Undefined, CenteredOn(Display), or UndefinedOn(Display) to specify some special window positions to be determined in relation to the primary display or a specific display.

If the window is in exclusive fullscreen mode or maximized state, a call to this method has no effect.

However, this method can be used to reposition fullscreen-desktop windows onto a different display. Whereas exclusive fullscreen windows are locked to a specific display, they can only be repositioned programmatically by setting FullscreenMode.

On some windowing backends, a request to change the position of a window is asynchronous and the new window position may not have have been applied immediately after calling this method. If an immediate change is required, you can call TrySync() to block until the changes have taken effect.

When the window position changes, an WindowMoved event will be emitted with the new window position. Note that the new position may not match the exact coordinates requested, as some windowing backends can restrict the window position in certain scenarios (e.g. constraining the position so the window is always within desktop bounds). Additionally, windowing backends can also deny the request to change this setting altogether.

This method should only be called from the main thread.

TryShow()

Tries to show the previously hidden window

public bool TryShow()

Returns

bool: true, if the window was successfully shown; otherwise, false (check TryGet(out string?) for more information)

Remarks

This method recursively shows all child windows of this window that weren't explicitly hidden (e.g. via TryHide()) but were only hidden because their parent was hidden.

This method should only be called from the main thread.

TryShowSystemMenu(int, int)

Tries to show the system-level menu for the window

public bool TryShowSystemMenu(int x, int y)

Parameters

x int: The X coordinate of the menu to show, relative to the top-left corner of the window's client area
y int: The Y coordinate of the menu to show, relative to the top-left corner of the window's client area

Returns

bool: true, if the system-level menu was successfully shown; otherwise, false (check TryGet(out string?) for more information)

Remarks

This default window menu is provided by the system and on some platforms provides functionality for setting or changing privileged state on the window, such as moving it between workspaces or displays, or toggling the always-on-top property.

On platforms or in environments where showing a system-level menu isn't supported, this method does nothing.

This method should only be called from the main thread.

TrySync()

Tries to block until any pending changes to the window state have been applied

public bool TrySync()

Returns

bool: true, if the window state was successfully fully synchronized before timing out; otherwise, false (check TryGet(out string?) for more information)

Remarks

On asynchronous windowing backends, this method acts as a synchronization barrier for pending window states. A call to this method will attempt to wait until any pending window state has been applied and is guaranteed to return within finite time. Note that for how long it can potentially block depends on the underlying window backend, as window state changes sometimes may involve somewhat lengthy animations that must complete before the window is in its final requested state.

On windowing backends where changes are immediate, this does nothing.

Table of Contents

Class Window

Remarks

Properties

AllWindows

Property Value

Exceptions

AspectRatio

Property Value

Remarks

Exceptions

BordersSize

Property Value

Remarks

Display

Property Value

Remarks

Exceptions

DisplayScale

Property Value

Remarks

Flags

Property Value

Remarks

FullscreenMode

Property Value

Remarks

Exceptions

GrabbedWindow

Property Value

Remarks

HasKeyboardGrab

Property Value

Remarks

Exceptions

HasMouseGrab

Property Value

Remarks

Exceptions

HasSurface

Property Value

Remarks

HdrHeadroom

Property Value

Remarks

HitTest

Property Value

Remarks

Exceptions

Id

Property Value

Remarks

IsAlwaysOnTop

Property Value

Remarks

Exceptions

IsBordered

Property Value

Remarks

Exceptions

IsFocusable

Property Value

Remarks

Exceptions

IsFullscreen

Property Value

Remarks

Exceptions

IsHdrEnabled

Property Value

Remarks

IsModal

Property Value

Remarks

Exceptions

IsResizable

Property Value

Remarks

Exceptions

IsValid