October 28, 2020
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.
To push a cursor onto the stack, call either
PushCustomCursor. Note that these are distinct from
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
To remove a cursor from the stack, call either
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.
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.