\c int (*fetch_preset)(int i, char **name, game_params **params);
-This function is used to populate the \q{Type} menu, which provides
-a list of conveniently accessible preset parameters for most games.
+This function is one of the two APIs a back end can provide to
+populate the \q{Type} menu, which provides a list of conveniently
+accessible preset parameters for most games.
The function is called with \c{i} equal to the index of the preset
required (numbering from zero). It returns \cw{FALSE} if that preset
If the game does not wish to support any presets at all, this
function is permitted to return \cw{FALSE} always.
+If the game wants to return presets in the form of a hierarchical menu
+instead of a flat list (and, indeed, even if it doesn't), then it may
+set this function pointer to \cw{NULL}, and instead fill in the
+alternative function pointer \cw{preset_menu}
+(\k{backend-preset-menu}).
+
+\S{backend-preset-menu} \cw{preset_menu()}
+
+\c struct preset_menu *(*preset_menu)(void);
+
+This function is the more flexible of the two APIs by which a back end
+can define a collection of preset game parameters.
+
+This function simply returns a complete menu hierarchy, in the form of
+a \c{struct preset_menu} (see \k{midend-get-presets}) and further
+submenus (if it wishes) dangling off it. There are utility functions
+described in \k{utils-presets} to make it easy for the back end to
+construct this menu.
+
+If the game has no need to return a hierarchy of menus, it may instead
+opt to implement the \cw{fetch_preset()} function (see
+\k{backend-fetch-preset}).
+
+The game need not fill in the \c{id} fields in the preset menu
+structures. The mid-end will do that after it receives the structure
+from the game, and before passing it on to the front end.
+
\S{backend-encode-params} \cw{encode_params()}
\c char *(*encode_params)(const game_params *params, int full);
\c char *name;
\c int type;
-\c char *sval;
-\c int ival;
+\c union { /* type-specific fields */ } u;
+\e iiiiiiiiiiiiiiiiiiiiiiiiii
\c{name} is an ASCII string giving the textual label for a GUI
control. It is \e{not} expected to be dynamically allocated.
\c{type} contains one of a small number of \c{enum} values defining
-what type of control is being described. The meaning of the \c{sval}
-and \c{ival} fields depends on the value in \c{type}. The valid
-values are:
+what type of control is being described. The usable member of the
+union field \c{u} depends on \c{type}. The valid type values are:
\dt \c{C_STRING}
input. The back end does not bother informing the front end that the
box is numeric rather than textual; some front ends do have the
capacity to take this into account, but I decided it wasn't worth
-the extra complexity in the interface.) For this type, \c{ival} is
-unused, and \c{sval} contains a dynamically allocated string
-representing the contents of the input box.
+the extra complexity in the interface.)
+
+\lcont{
+
+For controls of this type, \c{u.string} contains a single field
+
+\c char *sval;
+
+which stores a dynamically allocated string representing the contents
+of the input box.
+
+}
\dt \c{C_BOOLEAN}
-\dd Describes a simple checkbox. For this type, \c{sval} is unused,
-and \c{ival} is \cw{TRUE} or \cw{FALSE}.
+\dd Describes a simple checkbox.
+
+\lcont{
+
+For controls of this type, \c{u.boolean} contains a single field
+
+\c int bval;
+
+which is either \cw{TRUE} or \cw{FALSE}.
+
+}
\dt \c{C_CHOICES}
\dd Describes a drop-down list presenting one of a small number of
-fixed choices. For this type, \c{sval} contains a list of strings
-describing the choices; the very first character of \c{sval} is used
-as a delimiter when processing the rest (so that the strings
-\cq{:zero:one:two}, \cq{!zero!one!two} and \cq{xzeroxonextwo} all
-define a three-element list containing \cq{zero}, \cq{one} and
-\cq{two}). \c{ival} contains the index of the currently selected
-element, numbering from zero (so that in the above example, 0 would
-mean \cq{zero} and 2 would mean \cq{two}).
+fixed choices.
\lcont{
-Note that for this control type, \c{sval} is \e{not} dynamically
-allocated, whereas it was for \c{C_STRING}.
+For controls of this type, \c{u.choices} contains two fields:
+
+\c const char *choicenames;
+\c int selected;
+
+\c{choicenames} contains a list of strings describing the choices. The
+very first character of \c{sval} is used as a delimiter when
+processing the rest (so that the strings \cq{:zero:one:two},
+\cq{!zero!one!two} and \cq{xzeroxonextwo} all define a three-element
+list containing \cq{zero}, \cq{one} and \cq{two}).
+
+\c{selected} contains the index of the currently selected element,
+numbering from zero (so that in the above example, 0 would mean
+\cq{zero} and 2 would mean \cq{two}).
+
+Note that \c{u.choices.choicenames} is \e{not} dynamically allocated,
+unlike \c{u.string.sval}.
}
\dt \c{C_END}
-\dd Marks the end of the array of \c{config_item}s. All other fields
-are unused.
+\dd Marks the end of the array of \c{config_item}s. There is no
+associated member of the union field \c{u} for this type.
The array returned from this function is expected to have filled in
the initial values of all the controls according to the input
\S{backend-validate-params} \cw{validate_params()}
-\c char *(*validate_params)(const game_params *params, int full);
+\c const char *(*validate_params)(const game_params *params,
+\c int full);
This function takes a \c{game_params} structure as input, and checks
that the parameters described in it fall within sensible limits. (At
\S{backend-validate-desc} \cw{validate_desc()}
-\c char *(*validate_desc)(const game_params *params, const char *desc);
+\c const char *(*validate_desc)(const game_params *params,
+\c const char *desc);
This function is given a game description, and its job is to
validate that it describes a puzzle which makes sense.
in response to the input event; the puzzle was not interested in it
at all.
-\b Returning the empty string (\cw{""}) indicates that the input
+\b Returning the special value \cw{UI_UPDATE} indicates that the input
event has resulted in a change being made to the \c{game_ui} which
-will require a redraw of the game window, but that no actual
-\e{move} was made (i.e. no new \c{game_state} needs to be created).
+will require a redraw of the game window, but that no actual \e{move}
+was made (i.e. no new \c{game_state} needs to be created).
\b Returning anything else indicates that a move was made and that a
new \c{game_state} must be created. However, instead of actually
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 empty string.
+\e{or} the special string constant \c{UI_UPDATE}.
After this function is called, the back end is permitted to rely on
some subsequent operations happening in sequence:
\S{backend-solve} \cw{solve()}
\c char *(*solve)(const game_state *orig, const game_state *curr,
-\c const char *aux, char **error);
+\c const char *aux, const char **error);
This function is called when the user selects the \q{Solve} option
from the menu.
This function may be used for both drawing and printing.
+If the specified thickness is less than 1.0, 1.0 is used.
+This ensures that thin lines are visible even at small scales.
+
\S{drawing-draw-text} \cw{draw_text()}
\c void draw_text(drawing *dr, int x, int y, int fonttype,
-\c int fontsize, int align, int colour, char *text);
+\c int fontsize, int align, int colour,
+\c const char *text);
Draws text in the puzzle window.
\S{drawing-status-bar} \cw{status_bar()}
-\c void status_bar(drawing *dr, char *text);
+\c void status_bar(drawing *dr, const char *text);
Sets the text in the game's status bar to \c{text}. The text is copied
from the supplied buffer, so the caller is free to deallocate or
\S{drawingapi-draw-text} \cw{draw_text()}
\c void (*draw_text)(void *handle, int x, int y, int fonttype,
-\c int fontsize, int align, int colour, char *text);
+\c int fontsize, int align, int colour,
+\c const char *text);
This function behaves exactly like the back end \cw{draw_text()}
function; see \k{drawing-draw-text}.
\S{drawingapi-status-bar} \cw{status_bar()}
-\c void (*status_bar)(void *handle, char *text);
+\c void (*status_bar)(void *handle, const char *text);
This function behaves exactly like the back end \cw{status_bar()}
function; see \k{drawing-status-bar}.
The usual way in which the front end will have an actual
\c{game_params} structure to pass to this function is if it had
-previously got it from \cw{midend_fetch_preset()}
-(\k{midend-fetch-preset}). Thus, this function is usually called in
+previously got it from \cw{midend_get_presets()}
+(\k{midend-get-presets}). Thus, this function is usually called in
response to the user making a selection from the presets menu.
\H{midend-get-params} \cw{midend_get_params()}
move animation. Therefore, calling this function is very likely to
result in calls back to the front end's drawing API.
-\H{midend-num-presets} \cw{midend_num_presets()}
+\H{midend-get-presets} \cw{midend_get_presets()}
-\c int midend_num_presets(midend *me);
+\c struct preset_menu *midend_get_presets(midend *me, int *id_limit);
-Returns the number of game parameter presets supplied by this game.
-Front ends should use this function and \cw{midend_fetch_preset()}
-to configure their presets menu rather than calling the back end
-directly, since the mid-end adds standard customisation facilities.
-(At the time of writing, those customisation facilities are
-implemented hackily by means of environment variables, but it's not
-impossible that they may become more full and formal in future.)
+Returns a data structure describing this game's collection of preset
+game parameters, organised into a hierarchical structure of menus and
+submenus.
-\H{midend-fetch-preset} \cw{midend_fetch_preset()}
+The return value is a pointer to a data structure containing the
+following fields (among others, which are not intended for front end
+use):
-\c void midend_fetch_preset(midend *me, int n,
-\c char **name, game_params **params);
+\c struct preset_menu {
+\c int n_entries;
+\c struct preset_menu_entry *entries;
+\c /* and other things */
+\e iiiiiiiiiiiiiiiiiiiiii
+\c };
-Returns one of the preset game parameter structures for the game. On
-input \c{n} must be a non-negative integer and less than the value
-returned from \cw{midend_num_presets()}. On output, \c{*name} is set
-to an ASCII string suitable for entering in the game's presets menu,
-and \c{*params} is set to the corresponding \c{game_params}
-structure.
+Those fields describe the intended contents of one particular menu in
+the hierarchy. \cq{entries} points to an array of \cq{n_entries}
+items, each of which is a structure containing the following fields:
-Both of the two output values are dynamically allocated, but they
-are owned by the mid-end structure: the front end should not ever
-free them directly, because they will be freed automatically during
-\cw{midend_free()}.
+\c struct preset_menu_entry {
+\c char *title;
+\c game_params *params;
+\c struct preset_menu *submenu;
+\c int id;
+\c };
+
+Of these fields, \cq{title} and \cq{id} are present in every entry,
+giving (respectively) the textual name of the menu item and an integer
+identifier for it. The integer id will correspond to the one returned
+by \c{midend_which_preset} (\k{midend-which-preset}), when that preset
+is the one selected.
+
+The other two fields are mutually exclusive. Each \c{struct
+preset_menu_entry} will have one of those fields \cw{NULL} and the
+other one non-null. If the menu item is an actual preset, then
+\cq{params} will point to the set of game parameters that go with the
+name; if it's a submenu, then \cq{submenu} instead will be non-null,
+and will point at a subsidiary \c{struct preset_menu}.
+
+The complete hierarchy of these structures is owned by the mid-end,
+and will be freed when the mid-end is freed. The front end should not
+attempt to free any of it.
+
+The integer identifiers will be allocated densely from 0 upwards, so
+that it's reasonable for the front end to allocate an array which uses
+them as indices, if it needs to store information per preset menu
+item. For this purpose, the front end may pass the second parameter
+\cq{id_limit} to \cw{midend_get_presets} as the address of an \c{int}
+variable, into which \cw{midend_get_presets} will write an integer one
+larger than the largest id number actually used (i.e. the number of
+elements the front end would need in the array).
+
+Submenu-type entries also have integer identifiers.
\H{midend-which-preset} \cw{midend_which_preset()}
beside one of the items in the menu (or tick the \q{Custom} option
if the return value is less than zero).
+The returned index value (if non-negative) will match the \c{id} field
+of the corresponding \cw{struct preset_menu_entry} returned by
+\c{midend_get_presets()} (\k{midend-get-presets}).
+
\H{midend-wants-statusbar} \cw{midend_wants_statusbar()}
\c int midend_wants_statusbar(midend *me);
\H{midend-set-config} \cw{midend_set_config()}
-\c char *midend_set_config(midend *me, int which,
-\c config_item *cfg);
+\c const char *midend_set_config(midend *me, int which,
+\c config_item *cfg);
Passes the mid-end the results of a configuration dialog box.
\c{which} should have the same value which it had when
\H{midend-game-id} \cw{midend_game_id()}
-\c char *midend_game_id(midend *me, char *id);
+\c const char *midend_game_id(midend *me, const char *id);
Passes the mid-end a string game ID (of any of the valid forms
\cq{params}, \cq{params:description} or \cq{params#seed}) which the
\H{midend-solve} \cw{midend_solve()}
-\c char *midend_solve(midend *me);
+\c const char *midend_solve(midend *me);
Requests the mid-end to perform a Solve operation.
\H{midend-serialise} \cw{midend_serialise()}
\c void midend_serialise(midend *me,
-\c void (*write)(void *ctx, void *buf, int len),
-\c void *wctx);
+\c void (*write)(void *ctx, const void *buf, int len), void *wctx);
Calling this function causes the mid-end to convert its entire
internal state into a long ASCII text string, and to pass that
\H{midend-deserialise} \cw{midend_deserialise()}
-\c char *midend_deserialise(midend *me,
-\c int (*read)(void *ctx, void *buf, int len),
-\c void *rctx);
+\c const char *midend_deserialise(midend *me,
+\c int (*read)(void *ctx, void *buf, int len), void *rctx);
This function is the counterpart to \cw{midend_serialise()}. It
calls the supplied \cw{read} function repeatedly to read a quantity
\H{identify-game} \cw{identify_game()}
-\c char *identify_game(char **name,
-\c int (*read)(void *ctx, void *buf, int len),
-\c void *rctx);
+\c const char *identify_game(char **name,
+\c int (*read)(void *ctx, void *buf, int len), void *rctx);
This function examines a serialised midend stream, of the same kind
used by \cw{midend_serialise()} and \cw{midend_deserialise()}, and
\H{frontend-fatal} \cw{fatal()}
-\c void fatal(char *fmt, ...);
+\c void fatal(const char *fmt, ...);
This is called by some utility functions if they encounter a
genuinely fatal error such as running out of memory. It is a
\c{random_state} used to generate all the random numbers for the
shuffling process.
+\H{utils-presets} Presets menu management
+
+The function \c{midend_get_presets()} (\k{midend-get-presets}) returns
+a data structure describing a menu hierarchy. Back ends can also
+choose to provide such a structure to the mid-end, if they want to
+group their presets hierarchically. To make this easy, there are a few
+utility functions to construct preset menu structures, and also one
+intended for front-end use.
+
+\S{utils-preset-menu-new} \cw{preset_menu_new()}
+
+\c struct preset_menu *preset_menu_new(void);
+
+Allocates a new \c{struct preset_menu}, and initialises it to hold no
+menu items.
+
+\S{utils-preset-menu-add_submenu} \cw{preset_menu_add_submenu()}
+
+\c struct preset_menu *preset_menu_add_submenu
+\c (struct preset_menu *parent, char *title);
+
+Adds a new submenu to the end of an existing preset menu, and returns
+a pointer to a newly allocated \c{struct preset_menu} describing the
+submenu.
+
+The string parameter \cq{title} must be dynamically allocated by the
+caller. The preset-menu structure will take ownership of it, so the
+caller must not free it.
+
+\S{utils-preset-menu-add-preset} \cw{preset_menu_add_preset()}
+
+\c void preset_menu_add_preset
+\c (struct preset_menu *menu, char *title, game_params *params);
+
+Adds a preset game configuration to the end of a preset menu.
+
+Both the string parameter \cq{title} and the game parameter structure
+\cq{params} itself must be dynamically allocated by the caller. The
+preset-menu structure will take ownership of it, so the caller must
+not free it.
+
+\S{utils-preset-menu-lookup-by-id} \cw{preset_menu_lookup_by_id()}
+
+\c game_params *preset_menu_lookup_by_id
+\c (struct preset_menu *menu, int id);
+
+Given a numeric index, searches recursively through a preset menu
+hierarchy to find the corresponding menu entry, and returns a pointer
+to its existing \c{game_params} structure.
+
+This function is intended for front end use (but front ends need not
+use it if they prefer to do things another way). If a front end finds
+it inconvenient to store anything more than a numeric index alongside
+each menu item, then this function provides an easy way for the front
+end to get back the actual game parameters corresponding to a menu
+item that the user has selected.
+
\H{utils-alloc} Memory allocation
Puzzles has some central wrappers on the standard memory allocation
\c void free_cfg(config_item *cfg);
-This function correctly frees an array of \c{config_item}s,
-including walking the array until it gets to the end and freeing
-precisely those \c{sval} fields which are expected to be dynamically
-allocated.
+This function correctly frees an array of \c{config_item}s, including
+walking the array until it gets to the end and freeing any subsidiary
+data items in each \c{u} sub-union which are expected to be
+dynamically allocated.
(See \k{backend-configure} for details of the \c{config_item}
structure.)
~ian / sgt-puzzles.git / blobdiff