TSdlMouse
A mouse
Definition
Unit: Neslib.Sdl3.Input
Properties
| Name | Description |
|---|---|
| Focus | The window which currently has mouse focus. |
| HasMouse | Whether a mouse is currently connected. |
| Mice | A list of currently connected mice. |
| Name | Get the name of the mouse. |
| Pen | A virtual mouse used for mouse events simulated with pen input. |
| Touch | A virtual mouse used for mouse events simulated with touch input. |
Operators
| Name | Description |
|---|---|
| Equal(TSdlMouse, TSdlMouse) | Used to compare against another TSdlMouse. |
| Equal(TSdlMouse, Pointer) | Used to compare against nil. |
| Implicit | Used to set the value to nil. |
| NotEqual(TSdlMouse, TSdlMouse) | Used to compare against another TSdlMouse. |
| NotEqual(TSdlMouse, Pointer) | Used to compare against nil. |
Methods
| Name | Description |
|---|---|
| Capture | Capture the mouse and to track input outside an SDL window. |
| GetGlobalState(TSdlPointF) | Query the platform for the asynchronous mouse button state and the desktop-relative platform-cursor position. |
| GetGlobalState(Single, Single) | Query the platform for the asynchronous mouse button state and the desktop-relative platform-cursor position. |
| GetRelativeState(TSdlPointF) | Query SDL's cache for the synchronous mouse button state and accumulated mouse delta since last call. |
| GetRelativeState(Single, Single) | Query SDL's cache for the synchronous mouse button state and accumulated mouse delta since last call. |
| GetState(TSdlPointF) | Query SDL's cache for the synchronous mouse button state and the window-relative SDL-cursor position. |
| GetState(Single, Single) | Query SDL's cache for the synchronous mouse button state and the window-relative SDL-cursor position. |
| WarpGlobal(TSdlPointF) | Move the mouse to the given position in global screen space. |
| WarpGlobal(Single, Single) | Move the mouse to the given position in global screen space. |
Property Descriptions
Focus
The window which currently has mouse focus.
class property Focus: TSdlWindow read GetFocus
Type: TSdlWindow
Remarks
This property should only be used on the main thread.
HasMouse
Whether a mouse is currently connected.
class property HasMouse: Boolean read GetHasMouse
Type: Boolean
See Also
Remarks
This property should only be used on the main thread.
Mice
A list of currently connected mice.
Note that this will include any device or virtual driver that includes mouse functionality, including some game controllers, KVM switches, etc. You should wait for input from a device before you consider it actively in use.
class property Mice: TArray<TSdlMouse> read GetMice
Type: TArray<TSdlMouse>
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
Name
Get the name of the mouse.
This property returns an empty string if the mouse doesn't have a name.
property Name: String read GetName
Type: String
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
Pen
A virtual mouse used for mouse events simulated with pen input.
class property Pen: TSdlMouse read GetPen
Type: TSdlMouse
Touch
A virtual mouse used for mouse events simulated with touch input.
class property Touch: TSdlMouse read GetTouch
Type: TSdlMouse
Operator Descriptions
Equal(TSdlMouse, TSdlMouse)
Used to compare against another TSdlMouse.
class operator Equal(const ALeft, ARight: TSdlMouse): Boolean; inline; static
Parameters
ALeft: TSdlMouse
ARight: TSdlMouse
Returns
Boolean
Equal(TSdlMouse, Pointer)
Used to compare against nil.
class operator Equal(const ALeft: TSdlMouse; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlMouse
ARight: Pointer
Returns
Boolean
Implicit(Pointer)
Used to set the value to nil.
class operator Implicit(const AValue: Pointer): TSdlMouse; inline; static
Parameters
AValue: Pointer
Returns
NotEqual(TSdlMouse, TSdlMouse)
Used to compare against another TSdlMouse.
class operator NotEqual(const ALeft, ARight: TSdlMouse): Boolean; inline; static
Parameters
ALeft: TSdlMouse
ARight: TSdlMouse
Returns
Boolean
NotEqual(TSdlMouse, Pointer)
Used to compare against nil.
class operator NotEqual(const ALeft: TSdlMouse; const ARight: Pointer): Boolean; inline; static
Parameters
ALeft: TSdlMouse
ARight: Pointer
Returns
Boolean
Method Descriptions
Capture(Boolean)
Capture the mouse and to track input outside an SDL window.
Capturing enables your app to obtain mouse events globally, instead of just within your window. Not all video targets support this function. When capturing is enabled, the current window will get all mouse events, but unlike relative mode, no change is made to the cursor and it is not restrained to your window.
This function may also deny mouse input to other windows--both those in your application and others on the system--so you should use this function sparingly, and in small bursts. For example, you might want to track the mouse while the user is dragging something, until the user releases a mouse button. It is not recommended that you capture the mouse for long periods of time, such as the entire time your app is running. For that, you should probably use TSdlWindow.IsRelativeMouseMode or TSdlWindow.MouseGrab, depending on your goals.
While captured, mouse events still report coordinates relative to the current (foreground) window, but those coordinates may be outside the bounds of the window (including negative values). Capturing is only allowed for the foreground window. If the window loses focus while capturing, the capture will be disabled automatically.
While capturing is enabled, the current window will have the TSdlWindowFlag.MouseCapture flag set.
Please note that SDL will attempt to "auto capture" the mouse while the user is pressing a button; this is to try and make mouse behavior more consistent between platforms, and deal with the common case of a user dragging the mouse outside of the window. This means that if you are calling CaptureMouse only to deal with this situation, you do not have to (although it is safe to do so). If this causes problems for your app, you can disable auto capture by setting the TSdlHints.MouseAutoCapture hint to zero.
class procedure Capture(const AEnabled: Boolean); inline; static
Exceptions
ESdlError: Raised on failure.
Parameters
AEnabled: Boolean
: True to enable capturing, False to disable.
See Also
Remarks
This method should only be called on the main thread.
GetGlobalState(TSdlPointF)
Query the platform for the asynchronous mouse button state and the desktop-relative platform-cursor position.
This method immediately queries the platform for the most recent asynchronous state, more costly than retrieving SDL's cached state in GetState.
In Relative Mode, the platform-cursor's position usually contradicts the SDL-cursor's position as manually calculated from GetState and TSdlWindow.Position.
This method can be useful if you need to track the mouse outside of a specific window and Capture doesn't fit your needs. For example, it could be useful if you need to track the mouse while dragging a window, where coordinates relative to a window might not be in sync at all times.
function GetGlobalState(out APosition: TSdlPointF): TSdlMouseButtons; overload; inline
Parameters
APosition: TSdlPointF
: Is set to the platform-cursor's position from the desktop's top left corner.
Returns
TSdlMouseButtons: The mouse buttons that are pressed.
See Also
Remarks
This method should only be called on the main thread.
GetGlobalState(Single, Single)
Query the platform for the asynchronous mouse button state and the desktop-relative platform-cursor position.
This method immediately queries the platform for the most recent asynchronous state, more costly than retrieving SDL's cached state in GetState.
In Relative Mode, the platform-cursor's position usually contradicts the SDL-cursor's position as manually calculated from GetState and TSdlWindow.Position.
This method can be useful if you need to track the mouse outside of a specific window and Capture doesn't fit your needs. For example, it could be useful if you need to track the mouse while dragging a window, where coordinates relative to a window might not be in sync at all times.
function GetGlobalState(out AX, AY: Single): TSdlMouseButtons; overload; inline
Parameters
AX: Single
: Is set to the platform-cursor's X-position from the desktop's top left corner.
AY: Single
Returns
TSdlMouseButtons: The mouse buttons that are pressed.
See Also
Remarks
This method should only be called on the main thread.
GetRelativeState(TSdlPointF)
Query SDL's cache for the synchronous mouse button state and accumulated mouse delta since last call.
This method returns the cached synchronous state as SDL understands it from the last pump of the event queue.
To query the platform for immediate asynchronous state, use GetGlobalState.
This method is useful for reducing overhead by processing relative mouse inputs in one go per-frame instead of individually per-event, at the expense of losing the order between events within the frame (e.g. quickly pressing and releasing a button within the same frame).
function GetRelativeState(out ADelta: TSdlPointF): TSdlMouseButtons; overload; inline
Parameters
ADelta: TSdlPointF
: Is set to the mouse delta accumulated since last call.
Returns
TSdlMouseButtons: The mouse buttons that are pressed.
See Also
Remarks
This method should only be called on the main thread.
GetRelativeState(Single, Single)
Query SDL's cache for the synchronous mouse button state and accumulated mouse delta since last call.
This method returns the cached synchronous state as SDL understands it from the last pump of the event queue.
To query the platform for immediate asynchronous state, use GetGlobalState.
This method is useful for reducing overhead by processing relative mouse inputs in one go per-frame instead of individually per-event, at the expense of losing the order between events within the frame (e.g. quickly pressing and releasing a button within the same frame).
function GetRelativeState(out AX, AY: Single): TSdlMouseButtons; overload; inline
Parameters
AX: Single
: Is set to the X mouse delta accumulated since last call.
AY: Single
: Is set to the Y mouse delta accumulated since last call.
Returns
TSdlMouseButtons: The mouse buttons that are pressed.
See Also
Remarks
This method should only be called on the main thread.
GetState(TSdlPointF)
Query SDL's cache for the synchronous mouse button state and the window-relative SDL-cursor position.
This method returns the cached synchronous state as SDL understands it from the last pump of the event queue.
To query the platform for immediate asynchronous state, use GetGlobalState.
In Relative Mode, the SDL-cursor's position usually contradicts the platform-cursor's position as manually calculated from GetGlobalState and TSdlWindow.Position.
function GetState(out APosition: TSdlPointF): TSdlMouseButtons; overload; inline
Parameters
APosition: TSdlPointF
: Is set to the SDL-cursor's position from the focused window's top left corner.
Returns
TSdlMouseButtons: The mouse buttons that are pressed.
See Also
Remarks
This method should only be called on the main thread.
GetState(Single, Single)
Query SDL's cache for the synchronous mouse button state and the window-relative SDL-cursor position.
This method returns the cached synchronous state as SDL understands it from the last pump of the event queue.
To query the platform for immediate asynchronous state, use GetGlobalState.
In Relative Mode, the SDL-cursor's position usually contradicts the platform-cursor's position as manually calculated from GetGlobalState and TSdlWindow.Position.
function GetState(out AX, AY: Single): TSdlMouseButtons; overload; inline
Parameters
AX: Single
: Is set to the SDL-cursor's X-position from the focused window's top left corner.
AY: Single
: Is set to the SDL-cursor's Y-position from the focused window's top left corner.
Returns
TSdlMouseButtons: The mouse buttons that are pressed.
See Also
Remarks
This method should only be called on the main thread.
WarpGlobal(TSdlPointF)
Move the mouse to the given position in global screen space.
This method generates a mouse motion event.
A failure of this function usually means that it is unsupported by a platform.
Note that this function will appear to succeed, but not actually move the mouse when used over Microsoft Remote Desktop.
procedure WarpGlobal(const APosition: TSdlPointF); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
APosition: TSdlPointF
: The coordinate.
See Also
Remarks
This method should only be called on the main thread.
WarpGlobal(Single, Single)
Move the mouse to the given position in global screen space.
This method generates a mouse motion event.
A failure of this function usually means that it is unsupported by a platform.
Note that this function will appear to succeed, but not actually move the mouse when used over Microsoft Remote Desktop.
procedure WarpGlobal(const AX, AY: Single); overload; inline
Exceptions
ESdlError: Raised on failure.
Parameters
AX: Single
: The X coordinate.
AY: Single
: The Y coordinate.
See Also
Remarks
This method should only be called on the main thread.