Best practices for app to widget actions / messages / events

[alexveden]

Hi, thanks for a such great project!

I'm trying to figure out what is the best practice to propagate actions from app to widgets. For example, if I had a key binding in App class which launches some actions on its all child widgets.

Eventually, I wrote this simple code which works just fine:

from textual.app import App, ComposeResult
import asyncio
from textual.widgets import Header, Footer
from textual.containers import Container
from textual.widgets import DataTable, ListView, ListItem, Label, Button
from textual.widget import Widget

class RunnerListItem(ListItem):
    def compose(self) -> ComposeResult:
        yield Button('Run')

    async def action_run(self):
        self.log('Runner run')
            
class TableTestApp(App):
    BINDINGS = [("r", "run", "Run all")]

    def compose(self) -> ComposeResult:
        """Create child widgets for the app."""
        yield ListView(
            RunnerListItem(),
            RunnerListItem(),
            RunnerListItem(),
            id='list'
        )
        yield Footer()

    async def action_run(self):
        self.log('App action run')

        await asyncio.gather(*[r.action_run()  
                                    for r in self.query(RunnerListItem)])

if __name__ == "__main__":
    app = TableTestApp()
    app.run()

However, I tried some weird paths which didn't work, and I'm wondering if I didn't get the idea correctly, or I found some bugs.

Could you confirm my thinking and answer some questions?

1. It looks like events and messages are designed to work from bottom to top. In other words, child widgets can emit events to App, but App can't emit events to widget. Right?
2. Is it possible to propagate actions from App to a child widget directly by action_() method? It looks like namespaces of actions are only allowed to be screens and app, probably widgets are not allowed.
3. I also tried to experiment with app.post_message(), however didn't manage to make it work. Is it possible instead of running [r.action_run() for r in self.query(RunnerListItem) to send a message to widget? Or it's a bad practice?

Can you confirm if my understanding of design principles is correct, according to the docs and examples projects I saw?

1. Child widgets should communicate with parents via emitting events
2. Parent widgets and apps should directly call child widgets methods, i.e. self.query_one(RunnerListItem).my_method(arg)
3. Widgets should handle self-drawing logic, application/screens should handle business logic and get core information from widgets using event handlers.
4. Actions are deliberately designed to work with apps / screens, so they should be manually dispatched across child widgets by app/screen. I'm aware of this example, but the binding key action is not propagated to the widget, only the link related action is propagated.

Hopefully you'll find time to finish #1532 documentation for compound widgets anytime soon.

Thanks.

[rodrigogiraoserrao]

Hey there, thanks for opening this issue!

(Consider taking a look at this blog post with some suggestions on how to best get help to use Textual :) )

Regarding your questions:

1. Yes, events ”work from bottom to top” in the sense that an event that is generated somewhere in your DOM hierarchy will bubble up, looking for a widget higher up in the hierarchy that knows how to handle that event.
2. action_ methods are screen/app methods and Textual will only trigger action_ methods in screens/apps. Of course, you can have a method with a name action_bla_bla in another widget, but that is likely to create confusion because that method action_bla_bla will never be called automatically by Textual.
3. app.post_message is a coroutine, so you would need to do await app.post_message to make sure the message is posted right then and there, or use app.post_message_no_wait.

Regarding your understanding of design principles:

1. Yes.
2. That's a standard way for parent widgets to manipulate child widgets, yes.
3. Widgets know how to draw themselves, yes. Core logic typically belongs in screens or the app, yes.
4. Related to point 2. from your questions, if I'm not mistaken. Screens/apps/parent widgets can and usually do call other methods on their child widgets.

Issue 1532 is at the top of my TODO list, don't worry :)

In the meantime, because this isn't a feature request/bug report and because we already have issues that track the lack of documentation that should address your questions and concerns, I will ask you to consider closing this issue.
If you think my answer(s) weren't clear enough — I apologise in advance — feel free to ask for further clarification or to read the blog post I linked above to see if there is a better channel for you to ask your follow-up questions!

Either way, thanks for taking the time to reach out to us!

[alexveden]

Thank you, for clarification.