This function is called when the user requests a dialog box for
custom parameter configuration. It returns a newly allocated array
of \cw{config_item} structures, describing the GUI elements required
-in the dialog box. The
+in the dialog box. The array should have one more element than the
+number of controls, since it is terminated with a \cw{C_END} marker
+(see below). Each array element describes the control together with
+its initial value; the front end will modify the value fields and
+return the updated array to \cw{custom_params()} (see
+\k{backend-custom-params}).
The \cw{config_item} structure contains the following elements:
\cw{changed_state()} function clears the current selection whenever
it is called.
-Any call to \cw{changed_state()} can be sure that there will be a
-subsequent call to \cw{anim_length()} and \cw{flash_length()}. So
-\cw{changed_state()} can set up data in the \c{game_ui} which will
-be read by \cw{anim_length()} and \cw{flash_length()}, and not have
-to worry about those functions being called without the data having
-been uninitialised.
+When \cw{anim_length()} or \cw{flash_length()} are called, you can
+be sure that there has been a previous call to \cw{changed_state()}.
+So \cw{changed_state()} can set up data in the \c{game_ui} which will
+be read by \cw{anim_length()} and \cw{flash_length()}, and those
+functions will not have to worry about being called without the data
+having been initialised.
\H{backend-moves} Making moves
either remove it or fix it; probably the former.)
The final parameter passed to this function is a front end handle.
-The only thing it is permitted to do with this handle is to call the
-front-end function called \cw{frontend_default_colour()} (see
-\k{frontend-default-colour}). This allows \cw{colours()} to take
-local configuration into account when deciding on its own colour
-allocations. Most games use the front end's default colour as their
-background, apart from a few which depend on drawing relief
-highlights so they adjust the background colour if it's too light
-for highlights to show up against it.
+The only things it is permitted to do with this handle are to call
+the front-end function called \cw{frontend_default_colour()} (see
+\k{frontend-default-colour}) or the utility function called
+\cw{game_mkhighlight()} (see \k{utils-game-mkhighlight}). (The
+latter is a wrapper on the former, so front end implementors only
+need to provide \cw{frontend_default_colour()}.) This allows
+\cw{colours()} to take local configuration into account when
+deciding on its own colour allocations. Most games use the front
+end's default colour as their background, apart from a few which
+depend on drawing relief highlights so they adjust the background
+colour if it's too light for highlights to show up against it.
\S{backend-anim-length} \cw{anim_length()}
\c void status_bar(frontend *fe, char *text);
-Sets the text in the game's status bar to \c{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
+modify the buffer after use.
(This function is not exactly a \e{drawing} function, but it shares
with the drawing API the property that it may only be called from
\H{drawing-blitter} Blitter functions
-This section describes a group of related function which save and
+This section describes a group of related functions which save and
restore a section of the puzzle window. This is most commonly used
to implement user interfaces involving dragging a puzzle element
around the window: at the end of each call to \cw{redraw()}, if an
The seed data can be any data at all; there is no requirement to use
printable ASCII, or NUL-terminated strings, or anything like that.
+\S{utils-random-copy} \cw{random_copy()}
+
+\c random_state *random_copy(random_state *tocopy);
+
+Allocates a new \c{random_state}, copies the contents of another
+\c{random_state} into it, and returns the new state. If exactly the
+same sequence of functions is subseqently called on both the copy and
+the original, the results will be identical. This may be useful for
+speculatively performing some operation using a given random state,
+and later replaying that operation precisely.
+
\S{utils-random-free} \cw{random_free()}
\c void random_free(random_state *state);
\S{utils-snewn} \cw{snewn()}
\c var = snewn(n, type);
-\e iii iiii
+\e iii i iiii
This macro is the array form of \cw{snew()}. It takes two arguments;
the first is a number, and the second is a type name. It allocates
the 56 squares in the default setting!), so this tweaking strategy
would be rather less likely to work well.
-A more specialised strategy is that used in Solo. Solo has the
-unusual property that the clues (information provided at the
-beginning of the puzzle) and the solution (information the user is
-required to fill in) are inherently interchangeable; therefore a
-simple generation technique is to leave the decision of which
-numbers are clues until the last minute. Solo works by first
-generating a random \e{filled} grid, and then gradually removing
-numbers for as long as the solver reports that it's still soluble.
-Unlike the methods described above, this technique \e{cannot} fail
-\dash once you've got a filled grid, nothing can stop you from being
-able to convert it into a viable puzzle. However, it wouldn't even
-be meaningful to apply this technique to (say) Pattern, in which the
-clues and the solution occupy completely different spaces.
+A more specialised strategy is that used in Solo and Slant. These
+puzzles have the property that they derive their difficulty from not
+presenting all the available clues. (In Solo's case, if all the
+possible clues were provided then the puzzle would already be
+solved; in Slant it would still require user action to fill in the
+lines, but it would present no challenge at all). Therefore, a
+simple generation technique is to leave the decision of which clues
+to provide until the last minute. In other words, first generate a
+random \e{filled} grid with all possible clues present, and then
+gradually remove clues for as long as the solver reports that it's
+still soluble. Unlike the methods described above, this technique
+\e{cannot} fail \dash once you've got a filled grid, nothing can
+stop you from being able to convert it into a viable puzzle.
+However, it wouldn't even be meaningful to apply this technique to
+(say) Pattern, in which clues can never be left out, so the only way
+to affect the set of clues is by altering the solution.
(Unfortunately, Solo is complicated by the need to provide puzzles
at varying difficulty levels. It's easy enough to generate a puzzle
puzzle at all, provided it doesn't do either so often as to become
slow.
-One last piece of advice: for grid-based puzzles when writing and
+One last piece of advice: for grid-based puzzles, when writing and
testing your generation algorithm, it's almost always a good idea
\e{not} to test it initially on a grid that's square (i.e.
-\cw{w==h}), because that way you won't notice if you mistakenly
-write \c{w} instead of \c{h} or vice versa somewhere in the code.
-Use a rectangular grid for testing, and any size of grid will be
-likely to work after that.
+\cw{w==h}), because if the grid is square then you won't notice if
+you mistakenly write \c{h} instead of \c{w} (or vice versa)
+somewhere in the code. Use a rectangular grid for testing, and any
+size of grid will be likely to work after that.
\S{writing-textformats} Designing textual description formats
it, and would introduce the potential for synchronisation bugs in
which you ended up with two cursors or none. The obviously sensible
way to store a cursor in the \c{game_ui} is to have fields directly
-encodings the cursor's coordinates.
+encoding the cursor's coordinates.
However, it is a mistake to assume that the same logic applies to
the \c{game_drawstate}. If you replicate the cursor position fields
~mdw / sgt / puzzles / blobdiff