Merge pull request #4520 from Textualize/default-screen

default screen method

CHANGELOG.md

@@ -5,11 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](http://keepachangelog.com/)
 and this project adheres to [Semantic Versioning](http://semver.org/).
 
-
 ## [0.61.0] - Unreleased
 
 ### Added
 
+- Added `App.get_default_screen` https://github.com/Textualize/textual/pull/4520
 - Added dynamic binding via `DOMNode.check_action` https://github.com/Textualize/textual/pull/4516
 - Added `"focused"` action namespace so you can bind a key to an action on the focused widget https://github.com/Textualize/textual/pull/4516
 - Added "focused" to allowed action namespaces https://github.com/Textualize/textual/pull/4516
@@ -19,6 +19,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Breaking change: Actions (as used in bindings) will no longer check the app if they are unhandled. This was undocumented anyway, and not that useful. https://github.com/Textualize/textual/pull/4516
 - Breaking change: Renamed `App.namespace_bindings` to `active_bindings`
 
+
 ## [0.60.1] - 2024-05-15
 
 ### Fixed

src/textual/app.py

@@ -861,6 +861,19 @@ def active_bindings(self) -> dict[str, ActiveBinding]:
         """
         return self.screen.active_bindings
 
+    def get_default_screen(self) -> Screen:
+        """Get the default screen.
+
+        This is called when the App is first composed. The returned screen instance
+        will be the first screen on the stack.
+
+        Implement this method if you would like to use a custom Screen as the default screen.
+
+        Returns:
+            A screen instance.
+        """
+        return Screen(id="_default")
+
     def _set_active(self) -> None:
         """Set this app to be the currently active app."""
         active_app.set(self)
@@ -2948,7 +2961,7 @@ async def on_event(self, event: events.Event) -> None:
         # Handle input events that haven't been forwarded
         # If the event has been forwarded it may have bubbled up back to the App
         if isinstance(event, events.Compose):
-            screen: Screen[Any] = Screen(id=f"_default")
+            screen: Screen[Any] = self.get_default_screen()
             self._register(self, screen)
             self._screen_stack.append(screen)
             screen.post_message(events.ScreenResume())

tests/test_screens.py

@@ -496,3 +496,20 @@ async def action_exit(self) -> None:
     with pytest.raises(NoActiveWorker):
         async with app.run_test() as pilot:
             await pilot.press("x", "y")
+
+
+async def test_default_custom_screen() -> None:
+    """Test we can override the default screen."""
+
+    class CustomScreen(Screen):
+        pass
+
+    class CustomScreenApp(App):
+        def get_default_screen(self) -> Screen:
+            return CustomScreen()
+
+    app = CustomScreenApp()
+    async with app.run_test():
+        assert len(app.screen_stack) == 1
+        assert isinstance(app.screen_stack[0], CustomScreen)
+        assert app.screen is app.screen_stack[0]