Add a request_keys() function with a midend wrapper.

This function gives the front end a way to find out what keys the back
end requires; and as such it is mostly useful for ports without a
keyboard. It is based on changes originally found in Chris Boyle's
Android port, though some modifications were needed to make it more
flexible.

1 files changed, 26 insertions, 0 deletions

diff --git a/puzzles.h b/puzzles.h
index 6b6e6b3..2eb7647 100644
--- a/puzzles.h
+++ b/puzzles.h
@@ -218,6 +218,24 @@ void preset_menu_add_preset(struct preset_menu *menu,
 game_params *preset_menu_lookup_by_id(struct preset_menu *menu, int id);
 
 /*
+ * Small structure specifying a UI button in a keyboardless front
+ * end. The button will have the text of "label" written on it, and
+ * pressing it causes the value "button" to be passed to
+ * midend_process_key() as if typed at the keyboard.
+ *
+ * If `label' is NULL (which it likely will be), a generic label can
+ * be generated with the button2label() function.
+ */
+typedef struct key_label {
+    /* What should be displayed to the user by the frontend. Backends
+     * can set this field to NULL and have it filled in by the midend
+     * with a generic label. Dynamically allocated, but frontends
+     * should probably use free_keys() to free instead. */
+    char *label;
+    int button; /* passed to midend_process_key when button is pressed */
+} key_label;
+
+/*
  * Platform routines
  */
 
@@ -301,6 +319,7 @@ void midend_new_game(midend *me);
 void midend_restart_game(midend *me);
 void midend_stop_anim(midend *me);
 int midend_process_key(midend *me, int x, int y, int button);
+key_label *midend_request_keys(midend *me, int *nkeys);
 void midend_force_redraw(midend *me);
 void midend_redraw(midend *me);
 float *midend_colours(midend *me, int *ncolours);
@@ -356,6 +375,7 @@ char *dupstr(const char *s);
  * misc.c
  */
 void free_cfg(config_item *cfg);
+void free_keys(key_label *keys, int nkeys);
 void obfuscate_bitmap(unsigned char *bmp, int bits, int decode);
 char *fgetline(FILE *fp);
 
@@ -400,6 +420,11 @@ void draw_text_outline(drawing *dr, int x, int y, int fonttype,
  * less than buffer size. */
 void copy_left_justified(char *buf, size_t sz, const char *str);
 
+/* Returns a generic label based on the value of `button.' To be used
+   whenever a `label' field returned by the request_keys() game
+   function is NULL. Dynamically allocated, to be freed by caller. */
+char *button2label(int button);
+
 /*
  * dsf.c
  */
@@ -610,6 +635,7 @@ struct game {
     void (*free_ui)(game_ui *ui);
     char *(*encode_ui)(const game_ui *ui);
     void (*decode_ui)(game_ui *ui, const char *encoding);
+    key_label *(*request_keys)(const game_params *params, int *nkeys);
     void (*changed_state)(game_ui *ui, const game_state *oldstate,
                           const game_state *newstate);
     char *(*interpret_move)(const game_state *state, game_ui *ui,