1224
1224
to achieve this, its \cw{flash_length()} function has to store a
1225
1225
flag in the \c{game_ui} to indicate which flash type is required.)
1227
\S{backend-status} \cw{status()}
1229
\c int (*status)(game_state *state);
1231
This function returns a status value indicating whether the current
1232
game is still in play, or has been won, or has been conclusively lost.
1233
The mid-end uses this to implement \cw{midend_status()}
1234
(\k{midend-status}).
1236
The return value should be +1 if the game has been successfully
1237
solved. If the game has been lost in a situation where further play is
1238
unlikely, the return value should be -1. If neither is true (so play
1239
is still ongoing), return zero.
1241
Front ends may wish to use a non-zero status as a cue to proactively
1242
offer the option of starting a new game. Therefore, back ends should
1243
not return -1 if the game has been \e{technically} lost but undoing
1244
and continuing is still a realistic possibility.
1246
(For instance, games with hidden information such as Guess or Mines
1247
might well return a non-zero status whenever they reveal the solution,
1248
whether or not the player guessed it correctly, on the grounds that a
1249
player would be unlikely to hide the solution and continue playing
1250
after the answer was spoiled. On the other hand, games where you can
1251
merely get into a dead end such as Same Game or Inertia might choose
1252
to return 0 in that situation, on the grounds that the player would
1253
quite likely press Undo and carry on playing.)
1227
1255
\S{backend-redraw} \cw{redraw()}
1229
1257
\c void (*redraw)(drawing *dr, game_drawstate *ds,
3096
3124
\cw{activate_timer()} to be called from within a call to this
3127
\H{midend-status} \cw{midend_status()}
3129
\c int midend_status(midend *me);
3131
This function returns +1 if the midend is currently displaying a game
3132
in a solved state, -1 if the game is in a permanently lost state, or 0
3133
otherwise. This function just calls the back end's \cw{status()}
3134
function. Front ends may wish to use this as a cue to proactively
3135
offer the option of starting a new game.
3137
(See \k{backend-status} for more detail about the back end's
3138
\cw{status()} function and discussion of what should count as which
3141
\H{midend-can-undo} \cw{midend_can_undo()}
3143
\c int midend_can_undo(midend *me);
3145
Returns \cw{TRUE} if the midend is currently in a state where the undo
3146
operation is meaningful (i.e. at least one position exists on the undo
3147
chain before the present one). Front ends may wish to use this to
3148
visually activate and deactivate an undo button.
3150
\H{midend-can-redo} \cw{midend_can_redo()}
3152
\c int midend_can_redo(midend *me);
3154
Returns \cw{TRUE} if the midend is currently in a state where the redo
3155
operation is meaningful (i.e. at least one position exists on the redo
3156
chain after the present one). Front ends may wish to use this to
3157
visually activate and deactivate a redo button.
3099
3159
\H{midend-serialise} \cw{midend_serialise()}
3101
3161
\c void midend_serialise(midend *me,
added
removed
devel.but
