X-Git-Url: https://git.distorted.org.uk/~mdw/sgt/puzzles/blobdiff_plain/bcc26b703eb58da787619f10e29928bf43954037..HEAD:/devel.but diff --git a/devel.but b/devel.but index 5e9ff22..970a73a 100644 --- a/devel.but +++ b/devel.but @@ -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, -\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 @@ -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. +(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 @@ -1224,27 +1229,33 @@ 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.) -\S{backend-is-solved} \cw{is_solved()} +\S{backend-status} \cw{status()} + +\c int (*status)(game_state *state); -\c int (*is_solved)(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}). -This function returns \cw{TRUE} if the game represented by \cw{state} -is currently in a solved state. The mid-end uses this to implement -\cw{midend_is_solved()} (\k{midend-is-solved}). +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 this as a cue to proactively offer the -option of starting a new game. Therefore, back ends should consider -returning TRUE in situations where the game is \e{lost} as well as -won, if losing makes it unlikely that the player would play on. +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 set this flag 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 not to, on -the grounds that the player would quite likely press Undo and carry on -playing.) +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()} @@ -1455,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.) -\S{backend-wants-statusbar} \cw{wants_statusbar()} +\S{backend-wants-statusbar} \cw{wants_statusbar} \c int wants_statusbar; @@ -2708,14 +2719,12 @@ without closing the window...) Frees a mid-end structure and all its associated data. -\H{midend-tilesize} +\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} +current puzzle (\k{backend-preferred-tilesize}). \H{midend-set-params} \cw{midend_set_params()} @@ -2800,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! +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); @@ -2836,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 -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()} @@ -2847,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 -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()} @@ -2858,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 -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()} @@ -3116,20 +3131,22 @@ user. 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-is-solved} \cw{midend_is_solved()} +\H{midend-status} \cw{midend_status()} -\c int midend_is_solved(midend *me); +\c int midend_status(midend *me); -This function returns \cw{TRUE} if the midend is currently displaying -a game in a solved state, according to the back end's \cw{is_solved()} +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-is-solved} for more detail about the back end's -\cw{is_solved()} function and discussion of what should count as -\q{solved} anyway). +(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()}