Refactoring patch from Ben Hutchings: move all the Gtk resize code into one

[sgt/puzzles] / devel.but

diff --git a/devel.but b/devel.but
index 66413ec..096aa12 100644 (file)
--- a/devel.but
+++ b/devel.but
@@ -170,8 +170,8 @@ other miscellaneous functions. All of these are documented in
 
 There are a number of function call interfaces within Puzzles, and
 this guide will discuss each one in a chapter of its own. After
 
 There are a number of function call interfaces within Puzzles, and
 this guide will discuss each one in a chapter of its own. After

-that, there will be a section about how to design new games, with
-some general design thoughts and tips.
+that, (\k{writing}) discusses how to design new games, with some
+general design thoughts and tips.

 
 \C{backend} Interface to the back end
 
 
 \C{backend} Interface to the back end
 


@@ -193,7 +193,9 @@ end module builds a different puzzle.
 \b On platforms such as MacOS X and PalmOS, which build all the
 puzzles into a single monolithic binary, the game structure in each
 back end must have a different name, and there's a helper module
 \b On platforms such as MacOS X and PalmOS, which build all the
 puzzles into a single monolithic binary, the game structure in each
 back end must have a different name, and there's a helper module

-\c{list.c} which contains a complete list of those game structures.
+\c{list.c} (constructed automatically by the same Perl script that
+builds the \cw{Makefile}s) which contains a complete list of those
+game structures.

 
 On the latter type of platform, source files may assume that the
 preprocessor symbol \c{COMBINED} has been defined. Thus, the usual
 
 On the latter type of platform, source files may assume that the
 preprocessor symbol \c{COMBINED} has been defined. Thus, the usual


@@ -443,7 +445,7 @@ difficulty, since to describe a puzzle once generated it's
 sufficient to give the grid dimensions and the location and contents
 of the clue squares. (Indeed, one might very easily type in a puzzle
 out of a newspaper without \e{knowing} what its difficulty level is
 sufficient to give the grid dimensions and the location and contents
 of the clue squares. (Indeed, one might very easily type in a puzzle
 out of a newspaper without \e{knowing} what its difficulty level is

-in Solo's terminology.) Therefore. Solo's \cw{encode_params()} only
+in Solo's terminology.) Therefore, Solo's \cw{encode_params()} only

 encodes the difficulty level if \c{full} is set.
 
 \S{backend-decode-params} \cw{decode_params()}
 encodes the difficulty level if \c{full} is set.
 
 \S{backend-decode-params} \cw{decode_params()}


@@ -791,7 +793,7 @@ important enough to save. The location of the keyboard-controlled
 cursor, for example, can be reset to a default position on reloading
 the game without impacting the user experience. If the user should
 somehow manage to save a game while a mouse drag was in progress,
 cursor, for example, can be reset to a default position on reloading
 the game without impacting the user experience. If the user should
 somehow manage to save a game while a mouse drag was in progress,

-then discarding that mouse drag would be an outright \e{feature},
+then discarding that mouse drag would be an outright \e{feature}.

 
 A typical thing that \e{would} be worth encoding in this function is
 the Mines death counter: it's in the \c{game_ui} rather than the
 
 A typical thing that \e{would} be worth encoding in this function is
 the Mines death counter: it's in the \c{game_ui} rather than the


@@ -1104,7 +1106,7 @@ create a fresh drawstate.
 
 \S{backend-colours} \cw{colours()}
 
 
 \S{backend-colours} \cw{colours()}
 

-\c float *(*colours)(frontend *fe, game_state *state, int *ncolours);
+\c float *(*colours)(frontend *fe, int *ncolours);

 
 This function is responsible for telling the front end what colours
 the puzzle will need to draw itself.
 
 This function is responsible for telling the front end what colours
 the puzzle will need to draw itself.


@@ -1115,15 +1117,7 @@ array of three times that many \c{float}s, containing the red, green
 and blue components of each colour respectively as numbers in the
 range [0,1].
 
 and blue components of each colour respectively as numbers in the
 range [0,1].
 

-It is passed a sample \c{game_state} in case it needs one, although
-currently no puzzle does need this. (In fact, colours are not
-reallocated when the game parameters change or a new game is
-started, so you can't reliably use this \c{game_state} to allocate a
-different number of colours depending on the game. It is probably
-actually a mistake to rely on this parameter at all. I ought to
-either remove it or fix it; probably the former.)
-
-The final parameter passed to this function is a front end handle.
+The second parameter passed to this function is a front end handle.

 The only things it is permitted to do with this handle are to call
 the front-end function called \cw{frontend_default_colour()} (see
 \k{frontend-default-colour}) or the utility function called
 The only things it is permitted to do with this handle are to call
 the front-end function called \cw{frontend_default_colour()} (see
 \k{frontend-default-colour}) or the utility function called


@@ -1406,16 +1400,12 @@ 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)(void);
+\c int wants_statusbar;

 
 

-This function returns \cw{TRUE} if the puzzle has a use for a
+This boolean field is set to \cw{TRUE} if the puzzle has a use for a

 textual status line (to display score, completion status, currently
 active tiles, etc).
 
 textual status line (to display score, completion status, currently
 active tiles, etc).
 

-(This should probably be a static boolean field rather than a
-function. I don't remember why I did it this way. I probably ought
-to change it.)
-

 \S{backend-is-timed} \c{is_timed}
 
 \c int is_timed;
 \S{backend-is-timed} \c{is_timed}
 
 \c int is_timed;


@@ -1449,8 +1439,8 @@ the bitwise OR of some combination of the following:
 
 \dt \cw{BUTTON_BEATS(x,y)}
 
 
 \dt \cw{BUTTON_BEATS(x,y)}
 

-\dd Given any \cw{x} and \cw{y} from the set (\cw{LEFT_BUTTON},
-\cw{MIDDLE_BUTTON}, \cw{RIGHT_BUTTON}), this macro evaluates to a
+\dd Given any \cw{x} and \cw{y} from the set \{\cw{LEFT_BUTTON},
+\cw{MIDDLE_BUTTON}, \cw{RIGHT_BUTTON}\}, this macro evaluates to a

 bit flag which indicates that when buttons \cw{x} and \cw{y} are
 both pressed simultaneously, the mid-end should consider \cw{x} to
 have priority. (In the absence of any such flags, the mid-end will
 bit flag which indicates that when buttons \cw{x} and \cw{y} are
 both pressed simultaneously, the mid-end should consider \cw{x} to
 have priority. (In the absence of any such flags, the mid-end will


@@ -1466,6 +1456,26 @@ mid-end doesn't even bother calling \cw{anim_length()}
 each game. On the rare occasion that animated solve moves are
 actually required, you can set this flag.
 
 each game. On the rare occasion that animated solve moves are
 actually required, you can set this flag.
 

+\dt \cw{REQUIRE_RBUTTON}
+
+\dd This flag indicates that the puzzle cannot be usefully played
+without the use of mouse buttons other than the left one. On some
+PDA platforms, this flag is used by the front end to enable
+right-button emulation through an appropriate gesture. Note that a
+puzzle is not required to set this just because it \e{uses} the
+right button, but only if its use of the right button is critical to
+playing the game. (Slant, for example, uses the right button to
+cycle through the three square states in the opposite order from the
+left button, and hence can manage fine without it.)
+
+\dt \cw{REQUIRE_NUMPAD}
+
+\dd This flag indicates that the puzzle cannot be usefully played
+without the use of number-key input. On some PDA platforms it causes
+an emulated number pad to appear on the screen. Similarly to
+\cw{REQUIRE_RBUTTON}, a puzzle need not specify this simply if its
+use of the number keys is not critical.
+

 \H{backend-initiative} Things a back end may do on its own initiative
 
 This section describes a couple of things that a back end may choose
 \H{backend-initiative} Things a back end may do on its own initiative
 
 This section describes a couple of things that a back end may choose


@@ -1481,7 +1491,7 @@ the returned seed data to \cw{random_new()}.
 
 This is likely not to be what you want. If a puzzle needs randomness
 in the middle of play, it's likely to be more sensible to store some
 
 This is likely not to be what you want. If a puzzle needs randomness
 in the middle of play, it's likely to be more sensible to store some

-sort of random state within the \e{game_state}, so that the random
+sort of random state within the \c{game_state}, so that the random

 numbers are tied to the particular game state and hence the player
 can't simply keep undoing their move until they get numbers they
 like better.
 numbers are tied to the particular game state and hence the player
 can't simply keep undoing their move until they get numbers they
 like better.


@@ -1583,10 +1593,10 @@ manipulation.
 \e{Puzzles' redraw functions may assume that the surface they draw
 on is persistent}. It is the responsibility of every front end to
 preserve the puzzle's window contents in the face of GUI window
 \e{Puzzles' redraw functions may assume that the surface they draw
 on is persistent}. It is the responsibility of every front end to
 preserve the puzzle's window contents in the face of GUI window

-expose issues and similar. It is not permissible to request the back
-end redraw any part of a window that it has already drawn, unless
-something has actually changed as a result of making moves in the
-puzzle.
+expose issues and similar. It is not permissible to request that the
+back end redraw any part of a window that it has already drawn,
+unless something has actually changed as a result of making moves in
+the puzzle.

 
 Most front ends accomplish this by having the drawing routines draw
 on a stored bitmap rather than directly on the window, and copying
 
 Most front ends accomplish this by having the drawing routines draw
 on a stored bitmap rather than directly on the window, and copying


@@ -1875,6 +1885,11 @@ with the drawing API the property that it may only be called from
 within the back end redraw function, so this is as good a place as
 any to document it.)
 
 within the back end redraw function, so this is as good a place as
 any to document it.)
 

+The supplied text is filtered through the mid-end for optional
+rewriting before being passed on to the front end; the mid-end will
+prepend the current game time if the game is timed (and may in
+future perform other rewriting if it seems like a good idea).
+

 This function is for drawing only; it must never be called during
 printing.
 
 This function is for drawing only; it must never be called during
 printing.
 


@@ -2080,7 +2095,7 @@ structure called \c{drawing_api}. Each of the functions takes a
 a more useful type. Thus, a drawing \e{object} (\c{drawing *)}
 suitable for passing to the back end redraw or printing functions
 is constructed by passing a \c{drawing_api} and a \cq{void *} to the
 a more useful type. Thus, a drawing \e{object} (\c{drawing *)}
 suitable for passing to the back end redraw or printing functions
 is constructed by passing a \c{drawing_api} and a \cq{void *} to the

-function \cw{drawing_init()} (see \k{drawing-init}).
+function \cw{drawing_new()} (see \k{drawing-new}).

 
 \S{drawingapi-draw-text} \cw{draw_text()}
 
 
 \S{drawingapi-draw-text} \cw{draw_text()}
 


@@ -2126,8 +2141,8 @@ function; see \k{drawing-draw-circle}.
 
 \c void (*draw_update)(void *handle, int x, int y, int w, int h);
 
 
 \c void (*draw_update)(void *handle, int x, int y, int w, int h);
 

-This function behaves exactly like the back end \cw{draw_text()}
-function; see \k{drawing-draw-text}.
+This function behaves exactly like the back end \cw{draw_update()}
+function; see \k{drawing-draw-update}.

 
 An implementation of this API which only supports printing is
 permitted to define this function pointer to be \cw{NULL} rather
 
 An implementation of this API which only supports printing is
 permitted to define this function pointer to be \cw{NULL} rather


@@ -2179,19 +2194,9 @@ called unless drawing is attempted.
 This function behaves exactly like the back end \cw{status_bar()}
 function; see \k{drawing-status-bar}.
 
 This function behaves exactly like the back end \cw{status_bar()}
 function; see \k{drawing-status-bar}.
 

-Front ends implementing this function should not use the provided
-text directly; they should call \cw{midend_rewrite_statusbar()}
-(\k{midend-rewrite-statusbar}) to process it first.
-
-In a game which has a timer, this function is likely to be called
-every time the timer goes off, i.e. many times a second. It is
-therefore likely to be common that this function is called with
-precisely the same text as the last time it was called. Front ends
-may well wish to detect this common case and avoid bothering to do
-anything. If they do, however, they \e{must} perform this check on
-the value \e{returned} from \cw{midend_rewrite_statusbar()}, rather
-than the value passed in to it (because the mid-end will frequently
-update the status-bar timer without the back end's intervention).
+Front ends implementing this function need not worry about it being
+called repeatedly with the same text; the middleware code in
+\cw{status_bar()} will take care of this.

 
 Implementations of this API which do not provide drawing services
 may define this function pointer to be \cw{NULL}; it will never be
 
 Implementations of this API which do not provide drawing services
 may define this function pointer to be \cw{NULL}; it will never be


@@ -2282,7 +2287,7 @@ of the puzzle.
 
 Similarly, \c{ym} and \c{yc} specify the vertical position of the
 puzzle as a function of the page height: the page height times
 
 Similarly, \c{ym} and \c{yc} specify the vertical position of the
 puzzle as a function of the page height: the page height times

-\c{xm}, plus \c{xc} millimetres, equals the desired distance from
+\c{ym}, plus \c{yc} millimetres, equals the desired distance from

 the top of the page to the top of the puzzle.
 
 (This unwieldy mechanism is required because not all printing
 the top of the page to the top of the puzzle.
 
 (This unwieldy mechanism is required because not all printing


@@ -2363,15 +2368,23 @@ There are a small number of functions provided in \cw{drawing.c}
 which the front end needs to \e{call}, rather than helping to
 implement. They are described in this section.
 
 which the front end needs to \e{call}, rather than helping to
 implement. They are described in this section.
 

-\S{drawing-init} \cw{drawing_init()}
+\S{drawing-new} \cw{drawing_new()}

 
 

-\c drawing *drawing_init(const drawing_api *api, void *handle);
+\c drawing *drawing_new(const drawing_api *api, midend *me,
+\c                      void *handle);

 
 This function creates a drawing object. It is passed a
 \c{drawing_api}, which is a structure containing nothing but
 function pointers; and also a \cq{void *} handle. The handle is
 passed back to each function pointer when it is called.
 
 
 This function creates a drawing object. It is passed a
 \c{drawing_api}, which is a structure containing nothing but
 function pointers; and also a \cq{void *} handle. The handle is
 passed back to each function pointer when it is called.
 

+The \c{midend} parameter is used for rewriting the status bar
+contents: \cw{status_bar()} (see \k{drawing-status-bar}) has to call
+a function in the mid-end which might rewrite the status bar text.
+If the drawing object is to be used only for printing, or if the
+game is known not to call \cw{status_bar()}, this parameter may be
+\cw{NULL}.
+

 \S{drawing-free} \cw{drawing_free()}
 
 \c void drawing_free(drawing *dr);
 \S{drawing-free} \cw{drawing_free()}
 
 \c void drawing_free(drawing *dr);


@@ -2424,7 +2437,7 @@ calling back to functions such as \cw{activate_timer()}
 function \cw{colours()} (\k{backend-colours}).
 
 The parameters \c{drapi} and \c{drhandle} are passed to
 function \cw{colours()} (\k{backend-colours}).
 
 The parameters \c{drapi} and \c{drhandle} are passed to

-\cw{drawing_init()} (\k{drawing-init}) to construct a drawing object
+\cw{drawing_new()} (\k{drawing-new}) to construct a drawing object

 which will be passed to the back end function \cw{redraw()}
 (\k{backend-redraw}). Hence, all drawing-related function pointers
 defined in \c{drapi} can expect to be called with \c{drhandle} as
 which will be passed to the back end function \cw{redraw()}
 (\k{backend-redraw}). Hence, all drawing-related function pointers
 defined in \c{drapi} can expect to be called with \c{drhandle} as


@@ -2810,32 +2823,6 @@ The front end can expect its drawing API and/or
 \cw{activate_timer()} to be called from within a call to this
 function.
 
 \cw{activate_timer()} to be called from within a call to this
 function.
 

-\H{midend-rewrite-statusbar} \cw{midend_rewrite_statusbar()}
-
-\c char *midend_rewrite_statusbar(midend *me, char *text);
-
-The front end should call this function from within
-\cw{status_bar()} (\k{drawing-status-bar}). It should be passed the
-string that was passed by the back end to \cw{status_bar()}; it will
-return a dynamically allocated string adjusted by the mid-end.
-(Specifically, adjusted to include the timer if the game is a timed
-one.) The returned value should be placed in the actual status bar
-in place of the input value.
-
-(This is a nasty piece of architecture; I apologise for it. It would
-seem a lot more pleasant to have the back end pass its status bar
-text to the mid-end, which in turn would rewrite it and pass it on
-to the front end, so that each front end needed to do nothing
-strange. The main reason why I haven't done this is because it means
-the back end redraw function would need to be passed a mid-end
-pointer \e{as well} as a front end pointer, which seemed like an
-excessive proliferation of opaque handles. The only way to avoid
-that proliferation would be to have all the drawing API functions
-also gatewayed through the mid-end, and that seemed like an
-excessive proliferation of wrapper functions. The current setup
-isn't nice, but it has minimal impact and I'm unconvinced that any
-of the other options are an improvement.)
-

 \H{midend-serialise} \cw{midend_serialise()}
 
 \c void midend_serialise(midend *me,
 \H{midend-serialise} \cw{midend_serialise()}
 
 \c void midend_serialise(midend *me,


@@ -2951,9 +2938,10 @@ base), then there will be two global variables defined:
 \c extern const int gamecount;
 
 \c{gamelist} will be an array of \c{gamecount} game structures,
 \c extern const int gamecount;
 
 \c{gamelist} will be an array of \c{gamecount} game structures,

-declared in the source module \c{list.c}. The application should
-search that array for the game it wants, probably by reaching into
-each game structure and looking at its \c{name} field.
+declared in the automatically constructed source module \c{list.c}.
+The application should search that array for the game it wants,
+probably by reaching into each game structure and looking at its
+\c{name} field.

 
 }
 
 
 }
 


@@ -3532,10 +3520,10 @@ sensibly fit anywhere else.
 \S{utils-truefalse} \cw{TRUE} and \cw{FALSE}
 
 The main Puzzles header file defines the macros \cw{TRUE} and
 \S{utils-truefalse} \cw{TRUE} and \cw{FALSE}
 
 The main Puzzles header file defines the macros \cw{TRUE} and

-\cw{FALSE}, which are used throughout the code in place of 0 and 1
-to indicate that the values are in a boolean context. For code base
-consistency, I'd prefer it if submissions of new code followed this
-convention as well.
+\cw{FALSE}, which are used throughout the code in place of 1 and 0
+(respectively) to indicate that the values are in a boolean context.
+For code base consistency, I'd prefer it if submissions of new code
+followed this convention as well.

 
 \S{utils-maxmin} \cw{max()} and \cw{min()}
 
 
 \S{utils-maxmin} \cw{max()} and \cw{min()}
 


@@ -3746,6 +3734,11 @@ compile it conveniently. \e{Do not edit the Makefiles}: they are
 created automatically by the script \c{mkfiles.pl}, from the file
 called \c{Recipe}. Edit \c{Recipe}, and then re-run \c{mkfiles.pl}.
 
 created automatically by the script \c{mkfiles.pl}, from the file
 called \c{Recipe}. Edit \c{Recipe}, and then re-run \c{mkfiles.pl}.
 

+Also, don't forget to add your puzzle to \c{list.c}: if you don't,
+then it will still run fine on platforms which build each puzzle
+separately, but Mac OS X and other monolithic platforms will not
+include your new puzzle in their single binary.
+

 Once your source file is building, you can move on to the fun bit.
 
 \S{writing-generation} Puzzle generation
 Once your source file is building, you can move on to the fun bit.
 
 \S{writing-generation} Puzzle generation