Add wait_for_dismiss to push_screen

[willmcgugan]

An addition to the screens API to avoid callbacks. Adds a wait_for_dismiss parameter which waits for the new screen to be dismissed.

It works like this:

result = await self.push_screen(MyScreen(), wait_for_dismiss=True)

This only works from within a worker. If not run within a worker it will raise a NoActiveWorker error.

Without a worker, waiting on the result would cause a deadlock. But at least we can identify that and raise a helpful error.

This allows for more natural code than callbacks. For example, here's how you might use a screen to ask the user if they want to quit:

@work
async def action_close(self) -> None:
    if await self.push_screen(QuitScreen(), wait_for_dismiss=True):
        self.app.quit()

The push_screen has overloaded signatures, so the type checker knows that there will only be a return value when wait_for_dismiss is True, and it knows the type of the return -- which is nice!

[mistotebe]

Isn't it better (definitely cleaner) to just add a new method, so you don't have to add wait_for_dismiss? Also no need to keep callback in that case...

[willmcgugan]

@mistotebe Nothing prevents us for doing both. But awaiting the screen is more verbose.

screen = QuitScreen()
await self.push_screen(screen)
result = await screen.wait_for_dismiss()

Compared to:

result = await self.push_screen(QuitScreen(), wait_for_dismiss=True)

And callbacks still have their uses.

[mistotebe]

@mistotebe Nothing prevents us for doing both. But awaiting the screen is more verbose.

screen = QuitScreen()
await self.push_screen(screen)
result = await screen.wait_for_dismiss()

If such a method existed, yes, but it appears to be missing from the PR? And sounds race-prone unless implemented correctly.

My instinct would have been to add something like this instead:

async def push_modal_screen+bikeshed(self, screen: ModalScreen[ScreenResultType]) -> ScreenResultType:
    ...