Add canvas.set_update_mode() (#83)

Author: almarklein

docs/api.rst

@@ -1,11 +1,12 @@
 API
 ===
 
-These are the base classes that make up the rendercanvas API:
+These are the classes that make up the rendercanvas API:
 
 * The :class:`~rendercanvas.BaseRenderCanvas` represents the main API.
 * The :class:`~rendercanvas.BaseLoop` provides functionality to work with the event-loop in a generic way.
 * The :class:`~rendercanvas.EventType` enum specifies the types of events for :func:`canvas.add_event_handler() <rendercanvas.BaseRenderCanvas.add_event_handler>`.
+* The :class:`~rendercanvas.UpdateMode` enum specifies the scheduler behaviour for  :func:`canvas.set_update_mode() <rendercanvas.BaseRenderCanvas.set_update_mode>`.
 * The :class:`~rendercanvas.CursorShape` enum specifies the cursor shapes for :func:`canvas.set_cursor() <rendercanvas.BaseRenderCanvas.set_cursor>`.
 
 .. autoclass:: rendercanvas.BaseRenderCanvas
@@ -20,6 +21,10 @@ These are the base classes that make up the rendercanvas API:
     :members:
     :member-order: bysource
 
+.. autoclass:: rendercanvas.UpdateMode
+    :members:
+    :member-order: bysource
+
 .. autoclass:: rendercanvas.CursorShape
     :members:
     :member-order: bysource

rendercanvas/__init__.py

@@ -7,6 +7,7 @@
 from ._version import __version__, version_info
 from . import _coreutils
 from ._events import EventType
+from ._scheduler import UpdateMode
 from .base import BaseRenderCanvas, BaseLoop, CursorShape
 
-__all__ = ["BaseLoop", "BaseRenderCanvas", "CursorShape", "EventType"]
+__all__ = ["BaseLoop", "BaseRenderCanvas", "CursorShape", "EventType", "UpdateMode"]

rendercanvas/_scheduler.py

@@ -10,7 +10,7 @@
 
 
 class UpdateMode(BaseEnum):
-    """The different modes to schedule draws for the canvas."""
+    """The UpdateMode enum specifies the different modes to schedule draws for the canvas."""
 
     manual = None  #: Draw events are never scheduled. Draws only happen when you ``canvas.force_draw()``, and maybe when the GUI system issues them (e.g. when resizing).
     ondemand = None  #: Draws are only scheduled when ``canvas.request_draw()`` is called when an update is needed. Safes your laptop battery. Honours ``min_fps`` and ``max_fps``.
@@ -48,7 +48,9 @@ class Scheduler:
     # Note that any extra draws, e.g. via force_draw() or due to window resizes,
     # don't affect the scheduling loop; they are just extra draws.
 
-    def __init__(self, canvas, events, *, mode="ondemand", min_fps=1, max_fps=30):
+    def __init__(
+        self, canvas, events, *, update_mode="ondemand", min_fps=0, max_fps=30
+    ):
         self.name = f"{canvas.__class__.__name__} scheduler"
 
         # We don't keep a ref to the canvas to help gc. This scheduler object can be
@@ -58,13 +60,7 @@ def __init__(self, canvas, events, *, mode="ondemand", min_fps=1, max_fps=30):
         # ... = canvas.get_context() -> No, context creation should be lazy!
 
         # Scheduling variables
-        if mode not in UpdateMode:
-            raise ValueError(
-                f"Invalid update_mode '{mode}', must be in {set(UpdateMode)}."
-            )
-        self._mode = mode
-        self._min_fps = float(min_fps)
-        self._max_fps = float(max_fps)
+        self.set_update_mode(update_mode, min_fps=min_fps, max_fps=max_fps)
         self._draw_requested = True  # Start with a draw in ondemand mode
         self._async_draw_event = None
 
@@ -86,6 +82,20 @@ def get_canvas(self):
         else:
             return canvas
 
+    def set_update_mode(self, update_mode, *, min_fps=None, max_fps=None):
+        update_mode = str(update_mode)
+        if update_mode not in UpdateMode:
+            raise ValueError(
+                f"Invalid update_mode '{update_mode}', must be in {set(UpdateMode)}."
+            )
+        self._mode = update_mode
+
+        if min_fps is not None:
+            self._min_fps = max(0.0, float(min_fps))
+
+        if max_fps is not None:
+            self._max_fps = max(1, float(max_fps))
+
     def request_draw(self):
         """Request a new draw to be done. Only affects the 'ondemand' mode."""
         # Just set the flag

rendercanvas/base.py

@@ -7,10 +7,11 @@
 import sys
 import weakref
 import importlib
+from typing import Optional, Tuple
 
 from ._events import EventEmitter, EventType  # noqa: F401
 from ._loop import BaseLoop
-from ._scheduler import Scheduler
+from ._scheduler import Scheduler, UpdateMode
 from ._coreutils import logger, log_exception, BaseEnum
 
 
@@ -94,9 +95,8 @@ class BaseRenderCanvas:
         size (tuple): the logical size (width, height) of the canvas.
         title (str): The title of the canvas. Can use '$backend' to show the RenderCanvas class name,
             and '$fps' to show the fps.
-        update_mode (EventType): The mode for scheduling draws and events. Default 'ondemand'.
-        min_fps (float): A minimal frames-per-second to use when the ``update_mode`` is 'ondemand'.
-            The default is 1: even without draws requested, it still draws every second.
+        update_mode (UpdateMode): The mode for scheduling draws and events. Default 'ondemand'.
+        min_fps (float): A minimal frames-per-second to use when the ``update_mode`` is 'ondemand'. The default is 0:
         max_fps (float): A maximal frames-per-second to use when the ``update_mode`` is 'ondemand'
             or 'continuous'. The default is 30, which is usually enough.
         vsync (bool): Whether to sync the draw with the monitor update. Helps
@@ -126,13 +126,13 @@ def select_loop(cls, loop):
     def __init__(
         self,
         *args,
-        size=(640, 480),
-        title="$backend",
-        update_mode="ondemand",
-        min_fps=1.0,
-        max_fps=30.0,
-        vsync=True,
-        present_method=None,
+        size: Tuple[int] = (640, 480),
+        title: str = "$backend",
+        update_mode: UpdateMode = "ondemand",
+        min_fps: float = 0.0,
+        max_fps: float = 30.0,
+        vsync: bool = True,
+        present_method: Optional[str] = None,
         **kwargs,
     ):
         # Initialize superclass. Note that super() can be e.g. a QWidget, RemoteFrameBuffer, or object.
@@ -170,7 +170,7 @@ def __init__(
                 self._events,
                 min_fps=min_fps,
                 max_fps=max_fps,
-                mode=update_mode,
+                update_mode=update_mode,
             )
             self._rc_canvas_group._register_canvas(self, self.__scheduler.get_task())
 
@@ -354,6 +354,17 @@ def _draw_frame(self):
         """
         pass
 
+    def set_update_mode(self, update_mode, *, min_fps=None, max_fps=None):
+        """Set the update mode for scheduling draws.
+
+        Arguments:
+            update_mode (UpdateMode): The mode for scheduling draws and events.
+            min_fps (float): The minimum fps with update mode 'ondemand'.
+            max_fps (float): The maximum fps with update mode 'ondemand' and 'continuous'.
+
+        """
+        self.__scheduler.set_update_mode(update_mode, min_fps=min_fps, max_fps=max_fps)
+
     def request_draw(self, draw_function=None):
         """Schedule a new draw event.