\S{backend-colours} \cw{colours()}
-\c float *(*colours)(frontend *fe, game_state *state, int *ncolours);
+\c float *(*colours)(frontend *fe, int *ncolours);
This function is responsible for telling the front end what colours
the puzzle will need to draw itself.
and blue components of each colour respectively as numbers in the
range [0,1].
-It is passed a sample \c{game_state} in case it needs one, although
-currently no puzzle does need this. (In fact, colours are not
-reallocated when the game parameters change or a new game is
-started, so you can't reliably use this \c{game_state} to allocate a
-different number of colours depending on the game. It is probably
-actually a mistake to rely on this parameter at all. I ought to
-either remove it or fix it; probably the former.)
-
-The final parameter passed to this function is a front end handle.
+The second parameter passed to this function is a front end handle.
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
the mid-end will handle them internally and never consult this
function at all. State changes as a result of Solve operations are
also not animated by default, although you can change this for a
-particular game by setting a flag in \c{mouse_priorities}
-(\k{backend-mouse-priorities}).
+particular game by setting a flag in \c{flags} (\k{backend-flags}).
The function is also passed a pointer to the local \c{game_ui}. It
may refer to information in here to help with its decision (see
\S{backend-wants-statusbar} \cw{wants_statusbar()}
-\c int (*wants_statusbar)(void);
+\c int wants_statusbar;
-This function returns \cw{TRUE} if the puzzle has a use for a
+This boolean field is set to \cw{TRUE} if the puzzle has a use for a
textual status line (to display score, completion status, currently
active tiles, etc).
-(This should probably be a static boolean field rather than a
-function. I don't remember why I did it this way. I probably ought
-to change it.)
-
\S{backend-is-timed} \c{is_timed}
\c int is_timed;
freeze the timer thereafter so that the user can undo back through
their solution process without altering their time.
-\S{backend-mouse-priorities} \c{mouse_priorities}
+\S{backend-flags} \c{flags}
-\c int mouse_priorities;
+\c int flags;
-This field is badly named. It is in fact a generic flags word. It
-consists of the bitwise OR of the following flags:
+This field contains miscellaneous per-backend flags. It consists of
+the bitwise OR of some combination of the following:
\dt \cw{BUTTON_BEATS(x,y)}
If a back end needs random numbers at some point during normal play,
it can create a fresh \c{random_state} by first calling
\c{get_random_seed} (\k{frontend-get-random-seed}) and then passing
-the returned seed data to \cw{random_init()}.
+the returned seed data to \cw{random_new()}.
This is likely not to be what you want. If a puzzle needs randomness
in the middle of play, it's likely to be more sensible to store some
within the back end redraw function, so this is as good a place as
any to document it.)
+The supplied text is filtered through the mid-end for optional
+rewriting before being passed on to the front end; the mid-end will
+prepend the current game time if the game is timed (and may in
+future perform other rewriting if it seems like a good idea).
+
This function is for drawing only; it must never be called during
printing.
a more useful type. Thus, a drawing \e{object} (\c{drawing *)}
suitable for passing to the back end redraw or printing functions
is constructed by passing a \c{drawing_api} and a \cq{void *} to the
-function \cw{drawing_init()} (see \k{drawing-init}).
+function \cw{drawing_new()} (see \k{drawing-new}).
\S{drawingapi-draw-text} \cw{draw_text()}
This function behaves exactly like the back end \cw{status_bar()}
function; see \k{drawing-status-bar}.
-Front ends implementing this function should not use the provided
-text directly; they should call \cw{midend_rewrite_statusbar()}
-(\k{midend-rewrite-statusbar}) to process it first.
-
-In a game which has a timer, this function is likely to be called
-every time the timer goes off, i.e. many times a second. It is
-therefore likely to be common that this function is called with
-precisely the same text as the last time it was called. Front ends
-may well wish to detect this common case and avoid bothering to do
-anything. If they do, however, they \e{must} perform this check on
-the value \e{returned} from \cw{midend_rewrite_statusbar()}, rather
-than the value passed in to it (because the mid-end will frequently
-update the status-bar timer without the back end's intervention).
+Front ends implementing this function need not worry about it being
+called repeatedly with the same text; the middleware code in
+\cw{status_bar()} will take care of this.
Implementations of this API which do not provide drawing services
may define this function pointer to be \cw{NULL}; it will never be
which the front end needs to \e{call}, rather than helping to
implement. They are described in this section.
-\S{drawing-init} \cw{drawing_init()}
+\S{drawing-new} \cw{drawing_new()}
-\c drawing *drawing_init(const drawing_api *api, void *handle);
+\c drawing *drawing_new(const drawing_api *api, midend *me,
+\c void *handle);
This function creates a drawing object. It is passed a
\c{drawing_api}, which is a structure containing nothing but
function pointers; and also a \cq{void *} handle. The handle is
passed back to each function pointer when it is called.
+The \c{midend} parameter is used for rewriting the status bar
+contents: \cw{status_bar()} (see \k{drawing-status-bar}) has to call
+a function in the mid-end which might rewrite the status bar text.
+If the drawing object is to be used only for printing, or if the
+game is known not to call \cw{status_bar()}, this parameter may be
+\cw{NULL}.
+
\S{drawing-free} \cw{drawing_free()}
\c void drawing_free(drawing *dr);
function \cw{colours()} (\k{backend-colours}).
The parameters \c{drapi} and \c{drhandle} are passed to
-\cw{drawing_init()} (\k{drawing-init}) to construct a drawing object
+\cw{drawing_new()} (\k{drawing-new}) to construct a drawing object
which will be passed to the back end function \cw{redraw()}
(\k{backend-redraw}). Hence, all drawing-related function pointers
defined in \c{drapi} can expect to be called with \c{drhandle} as
\cw{activate_timer()} to be called from within a call to this
function.
-\H{midend-rewrite-statusbar} \cw{midend_rewrite_statusbar()}
-
-\c char *midend_rewrite_statusbar(midend *me, char *text);
-
-The front end should call this function from within
-\cw{status_bar()} (\k{drawing-status-bar}). It should be passed the
-string that was passed by the back end to \cw{status_bar()}; it will
-return a dynamically allocated string adjusted by the mid-end.
-(Specifically, adjusted to include the timer if the game is a timed
-one.) The returned value should be placed in the actual status bar
-in place of the input value.
-
-(This is a nasty piece of architecture; I apologise for it. It would
-seem a lot more pleasant to have the back end pass its status bar
-text to the mid-end, which in turn would rewrite it and pass it on
-to the front end, so that each front end needed to do nothing
-strange. The main reason why I haven't done this is because it means
-the back end redraw function would need to be passed a mid-end
-pointer \e{as well} as a front end pointer, which seemed like an
-excessive proliferation of opaque handles. The only way to avoid
-that proliferation would be to have all the drawing API functions
-also gatewayed through the mid-end, and that seemed like an
-excessive proliferation of wrapper functions. The current setup
-isn't nice, but it has minimal impact and I'm unconvinced that any
-of the other options are an improvement.)
-
\H{midend-serialise} \cw{midend_serialise()}
\c void midend_serialise(midend *me,
\c{random_state}. One of these is managed by each mid-end, for
example, and passed to the back end to generate a game with.
-\S{utils-random-init} \cw{random_init()}
+\S{utils-random-init} \cw{random_new()}
-\c random_state *random_init(char *seed, int len);
+\c random_state *random_new(char *seed, int len);
Allocates, initialises and returns a new \c{random_state}. The input
data is used as the seed for the random number stream (i.e. using
~mdw / sgt / puzzles / blobdiff