Scoped Cursors and the Cursor Stack

There are many situations where you may want to display a specific cursor for a limited scope event, but want to switch back to the main cursor when the event is over. For example, you may want to show a grab cursor when hovering over a pickup on the floor but revert back to a standard pointer when the mouse is no longer over the pickup. Or you might want to show a sword cursor when hovering over an attackable monster.

Cursory provides an interface for deploying these temporary cursors for discrete events and then falling back to the base cursor when the events finish. It does this by implementing a cursor stack, a structure that maintains one base cursor and supports adding cursors on top of the base. The cursor that is on the top of the stack is the cursor that will be shown.

Push Cursors Onto the Stack and Modify Stacked Cursors

To push a cursor onto the stack, call either PushStandardCursor or PushCustomCursor. Note that these are distinct from UseBaseStandardCursor and UseBaseCustomCursor, which only change the base cursor.

Using either of the functions above will add a cursor to the stack and return an FCursorStackElementHandle. This handle can be used to change the stacked cursor later, using SetStandardCursorByHandle or SetCustomCursorByHandle.

Remove Cursors From the Stack

To remove a cursor from the stack, call either PopCursor or RemoveCursorByHandle.

Using PopCursor will remove the topmost element from the stack and should be sufficient in most cases. However, consider a scenario where one cursor is pushed onto the stack, and then a second cursor is pushed onto the stack before the first is removed. Using PopCursor in this scenario will result in the second cursor being removed, which may not be the intended effect.

In this case, it may be better to use RemoveCursorByHandle. Pass the handle returned when the first cursor stack was created as a parameter, and only that element will be removed, leaving the remainder of the stack intact.

A Simple Example: Hover a Monster

For a simple example, take the common situation of hovering over an attackable monster. When the monster receives the OnBeginCursorOver event (which all actors have), simply PushCustomCursor onto the stack with your desired custom cursor identifier, such as a sword. When the monster receives the OnEndCursorOver event, call PopCursor, and the cursor will revert to the specified base.