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:
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 |
The default cursor | |
Ibeam |
Indicates text can be selected | |
Crosshair |
Used for finer precision than the default arrow cursor | |
Hand |
Indicates hyperlink can be followed | |
HorizontalResize |
Indicates item can be resized horizontally | |
VerticalResize |
Indicates item can be resized vertically | |
NWSEResize |
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 |
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 |
Indicates the ability to scroll/pan in all directions | |
NotAllowed |
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 libGDX 1.11.0. They aren’t present in earlier versions.
Additional resources
If you wish to let your HTML5 game use system cursors libGDX doesn’t support, this is a good starting point: