shithub: puzzles

Info  •  Files  •  Log  •  Branches

Add MOVE_NO_EFFECT and MOVE_UNUSED return values from interpret_move()

These allow for distinguishing the case where a puzzle doesn't have a
use for a key from the case where it just happens to have no effect in
the current state of the puzzle.  These were both represented by NULL,
but that now represents the case where a puzzle hasn't been updated to
make the distinction yet.

--- a/devel.but

+++ b/devel.but

@@ -1056,11 +1056,16 @@

 pointer will be to read the game's tile size parameter in order to

 divide mouse coordinates by it.)

-\cw{interpret_move()} may return in three different ways:

+\cw{interpret_move()} may return in four different ways:

-\b Returning \cw{NULL} indicates that no action whatsoever occurred

-in response to the input event; the puzzle was not interested in it

-at all.

+\b Returning \cw{MOVE_UNUSED} or \cw{MOVE_NO_EFFECT} indicates that no

+action whatsoever occurred in response to the input event; the puzzle

+was not interested in it at all.  The distinction between this is that

+\cw{MOVE_NO_EFFECT} implies that the state of the game is what makes

+the event uninteresting, while \cw{MOVE_NO_EFFECT} means that the

+event is intrinsically uninteresting.  For example, a mouse click on

+an already-revealed square in Mines might return \cw{MOVE_NO_EFFECT}

+while a click outside the board would return \cw{MOVE_UNUSED}.

 \b Returning the special value \cw{MOVE_UI_UPDATE} indicates that the input

 event has resulted in a change being made to the \c{game_ui} which

@@ -1080,7 +1085,8 @@

 The return value from \cw{interpret_move()} is expected to be

 dynamically allocated if and only if it is not either \cw{NULL}

-\e{or} the special string constant \c{MOVE_UI_UPDATE}.

+\e{or} one of the special string constants \cw{MOVE_UNUSED},

+\cw{MOVE_NO_EFFECT}, or \cw{MOVE_UI_UPDATE}.

 After this function is called, the back end is permitted to rely on

 some subsequent operations happening in sequence:

--- a/midend.c

+++ b/midend.c

@@ -990,7 +990,7 @@

             me->ui, me->drawstate, x, y, button);

     }

-    if (!movestr) {

+    if (movestr == NULL || movestr == MOVE_UNUSED) {

 	if ((me->one_key_shortcuts && (button == 'n' || button == 'N')) ||

              button == '\x0E' || button == UI_NEWGAME) {

 	    midend_new_game(me);

@@ -1025,6 +1025,8 @@

 	    goto done;

 	} else

 	    goto done;

+    } else if (movestr == MOVE_NO_EFFECT) {

+        goto done;

     } else {

         *handled = true;

 	if (movestr == MOVE_UI_UPDATE)

--- a/misc.c

+++ b/misc.c

@@ -16,6 +16,8 @@

 #include "puzzles.h"

 char MOVE_UI_UPDATE[] = "";

+char MOVE_NO_EFFECT[] = "";

+char MOVE_UNUSED[] = "";

 void free_cfg(config_item *cfg)

 {

--- a/puzzles.h

+++ b/puzzles.h

@@ -800,12 +800,20 @@

 #endif

 /*

- * Special string value to return from interpret_move in the case

- * where the game UI has been updated but no actual move is being

- * appended to the undo chain. Must be declared as a non-const char,

- * but should never actually be modified by anyone.

+ * Special string values to return from interpret_move.

+ *

+ * MOVE_UI_UPDATE is for the case where the game UI has been updated

+ * but no actual move is being appended to the undo chain.

+ *

+ * MOVE_NO_EFFECT is for when the key was understood by the puzzle,

+ * but it happens that there isn't effect, not even a UI change.

+ *

+ * MOVE_UNUSED is for keys that the puzzle has no use for at all.

+ *

+ * Each must be declared as a non-const char, but should never

+ * actually be modified by anyone.

  */

-extern char MOVE_UI_UPDATE[];

+extern char MOVE_UI_UPDATE[], MOVE_NO_EFFECT[], MOVE_UNUSED[];

 /* A little bit of help to lazy developers */

 #define DEFAULT_STATUSBAR_TEXT "Use status_bar() to fill this in."