Cursors

If developing an application that accepts mouse input, you can control the behaviour of the cursor through the Cursor class, accessible globally through gCursor(). It allows you to manipulate cursor position, look and clipping behaviour.

Position

You can retrieve the current position of the cursor by calling Cursor::getScreenPosition(). Note that this same information is reported by the input system, and is generally preferred to use those values instead.

You can also change the cursor position directly by calling Cursor::setScreenPosition(). Values for both methods will be in pixels relative to the user's screen (or screens).

// Move cursor to the top left corner of the screen
gCursor().setScreenPosition(Vector2I(0, 0));

Visibility

Cursor can be hidden by calling Cursor::hide(), and shown again by calling Cursor::show().

// Hide the cursor if user is holding right mouse button (e.g. rotating the camera)
if(gInput().isButtonHeld(BC_MOUSE_RIGHT))
else
gCursor().show();

Icon

You can change the cursor's icon by calling Cursor::setCursor() and specifying one of the builtin cursor types, as CursorType enum.

// Change to wait cursor in case we're doing some processing
gCursor().setCursor(CursorType::Wait);

You can also define your own cursor icons by calling Cursor::setCursorIcon(). You'll need to provide a unique name for your cursor, a PixelData object containing the image to use, and a cursor hot-spot. Hot spot determines at which part of the image will the user's clicks be registered (e.g. in case of an arrow icon, it would be at the top of the arrow).

SPtr<PixelData> pixelData = ...; // Manually fill or read pixel data from a texture
Vector2I hotSpot(5, 5);
gCursor().setCursorIcon("MyCustomCursor", *pixelData, hotSpot);

Once you have registered the icon you can apply it by calling an overload of Cursor::setCursor() that accepts a cursor name.

gCursor().setCursor("MyCustomCursor");

You can also change icons of the built-in cursor types by calling Cursor::setCursorIcon() overload that accepts a CursorType as its first parameter.

Clipping

Sometimes it is useful to limit the cursor to a specific area of the screen (e.g. if playing in windowed mode its useful to limit the cursor to the window). For this purpose you can use either of these methods:

  • Cursor::clipToWindow() - Accepts a RenderWindow as a parameter, and will limit cursor movement within that window.
  • Cursor::clipToRect() - Accepts an area relative to the user's screen, to which to limit the movement to.
// Limit cursor movement to the primary application window
SPtr<RenderWindow> window = gApplication().getPrimaryWindow();

When you wish to disable clipping, you can call Cursor::clipDisable().

// Remove any limits to cursor movement