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]

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.
+Use \c{user_size} to indicate whether \c{*x} and \c{*y} are a
+requested size, or just a maximum size.
 
-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.
+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()}
 

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;

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);

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_