Add Context.new_console method.

Examples have been updated to use the new method, the older way to do
this has been deprecated.

Author: HexDecimal

CHANGELOG.rst

@@ -8,6 +8,12 @@ v2.0.0
 
 Unreleased
 ------------------
+Added
+ - New context method `Context.new_console`.
+
+Deprecated
+ - `Context.recommended_console_size` has been replaced with
+   `Context.new_console`.
 
 11.17.0 - 2020-10-30
 --------------------

docs/tcod/getting-started.rst

@@ -61,7 +61,7 @@ Dynamically-sized console
 
 The next example shows a more advanced setup.  A maximized window is created
 and the console is dynamically scaled to fit within it.  If the window is
-resized then the console will be replaced by a new dynamically sized console.
+resized then the console will be resized to match it.
 
 Because a tileset wasn't manually loaded in this example an OS dependent
 fallback font will be used.  This is useful for prototyping but it's not
@@ -70,12 +70,17 @@ platforms.
 
 The `integer_scaling` parameter to :any:`Context.present` prevents the console
 from being slightly stretched, since the console will rarely be the prefect
-size a small border will exist.
+size a small border will exist.  This border is black by default but can be
+changed to another color.
 
 You'll need to consider things like the console being too small for your code
 to handle or the tiles being small compared to an extra large monitor
-resolution.  :any:`Context.recommended_console_size` can be given a minimum
-size that it will never go below.
+resolution.  :any:`Context.new_console` can be given a minimum size that it
+will never go below.
+
+You can call :any:`Context.new_console` every frame or only when the window
+is resized.  This example creates a new console every frame instead of
+clearing the console every frame and replacing it only on resizing the window.
 
 Example::
 
@@ -91,10 +96,8 @@ Example::
         with tcod.context.new(  # New window with pixel resolution of width×height.
             width=WIDTH, height=HEIGHT, sdl_window_flags=FLAGS
         ) as context:
-            # Create the console based on the context.
-            console = tcod.Console(*context.recommended_console_size())
             while True:
-                console.clear()
+                console = context.new_console()
                 console.print(0, 0, "Hello World")
                 context.present(console, integer_scaling=True)
 
@@ -104,8 +107,7 @@ Example::
                     if event.type == "QUIT":
                         raise SystemExit()
                     if event.type == "WINDOWRESIZED":
-                        # Replace the console with one that fits the new resolution.
-                        console = tcod.Console(*context.recommended_console_size())
+                        pass  # The next call to context.new_console may return a different size.
 
 
     if __name__ == "__main__":

examples/eventget.py

@@ -23,7 +23,7 @@ def main() -> None:
     with tcod.context.new(
         width=WIDTH, height=HEIGHT, sdl_window_flags=FLAGS
     ) as context:
-        console = tcod.Console(*context.recommended_console_size())
+        console = context.new_console()
         while True:
             # Display all event items.
             console.clear()
@@ -42,7 +42,7 @@ def main() -> None:
                 if event.type == "QUIT":
                     raise SystemExit()
                 if event.type == "WINDOWRESIZED":
-                    console = tcod.Console(*context.recommended_console_size())
+                    console = context.new_console()
                 if event.type == "MOUSEMOTION":
                     motion_desc = str(event)
                 else:

libtcod

@@ -53,7 +53,7 @@
 from typing import Any, Iterable, List, Optional, Tuple
 
 import tcod
-from tcod._internal import _check, _check_warn, pending_deprecate
+from tcod._internal import _check, _check_warn, pending_deprecate, deprecate
 from tcod.loader import ffi, lib
 import tcod.event
 import tcod.tileset
@@ -263,25 +263,61 @@ def change_tileset(self, tileset: Optional[tcod.tileset.Tileset]) -> None:
             )
         )
 
-    def recommended_console_size(
-        self, min_columns: int = 1, min_rows: int = 1
-    ) -> Tuple[int, int]:
-        """Return the recommended (columns, rows) of a console for this
-        context.
+    def new_console(
+        self,
+        min_columns: int = 1,
+        min_rows: int = 1,
+        magnification: float = 1.0,
+    ) -> tcod.console.Console:
+        """Return a new console sized for this context.
 
-        The times where it's the most useful to call this method are:
+        `min_columns` and `min_rows` are the minimum size to use for the new
+        console.
+
+        `magnification` determines the apparent size of the tiles on the output
+        display.  A `magnification` larger then 1.0 will output smaller
+        consoles, which will show as larger tiles when presented.
+        `magnification` must be greater than zero.
+
+        The times where it is the most useful to call this method are:
 
         * After the context is created, even if the console was given a
           specific size.
         * After the :any:`change_tileset` method is called.
         * After any window resized event, or any manual resizing of the window.
 
+        .. versionadded:: 11.18
+        """
+        if magnification < 0:
+            raise ValueError(
+                "Magnification must be greater than zero. (Got %f)"
+                % magnification
+            )
+        size = ffi.new("int[2]")
+        _check(
+            lib.TCOD_context_recommended_console_size(
+                self._context_p, magnification, size, size + 1
+            )
+        )
+        width, height = max(min_columns, size[0]), max(min_rows, size[1])
+        return tcod.console.Console(width, height)
+
+    @deprecate("This method has been replaced by Context.new_console.")
+    def recommended_console_size(
+        self, min_columns: int = 1, min_rows: int = 1
+    ) -> Tuple[int, int]:
+        """Return the recommended (columns, rows) of a console for this
+        context.
+
         `min_columns`, `min_rows` are the lowest values which will be returned.
+
+        .. deprecated::
+            This method has been replaced by :any:`Context.new_console`.
         """
         with ffi.new("int[2]") as size:
             _check(
                 lib.TCOD_context_recommended_console_size(
-                    self._context_p, size, size + 1
+                    self._context_p, 1.0, size, size + 1
                 )
             )
             return max(min_columns, size[0]), max(min_rows, size[1])