This is a copy of the Java documentation for libGDX. It is not finished being ported.

Cursor catching

For some games like first-person shooters, it is often necessary to catch the cursor so it stays in the center of the screen, and only use position deltas to rotate the camera. Other times we might want to position the cursor manually. Both things can be done as follows:

Gdx.input.setCursorCatched(true);
Gdx.input.setCursorPosition(x, y);

Cursor catching is only available on the desktop and GWT backends, and positioning is only available on the desktop backends.

Custom cursor

Changing the cursor to a custom image can be done like so. The following example turns this 32×32 image into a cursor: Example custom cursor image

Pixmap pixmap = new Pixmap(Gdx.files.internal("badcursor.png"));
// Set hotspot to the middle of it (0,0 would be the top-left corner)
int xHotspot = 15, yHotspot = 15;
Cursor cursor = Gdx.graphics.newCursor(pixmap, xHotspot, yHotspot);
pixmap.dispose(); // We don't need the pixmap anymore
Gdx.graphics.setCursor(cursor);

Note: You should call dispose() on your cursor if you don’t need it anymore.

Only cursors of power-of-two resolutions are supported. For example, if your cursor is 24×24, you must pad it to 32×32. Remember that your cursor may appear small on HDPI monitors if you don’t account for them. Custom cursors are supported only on the desktop and GWT backends.

System cursors

You can also change the cursor to one of the other system cursors. This only works on the LWJGL3, GWT and Android backends. It can be done as follows:

Gdx.graphics.setSystemCursor(SystemCursor.Crosshair);

Supported system cursors

Cursor appearance varies depending on operating system and user preferences. The images below are from Ubuntu. Windows and macOS cursors are not displayed out of respect for copyright, but they look similar.

You can hover over each row in the table with your mouse to see what the cursors look like on your own system.

SystemCursor Appearance Notes
Arrow default cursor The default cursor
Ibeam text cursor Indicates text can be selected
Crosshair crosshair cursor Used for finer precision than the default arrow cursor
Hand pointer cursor Indicates hyperlink can be followed
HorizontalResize ew-resize cursor Indicates item can be resized horizontally
VerticalResize ns-resize cursor Indicates item can be resized vertically
NWSEResize nwse-resize cursor Indicates item corner can be resized inwards or outwards
macOS: Uses private system API and may fail in future
Linux: Uses newer standard that not all cursor themes support
NESWResize nesw-resize cursor Indicates item corner can be resized inwards or outwards
macOS: Uses private system API and may fail in future
Linux: Uses newer standard that not all cursor themes support
AllResize move cursor Indicates the ability to scroll/pan in all directions
NotAllowed not-allowed cursor Indicates an action is prohibited
Linux: Uses newer standard that not all cursor themes support
None
Hides the cursor for when it may be unwanted, such as during video playback

Note that NWSEResize onwards are new in SharpGDX 1.11.0. They aren’t present in earlier versions.

Additional resources

If you wish to let your HTML5 game use system cursors SharpGDX doesn’t support, this is a good starting point:

Copyright © 2024 SharpGDX.