move_cursor(): handle visible flag; return useful value

This adds an extra parameter to move_cursor() that's an optional pointer
to a bool indicating whether the cursor is visible.  This allows for
centralising the common idiom of having the keyboard cursor become
visible when a cursor key is pressed.  Consistently with the vast
majority of existing puzzles, the cursor moves even if it was invisible
before, and becomes visible even if it can't move.

The function now also returns one of the special constants that can be
returned by interpret_move(), so that the caller can correctly return
MOVE_UI_UPDATE or MOVE_NO_EFFECT without needing to carefully check for
changes itself.

Callers are updated only to the extent that they all pass NULL as the
new argument.  Most of them could now be substantially simplified.

1 files changed, 11 insertions, 2 deletions

diff --git a/devel.but b/devel.but
index 65c1571..4d205ac 100644
--- a/devel.but
+++ b/devel.but
@@ -5239,8 +5239,8 @@ The returned string is dynamically allocated and should be
 
 \S{utils-move-cursor} \cw{move_cursor()}
 
-\c void move_cursor(int button, int *x, int *y, int w, int h,
-\c                  bool wrap);
+\c char *move_cursor(int button, int *x, int *y, int w, int h,
+\c                   bool wrap, bool *visible);
 
 This function can be called by \cw{interpret_move()} to implement the
 default keyboard API for moving a cursor around a grid.
@@ -5263,6 +5263,15 @@ of the grid will result in it wrapping round to the corresponding
 square on the opposite edge. If \c{wrap} is \cw{false}, such a move
 will have no effect.
 
+If \c{visible} is not \cw{NULL}, it points to a flag indicating
+whether the cursor is visible.  This will be set to \cw{true} if
+\c{button} represents a cursor-movement key.
+
+The function returns one of the special constants that can be returned
+by \cw{interpret_move()}.  The return value is \cw{MOVE_UNUSED} if
+\c{button} is unrecognised, \cw{MOVE_UI_UPDATE} if \c{x}, \c{y}, or
+\c{visible} was updated, and \cw{MOVE_NO EFFECT} otherwise.
+
 \S{utils-divvy-rectangle} \cw{divvy_rectangle()}
 
 \c int *divvy_rectangle(int w, int h, int k, random_state *rs);