New backend function: current_key_label()

This provides a way for the front end to ask how a particular key should
be labelled right now (specifically, for a given game_state and
game_ui).  This is useful on feature phones where it's conventional to
put a small caption above each soft key indicating what it currently
does.

The function currently provides labels only for CURSOR_SELECT and
CURSOR_SELECT2.  This is because these are the only keys that need
labelling on KaiOS.

The concept of labelling keys also turns up in the request_keys() call,
but there are quite a few differences.  The labels returned by
current_key_label() are dynamic and likely to vary with each move, while
the labels provided by request_keys() are constant for a given
game_params.  Also, the keys returned by request_keys() don't generally
include CURSOR_SELECT and CURSOR_SELECT2, because those aren't necessary
on platforms with pointing devices.  It might be possible to provide a
unified API covering both of this, but I think it would be quite
difficult to work with.

Where a key is to be unlabelled, current_key_label() is expected to
return an empty string.  This leaves open the possibility of NULL
indicating a fallback to button2label or the label specified by
request_keys() in the future.

It's tempting to try to implement current_key_label() by calling
interpret_move() and parsing its output.  This doesn't work for two
reasons.  One is that interpret_move() is entitled to modify the
game_ui, and there isn't really a practical way to back those changes
out.  The other is that the information returned by interpret_move()
isn't sufficient to generate a label.  For instance, in many puzzles it
generates moves that toggle the state of a square, but we want the label
to reflect which state the square will be toggled to.  The result is
that I've generally ended up pulling bits of code from interpret_move()
and execute_move() together to implement current_key_label().

Alongside the back-end function, there's a midend_current_key_label()
that's a thin wrapper around the back-end function.  It just adds an
assertion about which key's being requested and a default null
implementation so that back-ends can avoid defining the function if it
will do nothing useful.

1 files changed, 36 insertions, 0 deletions

diff --git a/blackbox.c b/blackbox.c
index 1478943..f8d6b27 100644
--- a/blackbox.c
+++ b/blackbox.c
@@ -532,6 +532,41 @@ static void game_changed_state(game_ui *ui, const game_state *oldstate,
     ui->newmove = false;
 }
 
+static const char *current_key_label(const game_ui *ui,
+                                     const game_state *state, int button)
+{
+    if (IS_CURSOR_SELECT(button) && ui->cur_visible && !state->reveal) {
+        int gx = ui->cur_x, gy = ui->cur_y, rangeno = -1;
+        if (gx == 0 && gy == 0 && button == CURSOR_SELECT) return "Check";
+        if (gx >= 1 && gx <= state->w && gy >= 1 && gy <= state->h) {
+            /* Cursor somewhere in the arena. */
+            if (button == CURSOR_SELECT && !(GRID(state, gx,gy) & BALL_LOCK))
+                return (GRID(state, gx, gy) & BALL_GUESS) ? "Clear" : "Ball";
+            if (button == CURSOR_SELECT2)
+                return (GRID(state, gx, gy) & BALL_LOCK) ? "Unlock" : "Lock";
+        }
+        if (grid2range(state, gx, gy, &rangeno)) {
+            if (button == CURSOR_SELECT &&
+                state->exits[rangeno] == LASER_EMPTY)
+                return "Fire";
+            if (button == CURSOR_SELECT2) {
+                int n = 0;
+                /* Row or column lock or unlock. */
+                if (gy == 0 || gy > state->h) { /* Column lock */
+                    for (gy = 1; gy <= state->h; gy++)
+                        n += !!(GRID(state, gx, gy) & BALL_LOCK);
+                    return n > state->h/2 ? "Unlock" : "Lock";
+                } else { /* Row lock */
+                    for (gx = 1; gx <= state->w; gx++)
+                        n += !!(GRID(state, gx, gy) & BALL_LOCK);
+                    return n > state->w/2 ? "Unlock" : "Lock";
+                }
+            }
+        }
+    }
+    return "";
+}
+
 #define OFFSET(gx,gy,o) do {                                    \
     int off = (4 + (o) % 4) % 4;                                \
     (gx) += offsets[off].x;                                     \
@@ -1543,6 +1578,7 @@ const struct game thegame = {
     decode_ui,
     NULL, /* game_request_keys */
     game_changed_state,
+    current_key_label,
     interpret_move,
     execute_move,
     PREFERRED_TILE_SIZE, game_compute_size, game_set_size,