Stop the analysis pass in Loopy's redraw routine from being

[sgt/puzzles] / devel.but

diff --git a/devel.but b/devel.but
index ea23d52..970a73a 100644 (file)
--- a/devel.but
+++ b/devel.but
@@ -170,7 +170,7 @@ other miscellaneous functions. All of these are documented in
 
 There are a number of function call interfaces within Puzzles, and
 this guide will discuss each one in a chapter of its own. After
 
 There are a number of function call interfaces within Puzzles, and
 this guide will discuss each one in a chapter of its own. After

-that, (\k{writing}) discusses how to design new games, with some
+that, \k{writing} discusses how to design new games, with some

 general design thoughts and tips.
 
 \C{backend} Interface to the back end
 general design thoughts and tips.
 
 \C{backend} Interface to the back end


@@ -856,7 +856,7 @@ producing new \c{game_state}s.
 \S{backend-interpret-move} \cw{interpret_move()}
 
 \c char *(*interpret_move)(game_state *state, game_ui *ui,
 \S{backend-interpret-move} \cw{interpret_move()}
 
 \c char *(*interpret_move)(game_state *state, game_ui *ui,

-\c                         game_drawstate *ds,
+\c                         const game_drawstate *ds,

 \c                         int x, int y, int button);
 
 This function receives user input and processes it. Its input
 \c                         int x, int y, int button);
 
 This function receives user input and processes it. Its input


@@ -868,6 +868,11 @@ indicating an arrow or function key or a mouse event; when
 coordinates of the mouse pointer relative to the top left of the
 puzzle's drawing area.
 
 coordinates of the mouse pointer relative to the top left of the
 puzzle's drawing area.
 

+(The pointer to the \c{game_drawstate} is marked \c{const}, because
+\c{interpret_move} should not write to it. The normal use of that
+pointer will be to read the game's tile size parameter in order to
+divide mouse coordinates by it.)
+

 \cw{interpret_move()} may return in three different ways:
 
 \b Returning \cw{NULL} indicates that no action whatsoever occurred
 \cw{interpret_move()} may return in three different ways:
 
 \b Returning \cw{NULL} indicates that no action whatsoever occurred


@@ -1224,6 +1229,34 @@ a mine from the colour it uses when you complete the game. In order
 to achieve this, its \cw{flash_length()} function has to store a
 flag in the \c{game_ui} to indicate which flash type is required.)
 
 to achieve this, its \cw{flash_length()} function has to store a
 flag in the \c{game_ui} to indicate which flash type is required.)
 

+\S{backend-status} \cw{status()}
+
+\c int (*status)(game_state *state);
+
+This function returns a status value indicating whether the current
+game is still in play, or has been won, or has been conclusively lost.
+The mid-end uses this to implement \cw{midend_status()}
+(\k{midend-status}).
+
+The return value should be +1 if the game has been successfully
+solved. If the game has been lost in a situation where further play is
+unlikely, the return value should be -1. If neither is true (so play
+is still ongoing), return zero.
+
+Front ends may wish to use a non-zero status as a cue to proactively
+offer the option of starting a new game. Therefore, back ends should
+not return -1 if the game has been \e{technically} lost but undoing
+and continuing is still a realistic possibility.
+
+(For instance, games with hidden information such as Guess or Mines
+might well return a non-zero status whenever they reveal the solution,
+whether or not the player guessed it correctly, on the grounds that a
+player would be unlikely to hide the solution and continue playing
+after the answer was spoiled. On the other hand, games where you can
+merely get into a dead end such as Same Game or Inertia might choose
+to return 0 in that situation, on the grounds that the player would
+quite likely press Undo and carry on playing.)
+

 \S{backend-redraw} \cw{redraw()}
 
 \c void (*redraw)(drawing *dr, game_drawstate *ds,
 \S{backend-redraw} \cw{redraw()}
 
 \c void (*redraw)(drawing *dr, game_drawstate *ds,


@@ -1365,17 +1398,50 @@ called.
 
 \H{backend-misc} Miscellaneous
 
 
 \H{backend-misc} Miscellaneous
 

-\S{backend-can-format-as-text} \c{can_format_as_text}
+\S{backend-can-format-as-text-ever} \c{can_format_as_text_ever}

 
 

-\c int can_format_as_text;
+\c int can_format_as_text_ever;

 
 This boolean field is \cw{TRUE} if the game supports formatting a
 game state as ASCII text (typically ASCII art) for copying to the
 clipboard and pasting into other applications. If it is \cw{FALSE},
 front ends will not offer the \q{Copy} command at all.
 
 
 This boolean field is \cw{TRUE} if the game supports formatting a
 game state as ASCII text (typically ASCII art) for copying to the
 clipboard and pasting into other applications. If it is \cw{FALSE},
 front ends will not offer the \q{Copy} command at all.
 

-If this field is \cw{FALSE}, the function \cw{text_format()}
-(\k{backend-text-format}) is not expected to do anything at all.
+If this field is \cw{TRUE}, the game does not necessarily have to
+support text formatting for \e{all} games: e.g. a game which can be
+played on a square grid or a triangular one might only support copy
+and paste for the former, because triangular grids in ASCII art are
+just too difficult.
+
+If this field is \cw{FALSE}, the functions
+\cw{can_format_as_text_now()} (\k{backend-can-format-as-text-now})
+and \cw{text_format()} (\k{backend-text-format}) are never called.
+
+\S{backend-can-format-as-text-now} \c{can_format_as_text_now()}
+
+\c int (*can_format_as_text_now)(game_params *params);
+
+This function is passed a \c{game_params} and returns a boolean,
+which is \cw{TRUE} if the game can support ASCII text output for
+this particular game type. If it returns \cw{FALSE}, front ends will
+grey out or otherwise disable the \q{Copy} command.
+
+Games may enable and disable the copy-and-paste function for
+different game \e{parameters}, but are currently constrained to
+return the same answer from this function for all game \e{states}
+sharing the same parameters. In other words, the \q{Copy} function
+may enable or disable itself when the player changes game preset,
+but will never change during play of a single game or when another
+game of exactly the same type is generated.
+
+This function should not take into account aspects of the game
+parameters which are not encoded by \cw{encode_params()}
+(\k{backend-encode-params}) when the \c{full} parameter is set to
+\cw{FALSE}. Such parameters will not necessarily match up between a
+call to this function and a subsequent call to \cw{text_format()}
+itself. (For instance, game \e{difficulty} should not affect whether
+the game can be copied to the clipboard. Only the actual visible
+\e{shape} of the game can affect that.)

 
 \S{backend-text-format} \cw{text_format()}
 
 
 \S{backend-text-format} \cw{text_format()}
 


@@ -1386,9 +1452,11 @@ allocated C string containing an ASCII representation of that game
 state. It is used to implement the \q{Copy} operation in many front
 ends.
 
 state. It is used to implement the \q{Copy} operation in many front
 ends.
 

-This function should only be called if the back end field
-\c{can_format_as_text} (\k{backend-can-format-as-text}) is
-\cw{TRUE}.
+This function will only ever be called if the back end field
+\c{can_format_as_text_ever} (\k{backend-can-format-as-text-ever}) is
+\cw{TRUE} \e{and} the function \cw{can_format_as_text_now()}
+(\k{backend-can-format-as-text-now}) has returned \cw{TRUE} for the
+currently selected game parameters.

 
 The returned string may contain line endings (and will probably want
 to), using the normal C internal \cq{\\n} convention. For
 
 The returned string may contain line endings (and will probably want
 to), using the normal C internal \cq{\\n} convention. For


@@ -1398,7 +1466,7 @@ them internally. (There are currently no puzzles which have a
 one-line ASCII representation, so there's no precedent yet for
 whether that should come with a newline or not.)
 
 one-line ASCII representation, so there's no precedent yet for
 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;
 
 
 \c int wants_statusbar;
 


@@ -1606,6 +1674,43 @@ end does any drawing it informs the front end of which parts of the
 window it has accessed, and hence which parts need repainting. This
 is done by calling \cw{draw_update()} (\k{drawing-draw-update}).
 
 window it has accessed, and hence which parts need repainting. This
 is done by calling \cw{draw_update()} (\k{drawing-draw-update}).
 

+Persistence of old drawing is convenient. However, a puzzle should
+be very careful about how it updates its drawing area. The problem
+is that some front ends do anti-aliased drawing: rather than simply
+choosing between leaving each pixel untouched or painting it a
+specified colour, an antialiased drawing function will \e{blend} the
+original and new colours in pixels at a figure's boundary according
+to the proportion of the pixel occupied by the figure (probably
+modified by some heuristic fudge factors). All of this produces a
+smoother appearance for curves and diagonal lines.
+
+An unfortunate effect of drawing an anti-aliased figure repeatedly
+is that the pixels around the figure's boundary come steadily more
+saturated with \q{ink} and the boundary appears to \q{spread out}.
+Worse, redrawing a figure in a different colour won't fully paint
+over the old boundary pixels, so the end result is a rather ugly
+smudge.
+
+A good strategy to avoid unpleasant anti-aliasing artifacts is to
+identify a number of rectangular areas which need to be redrawn,
+clear them to the background colour, and then redraw their contents
+from scratch, being careful all the while not to stray beyond the
+boundaries of the original rectangles. The \cw{clip()} function
+(\k{drawing-clip}) comes in very handy here. Games based on a square
+grid can often do this fairly easily. Other games may need to be
+somewhat more careful. For example, Loopy's redraw function first
+identifies portions of the display which need to be updated. Then,
+if the changes are fairly well localised, it clears and redraws a
+rectangle containing each changed area. Otherwise, it gives up and
+redraws the entire grid from scratch.
+
+It is possible to avoid clearing to background and redrawing from
+scratch if one is very careful about which drawing functions one
+uses: if a function is documented as not anti-aliasing under some
+circumstances, you can rely on each pixel in a drawing either being
+left entirely alone or being set to the requested colour, with no
+blending being performed.
+

 In the following sections I first discuss the drawing API as seen by
 the back end, and then the \e{almost} identical function-pointer
 form seen by the front end.
 In the following sections I first discuss the drawing API as seen by
 the back end, and then the \e{almost} identical function-pointer
 form seen by the front end.


@@ -1680,8 +1785,9 @@ the back end function \cw{colours()} (\k{backend-colours}).
 
 Some platforms may perform anti-aliasing on this function.
 Therefore, do not assume that you can erase a line by drawing the
 
 Some platforms may perform anti-aliasing on this function.
 Therefore, do not assume that you can erase a line by drawing the

-same line over it in the background colour; anti-aliasing might
-lead to perceptible ghost artefacts around the vanished line.
+same line over it in the background colour; anti-aliasing might lead
+to perceptible ghost artefacts around the vanished line. Horizontal
+and vertical lines, however, are pixel-perfect and not anti-aliased.

 
 This function may be used for both drawing and printing.
 
 
 This function may be used for both drawing and printing.
 


@@ -1718,7 +1824,8 @@ same polygon over it in the background colour. Also, be prepared for
 the polygon to extend a pixel beyond its obvious bounding box as a
 result of this; if you really need it not to do this to avoid
 interfering with other delicate graphics, you should probably use
 the polygon to extend a pixel beyond its obvious bounding box as a
 result of this; if you really need it not to do this to avoid
 interfering with other delicate graphics, you should probably use

-\cw{clip()} (\k{drawing-clip}).
+\cw{clip()} (\k{drawing-clip}). You can rely on horizontal and
+vertical lines not being anti-aliased.

 
 This function may be used for both drawing and printing.
 
 
 This function may be used for both drawing and printing.
 


@@ -1760,6 +1867,32 @@ interfering with other delicate graphics, you should probably use
 
 This function may be used for both drawing and printing.
 
 
 This function may be used for both drawing and printing.
 

+\S{drawing-draw-thick-line} \cw{draw_thick_line()}
+
+\c void draw_thick_line(drawing *dr, float thickness,
+\c                      float x1, float y1, float x2, float y2,
+\c                      int colour)
+
+Draws a line in the puzzle window, giving control over the line's
+thickness.
+
+\c{x1} and \c{y1} give the coordinates of one end of the line.
+\c{x2} and \c{y2} give the coordinates of the other end.
+\c{thickness} gives the thickness of the line, in pixels.
+
+Note that the coordinates and thickness are floating-point: the
+continuous coordinate system is in effect here. It's important to
+be able to address points with better-than-pixel precision in this
+case, because one can't otherwise properly express the endpoints of
+lines with both odd and even thicknesses.
+
+Some platforms may perform anti-aliasing on this function. The
+precise pixels affected by a thick-line drawing operation may vary
+between platforms, and no particular guarantees are provided.
+Indeed, even horizontal or vertical lines may be anti-aliased.
+
+This function may be used for both drawing and printing.
+

 \S{drawing-draw-text} \cw{draw_text()}
 
 \c void draw_text(drawing *dr, int x, int y, int fonttype,
 \S{drawing-draw-text} \cw{draw_text()}
 
 \c void draw_text(drawing *dr, int x, int y, int fonttype,


@@ -1813,6 +1946,54 @@ the back end function \cw{colours()} (\k{backend-colours}).
 
 This function may be used for both drawing and printing.
 
 
 This function may be used for both drawing and printing.
 

+The character set used to encode the text passed to this function is
+specified \e{by the drawing object}, although it must be a superset
+of ASCII. If a puzzle wants to display text that is not contained in
+ASCII, it should use the \cw{text_fallback()} function
+(\k{drawing-text-fallback}) to query the drawing object for an
+appropriate representation of the characters it wants.
+
+\S{drawing-text-fallback} \cw{text_fallback()}
+
+\c char *text_fallback(drawing *dr, const char *const *strings,
+\c                     int nstrings);
+
+This function is used to request a translation of UTF-8 text into
+whatever character encoding is expected by the drawing object's
+implementation of \cw{draw_text()}.
+
+The input is a list of strings encoded in UTF-8: \cw{nstrings} gives
+the number of strings in the list, and \cw{strings[0]},
+\cw{strings[1]}, ..., \cw{strings[nstrings-1]} are the strings
+themselves.
+
+The returned string (which is dynamically allocated and must be
+freed when finished with) is derived from the first string in the
+list that the drawing object expects to be able to display reliably;
+it will consist of that string translated into the character set
+expected by \cw{draw_text()}.
+
+Drawing implementations are not required to handle anything outside
+ASCII, but are permitted to assume that \e{some} string will be
+successfully translated. So every call to this function must include
+a string somewhere in the list (presumably the last element) which
+consists of nothing but ASCII, to be used by any front end which
+cannot handle anything else.
+
+For example, if a puzzle wished to display a string including a
+multiplication sign (U+00D7 in Unicode, represented by the bytes C3
+97 in UTF-8), it might do something like this:
+
+\c static const char *const times_signs[] = { "\xC3\x97", "x" };
+\c char *times_sign = text_fallback(dr, times_signs, 2);
+\c sprintf(buffer, "%d%s%d", width, times_sign, height);
+\c draw_text(dr, x, y, font, size, align, colour, buffer);
+\c sfree(buffer);
+
+which would draw a string with a times sign in the middle on
+platforms that support it, and fall back to a simple ASCII \cq{x}
+where there was no alternative.
+

 \S{drawing-clip} \cw{clip()}
 
 \c void clip(drawing *dr, int x, int y, int w, int h);
 \S{drawing-clip} \cw{clip()}
 
 \c void clip(drawing *dr, int x, int y, int w, int h);


@@ -1828,7 +2009,9 @@ inclusive. (These are exactly the same semantics as
 
 After this call, no drawing operation will affect anything outside
 the specified rectangle. The effect can be reversed by calling
 
 After this call, no drawing operation will affect anything outside
 the specified rectangle. The effect can be reversed by calling

-\cw{unclip()} (\k{drawing-unclip}).
+\cw{unclip()} (\k{drawing-unclip}). The clipping rectangle is
+pixel-perfect: pixels within the rectangle are affected as usual by
+drawing functions; pixels outside are completely untouched.

 
 Back ends should not assume that a clipping rectangle will be
 automatically cleared up by the front end if it's left lying around;
 
 Back ends should not assume that a clipping rectangle will be
 automatically cleared up by the front end if it's left lying around;


@@ -2108,6 +2291,22 @@ however, that it is a hint only: the central printing system may
 choose to vary line thicknesses at user request or due to printer
 capabilities.
 
 choose to vary line thicknesses at user request or due to printer
 capabilities.
 

+\S{print-line-dotted} \cw{print_line_dotted()}
+
+\c void print_line_dotted(drawing *dr, int dotted);
+
+This function is called to toggle the drawing of dotted lines during
+printing. It is not supported during drawing.
+
+The parameter \cq{dotted} is a boolean; \cw{TRUE} means that future
+lines drawn by \cw{draw_line()}, \cw{draw_circle} and
+\cw{draw_polygon()} will be dotted, and \cw{FALSE} means that they
+will be solid.
+
+Some front ends may impose restrictions on the width of dotted
+lines. Asking for a dotted line via this front end will override any
+line width request if the front end requires it.
+

 \H{drawing-frontend} The drawing API as implemented by the front end
 
 This section describes the drawing API in the function-pointer form
 \H{drawing-frontend} The drawing API as implemented by the front end
 
 This section describes the drawing API in the function-pointer form


@@ -2166,6 +2365,20 @@ function; see \k{drawing-draw-polygon}.
 This function behaves exactly like the back end \cw{draw_circle()}
 function; see \k{drawing-draw-circle}.
 
 This function behaves exactly like the back end \cw{draw_circle()}
 function; see \k{drawing-draw-circle}.
 

+\S{drawingapi-draw-thick-line} \cw{draw_thick_line()}
+
+\c void draw_thick_line(drawing *dr, float thickness,
+\c                      float x1, float y1, float x2, float y2,
+\c                      int colour)
+
+This function behaves exactly like the back end
+\cw{draw_thick_line()} function; see \k{drawing-draw-thick-line}.
+
+An implementation of this API which doesn't provide high-quality
+rendering of thick lines is permitted to define this function
+pointer to be \cw{NULL}. The middleware in \cw{drawing.c} will notice
+and provide a low-quality alternative using \cw{draw_polygon()}.
+

 \S{drawingapi-draw-update} \cw{draw_update()}
 
 \c void (*draw_update)(void *handle, int x, int y, int w, int h);
 \S{drawingapi-draw-update} \cw{draw_update()}
 
 \c void (*draw_update)(void *handle, int x, int y, int w, int h);


@@ -2391,6 +2604,19 @@ Implementations of this API which do not provide printing services
 may define this function pointer to be \cw{NULL}; it will never be
 called unless printing is attempted.
 
 may define this function pointer to be \cw{NULL}; it will never be
 called unless printing is attempted.
 

+\S{drawingapi-text-fallback} \cw{text_fallback()}
+
+\c char *(*text_fallback)(void *handle, const char *const *strings,
+\c                        int nstrings);
+
+This function behaves exactly like the back end \cw{text_fallback()}
+function; see \k{drawing-text-fallback}.
+
+Implementations of this API which do not support any characters
+outside ASCII may define this function pointer to be \cw{NULL}, in
+which case the central code in \cw{drawing.c} will provide a default
+implementation.
+

 \H{drawingapi-frontend} The drawing API as called by the front end
 
 There are a small number of functions provided in \cw{drawing.c}
 \H{drawingapi-frontend} The drawing API as called by the front end
 
 There are a small number of functions provided in \cw{drawing.c}


@@ -2493,6 +2719,13 @@ without closing the window...)
 
 Frees a mid-end structure and all its associated data.
 
 
 Frees a mid-end structure and all its associated data.
 

+\H{midend-tilesize} \cw{midend_tilesize()}
+
+\c int midend_tilesize(midend *me);
+
+Returns the \cq{tilesize} parameter being used to display the
+current puzzle (\k{backend-preferred-tilesize}).
+

 \H{midend-set-params} \cw{midend_set_params()}
 
 \c void midend_set_params(midend *me, game_params *params);
 \H{midend-set-params} \cw{midend_set_params()}
 
 \c void midend_set_params(midend *me, game_params *params);


@@ -2576,6 +2809,9 @@ to use scroll bars for large puzzles), you can pass dimensions of
 \cw{INT_MAX} as input to this function. You should probably not do
 that \e{and} set the \c{user_size} flag, though!
 
 \cw{INT_MAX} as input to this function. You should probably not do
 that \e{and} set the \c{user_size} flag, though!
 

+The midend relies on the frontend calling \cw{midend_new_game()}
+(\k{midend-new-game}) before calling \cw{midend_size()}.
+

 \H{midend-new-game} \cw{midend_new_game()}
 
 \c void midend_new_game(midend *me);
 \H{midend-new-game} \cw{midend_new_game()}
 
 \c void midend_new_game(midend *me);


@@ -2612,7 +2848,8 @@ undo list (so that an accidental restart can be undone).
 
 This function automatically causes a redraw, i.e. the front end can
 expect its drawing API to be called from \e{within} a call to this
 
 This function automatically causes a redraw, i.e. the front end can
 expect its drawing API to be called from \e{within} a call to this

-function.
+function. Some back ends require that \cw{midend_size()}
+(\k{midend-size}) is called before \cw{midend_restart_game()}.

 
 \H{midend-force-redraw} \cw{midend_force_redraw()}
 
 
 \H{midend-force-redraw} \cw{midend_force_redraw()}
 


@@ -2623,7 +2860,8 @@ discarding the current \c{game_drawstate} and creating a new one
 from scratch before calling the game's \cw{redraw()} function.
 
 The front end can expect its drawing API to be called from within a
 from scratch before calling the game's \cw{redraw()} function.
 
 The front end can expect its drawing API to be called from within a

-call to this function.
+call to this function. Some back ends require that \cw{midend_size()}
+(\k{midend-size}) is called before \cw{midend_force_redraw()}.

 
 \H{midend-redraw} \cw{midend_redraw()}
 
 
 \H{midend-redraw} \cw{midend_redraw()}
 


@@ -2634,7 +2872,8 @@ calling the game's \cw{redraw()} function. (That is, the only things
 redrawn will be things that have changed since the last redraw.)
 
 The front end can expect its drawing API to be called from within a
 redrawn will be things that have changed since the last redraw.)
 
 The front end can expect its drawing API to be called from within a

-call to this function.
+call to this function. Some back ends require that \cw{midend_size()}
+(\k{midend-size}) is called before \cw{midend_redraw()}.

 
 \H{midend-process-key} \cw{midend_process_key()}
 
 
 \H{midend-process-key} \cw{midend_process_key()}
 


@@ -2852,6 +3091,16 @@ Returns a descriptive game ID (i.e. one in the form
 \cq{params:description}) describing the game currently active in the
 mid-end. The returned string is dynamically allocated.
 
 \cq{params:description}) describing the game currently active in the
 mid-end. The returned string is dynamically allocated.
 

+\H{midend-can-format-as-text-now} \cw{midend_can_format_as_text_now()}
+
+\c int midend_can_format_as_text_now(midend *me);
+
+Returns \cw{TRUE} if the game code is capable of formatting puzzles
+of the currently selected game type as ASCII.
+
+If this returns \cw{FALSE}, then \cw{midend_text_format()}
+(\k{midend-text-format}) will return \cw{NULL}.
+

 \H{midend-text-format} \cw{midend_text_format()}
 
 \c char *midend_text_format(midend *me);
 \H{midend-text-format} \cw{midend_text_format()}
 
 \c char *midend_text_format(midend *me);


@@ -2860,8 +3109,9 @@ Formats the current game's current state as ASCII text suitable for
 copying to the clipboard. The returned string is dynamically
 allocated.
 
 copying to the clipboard. The returned string is dynamically
 allocated.
 

-You should not call this function if the game's
-\c{can_format_as_text} flag is \cw{FALSE}.
+If the game's \c{can_format_as_text_ever} flag is \cw{FALSE}, or if
+its \cw{can_format_as_text_now()} function returns \cw{FALSE}, then
+this function will return \cw{NULL}.

 
 If the returned string contains multiple lines (which is likely), it
 will use the normal C line ending convention (\cw{\\n} only). On
 
 If the returned string contains multiple lines (which is likely), it
 will use the normal C line ending convention (\cw{\\n} only). On


@@ -2881,7 +3131,40 @@ user.
 
 The front end can expect its drawing API and/or
 \cw{activate_timer()} to be called from within a call to this
 
 The front end can expect its drawing API and/or
 \cw{activate_timer()} to be called from within a call to this

-function.
+function.  Some back ends require that \cw{midend_size()}
+(\k{midend-size}) is called before \cw{midend_solve()}.
+
+\H{midend-status} \cw{midend_status()}
+
+\c int midend_status(midend *me);
+
+This function returns +1 if the midend is currently displaying a game
+in a solved state, -1 if the game is in a permanently lost state, or 0
+otherwise. This function just calls the back end's \cw{status()}
+function. Front ends may wish to use this as a cue to proactively
+offer the option of starting a new game.
+
+(See \k{backend-status} for more detail about the back end's
+\cw{status()} function and discussion of what should count as which
+status code.)
+
+\H{midend-can-undo} \cw{midend_can_undo()}
+
+\c int midend_can_undo(midend *me);
+
+Returns \cw{TRUE} if the midend is currently in a state where the undo
+operation is meaningful (i.e. at least one position exists on the undo
+chain before the present one). Front ends may wish to use this to
+visually activate and deactivate an undo button.
+
+\H{midend-can-redo} \cw{midend_can_redo()}
+
+\c int midend_can_redo(midend *me);
+
+Returns \cw{TRUE} if the midend is currently in a state where the redo
+operation is meaningful (i.e. at least one position exists on the redo
+chain after the present one). Front ends may wish to use this to
+visually activate and deactivate a redo button.

 
 \H{midend-serialise} \cw{midend_serialise()}
 
 
 \H{midend-serialise} \cw{midend_serialise()}
 


@@ -2964,8 +3247,8 @@ mid-end because there didn't seem much point in doing so:
 \b fetching the \c{name} field to use in window titles and similar
 
 \b reading the \c{can_configure}, \c{can_solve} and
 \b fetching the \c{name} field to use in window titles and similar
 
 \b reading the \c{can_configure}, \c{can_solve} and

-\c{can_format_as_text} fields to decide whether to add those items
-to the menu bar or equivalent
+\c{can_format_as_text_ever} fields to decide whether to add those
+items to the menu bar or equivalent

 
 \b reading the \c{winhelp_topic} field (Windows only)
 
 
 \b reading the \c{winhelp_topic} field (Windows only)