October 28, 2020
Cursory
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 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
.
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.
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.