Confused about ListView focus handling

[dAnjou]

Hi,

with the following code:

from textual import on
from textual.events import Focus, Blur
from textual.app import App, ComposeResult
from textual.widgets import ListView

class MyListView(ListView):
    DEFAULT_CSS = """
    MyListView {
        border: solid white;
        &:focus {
            border: solid green;
        }
    }
    """

    @on(Focus)
    @on(Blur)
    def focus_toggled(self):
        self.border_title = "has_focus" if self.has_focus else None
        self.border_subtitle = "has_focus_within" if self.has_focus_within else None

class ListViewSample(App):
    def compose(self) -> ComposeResult:
        yield MyListView()
        yield MyListView()

if __name__ == "__main__":
    sample = ListViewSample()
    sample.run()

The app looks like this right after start:

And when I TAB to switch focus, it looks like this:

I'm confused because ListView is defined like this:

class ListView(VerticalScroll, can_focus=True, can_focus_children=False):

But the behavior above looks like the focus is actually still on whatever is inside the ListView 🤔

Am I missing something? 🙏

PS: My goal is pretty much what the sample does, to update the border subtitle whenever the ListView has or loses focus.

[initial-d]

I think the confusing bit is the meaning of has_focus_within.

has_focus_within does not mean “one of my children has focus”. It means “this widget or something inside it has focus”. So when the ListView itself is focused, both of these being true is expected:

self.has_focus         # the ListView itself is focused
self.has_focus_within  # focus is within the ListView subtree, including itself

That is the same idea as CSS :focus-within: the element itself counts, not only descendants. can_focus_children=False prevents normal focus from moving into child widgets, but it does not make has_focus_within false when the ListView itself has focus.

For your goal, I would key the subtitle/title off has_focus only:

from textual import on
from textual.events import Focus, Blur
from textual.widgets import ListView

class MyListView(ListView):
    @on(Focus)
    @on(Blur)
    def focus_toggled(self) -> None:
        focused = self.has_focus
        self.border_title = "focused" if focused else None
        self.border_subtitle = None

Or, if all you need is the visual border, CSS is the cleanest source of truth:

MyListView {
    border: solid white;
}

MyListView:focus {
    border: solid green;
}

If you want the initial focused widget to show a title immediately at startup, also call the same update method from on_mount, because the initial focus state can already be established before you visually inspect the widget.

[dAnjou]

Thanks for clarifying the meaning of has_focus_within 🙏 I still think it's a bit counterintuitive but that might be just me.

Regarding has_focus however, my second screenshot shows that after TABing to the second ListView, the first one's has_focus is still True which shouldn't be the case according to your explanation:

[initial-d]

You are right to call that out. Looking at your screenshot again, the sticky has_focus title is the important part.

I would not read self.has_focus inside the combined Focus/Blur handler here. During focus transition, the event and the focus-state property can be observed at slightly awkward times, so the blur handler may still see the previous state and leave the title set.

For this UI, use the event type as the source of truth:

from textual import on
from textual.events import Focus, Blur
from textual.widgets import ListView

class MyListView(ListView):
    @on(Focus)
    def focused(self) -> None:
        self.border_title = "has_focus"
        self.border_subtitle = "has_focus_within"

    @on(Blur)
    def blurred(self) -> None:
        self.border_title = None
        self.border_subtitle = None

If you specifically want to display the computed properties rather than just react to the event, defer the read until after the focus transition has settled:

@on(Focus)
@on(Blur)
def focus_toggled(self) -> None:
    self.call_after_refresh(self.update_focus_labels)

def update_focus_labels(self) -> None:
    self.border_title = "has_focus" if self.has_focus else None
    self.border_subtitle = "has_focus_within" if self.has_focus_within else None

For your stated goal, the first version is simpler: focus event sets the labels, blur event clears them. That avoids depending on the exact moment has_focus is updated during the transition.

[dAnjou]

Thanks for the pointer to App.call_after_refresh, I ended up using App.call_next which works too and seems to be smaller hammer for this particular nail.

---

I'd still be interested in a maintainer's opinion on this, since it still seems a bit counterintuitive that the attribute does reflect reality inside the event handler of the very much corresponding event.

[willmcgugan]

The job of the handler is to set the has_focus flag. If you implement the handler you have the option of preventing focus with "event.prevent_default" or doing something different entirely. The call next works because it runs after the event has been processes by the base class.

If you want to know the instant the focus flags change, a watcher would be the better option.

from textual import on
from textual.events import Focus, Blur
from textual.app import App, ComposeResult
from textual.widgets import ListView


class MyListView(ListView):
    DEFAULT_CSS = """
    MyListView {
        border: solid white;
        &:focus {
            border: solid green;
        }
    }
    """

    def update_labels(self):
        self.border_title = "has_focus" if self.has_focus else None
        self.border_subtitle = "has_focus_within" if self.has_focus_within else None

    def watch_has_focus(self, focus: bool) -> None:
        self.update_labels()

    def watch_has_focus_within(self, focus: bool) -> None:
        self.update_labels()


class ListViewSample(App):
    def compose(self) -> ComposeResult:
        yield MyListView()
        yield MyListView()


if __name__ == "__main__":
    sample = ListViewSample()
    sample.run()

Also note that Focus and Blur don't bubble. If you want to know if a descendant has been focused, you can implement DescendantFocus and DescendantBlur.