Table of Contents

Class Window<TDriver>

Namespace
Sdl3Sharp.Video.Windowing
Assembly
Sdl3Sharp.dll

Represents a window

public sealed class Window<TDriver> : Window, IDisposable where TDriver : notnull, IWindowingDriver

Type Parameters

TDriver
Inheritance
Window<TDriver>
Implements
Inherited Members

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<TDriver>, 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 Window<TDriver> using the TryCreate(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?) method, but be aware that if the currently active windowing driver doesn't match the specified one, this method will fail. Alternatively, you can create new popup windows using the TryCreatePopup(int, int, int, int, out Window<TDriver>?, WindowFlags) method. This method will create the new window as a child window of the window the method was called on.

Additionally, there are some driver-specific methods for creating windows, such as Wayland, Windows, Cocoa, and some more. Similar rules apply to these methods as well: if the currently active windowing driver doesn't match the specified one, these method will fail.

For the most part Window<TDriver>s are not thread-safe, and most of their properties and methods should only be accessed from the main thread!

Window<TDriver>s are concrete window types, associated with a specific windowing driver.

If you want to use them in a more general way, you can use them as Window instances, which serve as common abstractions.

Properties

Display

Gets the display associated with the window

public Display<TDriver> Display { get; }

Property Value

Display<TDriver>

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)

Methods

TryCreate(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(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)

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)

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.

TryCreatePopup(int, int, int, int, out Window<TDriver>?, 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<TDriver>? popupWindow, WindowFlags flags = WindowFlags.None)

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<TDriver>

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.

Edit this page