1456
1456
each game. On the rare occasion that animated solve moves are
1457
1457
actually required, you can set this flag.
1459
\dt \cw{REQUIRE_RBUTTON}
1461
\dd This flag indicates that the puzzle cannot be usefully played
1462
without the use of mouse buttons other than the left one. On some
1463
PDA platforms, this flag is used by the front end to enable
1464
right-button emulation through an appropriate gesture. Note that a
1465
puzzle is not required to set this just because it \e{uses} the
1466
right button, but only if its use of the right button is critical to
1467
playing the game. (Slant, for example, uses the right button to
1468
cycle through the three square states in the opposite order from the
1469
left button, and hence can manage fine without it.)
1471
\dt \cw{REQUIRE_NUMPAD}
1473
\dd This flag indicates that the puzzle cannot be usefully played
1474
without the use of number-key input. On some PDA platforms it causes
1475
an emulated number pad to appear on the screen. Similarly to
1476
\cw{REQUIRE_RBUTTON}, a puzzle need not specify this simply if its
1477
use of the number keys is not critical.
1459
1479
\H{backend-initiative} Things a back end may do on its own initiative
1461
1481
This section describes a couple of things that a back end may choose
2122
2142
\c void (*draw_update)(void *handle, int x, int y, int w, int h);
2124
2144
This function behaves exactly like the back end \cw{draw_update()}
2125
function; see \k{drawing-draw-text}.
2145
function; see \k{drawing-draw-update}.
2127
2147
An implementation of this API which only supports printing is
2128
2148
permitted to define this function pointer to be \cw{NULL} rather
2464
2484
\H{midend-size} \cw{midend_size()}
2466
\c void midend_size(midend *me, int *x, int *y, int expand);
2486
\c void midend_size(midend *me, int *x, int *y, int user_size);
2468
2488
Tells the mid-end to figure out its window size.
2478
2498
furniture such as menu bars and window borders, if necessary. The
2479
2499
status bar is also not included in this size.)
2481
If \c{expand} is set to \cw{FALSE}, then the game's tile size will
2482
never go over its preferred one. This is the recommended approach
2483
when opening a new window at default size: the game will use its
2484
preferred size unless it has to use a smaller one to fit on the
2487
If \c{expand} is set to \cw{TRUE}, the mid-end will pick a tile size
2488
which approximates the input size \e{as closely as possible}, and
2489
will go over the game's preferred tile size if necessary to achieve
2490
this. Use this option if you want your front end to support dynamic
2491
resizing of the puzzle window with automatic scaling of the puzzle
2501
Use \c{user_size} to indicate whether \c{*x} and \c{*y} are a
2502
requested size, or just a maximum size.
2504
If \c{user_size} is set to \cw{TRUE}, the mid-end will treat the
2505
input size as a request, and will pick a tile size which
2506
approximates it \e{as closely as possible}, going over the game's
2507
preferred tile size if necessary to achieve this. The mid-end will
2508
also use the resulting tile size as its preferred one until further
2509
notice, on the assumption that this size was explicitly requested
2510
by the user. Use this option if you want your front end to support
2511
dynamic resizing of the puzzle window with automatic scaling of the
2514
If \c{user_size} is set to \cw{FALSE}, then the game's tile size
2515
will never go over its preferred one, although it may go under in
2516
order to fit within the maximum bounds specified by \c{*x} and
2517
\c{*y}. This is the recommended approach when opening a new window
2518
at default size: the game will use its preferred size unless it has
2519
to use a smaller one to fit on the screen. If the tile size is
2520
shrunk for this reason, the change will not persist; if a smaller
2521
grid is subsequently chosen, the tile size will recover.
2494
2523
The mid-end will try as hard as it can to return a size which is
2495
2524
less than or equal to the input size, in both dimensions. In extreme
2509
2538
If your platform has no limit on window size (or if you're planning
2510
2539
to use scroll bars for large puzzles), you can pass dimensions of
2511
2540
\cw{INT_MAX} as input to this function. You should probably not do
2512
that \e{and} set the \c{expand} flag, though!
2541
that \e{and} set the \c{user_size} flag, though!
2514
2543
\H{midend-new-game} \cw{midend_new_game()}