X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/puzzles/blobdiff_plain/8c4ea6f0ea2024075e110bef9a6ad3037cbf9b1d..63ed24043747435fc5b67339248426ca236e0739:/devel.but diff --git a/devel.but b/devel.but index cf06656..45e05d6 100644 --- 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 -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 @@ -1365,17 +1365,50 @@ called. \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. -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()} @@ -1386,9 +1419,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. -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 @@ -1991,7 +2026,7 @@ black; if \c{grey} is 1, the colour is white. \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. @@ -1999,18 +2034,17 @@ 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: +The chosen colour will be rendered to the limits of the printer's +halftoning capability. -\dt \cw{HATCH_SOLID} +\S{print-hatched-colour} \cw{print_hatched_colour()} -\dd In black and white, this colour will be replaced by solid black. +\c int print_hatched_colour(drawing *dr, int hatch); -\dt \cw{HATCH_CLEAR} - -\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} @@ -2039,29 +2073,59 @@ vertical lines. \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-mono-colour} \cw{print_rgb_mono_colour()} + +\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 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-colour} \cw{print_rgb_colour()} +\S{print-rgb-hatched-colour} \cw{print_rgb_hatched_colour()} -\c int print_rgb_colour(drawing *dr, int hatch, -\c float r, float g, float b); +\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 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 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()} @@ -2395,20 +2459,27 @@ the front end. \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 @@ -2635,6 +2706,11 @@ Calling this function is very likely to result in calls back to the 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); @@ -2692,6 +2768,16 @@ are owned by the mid-end structure: the front end should not ever 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); @@ -2801,6 +2887,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. +\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); @@ -2809,8 +2905,9 @@ Formats the current game's current state as ASCII text suitable for 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 @@ -2913,8 +3010,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 -\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)