TSdlWindow
A window.
Definition
Unit: Neslib.Sdl3.Video
Properties
| Name | Description |
|---|---|
| AlwaysOnTop | The window "always on top" state of the window. |
| Bordered | The border state of the window. |
| Display | The display associated with this window (that is, the display containing the center of this window). |
| DisplayScale | The content display scale relative to a window's pixel size. |
| Flags | The window flags. |
| Focusable | Whether the window may have input focus. |
| Fullscreen | The window's fullscreen state. |
| FullscreenMode | The display mode to use when a window is visible and fullscreen. This is a pointer to the display mode to use, which can be nil for borderless fullscreen desktop mode, or one of the fullscreen modes returned by TSdlDisplay.FullscreenModes for an exclusive fullscreen mode. |
| GrabbedWindow | The window that currently has an input grab enabled, or nil otherwise. |
| HasSurface | Whether the window has a surface associated with it. |
| IccProfile | The raw ICC profile data for the screen the window is currently on. |
| Icon | Set the icon for the window. |
| ID | The numeric ID of the window. |
| IsRelativeMouseMode | Whether relative mouse mode for the window is eneabled. |
| IsScreenKeyboardShown | Whether the screen keyboard is shown for the window. |
| KeyboardGrab | The window's keyboard grab mode. |
| MaximumSize | The maximum size of the window's client area. See GetMaximumSize and SetMaximumSize for more information. |
| MinimumSize | The minimum size of the window's client area. See GetMinimumSize and SetMinimumSize for more information. |
| Modal | The modal state of the window. |
| MouseGrab | The window's mouse grab mode. |
| MouseRect | The mouse confinement rectange of the window. |
| Opacity | The opacity of the window, which will be clamped internally between 0.0 (transparent) and 1.0 (opaque). Will be 1.0 (opaque) on platforms that don't support opacity. |
| Parent | The parent of the window or nil if the window has no parent. |
| PixelDensity | The pixel density of the window. |
| PixelFormat | The pixel format associated with the window. |
| Position | The position of the window. See SetPosition and GetPosition for more information. |
| Properties | The properties associated with a window. |
| Resizable | The user-resizable state of the window. |
| SafeArea | The safe area for this window. |
| Shape | The shape of the transparent window, or nil if the window has no shape (or to remove the shape). |
| Size | The size of the window. See SetSize and GetSize for more information. |
| SizeInPixels | The size of the window in pixels. See GetSizeInPixels for more information. |
| Surface | The SDL surface associated with the window. |
| SurfaceVSync | The VSync for the window surface. |
| TextInputActive | Whether or not Unicode text input events are enabled for the window. |
| Title | The title of the window. |
| Windows | A list of valid windows. |
| WithKeyboardFocus | The window which currently has keyboard focus. |
Constructors
| Name | Description |
|---|---|
| Create(TSdlProperties) | Create a window with the specified properties. |
| Create(TSdlWindow, Integer, Integer, Integer, Integer, TSdlWindowFlags) | Create a child popup window of the specified parent window. |
| Create(String, Integer, Integer, TSdlWindowFlags) | Create a window with the specified dimensions and flags. |
| Destroy |
Operators
| Name | Description |
|---|---|
| Equal(TSdlWindow, TSdlWindow) | Used to compare against another TSdlWindow. |
| Equal(TSdlWindow, Pointer) | Used to compare against nil. |
| Implicit | Used to set the value to nil. |
| NotEqual(TSdlWindow, TSdlWindow) | Used to compare against another TSdlWindow. |
| NotEqual(TSdlWindow, Pointer) | Used to compare against nil. |
Methods
| Name | Description |
|---|---|
| ClearComposition | Dismiss the composition window/IME without disabling the subsystem. |
| ClearTextInputArea | Clear the area used to type Unicode text input. |
| Flash | Request a window to demand attention from the user. |
| Free | Frees the window. |
| FreeSurface | Destroy the surface associated with the window. |
| FromID | Get a window from a stored ID. |
| GetAspectRatio | Get the aspect ratio of the window's client area. |
| GetBordersSize | Get the size of the window's borders (decorations) around the client area. |
| GetMaximumSize | Get the maximum size of the window's client area. |
| GetMinimumSize | Get the minimum size of the window's client area. |
| GetPosition | Get the position of the window. |
| GetSize | Get the size of the window's client area. |
| GetSizeInPixels | Get the size of the window's client area, in pixels. |
| GetTextInputArea | Get the area used to type Unicode text input. |
| Hide | Hide the window. |
| Maximize | Request that the window be made as large as possible. |
| Minimize | Request that the window be minimized to an iconic representation. |
| RaiseAndFocus | Request that a window be raised above other windows and gain the input focus. |
| Restore | Request that the size and position of a minimized or maximized window be restored. |
| SetAspectRatio | Request that the aspect ratio of a window's client area be set. |
| SetHitTestCallback | Provide a callback that decides if a window region has special properties. |
| SetMaximumSize | Set the maximum size of the window's client area. |
| SetMinimumSize | Set the minimum size of the window's client area. |
| SetPosition | Request that the window's position be set. |
| SetSize | Request that the size of a window's client area be set. |
| SetTextInputArea | Set the area used to type Unicode text input. |
| Show | Show the window. |
| ShowSystemMenu | Display the system-level window menu. |
| StartTextInput(TSdlProperties) | Start accepting Unicode text input events in the window, with properties describing the input. |
| StartTextInput | Start accepting Unicode text input events in the window. |
| StopTextInput | Stop receiving any text input events in the window. |
| Sync | Block until any pending window state is finalized. |
| UpdateSurface(TSdlRect[]) | Copy areas of the window surface to the screen. |
| UpdateSurface(TArray<TSdlRect>) | Copy areas of the window surface to the screen. |
| UpdateSurface | Copy the window surface to the screen. |
| WarpMouse(TSdlPointF) | Move the mouse cursor to the given position within the window. |
| WarpMouse(Single, Single) | Move the mouse cursor to the given position within the window. |
Property Descriptions
AlwaysOnTop
The window "always on top" state of the window.
This will add or remove the window's TSdlWindowFlag.AlwaysOnTop flag. This will bring the window to the front and keep the window above the rest.
property AlwaysOnTop: Boolean read GetAlwaysOnTop write SetAlwaysOnTop
Type: Boolean
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
Bordered
The border state of the window.
This will add or remove the window's TSdlWindowFlag.Borderless flag and add or remove the border from the actual window. This is a no-op if the window's border already matches the requested state.
You can't change the border state of a fullscreen window.
property Bordered: Boolean read GetBordered write SetBordered
Type: Boolean
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
Display
The display associated with this window (that is, the display containing the center of this window).
property Display: TSdlDisplay read GetDisplay
Type: TSdlDisplay
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
DisplayScale
The content display scale relative to a window's pixel size.
This 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 3840x2160 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 1920x1080 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.
property DisplayScale: Single read GetDisplayScale
Type: Single
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Flags
The window flags.
property Flags: TSdlWindowFlags read GetFlags
Type: TSdlWindowFlags
See Also
Remarks
This property should only be used on the main thread.
Focusable
Whether the window may have input focus.
property Focusable: Boolean read GetFocusable write SetFocusable
Type: Boolean
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Fullscreen
The window's fullscreen state.
By default a window in fullscreen state uses borderless fullscreen desktop mode, but a specific exclusive display mode can be set using FullscreenMode.
On some windowing systems setting this property is asynchronous and the new fullscreen state may not have have been applied immediately upon the return of this function. If an immediate change is required, call Sync to block until the changes have taken effect.
When the window state changes, an TSdlEventKind.WindowEnterFullscreen or TSdlEventKind.WindowLeaveFullscreen event will be emitted. Note that, as this is just a request, it can be denied by the windowing system.
property Fullscreen: Boolean read GetFullscreen write SetFullscreen
Type: Boolean
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
FullscreenMode
The display mode to use when a window is visible and fullscreen. This is a pointer to the display mode to use, which can be nil for borderless fullscreen desktop mode, or one of the fullscreen modes returned by TSdlDisplay.FullscreenModes for an exclusive fullscreen mode.
This only affects the display mode used when the window is fullscreen. To change the window size when the window is not fullscreen, use Size.
If the window is currently in the fullscreen state, this request is asynchronous on some windowing systems and the new mode dimensions may not be applied immediately upon the return of this function. If an immediate change is required, call Sync to block until the changes have taken effect.
When the new mode takes effect, an TSdlEventKind.WindowResized and/or an TSdlEventKind.WindowPixelSizeChanged event will be emitted with the new mode dimensions.
property FullscreenMode: PSdlDisplayMode read GetFullscreenMode write SetFullscreenMode
Type: PSdlDisplayMode
Exceptions
ESdlError: Raised when setting the mode failed.
See Also
Remarks
This property should only be used on the main thread.
GrabbedWindow
The window that currently has an input grab enabled, or nil otherwise.
class property GrabbedWindow: TSdlWindow read GetGrabbedWindow
Type: TSdlWindow
See Also
Remarks
This property should only be used on the main thread.
HasSurface
Whether the window has a surface associated with it.
property HasSurface: Boolean read GetHasSurface
Type: Boolean
See Also
Remarks
This property should only be used on the main thread.
IccProfile
The raw ICC profile data for the screen the window is currently on.
property IccProfile: TBytes read GetIccProfile
Type: TBytes
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Icon
Set the icon for the window.
If this property 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 32x32, then on a 2x macOS display or 200% display scale on Windows, a 64x64 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.
property Icon: TSdlSurface write SetIcon
Type: TSdlSurface
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
ID
The numeric ID of the window.
The numeric ID is what TSdlWindowEvent references, and is necessary to map these events to specific TSdlWindow objects.
property ID: TSdlWindowID read GetID
Type: TSdlWindowID
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
IsRelativeMouseMode
Whether relative mouse mode for the window is eneabled.
While the window has focus and relative mouse mode is enabled, the cursor is hidden, the mouse position is constrained to the window, and SDL will report continuous relative mouse motion even if the mouse is at the edge of the window.
If you'd like to keep the mouse position fixed while in relative mode you can use MouseRect. If you'd like the cursor to be at a specific location when relative mode ends, you should use WarpMouse before disabling relative mode.
This method will flush any pending mouse motion for this window.
property IsRelativeMouseMode: Boolean read GetIsRelativeMouseMode write SetIsRelativeMouseMode
Type: Boolean
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
IsScreenKeyboardShown
Whether the screen keyboard is shown for the window.
property IsScreenKeyboardShown: Boolean read GetIsScreenKeyboardShown
Type: Boolean
See Also
Remarks
This property should only be used on the main thread.
KeyboardGrab
The window's keyboard grab mode.
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 example is Ctrl+Alt+Del on Windows).
This is primarily intended for 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 full-screen 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 TSdlHints.AllowAltTabWhileGrabbed.
If the caller enables a grab while another window is currently grabbed, the other window loses its grab in favor of the caller's window.
property KeyboardGrab: Boolean read GetKeyboardGrab write SetKeyboardGrab
Type: Boolean
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
MaximumSize
The maximum size of the window's client area. See GetMaximumSize and SetMaximumSize for more information.
property MaximumSize: TSdlSize read GetMaximumSizeSize write SetMaximumSizeSize
Type: TSdlSize
MinimumSize
The minimum size of the window's client area. See GetMinimumSize and SetMinimumSize for more information.
property MinimumSize: TSdlSize read GetMinimumSizeSize write SetMinimumSizeSize
Type: TSdlSize
Modal
The modal state of the window.
To enable modal status on a window, the window must currently be the child window of a parent, or toggling modal status on will fail.
property Modal: Boolean read GetModal write SetModal
Type: Boolean
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
MouseGrab
The window's mouse grab mode.
Mouse grab confines the mouse cursor to the window.
property MouseGrab: Boolean read GetMouseGrab write SetMouseGrab
Type: Boolean
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
MouseRect
The mouse confinement rectange of the window.
Note that setting this does NOT grab the cursor, it only defines the area a cursor is restricted to when the window has mouse focus.
This property is a pointer to a rectangle in window-relative coordinates, or nil if there isn't a confinement rectangle.
property MouseRect: PSdlRect read GetMouseRect write SetMouseRect
Type: PSdlRect
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
Opacity
The opacity of the window, which will be clamped internally between 0.0 (transparent) and 1.0 (opaque). Will be 1.0 (opaque) on platforms that don't support opacity.
property Opacity: Single read GetOpacity write SetOpacity
Type: Single
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Parent
The parent of the window or nil if the window has no parent.
When setting this property, if the window is already the child of an existing window, it will be reparented to the new owner. Setting the parent window to nil unparents the window and removes child window status.
If a parent window is hidden or destroyed, the operation will be recursively applied to child windows. Child windows hidden with the parent that did not have their hidden status explicitly set will be restored when the parent is shown.
Attempting to set the parent of a window that is currently in the modal state will fail. Use Modal to cancel the modal status before attempting to change the parent.
Popup windows cannot change parents and attempts to do so will fail.
Setting a parent window that is currently the sibling or descendent of the child window results in undefined behavior.
property Parent: TSdlWindow read GetParent write SetParent
Type: TSdlWindow
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
PixelDensity
The pixel density of the window.
This is a ratio of pixel size to window size. For example, if the window is 1920x1080 and it has a high density back buffer of 3840x2160 pixels, it would have a pixel density of 2.0.
property PixelDensity: Single read GetPixelDensity
Type: Single
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
PixelFormat
The pixel format associated with the window.
property PixelFormat: TSdlPixelFormat read GetPixelFormat
Type: TSdlPixelFormat
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Position
The position of the window. See SetPosition and GetPosition for more information.
property Position: TSdlPoint read GetPositionPoint write SetPositionPoint
Type: TSdlPoint
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Properties
The properties associated with a window.
The following read-only properties are provided by SDL:
TSdlProperty.WindowShape: The surface associated with a shaped windowTSdlProperty.WindowHdrEnabled: True if the window has HDR headroom above the SDR white point. This property can change dynamically when TSdlEventKind.WindowHdrStateChanged is sent.TSdlProperty.WindowSdrWhiteLevel: the value of SDR white in the TSdlColorspace.SrgbLinear colorspace. On Windows this corresponds to the SDR white level in scRGB colorspace, and on Apple platforms this is always 1.0 for EDR content. This property can change dynamically when TSdlEventKind.WindowHdrStateChanged is sent.TSdlProperty.WindowHdrHeadroom: The additional high dynamic range that can be displayed, in terms of the SDR white point. When HDR is not enabled, this will be 1.0. This property can change dynamically when TSdlEventKind.WindowHdrStateChanged is sent.
On Android:
TSdlProperty.WindowAndroidWindow: The ANativeWindow associated with the windowTSdlProperty.WindowAndroidSurface: The EGLSurface associated with the window
On iOS:
TSdlProperty.WindowUIKitWindow: The UIWindow handle associated with the windowTSdlProperty.WindowUIKitMetalViewTag: The NSInteger handle tag associated with metal views on the windowTSdlProperty.WindowUIKitOpenGLFramebuffer: The OpenGL view's framebuffer object. It must be bound when rendering to the screen using OpenGL.TSdlProperty.WindowUIKitOpenGLRenderbuffer: the OpenGL view's renderbuffer object. It must be bound when TSdlGL.SwapWindow is called.TSdlProperty.WindowUIKitOpenGLResolveFramebuffer: the OpenGL view's resolve framebuffer, when MSAA is used.
On macOS:
TSdlProperty.WindowCocoaWindow: The NSWindow handle associated with the windowTSdlProperty.WindowCocoaMetalViewTag: The NSInteger handle tag assocated with metal views on the window
On Windows:
TSdlProperty.WindowWin32Hwnd: the HWND associated with the windowTSdlProperty.WindowWin32Hdc: the HDC associated with the windowTSdlProperty.WindowWin32Instance: the HINSTANCE associated with the window
property Properties: TSdlProperties read GetProperties
Type: TSdlProperties
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Resizable
The user-resizable state of the window.
This will add or remove the window's TSdlWindowFlag.Resizable flag and allow/disallow user resizing of the window. This is a no-op if the window's resizable state already matches the requested state.
You can't change the resizable state of a fullscreen window.
property Resizable: Boolean read GetResizable write SetResizable
Type: Boolean
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
SafeArea
The safe area for this window.
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 function provides the area of the window which is safe to have interactable content. You should continue rendering into the rest of the window, but it should not contain visually important or interactible content.
property SafeArea: TSdlRect read GetSafeArea
Type: TSdlRect
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Shape
The shape of the transparent window, or nil if the window has no shape (or to remove the shape).
This sets the alpha channel of a transparent window and any fully transparent areas are also transparent to mouse clicks. If you are using something besides the SDL render API, then you are responsible for drawing the alpha channel of the window to match the shape alpha channel to get consistent cross-platform results.
The shape is copied inside this function, so you can free it afterwards. If your shape surface changes, you should set this property again to update the window. This is an expensive operation, so should be done sparingly.
The window must have been created with the TSdlWindowFlag.Transparent flag.
property Shape: TSdlSurface read GetShape write SetShape
Type: TSdlSurface
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Size
The size of the window. See SetSize and GetSize for more information.
property Size: TSdlSize read GetSizeSize write SetSizeSize
Type: TSdlSize
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
SizeInPixels
The size of the window in pixels. See GetSizeInPixels for more information.
property SizeInPixels: TSdlSize read GetSizeInPixelsSize
Type: TSdlSize
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Surface
The SDL surface associated with the window.
A new surface will be created with the optimal format for the window, if necessary. This surface will be freed when the window is destroyed. Do not free this surface.
This surface will be invalidated if the window is resized. After resizing a window this function must be called again to return a valid surface.
You may not combine this with 3D or the rendering API on this window.
This function is affected by TSdlHints.FramebufferAcceleration.
property Surface: TSdlSurface read GetSurface
Type: TSdlSurface
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
SurfaceVSync
The VSync for the window surface.
When a window surface is created, vsync defaults to TSdlWindowSurfaceVsync.Disabled.
The property can be 1 to synchronize present with every vertical refresh, 2 to synchronize present with every second vertical refresh, etc., TSdlWindowSurfaceVsync.Adaptive for late swap tearing (adaptive vsync), or TSdlWindowSurfaceVsync.Disabled to disable. Not every value is supported by every driver, so you should check the return value to see whether the requested setting is supported.
property SurfaceVSync: TSdlWindowSurfaceVsync read GetSurfaceVSync write SetSurfaceVSync
Type: TSdlWindowSurfaceVsync
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
TextInputActive
Whether or not Unicode text input events are enabled for the window.
property TextInputActive: Boolean read GetTextInputActive
Type: Boolean
See Also
Remarks
This property should only be used on the main thread.
Title
The title of the window.
property Title: String read GetTitle write SetTitle
Type: String
Exceptions
ESdlError: Raised on failure.
Remarks
This property should only be used on the main thread.
Windows
A list of valid windows.
class property Windows: TArray<TSdlWindow> read GetWindows
Type: TArray<TSdlWindow>
Remarks
This property should only be used on the main thread.
WithKeyboardFocus
The window which currently has keyboard focus.
class property WithKeyboardFocus: TSdlWindow read GetWithKeyboardFocus
Type: TSdlWindow
Remarks
This property should only be used on the main thread.
Constructor Descriptions
Create
Create a window with the specified properties.
These are the supported properties:
TSdlProperty.WindowCreateAlwaysOnTop: True if the window should be always on topTSdlProperty.WindowCreateBorderless: True if the window has no window decorationTSdlProperty.WindowCreateExternalGraphicsContext: True if the window will be used with an externally managed graphics context.TSdlProperty.WindowCreateFocusable: True if the window should accept keyboard input (defaults true)TSdlProperty.WindowCreateFullscreen: True if the window should start in fullscreen mode at desktop resolutionTSdlProperty.WindowCreateHeight: The height of the windowTSdlProperty.WindowCreateHidden: True if the window should start hiddenTSdlProperty.WindowCreateHighPixelDensity: True if the window uses a high pixel density buffer if possibleTSdlProperty.WindowCreateMaximized: True if the window should start maximizedTSdlProperty.WindowCreateMenu: True if the window is a popup menu- `TSdlProperty.WindowCreateMetal': True if the window will be used with Metal rendering
TSdlProperty.WindowCreateMinimized: True if the window should start minimizedTSdlProperty.WindowCreateModal: True if the window is modal to its parentTSdlProperty.WindowCreateMouseGrabbed: True if the window starts with grabbed mouse focusTSdlProperty.WindowCreateOpenGL: True if the window will be used with OpenGL renderingTSdlProperty.WindowCreateParent: A TSdlWindow that will be the parent of this window, required for windows with the "tooltip", "menu", and "modal" propertiesTSdlProperty.WindowCreateResizable: True if the window should be resizableTSdlProperty.WindowCreateTitle: The title of the windowTSdlProperty.WindowCreateTransparent: True if the window show transparent in the areas with alpha of 0TSdlProperty.WindowCreateTooltip: True if the window is a tooltipTSdlProperty.WindowCreateUtility: True if the window is a utility window, not showing in the task bar and window listTSdlProperty.WindowCreateVulkan: True if the window will be used with Vulkan renderingTSdlProperty.WindowCreateWidth: the width of the windowTSdlProperty.WindowCreateX: The X position of the window, or TSdlWindowPos.Centered. Defaults to TSdlWindowPos.Undefined. This is relative to the parent for windows with the "tooltip" or "menu" property set.TSdlProperty.WindowCreateY: The Y position of the window, or TSdlWindowPos.Centered. Defaults to TSdlWindowPos.Undefined. This is relative to the parent for windows with the "tooltip" or "menu" property set.
These are additional supported properties on macOS:
TSdlProperty.WindowCreateCocoaWindow: The NSWindow handle associated with the window, if you want to wrap an existing window.TSdlProperty.WindowCreateCocoaView: The NSView handle associated with the window, defaults to[window contentView]
These are additional supported properties on Windows:
TSdlProperty.WindowCreateWin32Hwnd: the HWND associated with the window, if you want to wrap an existing window.TSdlProperty.WindowCreateWin32PixelFormatHwnd: optional, another window to share pixel format with, useful for OpenGL windows
The window is implicitly shown if the "hidden" property is not set.
Windows with the "tooltip" and "menu" properties are popup windows and have the behaviors and guidelines outlined in the constructor that creates a popup window.
If this window is being created to be used with an TSdlRenderer, you should not add a graphics API specific property (TSdlProperty.WindowCreateOpenGL, etc), as SDL will handle that internally when it chooses a renderer. However, SDL might need to recreate your window at that point, which may cause the window to appear briefly, and then flicker as it is recreated. The correct approach to this is to create the window with the TSdlProperty.WindowCreateHidden property set to True, then create the renderer, then show the window with Show.
constructor Create(const AProperties: TSdlProperties); overload
Parameters
AProperties: TSdlProperties
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This constructor should only be called on the main thread.
Create
Create a child popup window of the specified parent window.
The AFlags parameter must contain at least one of the following:
TSdlWindowFlag.Tooltip: The popup window is a tooltip and will not pass any input events.TSdlWindowFlag.PopupMenu: The popup window is a popup menu. The topmost popup menu will implicitly gain the keyboard focus.
The following flags are not relevant to popup window creation and will be ignored:
TSdlWindowFlag.MinimizedTSdlWindowFlag.MaximizedTSdlWindowFlag.FullscreenTSdlWindowFlag.Borderless
The following flags are incompatible with popup window creation and will cause it to fail:
TSdlWindowFlag.UtilityTSdlWindowFlag.Modal
The parent parameter must be non-null and a valid window. The parent of a popup window can be either a regular, toplevel window, or another popup window.
Popup windows cannot be minimized, maximized, made fullscreen, raised, flash, be made a modal window, be the parent of a toplevel window, or grab the mouse and/or keyboard. Attempts to do so will fail.
Popup windows implicitly do not have a border/decorations and do not appear on the taskbar/dock or in lists of windows such as alt-tab menus.
If a parent window is hidden or destroyed, any child popup windows will be recursively hidden or destroyed as well. Child popup windows not explicitly hidden will be restored when the parent is shown.
constructor Create(const AParent: TSdlWindow; const AOffsetX, AOffsetY, AW, AH: Integer; const AFlags: TSdlWindowFlags); overload
Parameters
AParent: TSdlWindow
: The parent of the window.
AOffsetX: Integer
: The X position of the popup window relative to the origin of the parent.
AOffsetY: Integer
: The Y position of the popup window relative to the origin of the parent window.
AW: Integer
: The width of the window.
AH: Integer
: The height of the window.
AFlags: TSdlWindowFlags
: TSdlWindowFlag.Tooltip or TSdlWindowFlag.PopupMenu, and zero or more additional flags.
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This constructor should only be called on the main thread.
Create
Create a window with the specified dimensions and flags.
AFlags may be zero or more of the following:
TSdlWindowFlag.Fullscreen: fullscreen window at desktop resolutionTSdlWindowFlag.OpenGL: window usable with an OpenGL contextTSdlWindowFlag.Occluded: window partially or completely obscured by another windowTSdlWindowFlag.Hidden: window is not visibleTSdlWindowFlag.Borderless: no window decorationTSdlWindowFlag.Resizable: window can be resizedTSdlWindowFlag.Minimized: window is minimizedTSdlWindowFlag.Maximized: window is maximizedTSdlWindowFlag.MouseGrabbed: window has grabbed mouse focusTSdlWindowFlag.InputFocus: window has input focusTSdlWindowFlag.MouseFocus: window has mouse focusTSdlWindowFlag.External: window not created by SDLTSdlWindowFlag.Modal: window is modalTSdlWindowFlag.HighPixelDensity: window uses high pixel density back buffer if possibleTSdlWindowFlag.MouseCapture: window has mouse captured (unrelated to MouseGrabbed)TSdlWindowFlag.AlwaysOnTop: window should always be above othersTSdlWindowFlag.Utility: window should be treated as a utility window, not showing in the task bar and window listTSdlWindowFlag.Tooltip: window should be treated as a tooltip and does not get mouse or keyboard focus, requires a parent windowTSdlWindowFlag.PopupMenu: window should be treated as a popup menu, requires a parent windowTSdlWindowFlag.KeyboardGrabbed: window has grabbed keyboard inputTSdlWindowFlag.Vulkan: window usable with a Vulkan instanceTSdlWindowFlag.Metal: window usable with a Metal instanceTSdlWindowFlag.Transparent: window with transparent bufferTSdlWindowFlag.NotFocusable: window should not be focusable
The window is implicitly shown if TSdlWindowFlag.Hidden is not set.
On Apple's macOS, you must set the NSHighResolutionCapable Info.plist property to YES, otherwise you will not receive a High-DPI OpenGL canvas.
The window pixel size may differ from its window coordinate size if the window is on a high pixel density display. Use Size to query the client area's size in window coordinates, and SizeInPixels or TSdlRenderer.OutputSize to query the drawable size in pixels. Note that the drawable size can vary after the window is created and should be queried again if you get an TSdlEventKind.WindowPixelSizeChanged event.
If the window is created with any of the TSdlWindowFlag.OpenGL or TSdlWindowFlag.Vulkan flags, then the corresponding LoadLibrary function is called and the corresponding UnloadLibrary function is called when the window is destroyed.
If TSdlWindowFlag.Vulkan is specified and there isn't a working Vulkan driver, then this constructor will fail.
If TSdlWindowFlag.Metal is specified on an OS that does not support Metal, then this constructor will fail.
If you intend to use this window with a TSdlRenderer, then you should use TSdlRenderer constructor that also creates a window, to avoid window flicker.
On non-Apple devices, SDL requires you to either not link to the Vulkan loader or link to a dynamic library version. This limitation may be removed in a future version of SDL.
constructor Create(const ATitle: String; const AW, AH: Integer; const AFlags: TSdlWindowFlags); overload
Parameters
ATitle: String
: The title of the window.
AW: Integer
: The width of the window.
AH: Integer
: The height of the window.
AFlags: TSdlWindowFlags
: Zero or more TSdlWindowFlag's.
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This constructor should only be called on the main thread.
Destroy
class destructor Destroy
Operator Descriptions
Equal(TSdlWindow, TSdlWindow)
Used to compare against another TSdlWindow.
class operator Equal(const ALeft, ARight: TSdlWindow): Boolean; inline; static
Parameters
ALeft: TSdlWindow
ARight: TSdlWindow
Returns
Boolean
Equal(TSdlWindow, Pointer)
Used to compare against nil.
class operator Equal(const ALeft: TSdlWindow; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlWindow
ARight: Pointer
Returns
Boolean
Implicit(Pointer)
Used to set the value to nil.
class operator Implicit(const AValue: Pointer): TSdlWindow; inline; static
Parameters
AValue: Pointer
Returns
NotEqual(TSdlWindow, TSdlWindow)
Used to compare against another TSdlWindow.
class operator NotEqual(const ALeft, ARight: TSdlWindow): Boolean; inline; static
Parameters
ALeft: TSdlWindow
ARight: TSdlWindow
Returns
Boolean
NotEqual(TSdlWindow, Pointer)
Used to compare against nil.
class operator NotEqual(const ALeft: TSdlWindow; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlWindow
ARight: Pointer
Returns
Boolean
Method Descriptions
ClearComposition
Dismiss the composition window/IME without disabling the subsystem.
procedure ClearComposition; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
ClearTextInputArea(Integer)
Clear the area used to type Unicode text input.
Native input methods may place a window with word suggestions near the cursor, without covering the text being entered.
procedure ClearTextInputArea(const ACursor: Integer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
ACursor: Integer
: The offset of the current cursor location relative to left position of the window, in window coordinates.
See Also
Remarks
This method should only be called on the main thread.
Flash(TSdlFlashOperation)
Request a window to demand attention from the user.
procedure Flash(const AOperation: TSdlFlashOperation); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AOperation: TSdlFlashOperation
: The operation to perform.
Remarks
This function should only be called on the main thread.
Free
Frees the window.
Any child windows owned by the window will be recursively destroyed as well.
Note that on some platforms, the visible window may not actually be removed from the screen until the SDL event loop is pumped again, even though the window is no longer valid after this call.
procedure Free; inline
Remarks
This method should only be called on the main thread.
FreeSurface
Destroy the surface associated with the window.
procedure FreeSurface; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
FromID(TSdlWindowID)
Get a window from a stored ID.
The numeric ID is what TSdlWindowEvent references, and is necessary to map these events to specific TSdlWindow objects.
class function FromID(const AId: TSdlWindowID): TSdlWindow; inline; static
Exceptions
ESdlError: Raised on failure or if the window does not exist.
Parameters
AId: TSdlWindowID
: The ID of the window.
Returns
TSdlWindow: The window associated with AId.
See Also
Remarks
This function should only be called on the main thread.
GetAspectRatio(Single, Single)
Get the aspect ratio of the window's client area.
procedure GetAspectRatio(out AMinAspect, AMaxAspect: Single); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AMinAspect: Single
: Is set to the minimum aspect ratio of the window.
AMaxAspect: Single
: Is set to the maximum aspect ratio of the window.
See Also
Remarks
This method should only be called on the main thread.
GetBordersSize(Integer, Integer, Integer, Integer)
Get the size of the window's borders (decorations) around the client area.
Note: This method may fail on systems where the window has not yet been decorated by the display server (for example, immediately after calling Create). It is recommended that you wait at least until the window has been presented and composited, so that the window system has a chance to decorate the window and provide the border dimensions to SDL.
procedure GetBordersSize(out ATop, ALeft, ABottom, ARight: Integer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
ATop: Integer
: Set to the size of the top border.
ALeft: Integer
: Set to size of the left border.
ABottom: Integer
: Set to size of the bottom border.
ARight: Integer
: Set to size of the right border.
See Also
Remarks
This function should only be called on the main thread.
GetMaximumSize(Integer, Integer)
Get the maximum size of the window's client area.
procedure GetMaximumSize(out AMaxW, AMaxH: Integer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AMaxW: Integer
AMaxH: Integer
See Also
Remarks
This method should only be called on the main thread.
GetMinimumSize(Integer, Integer)
Get the minimum size of the window's client area.
procedure GetMinimumSize(out AMinW, AMinH: Integer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AMinW: Integer
: Is set to the minimum width of the window.
AMinH: Integer
: Is set to the minimum height of the window.
See Also
Remarks
This method should only be called on the main thread.
GetPosition(TSdlWindowPos, TSdlWindowPos)
Get the position of the window.
This is the current position of the window as last reported by the windowing system.
procedure GetPosition(out AX, AY: TSdlWindowPos); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AX: TSdlWindowPos
: Set to the X position of the window.
AY: TSdlWindowPos
: Set to the Y position of the window.
See Also
Remarks
This method should only be called on the main thread.
GetSize(Integer, Integer)
Get the size of the window's client area.
The window pixel size may differ from its window coordinate size if the window is on a high pixel density display. Use GetSizeInPixels or TSdlRenderer.OutputSize to get the real client area size in pixels.
procedure GetSize(out AW, AH: Integer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AW: Integer
: Is set to the width of the window.
AH: Integer
: a pointer filled in with the height of the window, may be NULL.
See Also
Remarks
This method should only be called on the main thread.
GetSizeInPixels(Integer, Integer)
Get the size of the window's client area, in pixels.
procedure GetSizeInPixels(out AW, AH: Integer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AW: Integer
: Is set to the width in pixels.
AH: Integer
: Is set to the height in pixels.
See Also
Remarks
This method should only be called on the main thread.
GetTextInputArea(TSdlRect, Integer)
Get the area used to type Unicode text input.
This returns the values previously set by SetTextInputArea.
procedure GetTextInputArea(out ARect: TSdlRect; out ACursor: Integer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
ARect: TSdlRect
: Is set to the text input area.
ACursor: Integer
: Is set to the current cursor location relative to ARect.X.
See Also
Remarks
This method should only be called on the main thread.
Hide
Hide the window.
procedure Hide; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
Maximize
Request that the window be made as large as possible.
Non-resizable windows can't be maximized. The window must have the TSdlWindowFlag.Resizable flag set, or this will have no effect.
On some windowing systems this request is asynchronous and the new window state may not have have been applied immediately upon the return of this function. If an immediate change is required, call Sync to block until the changes have taken effect.
When the window state changes, an TSdlEventKind.WindowMaximized event will be emitted. Note that, as this is just a request, the windowing system can deny the state change.
When maximizing a window, whether the constraints set via SetMaximumSize are honored depends on the policy of the window manager. Win32 and macOS enforce the constraints when maximizing.
procedure Maximize; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
Minimize
Request that the window be minimized to an iconic representation.
If the window is in a fullscreen state, this request has no direct effect. It may alter the state the window is returned to when leaving fullscreen.
On some windowing systems this request is asynchronous and the new window state may not have been applied immediately upon the return of this function. If an immediate change is required, call Sync to block until the changes have taken effect.
When the window state changes, an TSdlEventKind.WindowMinimized event will be emitted. Note that, as this is just a request, the windowing system can deny the state change.
procedure Minimize; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
RaiseAndFocus
Request that a window be raised above other windows and gain the input focus.
The result of this request is subject to desktop window manager policy, particularly if raising the requested window would result in stealing focus from another application. If the window is successfully raised and gains input focus, an TSdlEventKind.WindowFocusGained event will be emitted, and the window will have the TSdlWindowFlag.InputFocus flag set.
procedure RaiseAndFocus; inline
Exceptions
ESdlError: Raised on failure.
Remarks
This method should only be called on the main thread.
Restore
Request that the size and position of a minimized or maximized window be restored.
If the window is in a fullscreen state, this request has no direct effect. It may alter the state the window is returned to when leaving fullscreen.
On some windowing systems this request is asynchronous and the new window state may not have have been applied immediately upon the return of this function. If an immediate change is required, call Sync to block until the changes have taken effect.
When the window state changes, an TSdlEventKind.WindowRestored event will be emitted. Note that, as this is just a request, the windowing system can deny the state change.
procedure Restore; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
SetAspectRatio(Single, Single)
Request that the aspect ratio of a window's client area be set.
The aspect ratio is the ratio of width divided by height, e.g. 2560x1600 would be 1.6. Larger aspect ratios are wider and smaller aspect ratios are narrower.
If, at the time of this request, the window in a fixed-size state, such as maximized or fullscreen, the request will be deferred until the window exits this state and becomes resizable again.
On some windowing systems, this request is asynchronous and the new window aspect ratio may not have have been applied immediately upon the return of this function. If an immediate change is required, call Sync to block until the changes have taken effect.
When the window size changes, an TSdlEventKind.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 systems 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, as this is just a request, it can be denied by the windowing system.
procedure SetAspectRatio(const AMinAspect, AMaxAspect: Single); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AMinAspect: Single
: The minimum aspect ratio of the window, or 0.0 for no limit.
AMaxAspect: Single
: The maximum aspect ratio of the window, or 0.0 for no limit.
See Also
Remarks
This method should only be called on the main thread.
SetHitTestCallback(TSdlHitTestCallback)
Provide a callback that decides if a window region has special properties.
Normally windows are dragged and resized by decorations provided by the system window manager (a title bar, borders, etc), but for some apps, it makes sense to drag them from somewhere else inside the window itself; for example, one might have a borderless window that wants to be draggable from any part, or simulate its own title bar, etc.
This function lets the app provide a callback that designates pieces of a given window as special. This callback is run during event processing if we need to tell the OS to treat a region of the window specially; the use of this callback is known as "hit testing."
Mouse input may not be delivered to your application if it is within a special area; the OS will often apply that input to moving the window or resizing the window and not deliver it to the application.
Specifying nil for a callback disables hit-testing. Hit-testing is disabled by default.
Platforms that don't support this functionality will return False unconditionally, even if you're attempting to disable hit-testing.
Your callback may fire at any time, and its firing does not indicate any specific behavior (for example, on Windows, this certainly might fire when the OS is deciding whether to drag your window, but it fires for lots of other reasons, too, some unrelated to anything you probably care about and when the mouse isn't actually at the location it is testing). Since this can fire at any time, you should try to keep your callback efficient, devoid of allocations, etc.
function SetHitTestCallback(const ACallback: TSdlHitTestCallback): Boolean
Parameters
ACallback: TSdlHitTestCallback
: The function to call when doing a hit-test.
Returns
Boolean: True on success or False on failure (eg. when the platform does not support hit-testing.
Remarks
This method should only be called on the main thread.
SetMaximumSize(Integer, Integer)
Set the maximum size of the window's client area.
procedure SetMaximumSize(const AMaxW, AMaxH: Integer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AMaxW: Integer
: The maximum width of the window, or 0 for no limit.
AMaxH: Integer
: The maximum height of the window, or 0 for no limit.
See Also
Remarks
This method should only be called on the main thread.
SetMinimumSize(Integer, Integer)
Set the minimum size of the window's client area.
procedure SetMinimumSize(const AMinW, AMinH: Integer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AMinW: Integer
: The minimum width of the window, or 0 for no limit.
AMinH: Integer
: The minimum height of the window, or 0 for no limit.
See Also
Remarks
This method should only be called on the main thread.
SetPosition(TSdlWindowPos, TSdlWindowPos)
Request that the window's position be set.
If the window is in an exclusive fullscreen or maximized state, this request has no effect.
This can be used to reposition fullscreen-desktop windows onto a different display, however, as exclusive fullscreen windows are locked to a specific display, they can only be repositioned programmatically via FullscreenMode.
On some windowing systems this request is asynchronous and the new coordinates may not have have been applied immediately upon the return of this function. If an immediate change is required, call Sync to block until the changes have taken effect.
When the window position changes, an TSdlEventKind.WindowMoved event will be emitted with the window's new coordinates. Note that the new coordinates may not match the exact coordinates requested, as some windowing systems can restrict the position of the window in certain scenarios (e.g. constraining the position so the window is always within desktop bounds). Additionally, as this is just a request, it can be denied by the windowing system.
procedure SetPosition(const AX, AY: TSdlWindowPos); inline
Parameters
AX: TSdlWindowPos
: The X coordinate of the window, or TSdlWindowPos.Centered The Y coordinate of the window, or TSdlWindowPos.Centered
AY: TSdlWindowPos
SetSize(Integer, Integer)
Request that the size of a window's client area be set.
If the window is in a fullscreen or maximized state, this request has no effect.
To change the exclusive fullscreen mode of a window, use FullscreenMode.
On some windowing systems, this request is asynchronous and the new window size may not have have been applied immediately upon the return of this function. If an immediate change is required, call Sync to block until the changes have taken effect.
When the window size changes, an TSdlEventKind.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 systems 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, as this is just a request, it can be denied by the windowing system.
function SetSize(const AW, AH: Integer): Boolean; inline
Parameters
AW: Integer
: The width of the window, must be > 0.
AH: Integer
: The height of the window, must be > 0.
Returns
Boolean: True on success, False on failure.
See Also
Remarks
This method should only be called on the main thread.
SetTextInputArea(TSdlRect, Integer)
Set the area used to type Unicode text input.
Native input methods may place a window with word suggestions near the cursor, without covering the text being entered.
procedure SetTextInputArea(const ARect: TSdlRect; const ACursor: Integer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
ARect: TSdlRect
: The text input area, in window coordinates.
ACursor: Integer
: The offset of the current cursor location relative to ARect.X, in window coordinates.
See Also
Remarks
This method should only be called on the main thread.
Show
Show the window.
procedure Show; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
ShowSystemMenu(Integer, Integer)
Display the system-level window menu.
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 desktops where this is unsupported, this function does nothing.
procedure ShowSystemMenu(const AX, AY: Integer); inline
Exceptions
ESdlError: Raised on failure.
Parameters
AX: Integer
: The X coordinate of the menu, relative to the origin (top-left) of the client area.
AY: Integer
: The Y coordinate of the menu, relative to the origin (top-left) of the client area.
Remarks
This method should only be called on the main thread.
StartTextInput(TSdlProperties)
Start accepting Unicode text input events in the window, with properties describing the input.
This function will enable text input (TSdlEventKind.TextInput and TSdlEventKind.TextEditing events) in this window. Please use this function paired with StopTextInput.
Text input events are not received by default.
On some platforms using this function shows the screen keyboard and/or activates an IME, which can prevent some key press events from being passed through.
These are the supported properties:
TSdlProperty.TextInputType- a TSdlTextInputType value that describes text being input, defaults to TSdlTextInputType.Text.TSdlProperty.TextInputCapitalization- a TSdlCapitalization value that describes how text should be capitalized, defaults to TSdlCapitalization.Sentences for normal text entry, TSdlCapitalization.Word for TSdlTextInputTYpe.TextName, and TSdlCapitalization.None for e-mail addresses, usernames, and passwords.TSdlProperty.TextInputAutoCorrect- True to enable auto completion and auto correction, defaults to True.TSdlProperty.TextInputMultiLine- True if multiple lines of text are allowed. This defaults to True if TSdlHints.ReturnKeyHidesIme is '0' or is not set, and defaults to False if TSdlHints.ReturnKeyHidesIme is '1'.
On Android you can directly specify the input type:
TSdlProperty.TextInputAndroidInputType- the text input type to use, overriding other properties. This is documented at InputType.
procedure StartTextInput(const AProps: TSdlProperties); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AProps: TSdlProperties
: The properties to use.
See Also
Remarks
This method should only be called on the main thread.
StartTextInput
Start accepting Unicode text input events in the window.
This function will enable text input (TSdlEventKind.TextInput and TSdlEventKind.TextEditing events) in this window. Please use this function paired with StopTextInput.
Text input events are not received by default.
On some platforms using this method shows the screen keyboard and/or activates an IME, which can prevent some key press events from being passed through.
procedure StartTextInput; overload; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
StopTextInput
Stop receiving any text input events in the window.
If StartTextInput showed the screen keyboard, this function will hide it.
procedure StopTextInput
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
Sync
Block until any pending window state is finalized.
On asynchronous windowing systems, this acts as a synchronization barrier for pending window state. It 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 system, as window state changes may involve somewhat lengthy animations that must complete before the window is in its final requested state.
On windowing systems where changes are immediate, this does nothing.
function Sync: Boolean; inline
Returns
Boolean: True on success or False if the operation timed out before the window was in the requested state.
See Also
Remarks
This method should only be called on the main thread.
UpdateSurface(TSdlRect[])
Copy areas of the window surface to the screen.
This is the function you use to reflect changes to portions of the surface on the screen.
Note that this function will update at least the rectangles specified, but this is only intended as an optimization; in practice, this might update more of the screen (or all of the screen!), depending on what method SDL uses to send pixels to the system.
procedure UpdateSurface(const ARects: array of TSdlRect); overload
Exceptions
ESdlError: Raised on failure.
Parameters
ARects: array of TSdlRect
: An array of TSdlRect records representing areas of the surface to copy, in pixels.
See Also
Remarks
This method should only be called on the main thread.
UpdateSurface(TArray<TSdlRect>)
Copy areas of the window surface to the screen.
This is the function you use to reflect changes to portions of the surface on the screen.
Note that this function will update at least the rectangles specified, but this is only intended as an optimization; in practice, this might update more of the screen (or all of the screen!), depending on what method SDL uses to send pixels to the system.
procedure UpdateSurface(const ARects: TArray<TSdlRect>); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
ARects: TArray<TSdlRect>
: An array of TSdlRect records representing areas of the surface to copy, in pixels.
See Also
Remarks
This method should only be called on the main thread.
UpdateSurface
Copy the window surface to the screen.
This is the function you use to reflect any changes to the surface on the screen.
procedure UpdateSurface; overload; inline
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
WarpMouse(TSdlPointF)
Move the mouse cursor to the given position within the window.
This method generates a mouse motion event if relative mode is not enabled. If relative mode is enabled, you can force mouse events for the warp by setting the TSdlHints.MouseRelativeWarpMotion hint.
Note that this function will appear to succeed, but not actually move the mouse when used over Microsoft Remote Desktop.
procedure WarpMouse(const APosition: TSdlPointF); overload; inline
Parameters
APosition: TSdlPointF
: The coordinate within the window.
See Also
Remarks
This method should only be called on the main thread.
WarpMouse(Single, Single)
Move the mouse cursor to the given position within the window.
This method generates a mouse motion event if relative mode is not enabled. If relative mode is enabled, you can force mouse events for the warp by setting the TSdlHints.MouseRelativeWarpMotion hint.
Note that this function will appear to succeed, but not actually move the mouse when used over Microsoft Remote Desktop.
procedure WarpMouse(const AX, AY: Single); overload; inline
Parameters
AX: Single
: The X coordinate within the window.
AY: Single
: The Y coordinate within the window.
See Also
Remarks
This method should only be called on the main thread.