X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/puzzles/blobdiff_plain/f92acd1ac36fa42e599c75fbc825b92e6c0cb1af..911c3ec1d26e2b5fddb5da67c1e139a97941d0ea:/devel.but diff --git a/devel.but b/devel.but index e481ec6..c5a2c43 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 @@ -1813,6 +1848,54 @@ the back end function \cw{colours()} (\k{backend-colours}). 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); @@ -2108,6 +2191,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. +\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 @@ -2391,6 +2490,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. +\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} @@ -2493,6 +2605,15 @@ without closing the window...) Frees a mid-end structure and all its associated data. +\H{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); @@ -2671,6 +2792,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); @@ -2847,6 +2973,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); @@ -2855,8 +2991,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 @@ -2959,8 +3096,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)