each game. On the rare occasion that animated solve moves are
actually required, you can set this flag.
+\dt \cw{REQUIRE_RBUTTON}
+
+\dd This flag indicates that the puzzle cannot be usefully played
+without the use of mouse buttons other than the left one. On some
+PDA platforms, this flag is used by the front end to enable
+right-button emulation through an appropriate gesture. Note that a
+puzzle is not required to set this just because it \e{uses} the
+right button, but only if its use of the right button is critical to
+playing the game. (Slant, for example, uses the right button to
+cycle through the three square states in the opposite order from the
+left button, and hence can manage fine without it.)
+
+\dt \cw{REQUIRE_NUMPAD}
+
+\dd This flag indicates that the puzzle cannot be usefully played
+without the use of number-key input. On some PDA platforms it causes
+an emulated number pad to appear on the screen. Similarly to
+\cw{REQUIRE_RBUTTON}, a puzzle need not specify this simply if its
+use of the number keys is not critical.
+
\H{backend-initiative} Things a back end may do on its own initiative
This section describes a couple of things that a back end may choose
\S{print-grey-colour} \cw{print_grey_colour()}
-\c int print_grey_colour(drawing *dr, int hatch, float grey);
+\c int print_grey_colour(drawing *dr, float grey);
This function allocates a colour index for a grey-scale colour
during printing.
\c{grey} may be any number between 0 (black) and 1 (white); for
example, 0.5 indicates a medium grey.
-If printing in black and white only, the \c{grey} value will not be
-used; instead, regions shaded in this colour will be hatched with
-parallel lines. The \c{hatch} parameter defines what type of
-hatching should be used in place of this colour:
-
-\dt \cw{HATCH_SOLID}
+The chosen colour will be rendered to the limits of the printer's
+halftoning capability.
-\dd In black and white, this colour will be replaced by solid black.
+\S{print-hatched-colour} \cw{print_hatched_colour()}
-\dt \cw{HATCH_CLEAR}
+\c int print_hatched_colour(drawing *dr, int hatch);
-\dd In black and white, this colour will be replaced by solid white.
+This function allocates a colour index which does not represent a
+literal \e{colour}. Instead, regions shaded in this colour will be
+hatched with parallel lines. The \c{hatch} parameter defines what
+type of hatching should be used in place of this colour:
\dt \cw{HATCH_SLASH}
\dd This colour will be hatched by criss-crossing diagonal lines.
-Colours defined to use hatching may not be used for drawing lines;
-they may only be used for filling areas. That is, they may be used
-as the \c{fillcolour} parameter to \cw{draw_circle()} and
+Colours defined to use hatching may not be used for drawing lines or
+text; they may only be used for filling areas. That is, they may be
+used as the \c{fillcolour} parameter to \cw{draw_circle()} and
\cw{draw_polygon()}, and as the colour parameter to
\cw{draw_rect()}, but may not be used as the \c{outlinecolour}
parameter to \cw{draw_circle()} or \cw{draw_polygon()}, or with
-\cw{draw_line()}.
+\cw{draw_line()} or \cw{draw_text()}.
-\S{print-rgb-colour} \cw{print_rgb_colour()}
+\S{print-rgb-mono-colour} \cw{print_rgb_mono_colour()}
-\c int print_rgb_colour(drawing *dr, int hatch,
-\c float r, float g, float b);
+\c int print_rgb_mono_colour(drawing *dr, float r, float g,
+\c float b, float grey);
This function allocates a colour index for a fully specified RGB
colour during printing.
\c{r}, \c{g} and \c{b} may each be anywhere in the range from 0 to 1.
-If printing in black and white only, these values will not be used;
-instead, regions shaded in this colour will be hatched with parallel
-lines. The \c{hatch} parameter defines what type of hatching should
-be used in place of this colour; see \k{print-grey-colour} for its
-definition.
+If printing in black and white only, these values will be ignored,
+and either pure black or pure white will be used instead, according
+to the \q{grey} parameter. (The fallback colour is the same as the
+one which would be allocated by \cw{print_mono_colour(grey)}.)
+
+\S{print-rgb-grey-colour} \cw{print_rgb_grey_colour()}
+
+\c int print_rgb_grey_colour(drawing *dr, float r, float g,
+\c float b, float grey);
+
+This function allocates a colour index for a fully specified RGB
+colour during printing.
+
+\c{r}, \c{g} and \c{b} may each be anywhere in the range from 0 to 1.
+
+If printing in black and white only, these values will be ignored,
+and a shade of grey given by the \c{grey} parameter will be used
+instead. (The fallback colour is the same as the one which would be
+allocated by \cw{print_grey_colour(grey)}.)
+
+\S{print-rgb-hatched-colour} \cw{print_rgb_hatched_colour()}
+
+\c int print_rgb_hatched_colour(drawing *dr, float r, float g,
+\c float b, float hatched);
+
+This function allocates a colour index for a fully specified RGB
+colour during printing.
+
+\c{r}, \c{g} and \c{b} may each be anywhere in the range from 0 to 1.
+
+If printing in black and white only, these values will be ignored,
+and a form of cross-hatching given by the \c{hatch} parameter will
+be used instead; see \k{print-hatched-colour} for the possible
+values of this parameter. (The fallback colour is the same as the
+one which would be allocated by \cw{print_hatched_colour(hatch)}.)
\S{print-line-width} \cw{print_line_width()}
\c void (*draw_update)(void *handle, int x, int y, int w, int h);
This function behaves exactly like the back end \cw{draw_update()}
-function; see \k{drawing-draw-text}.
+function; see \k{drawing-draw-update}.
An implementation of this API which only supports printing is
permitted to define this function pointer to be \cw{NULL} rather
\S{drawing-print-get-colour} \cw{print_get_colour()}
-\c void print_get_colour(drawing *dr, int colour, int *hatch,
-\c float *r, float *g, float *b)
+\c void print_get_colour(drawing *dr, int colour, int printincolour,
+\c int *hatch, float *r, float *g, float *b)
This function is called by the implementations of the drawing API
functions when they are called in a printing context. It takes a
colour index as input, and returns the description of the colour as
requested by the back end.
-\c{*r}, \c{*g} and \c{*b} are filled with the RGB values of the
-desired colour if printing in colour.
+\c{printincolour} is \cw{TRUE} iff the implementation is printing in
+colour. This will alter the results returned if the colour in
+question was specified with a black-and-white fallback value.
-\c{*hatch} is filled with the type of hatching (or not) desired if
-printing in black and white. See \k{print-grey-colour} for details
-of the values this integer can take.
+If the colour should be rendered by hatching, \c{*hatch} is filled
+with the type of hatching desired. See \k{print-grey-colour} for
+details of the values this integer can take.
+
+If the colour should be rendered as solid colour, \c{*hatch} is
+given a negative value, and \c{*r}, \c{*g} and \c{*b} are filled
+with the RGB values of the desired colour (if printing in colour),
+or all filled with the grey-scale value (if printing in black and
+white).
\C{midend} The API provided by the mid-end
\H{midend-size} \cw{midend_size()}
-\c void midend_size(midend *me, int *x, int *y, int expand);
+\c void midend_size(midend *me, int *x, int *y, int user_size);
Tells the mid-end to figure out its window size.
furniture such as menu bars and window borders, if necessary. The
status bar is also not included in this size.)
-If \c{expand} is set to \cw{FALSE}, then the game's tile size will
-never go over its preferred one. This is the recommended approach
-when opening a new window at default size: the game will use its
-preferred size unless it has to use a smaller one to fit on the
-screen.
-
-If \c{expand} is set to \cw{TRUE}, the mid-end will pick a tile size
-which approximates the input size \e{as closely as possible}, and
-will go over the game's preferred tile size if necessary to achieve
-this. Use this option if you want your front end to support dynamic
-resizing of the puzzle window with automatic scaling of the puzzle
-to fit.
+Use \c{user_size} to indicate whether \c{*x} and \c{*y} are a
+requested size, or just a maximum size.
+
+If \c{user_size} is set to \cw{TRUE}, the mid-end will treat the
+input size as a request, and will pick a tile size which
+approximates it \e{as closely as possible}, going over the game's
+preferred tile size if necessary to achieve this. The mid-end will
+also use the resulting tile size as its preferred one until further
+notice, on the assumption that this size was explicitly requested
+by the user. Use this option if you want your front end to support
+dynamic resizing of the puzzle window with automatic scaling of the
+puzzle to fit.
+
+If \c{user_size} is set to \cw{FALSE}, then the game's tile size
+will never go over its preferred one, although it may go under in
+order to fit within the maximum bounds specified by \c{*x} and
+\c{*y}. This is the recommended approach when opening a new window
+at default size: the game will use its preferred size unless it has
+to use a smaller one to fit on the screen. If the tile size is
+shrunk for this reason, the change will not persist; if a smaller
+grid is subsequently chosen, the tile size will recover.
The mid-end will try as hard as it can to return a size which is
less than or equal to the input size, in both dimensions. In extreme
If your platform has no limit on window size (or if you're planning
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{expand} flag, though!
+that \e{and} set the \c{user_size} flag, though!
\H{midend-new-game} \cw{midend_new_game()}
front end's drawing API and/or \cw{activate_timer()}
(\k{frontend-activate-timer}).
+The return value from \cw{midend_process_key()} is non-zero, unless
+the effect of the keypress was to request termination of the
+program. A front end should shut down the puzzle in response to a
+zero return.
+
\H{midend-colours} \cw{midend_colours()}
\c float *midend_colours(midend *me, int *ncolours);
free them directly, because they will be freed automatically during
\cw{midend_free()}.
+\H{midend-which-preset} \cw{midend_which_preset()}
+
+\c int midend_which_preset(midend *me);
+
+Returns the numeric index of the preset game parameter structure
+which matches the current game parameters, or a negative number if
+no preset matches. Front ends could use this to maintain a tick
+beside one of the items in the menu (or tick the \q{Custom} option
+if the return value is less than zero).
+
\H{midend-wants-statusbar} \cw{midend_wants_statusbar()}
\c int midend_wants_statusbar(midend *me);
~mdw / sgt / puzzles / blobdiff