52
52
a small API for other modules to call, mostly of drawing functions for
53
53
games to use when drawing their graphics. The drawing API is documented
54
54
in chapter 3; the other miscellaneous front end API functions are
55
documented in section 4.26.
55
documented in section 4.27.
142
142
1.5. Structure of this guide
143
143
----------------------------
145
There are a number of function call interfaces within Puzzles, and
146
this guide will discuss each one in a chapter of its own. After that,
147
(chapter 6) discusses how to design new games, with some general design
145
There are a number of function call interfaces within Puzzles, and this
146
guide will discuss each one in a chapter of its own. After that, chapter
147
6 discusses how to design new games, with some general design thoughts
150
150
2. Interface to the back end
151
151
----------------------------
1094
1094
The second parameter passed to this function is a front end handle.
1095
1095
The only things it is permitted to do with this handle are to call the
1096
front-end function called frontend_default_colour() (see section 4.31)
1096
front-end function called frontend_default_colour() (see section 4.32)
1097
1097
or the utility function called game_mkhighlight() (see section 5.4.7).
1098
1098
(The latter is a wrapper on the former, so front end implementors only
1099
1099
need to provide frontend_default_colour().) This allows colours() to
1131
1131
mid-end will handle them internally and never consult this function at
1132
1132
all. State changes as a result of Solve operations are also not animated
1133
1133
by default, although you can change this for a particular game by
1134
setting a flag in `flags' (section 2.10.6).
1134
setting a flag in `flags' (section 2.10.7).
1136
1136
The function is also passed a pointer to the local `game_ui'. It may
1137
1137
refer to information in here to help with its decision (see section
1329
1329
2.10. Miscellaneous
1330
1330
-------------------
1332
2.10.1. `can_format_as_text'
1333
----------------------------
1332
2.10.1. `can_format_as_text_ever'
1333
---------------------------------
1335
int can_format_as_text;
1335
int can_format_as_text_ever;
1337
1337
This boolean field is TRUE if the game supports formatting a game state
1338
1338
as ASCII text (typically ASCII art) for copying to the clipboard and
1339
1339
pasting into other applications. If it is FALSE, front ends will not
1340
1340
offer the `Copy' command at all.
1342
If this field is FALSE, the function text_format() (section 2.10.2) is
1343
not expected to do anything at all.
1345
2.10.2. text_format()
1342
If this field is TRUE, the game does not necessarily have to support
1343
text formatting for _all_ games: e.g. a game which can be played on
1344
a square grid or a triangular one might only support copy and paste
1345
for the former, because triangular grids in ASCII art are just too
1348
If this field is FALSE, the functions can_format_as_text_now() (section
1349
2.10.2) and text_format() (section 2.10.3) are never called.
1351
2.10.2. `can_format_as_text_now()'
1352
----------------------------------
1354
int (*can_format_as_text_now)(game_params *params);
1356
This function is passed a `game_params' and returns a boolean, which is
1357
TRUE if the game can support ASCII text output for this particular game
1358
type. If it returns FALSE, front ends will grey out or otherwise disable
1361
Games may enable and disable the copy-and-paste function for different
1362
game _parameters_, but are currently constrained to return the same
1363
answer from this function for all game _states_ sharing the same
1364
parameters. In other words, the `Copy' function may enable or disable
1365
itself when the player changes game preset, but will never change during
1366
play of a single game or when another game of exactly the same type is
1369
This function should not take into account aspects of the game
1370
parameters which are not encoded by encode_params() (section 2.3.3)
1371
when the `full' parameter is set to FALSE. Such parameters will not
1372
necessarily match up between a call to this function and a subsequent
1373
call to text_format() itself. (For instance, game _difficulty_ should
1374
not affect whether the game can be copied to the clipboard. Only the
1375
actual visible _shape_ of the game can affect that.)
1377
2.10.3. text_format()
1346
1378
---------------------
1348
1380
char *(*text_format)(game_state *state);
1351
1383
string containing an ASCII representation of that game state. It is used
1352
1384
to implement the `Copy' operation in many front ends.
1354
This function should only be called if the back end field
1355
`can_format_as_text' (section 2.10.1) is TRUE.
1386
This function will only ever be called if the back end field
1387
`can_format_as_text_ever' (section 2.10.1) is TRUE _and_ the function
1388
can_format_as_text_now() (section 2.10.2) has returned TRUE for the
1389
currently selected game parameters.
1357
1391
The returned string may contain line endings (and will probably want
1358
1392
to), using the normal C internal `\n' convention. For consistency
1455
1489
If a back end needs random numbers at some point during normal play, it
1456
1490
can create a fresh `random_state' by first calling `get_random_seed'
1457
(section 4.27) and then passing the returned seed data to random_new().
1491
(section 4.28) and then passing the returned seed data to random_new().
1459
1493
This is likely not to be what you want. If a puzzle needs randomness in
1460
1494
the middle of play, it's likely to be more sensible to store some sort
2457
2491
Allocates and returns a new mid-end structure.
2459
2493
The `fe' argument is stored in the mid-end. It will be used when calling
2460
back to functions such as activate_timer() (section 4.28), and will be
2494
back to functions such as activate_timer() (section 4.29), and will be
2461
2495
passed on to the back end function colours() (section 2.8.6).
2463
2497
The parameters `drapi' and `drhandle' are passed to drawing_new()
2655
2696
responsible for doing it.
2657
2698
Calling this function is very likely to result in calls back to the
2658
front end's drawing API and/or activate_timer() (section 4.28).
2699
front end's drawing API and/or activate_timer() (section 4.29).
2701
The return value from midend_process_key() is non-zero, unless the
2702
effect of the keypress was to request termination of the program. A
2703
front end should shut down the puzzle in response to a zero return.
2660
2705
4.11. midend_colours()
2661
2706
----------------------
2677
2722
void midend_timer(midend *me, float tplus);
2679
If the mid-end has called activate_timer() (section 4.28) to request
2724
If the mid-end has called activate_timer() (section 4.29) to request
2680
2725
regular callbacks for purposes of animation or timing, this is the
2681
2726
function the front end should call on a regular basis. The argument
2682
2727
`tplus' gives the time, in seconds, since the last time either this
2835
2880
`params:description') describing the game currently active in the mid-
2836
2881
end. The returned string is dynamically allocated.
2838
4.21. midend_text_format()
2883
4.21. midend_can_format_as_text_now()
2884
-------------------------------------
2886
int midend_can_format_as_text_now(midend *me);
2888
Returns TRUE if the game code is capable of formatting puzzles of the
2889
currently selected game type as ASCII.
2891
If this returns FALSE, then midend_text_format() (section 4.22) will
2894
4.22. midend_text_format()
2839
2895
--------------------------
2841
2897
char *midend_text_format(midend *me);
2843
2899
Formats the current game's current state as ASCII text suitable for
2844
2900
copying to the clipboard. The returned string is dynamically allocated.
2846
You should not call this function if the game's `can_format_as_text'
2902
If the game's `can_format_as_text_ever' flag is FALSE, or if its
2903
can_format_as_text_now() function returns FALSE, then this function will
2849
2906
If the returned string contains multiple lines (which is likely), it
2850
2907
will use the normal C line ending convention (\n only). On platforms
2851
2908
which use a different line ending convention for data in the clipboard,
2852
2909
it is the front end's responsibility to perform the conversion.
2854
4.22. midend_solve()
2911
4.23. midend_solve()
2855
2912
--------------------
2857
2914
char *midend_solve(midend *me);
2888
2945
of times, with the first parameter (`ctx') equal to `wctx', and the
2889
2946
other two parameters pointing at a piece of the output string.
2891
4.24. midend_deserialise()
2948
4.25. midend_deserialise()
2892
2949
--------------------------
2894
2951
char *midend_deserialise(midend *me,
2928
2985
game it was for; any front end implementor who needs such a function can
2929
2986
probably be accommodated.)
2931
4.25. Direct reference to the back end structure by the front end
2988
4.26. Direct reference to the back end structure by the front end
2932
2989
-----------------------------------------------------------------
2934
2991
Although _most_ things the front end needs done should be done by
2945
3002
- fetching the `name' field to use in window titles and similar
2947
- reading the `can_configure', `can_solve' and `can_format_as_text'
2948
fields to decide whether to add those items to the menu bar or
3004
- reading the `can_configure', `can_solve' and
3005
`can_format_as_text_ever' fields to decide whether to add those
3006
items to the menu bar or equivalent
2951
3008
- reading the `winhelp_topic' field (Windows only)
2978
3035
by reaching into each game structure and looking at its `name'
2981
4.26. Mid-end to front-end calls
3038
4.27. Mid-end to front-end calls
2982
3039
--------------------------------
2984
3041
This section describes the small number of functions which a front end
2985
3042
must provide to be called by the mid-end or other standard utility
2988
4.27. get_random_seed()
3045
4.28. get_random_seed()
2989
3046
-----------------------
2991
3048
void get_random_seed(void **randseed, int *randseedsize);
3679
3736
pointer to the start of your return array, and three colour indices. It
3682
- call frontend_default_colour() (section 4.31) to fetch the front
3739
- call frontend_default_colour() (section 4.32) to fetch the front
3683
3740
end's default background colour
3685
3742
- alter the brightness of that colour if it's unsuitable
added
removed
HACKING
