X-Git-Url: http://www.chiark.greenend.org.uk/ucgi/~ian/git?a=blobdiff_plain;f=devel.but;h=9befcadcb72874f212f026bff5bb00d44434fe0d;hb=3ce69e84cad15844282d691fa03e711c5353c05e;hp=5fb200d9eb23837a08e5e4c963602062d80efb11;hpb=bb14689b4a555b4b176192d2c3cd02a4c354a37f;p=sgt-puzzles.git diff --git a/devel.but b/devel.but index 5fb200d..9befcad 100644 --- a/devel.but +++ b/devel.but @@ -408,7 +408,7 @@ function is permitted to return \cw{FALSE} always. \S{backend-encode-params} \cw{encode_params()} -\c char *(*encode_params)(game_params *params, int full); +\c char *(*encode_params)(const game_params *params, int full); The job of this function is to take a \c{game_params}, and encode it in a string form for use in game IDs. The return value must be a @@ -493,7 +493,7 @@ allocations contained within it. \S{backend-dup-params} \cw{dup_params()} -\c game_params *(*dup_params)(game_params *params); +\c game_params *(*dup_params)(const game_params *params); This function allocates a new \c{game_params} structure and initialises it with an exact copy of the information in the one @@ -511,7 +511,7 @@ and \k{backend-custom-params} for more details. \S{backend-configure} \cw{configure()} -\c config_item *(*configure)(game_params *params); +\c config_item *(*configure)(const game_params *params); This function is called when the user requests a dialog box for custom parameter configuration. It returns a newly allocated array @@ -586,7 +586,7 @@ function is never called and need not do anything at all. \S{backend-custom-params} \cw{custom_params()} -\c game_params *(*custom_params)(config_item *cfg); +\c game_params *(*custom_params)(const config_item *cfg); This function is the counterpart to \cw{configure()} (\k{backend-configure}). It receives as input an array of @@ -611,7 +611,7 @@ function is never called and need not do anything at all. \S{backend-validate-params} \cw{validate_params()} -\c char *(*validate_params)(game_params *params, int full); +\c char *(*validate_params)(const game_params *params, int full); This function takes a \c{game_params} structure as input, and checks that the parameters described in it fall within sensible limits. (At @@ -655,7 +655,7 @@ a descriptive-format game ID. \S{backend-new-desc} \cw{new_desc()} -\c char *(*new_desc)(game_params *params, random_state *rs, +\c char *(*new_desc)(const game_params *params, random_state *rs, \c char **aux, int interactive); This function is where all the really hard work gets done. This is @@ -696,7 +696,7 @@ again in the game description. \S{backend-validate-desc} \cw{validate_desc()} -\c char *(*validate_desc)(game_params *params, char *desc); +\c char *(*validate_desc)(const game_params *params, const char *desc); This function is given a game description, and its job is to validate that it describes a puzzle which makes sense. @@ -720,8 +720,8 @@ non-dynamically-allocated C string containing an error message. \S{backend-new-game} \cw{new_game()} -\c game_state *(*new_game)(midend *me, game_params *params, -\c char *desc); +\c game_state *(*new_game)(midend *me, const game_params *params, +\c const char *desc); This function takes a game description as input, together with its accompanying \c{game_params}, and constructs a \c{game_state} @@ -749,7 +749,7 @@ game states and it had to go in one section or the other.) \S{backend-dup-game} \cw{dup_game()} -\c game_state *(*dup_game)(game_state *state); +\c game_state *(*dup_game)(const game_state *state); This function allocates a new \c{game_state} structure and initialises it with an exact copy of the information in the one @@ -766,7 +766,7 @@ allocations contained within it. \S{backend-new-ui} \cw{new_ui()} -\c game_ui *(*new_ui)(game_state *state); +\c game_ui *(*new_ui)(const game_state *state); This function allocates and returns a new \c{game_ui} structure for playing a particular puzzle. It is passed a pointer to the initial @@ -782,7 +782,7 @@ allocations contained within it. \S{backend-encode-ui} \cw{encode_ui()} -\c char *(*encode_ui)(game_ui *ui); +\c char *(*encode_ui)(const game_ui *ui); This function encodes any \e{important} data in a \c{game_ui} structure in string form. It is only called when saving a @@ -806,7 +806,7 @@ source.) \S{backend-decode-ui} \cw{decode_ui()} -\c void (*decode_ui)(game_ui *ui, char *encoding); +\c void (*decode_ui)(game_ui *ui, const char *encoding); This function parses a string previously output by \cw{encode_ui()}, and writes the decoded data back into the provided \c{game_ui} @@ -814,8 +814,8 @@ structure. \S{backend-changed-state} \cw{changed_state()} -\c void (*changed_state)(game_ui *ui, game_state *oldstate, -\c game_state *newstate); +\c void (*changed_state)(game_ui *ui, const game_state *oldstate, +\c const game_state *newstate); This function is called by the mid-end whenever the current game state changes, for any reason. Those reasons include: @@ -855,7 +855,7 @@ producing new \c{game_state}s. \S{backend-interpret-move} \cw{interpret_move()} -\c char *(*interpret_move)(game_state *state, game_ui *ui, +\c char *(*interpret_move)(const game_state *state, game_ui *ui, \c const game_drawstate *ds, \c int x, int y, int button); @@ -975,7 +975,7 @@ any input value. \S{backend-execute-move} \cw{execute_move()} -\c game_state *(*execute_move)(game_state *state, char *move); +\c game_state *(*execute_move)(const game_state *state, char *move); This function takes an input \c{game_state} and a move string as output from \cw{interpret_move()}. It returns a newly allocated @@ -999,8 +999,8 @@ not even offer the \q{Solve} menu option. \S{backend-solve} \cw{solve()} -\c char *(*solve)(game_state *orig, game_state *curr, -\c char *aux, char **error); +\c char *(*solve)(const game_state *orig, const game_state *curr, +\c const char *aux, char **error); This function is called when the user selects the \q{Solve} option from the menu. @@ -1020,9 +1020,11 @@ it may return \cw{NULL}. If it does this, it must also set \q{Solution not known for this puzzle}); that error message is not expected to be dynamically allocated. -If this function \e{does} produce a solution, it returns a move -string suitable for feeding to \cw{execute_move()} -(\k{backend-execute-move}). +If this function \e{does} produce a solution, it returns a move string +suitable for feeding to \cw{execute_move()} +(\k{backend-execute-move}). Like a (non-empty) string returned from +\cw{interpret_move()}, the returned string should be dynamically +allocated. \H{backend-drawing} Drawing the game graphics @@ -1031,7 +1033,8 @@ drawing. \S{backend-new-drawstate} \cw{new_drawstate()} -\c game_drawstate *(*new_drawstate)(drawing *dr, game_state *state); +\c game_drawstate *(*new_drawstate)(drawing *dr, +\c const game_state *state); This function allocates and returns a new \c{game_drawstate} structure for drawing a particular puzzle. It is passed a pointer to @@ -1081,7 +1084,7 @@ requesting a resize if that ever gets implemented). \S{backend-compute-size} \cw{compute_size()} -\c void (*compute_size)(game_params *params, int tilesize, +\c void (*compute_size)(const game_params *params, int tilesize, \c int *x, int *y); This function is passed a \c{game_params} structure and a tile size. @@ -1092,7 +1095,7 @@ at that tile size. \S{backend-set-size} \cw{set_size()} \c void (*set_size)(drawing *dr, game_drawstate *ds, -\c game_params *params, int tilesize); +\c const game_params *params, int tilesize); This function is responsible for setting up a \c{game_drawstate} to draw at a given tile size. Typically this will simply involve @@ -1141,7 +1144,8 @@ colour allocation policy. \S{backend-anim-length} \cw{anim_length()} -\c float (*anim_length)(game_state *oldstate, game_state *newstate, +\c float (*anim_length)(const game_state *oldstate, +\c const game_state *newstate, \c int dir, game_ui *ui); This function is called when a move is made, undone or redone. It is @@ -1185,7 +1189,8 @@ state. \S{backend-flash-length} \cw{flash_length()} -\c float (*flash_length)(game_state *oldstate, game_state *newstate, +\c float (*flash_length)(const game_state *oldstate, +\c const game_state *newstate, \c int dir, game_ui *ui); This function is called when a move is completed. (\q{Completed} @@ -1231,7 +1236,7 @@ flag in the \c{game_ui} to indicate which flash type is required.) \S{backend-status} \cw{status()} -\c int (*status)(game_state *state); +\c int (*status)(const 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. @@ -1260,8 +1265,10 @@ quite likely press Undo and carry on playing.) \S{backend-redraw} \cw{redraw()} \c void (*redraw)(drawing *dr, game_drawstate *ds, -\c game_state *oldstate, game_state *newstate, int dir, -\c game_ui *ui, float anim_time, float flash_time); +\c const game_state *oldstate, +\c const game_state *newstate, +\c int dir, const game_ui *ui, +\c float anim_time, float flash_time); This function is responsible for actually drawing the contents of the game window, and for redrawing every time the game state or the @@ -1333,7 +1340,7 @@ ignored. \S{backend-print-size} \cw{print_size()} -\c void (*print_size)(game_params *params, float *x, float *y); +\c void (*print_size)(const game_params *params, float *x, float *y); This function is passed a \c{game_params} structure and a tile size. It returns, in \c{*x} and \c{*y}, the preferred size in @@ -1344,7 +1351,7 @@ called. \S{backend-print} \cw{print()} -\c void (*print)(drawing *dr, game_state *state, int tilesize); +\c void (*print)(drawing *dr, const game_state *state, int tilesize); This function is called when a puzzle is to be printed out on paper. It should use the drawing API functions (see \k{drawing}) to print @@ -1419,7 +1426,7 @@ 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); +\c int (*can_format_as_text_now)(const 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 @@ -1445,7 +1452,7 @@ the game can be copied to the clipboard. Only the actual visible \S{backend-text-format} \cw{text_format()} -\c char *(*text_format)(game_state *state); +\c char *(*text_format)(const game_state *state); This function is passed a \c{game_state}, and returns a newly allocated C string containing an ASCII representation of that game @@ -1486,7 +1493,7 @@ called and need not do anything. \S{backend-timing-state} \cw{timing_state()} -\c int (*timing_state)(game_state *state, game_ui *ui); +\c int (*timing_state)(const game_state *state, game_ui *ui); This function is passed the current \c{game_state} and the local \c{game_ui}; it returns \cw{TRUE} if the game timer should currently @@ -1609,10 +1616,6 @@ should use it if they're not Mines; if you think you need to use it, think again repeatedly in the hope of finding a better way to do whatever it was you needed to do. -If a front end wants to be notified when this happens, it can ask the -midend to do so by calling \cw{midend_request_desc_changes()}; see -\k{midend-request-desc-changes}. - \C{drawing} The drawing API The back end function \cw{redraw()} (\k{backend-redraw}) is required @@ -2816,6 +2819,22 @@ 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-reset-tilesize} \cw{midend_reset_tilesize()} + +\c void midend_reset_tilesize(midend *me); + +This function resets the midend's preferred tile size to that of the +standard puzzle. + +As discussed in \k{midend-size}, puzzle resizes are typically +'sticky', in that once the user has dragged the puzzle to a different +window size, the resulting tile size will be remembered and used when +the puzzle configuration changes. If you \e{don't} want that, e.g. if +you want to provide a command to explicitly reset the puzzle size back +to its default, then you can call this just before calling +\cw{midend_size()} (which, in turn, you would probably call with +\c{user_size} set to \cw{FALSE}). + \H{midend-new-game} \cw{midend_new_game()} \c void midend_new_game(midend *me); @@ -3252,7 +3271,7 @@ place. \c void *rctx); This function examines a serialised midend stream, of the same kind -used by \cw{midend_serialise()} and \cw{midendd_deserialise()}, and +used by \cw{midend_serialise()} and \cw{midend_deserialise()}, and returns the \cw{name} field of the game back end from which it was saved. @@ -3274,17 +3293,18 @@ message (which does not need freeing at all). accept or return a pointer to a midend. You'd probably call it just \e{before} deciding what kind of midend you wanted to instantiate.) -\H{midend-request-desc-changes} \cw{midend_request_desc_changes()} +\H{midend-request-id-changes} \cw{midend_request_id_changes()} -\c void midend_request_desc_changes(midend *me, -\c void (*notify)(void *), void *ctx); +\c void midend_request_id_changes(midend *me, +\c void (*notify)(void *), void *ctx); This function is called by the front end to request notification by -the mid-end when a puzzle supersedes its game description (see -\k{backend-supersede}). After this function is called, any call to -\cw{midend_supersede_game_desc()} by the back end will cause the -mid-end to call \cw{notify(ctx)} after the game description is -changed. +the mid-end when the current game IDs (either descriptive or +random-seed) change. This can occur as a result of keypresses ('n' for +New Game, for example) or when a puzzle supersedes its game +description (see \k{backend-supersede}). After this function is +called, any change of the game ids will cause the mid-end to call +\cw{notify(ctx)} after the change. This is for use by puzzles which want to present the game description to the user constantly (e.g. as an HTML hyperlink) instead of only