how to change focus to newly mounted widgets

[calestyo]

Hey.

When form a binding I create new widgets like:

    def action_foo(self):
        table = DataTable()
        self.mount(table)
        table.focus()

Is merely using table.focus() here enough or may this cause glitches (I found one report, but haven't experienced any myself) and I need to call e.g. table.call_after_refresh(table.focus)?

I mean AFAIU mount() doens’t wait until it has been actually fully mounted, or does it?

Thanks,
Chris.

[calestyo]

A bit related perhaps, when should one fill widgets like DataTable (or one derived from that) with their (initial) data?

I mean I could do this:

• in a derived version's __init__, e.g. for the columns (if they're static) or even for the rows, if they're static, too.
• in the derived version's on_mount
• the compose-method of the widget that yields my widget derived from DataTable
• or the on_mount of that

I guess I don't quite understand the concepts here. O:-)
Like when at which exact point is on_mount called? Is the widget then already usable? Already displayed? What should one generally do in on_mount? I mean conceptually?

Should one fill in initial data before the mounting has happened or after?

Should things like e.g. setting the focus happen from "within" the respective widget itself (__init__, on_mount) or from whatever adds the widget?

Thanks :-)

[pyrrhonic]

1. Focusing a newly mounted widget

mount() doesn't mount the widget straight away. It schedules the mount and returns an AwaitMount. If you await it, the widget is fully mounted (it's in the DOM and has run on_mount) before your next line runs. Actions can be async, so the usual way to write this is:

async def action_foo(self) -> None:
    table = DataTable()
    await self.mount(table)
    table.focus()

Your version without the await usually works too. Widget.focus() doesn't move focus immediately; it schedules the change with call_later, which normally runs after the mount has finished. That depends on timing, though, which is probably where the glitch reports come from. Awaiting the mount makes the order explicit. call_after_refresh(table.focus) also works, but you shouldn't need it once you await.

2. When to fill a DataTable with data

• __init__: only store configuration here (e.g. save the rows on self). Avoid anything that needs the app, the DOM or the screen.
• compose: this is for declaring child widgets. Don't load data here.
• on_mount: the standard place, and what the Textual docs examples do (add_columns / add_rows in on_mount). When it runs, the widget is attached to the DOM, can query its parents and the app, and its children are composed. It hasn't been painted yet, so anything you set here appears on the first render with no flicker.
• The parent's on_mount: works too, but keeping the data logic in your DataTable subclass's own on_mount makes the widget self-contained.

If loading is slow (I/O, a database), start it from on_mount with a @work worker so the UI doesn't block, then fill the table when the data arrives.

3. Where to set focus

As a rule, the code that adds a widget decides whether it gets focus, since focus depends on context the widget itself doesn't know. The main exception is screens: for a screen's initial focus, use AUTO_FOCUS on the Screen or call .focus() in the screen's on_mount.

[calestyo]

btw: One thing I still don't get is... why would the await self.mount(table) ensure that it has fully finished (in DOM, on_mount called) while the non-awaited version doesn't? I mean isn't the idea of non-async funcs usually that they also finish completely - just without that chance of giving control to the even loop meanwhile?

I guess then that textual intentionally designed the async / non-async functions different, with the former ensuring everything has finished when it returns, while the later version merely schedules the work but doesn't wait for it? Why so? To not lock up the UI, despite using no async?

[calestyo]

And one more... when foo.on_mount() is called... are all the widgets yielded by foo.compose already read (i.e. in the DOM, etc)? (I presume so)

[pyrrhonic]

Glad it helped! Taking your follow-ups in order:

Why does await change anything?
It isn't two versions of one function. mount() is a normal method that schedules the mount and returns an AwaitMount object. The mount itself runs on the event loop: the widget's message pump starts, it composes its children, and it handles its Mount event. A sync function can't wait for that without blocking the same loop that has to do the work. So the sync call can only schedule. await hands control back to the loop until the work is done. remove() and remove_children() work the same way.

The docs cover this in the App guide under "Awaiting mount". Textual guarantees the mount is complete by the next message handler, but not right after the mount() call. That's why your original version usually worked: focus() is also deferred.

Are compose children ready in on_mount?
Yes. By the time a widget's on_mount runs, the widgets it yielded from compose() have been mounted, so query_one(...) etc. work there.

What does "in the DOM" mean in practice?
The widget is attached to its parent, so it can be queried and it can reach self.app / self.screen. It has styles applied and can handle messages, focus and so on. It hasn't necessarily been painted yet. If you need to know when it's actually shown, there's a separate Show event (on_show).

Naming your own attributes
Textual uses many single-underscore names internally, and widgets also have public ones. DataTable already has rows and columns, so self.rows = ... in a subclass would clobber it. Name mangling (__foo) works but isn't common. I'd just pick descriptive names (initial_rows, _pending_rows) and check dir(DataTable) if you're unsure. For state that should update the UI, use reactive.

compose: static only?
No. It can be dynamic: loops, conditionals, based on attributes set in __init__. With reactive(..., recompose=True) it even reruns when state changes. The rule is only to keep it fast and side-effect free: declare widgets there, and load or fetch data in on_mount or a worker.

[calestyo]

thanks again 🙃️

It was clear that I could e.g. check dir(DataTable), my main concern was that it might silently break if e.g. textual starts using some new generic name in some future version, which I happen to use as well.

[calestyo]

@pyrrhonic thanks for your help :-)

1. I see. Are things like "If you await it, the widget is fully mounted" and that this means "(it's in the DOM and has run on_mount)" respectively what that in turn actually means somewhere documented? I've already a fair share of the guides but haven't really found it that elaborate, yet what "being in the DOM" actually means, like can on only use it (e.g. focus/fill data/etc.) by then, or does it merely mean it can't be queried before)? Things like what you wrote above, that it's not yet painted by then.

init: only store configuration here (e.g. save the rows on self)

Is there any best practises when adding one's own attributes to such derived widget classes? I mean textual does come with a lot of special names and one doesn't want to have conflicts. Simply always using __foo name mangling?

compose: this is for declaring child widgets. Don't load data here.

But I assume only "static" ones?!

3. Okay that does sound quite reasonable.

Thanks :-)