Since we've changed the semantics of the `expand' argument to midend_size(),

change the name. Also document the new semantics.

[originally from svn r7369]

diff --git a/devel.but b/devel.but
index 096aa1243245e01643c25f8746de7e677d04d565..cf06656db60c470186c29a19556d4dfa41bdb02d 100644 (file)
--- a/devel.but
+++ b/devel.but
@@ -2483,7 +2483,7 @@ when finished with by passing it to the game's own
 
 \H{midend-size} \cw{midend_size()}
 
-\c void midend_size(midend *me, int *x, int *y, int expand);
+\c void midend_size(midend *me, int *x, int *y, int user_size);
 
 Tells the mid-end to figure out its window size.
 
@@ -2498,18 +2498,27 @@ course up to the front end to adjust this for any additional window
 furniture such as menu bars and window borders, if necessary. The
 status bar is also not included in this size.)
 
-If \c{expand} is set to \cw{FALSE}, then the game's tile size will
-never go over its preferred one. This is the recommended approach
-when opening a new window at default size: the game will use its
-preferred size unless it has to use a smaller one to fit on the
-screen.
-
-If \c{expand} is set to \cw{TRUE}, the mid-end will pick a tile size
-which approximates the input size \e{as closely as possible}, and
-will go over the game's preferred tile size if necessary to achieve
-this. Use this option if you want your front end to support dynamic
-resizing of the puzzle window with automatic scaling of the puzzle
-to fit.
+Use \c{user_size} to indicate whether \c{*x} and \c{*y} are a
+requested size, or just a maximum size.
+
+If \c{user_size} is set to \cw{TRUE}, the mid-end will treat the
+input size as a request, and will pick a tile size which
+approximates it \e{as closely as possible}, going over the game's
+preferred tile size if necessary to achieve this. The mid-end will
+also use the resulting tile size as its preferred one until further
+notice, on the assumption that this size was explicitly requested
+by the user. Use this option if you want your front end to support
+dynamic resizing of the puzzle window with automatic scaling of the
+puzzle to fit.
+
+If \c{user_size} is set to \cw{FALSE}, then the game's tile size
+will never go over its preferred one, although it may go under in
+order to fit within the maximum bounds specified by \c{*x} and
+\c{*y}. This is the recommended approach when opening a new window
+at default size: the game will use its preferred size unless it has
+to use a smaller one to fit on the screen. If the tile size is
+shrunk for this reason, the change will not persist; if a smaller
+grid is subsequently chosen, the tile size will recover.
 
 The mid-end will try as hard as it can to return a size which is
 less than or equal to the input size, in both dimensions. In extreme
@@ -2529,7 +2538,7 @@ creatively.
 If your platform has no limit on window size (or if you're planning
 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{expand} flag, though!
+that \e{and} set the \c{user_size} flag, though!
 
 \H{midend-new-game} \cw{midend_new_game()}
 

diff --git a/midend.c b/midend.c
index d0bc950490871e813056a41dc5191a534ff4b8bc..250a479e3a59a952582f9b965de88fc7ca745f48 100644 (file)
--- a/midend.c
+++ b/midend.c
@@ -212,7 +212,7 @@ static void midend_size_new_drawstate(midend *me)
     }
 }
 
-void midend_size(midend *me, int *x, int *y, int expand)
+void midend_size(midend *me, int *x, int *y, int user_size)
 {
     int min, max;
     int rx, ry;
@@ -230,11 +230,14 @@ void midend_size(midend *me, int *x, int *y, int expand)
 
     /*
      * Find the tile size that best fits within the given space. If
-     * `expand' is TRUE, we must actually find the _largest_ such
-     * tile size; otherwise, we bound above at the game's preferred
-     * tile size.
+     * `user_size' is TRUE, we must actually find the _largest_ such
+     * tile size, in order to get as close to the user's explicit
+     * request as possible; otherwise, we bound above at the game's
+     * preferred tile size, so that the game gets what it wants
+     * provided that this doesn't break the constraint from the
+     * front-end (which is likely to be a screen size or similar).
      */
-    if (expand) {
+    if (user_size) {
        max = 1;
        do {
            max *= 2;
@@ -264,7 +267,8 @@ void midend_size(midend *me, int *x, int *y, int expand)
      */
 
     me->tilesize = min;
-    if (expand)
+    if (user_size)
+        /* If the user requested a change in size, make it permanent. */
         me->preferred_tilesize = me->tilesize;
     midend_size_new_drawstate(me);
     *x = me->winwidth;

diff --git a/puzzles.h b/puzzles.h
index a8f82a2006a4440998511a9d3186ca499701687a..37857725f6ad62b9cf2c657f2a690121097b9d5e 100644 (file)
--- a/puzzles.h
+++ b/puzzles.h
@@ -219,7 +219,7 @@ midend *midend_new(frontend *fe, const game *ourgame,
 void midend_free(midend *me);
 void midend_set_params(midend *me, game_params *params);
 game_params *midend_get_params(midend *me);
-void midend_size(midend *me, int *x, int *y, int expand);
+void midend_size(midend *me, int *x, int *y, int user_size);
 void midend_new_game(midend *me);
 void midend_restart_game(midend *me);
 void midend_stop_anim(midend *me);

diff --git a/windows.c b/windows.c
index 1117adeab929eb8b20ecdb9e1810f1d59788690d..9863de4746235eb343f068e693c8f1fdb7b266b4 100644 (file)
--- a/windows.c
+++ b/windows.c
@@ -1312,7 +1312,7 @@ static void get_menu_size(HWND wh, RECT *r)
 
 static int check_window_resize(frontend *fe, int cx, int cy,
                                int *px, int *py,
-                               int *wx, int *wy, int expand)
+                               int *wx, int *wy, int resize)
 {
     RECT r;
     int x, y, sy = get_statusbar_height(fe), changed = 0;
@@ -1325,7 +1325,7 @@ static int check_window_resize(frontend *fe, int cx, int cy,
      * See if we actually got the window size we wanted, and adjust
      * the puzzle size if not.
      */
-    midend_size(fe->me, &x, &y, expand);
+    midend_size(fe->me, &x, &y, resize);
     if (x != cx || y != cy) {
         /*
          * Resize the window, now we know what size we _really_