It's a new year.

[sgt/puzzles] / devel.but

diff --git a/devel.but b/devel.but
index 88ff947..4a91349 100644 (file)
--- a/devel.but
+++ b/devel.but
@@ -1104,7 +1104,7 @@ create a fresh drawstate.
 
 \S{backend-colours} \cw{colours()}
 
 
 \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.
 
 This function is responsible for telling the front end what colours
 the puzzle will need to draw itself.


@@ -1115,15 +1115,7 @@ array of three times that many \c{float}s, containing the red, green
 and blue components of each colour respectively as numbers in the
 range [0,1].
 
 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 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


@@ -1166,8 +1158,7 @@ State changes as a result of a Restart operation are never animated;
 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
 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
 
 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


@@ -1407,16 +1398,12 @@ whether that should come with a newline or not.)
 
 \S{backend-wants-statusbar} \cw{wants_statusbar()}
 
 
 \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).
 
 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;
 \S{backend-is-timed} \c{is_timed}
 
 \c int is_timed;


@@ -1441,12 +1428,12 @@ the game was first completed (by setting a flag in
 freeze the timer thereafter so that the user can undo back through
 their solution process without altering their time.
 
 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)}
 
 
 \dt \cw{BUTTON_BEATS(x,y)}
 


@@ -1876,6 +1863,11 @@ with the drawing API the property that it may only be called from
 within the back end redraw function, so this is as good a place as
 any to document it.)
 
 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.
 
 This function is for drawing only; it must never be called during
 printing.
 


@@ -2081,7 +2073,7 @@ structure called \c{drawing_api}. Each of the functions takes a
 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
 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()}
 
 
 \S{drawingapi-draw-text} \cw{draw_text()}
 


@@ -2180,19 +2172,9 @@ called unless drawing is attempted.
 This function behaves exactly like the back end \cw{status_bar()}
 function; see \k{drawing-status-bar}.
 
 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
 
 Implementations of this API which do not provide drawing services
 may define this function pointer to be \cw{NULL}; it will never be


@@ -2364,15 +2346,23 @@ There are a small number of functions provided in \cw{drawing.c}
 which the front end needs to \e{call}, rather than helping to
 implement. They are described in this section.
 
 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.
 
 
 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);
 \S{drawing-free} \cw{drawing_free()}
 
 \c void drawing_free(drawing *dr);


@@ -2425,7 +2415,7 @@ calling back to functions such as \cw{activate_timer()}
 function \cw{colours()} (\k{backend-colours}).
 
 The parameters \c{drapi} and \c{drhandle} are passed to
 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
 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


@@ -2811,32 +2801,6 @@ The front end can expect its drawing API and/or
 \cw{activate_timer()} to be called from within a call to this
 function.
 
 \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,
 \H{midend-serialise} \cw{midend_serialise()}
 
 \c void midend_serialise(midend *me,