TSdlCursor

The structure used to identify an SDL cursor.

This is opaque data.

Definition

Unit: Neslib.Sdl3.Input

type TSdlCursor = record ... end;

Remarks

This struct is available since SDL 3.2.0.

Properties

Name	Description
Active	The active cursor.
Default	The default cursor.
IsVisible	Whether the cursor is currently being shown.

Constructors

Name	Description
Create(TSdlSystemCursor)	Create a system cursor.
Create(TSdlSurface, Integer, Integer)	Create a color cursor.
Create(Pointer, Pointer, Integer, Integer, Integer, Integer)	Create a cursor using the specified bitmap data and mask (in MSB format).

Operators

Name	Description
Equal(TSdlCursor, TSdlCursor)	Used to compare against another TSdlCursor.
Equal(TSdlCursor, Pointer)	Used to compare against nil.
Implicit	Used to set the value to nil.
NotEqual(TSdlCursor, TSdlCursor)	Used to compare against another TSdlCursor.
NotEqual(TSdlCursor, Pointer)	Used to compare against nil.

Methods

Name	Description
Free	Free a previously-created cursor.
Hide	Hide the cursor.
Show	Show the cursor.

Property Descriptions

Active

The active cursor.

Allows you to set the currently active cursor to the specified one. If the cursor is currently visible, the change will be immediately represented on the display. You can set this properyt to nil to force cursor redraw, if this is desired for any reason.

class property Active: TSdlCursor read GetActive write SetActive

Type: TSdlCursor

Exceptions

ESdlError: Raised on failure.

Remarks

This property should only be used on the main thread.

---

Default

The default cursor.

You do not have to call Free on this cursor, but it is safe to do so.

class property Default: TSdlCursor read GetDefault

Type: TSdlCursor

Exceptions

ESdlError: Raised on failure.

Remarks

This property should only be used on the main thread.

---

IsVisible

Whether the cursor is currently being shown.

Setting this property is equivalent to calling Show or Hide.

class property IsVisible: Boolean read GetIsVisible write SetIsVisible

Type: Boolean

Exceptions

ESdlError: Raised on failure.

See Also

• Hide
• Show

Remarks

This property should only be used on the main thread.

---

Constructor Descriptions

Create

Create a system cursor.

constructor Create(const ASystemCursor: TSdlSystemCursor); overload

Parameters

ASystemCursor: TSdlSystemCursor : The TSdlSystemCursor enum value.

Exceptions

ESdlError: Raised on failure.

See Also

• Free

Remarks

This constructor should only be called on the main thread.

---

Create

Create a color cursor.

If this constructor is passed 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.

constructor Create(const ASurface: TSdlSurface; const AHotX, AHotY: Integer); overload

Parameters

ASurface: TSdlSurface : An SDL surface representing the cursor image.

AHotX: Integer : The X position of the cursor hot spot.

AHotY: Integer : The Y position of the cursor hot spot.

Exceptions

ESdlError: Raised on failure.

See Also

• Free
• Active

Remarks

This constructor should only be called on the main thread.

---

Create

Create a cursor using the specified bitmap data and mask (in MSB format).

AMask has to be in MSB (Most Significant Bit) format.

The cursor width (AW) must be a multiple of 8 bits.

The cursor is created in black and white according to the following:

• AData=0, AMask=1: white
• AData=1, AMask=1: black
• AData=0, AMask=0: transparent
• AData=1, AMask=0: inverted color if possible, black if not.

Cursors created with this function must be freed with Free.

If you want to have a color cursor, or create your cursor from an SDL_Surface, you should use another constructor. Alternately, you can hide the cursor and draw your own as part of your game's rendering, but it will be bound to the framerate.

There is also a constructor that creates a system cursor, which provides several readily-available system cursors to pick from.

constructor Create(const AData, AMask: Pointer; const AW, AH, AHotX, AHotY: Integer); overload

Parameters

AData: Pointer : The color value for each pixel of the cursor.

AMask: Pointer : The mask value for each pixel of the cursor.

AW: Integer : The width of the cursor.

AH: Integer : The height of the cursor.

AHotX: Integer : The X-axis offset from the left of the cursor image to the mouse X position, in the range of 0 to AW - 1.

AHotY: Integer : The Y-axis offset from the top of the cursor image to the mouse Y position, in the range of 0 to AH - 1.

Exceptions

ESdlError: Raised on failure.

See Also

• Free
• Active

Remarks

This constructor should only be called on the main thread.

---

Operator Descriptions

Equal(TSdlCursor, TSdlCursor)

Used to compare against another TSdlCursor.

class operator Equal(const ALeft, ARight: TSdlCursor): Boolean; inline; static

Parameters

ALeft: TSdlCursor

ARight: TSdlCursor

Returns

Boolean

---

Equal(TSdlCursor, Pointer)

Used to compare against nil.

class operator Equal(const ALeft: TSdlCursor; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlCursor

ARight: Pointer

Returns

Boolean

---

Implicit(Pointer)

Used to set the value to nil.

class operator Implicit(const AValue: Pointer): TSdlCursor; inline; static

Parameters

AValue: Pointer

Returns

TSdlCursor

---

NotEqual(TSdlCursor, TSdlCursor)

Used to compare against another TSdlCursor.

class operator NotEqual(const ALeft, ARight: TSdlCursor): Boolean; inline; static

Parameters

ALeft: TSdlCursor

ARight: TSdlCursor

Returns

Boolean

---

NotEqual(TSdlCursor, Pointer)

Used to compare against nil.

class operator NotEqual(const ALeft: TSdlCursor; const ARight: Pointer): Boolean; inline; static

Parameters

ALeft: TSdlCursor

ARight: Pointer

Returns

Boolean

---

Method Descriptions

Free

Free a previously-created cursor.

procedure Free; inline

See Also

• Create

Remarks

This method should only be called on the main thread.

---

Hide

Hide the cursor.

class procedure Hide; inline; static

Exceptions

ESdlError: Raised on failure.

See Also

• IsVisible
• Show

Remarks

This method should only be called on the main thread.

---

Show

Show the cursor.

class procedure Show; inline; static

Exceptions

ESdlError: Raised on failure.

See Also

• IsVisible
• Hide

Remarks

This method should only be called on the main thread.

---