Add can_focus to guide, mention how BINDINGS are checked
#4985
Conversation
|
I've added a section to the guide showing how to construct a basic focusable widget with simple bindings defined. 
|
| @@ -190,6 +190,67 @@ If the supplied text is too long to fit within the widget, it will be cropped (a | |||
| There are a number of styles that influence how titles are displayed (color and alignment). | |||
| See the [style reference](../styles/index.md) for details. | |||
|
|
|||
| ## Focus & keybindings | |||
There was a problem hiding this comment.
Perhaps this section should be called "Focusable widgets"? Its just that prior to this heading, we've already introduced focus and keybindings. We want the reader to know what they are about to learn.
There was a problem hiding this comment.
Yeah I changed this around a few times -
We're on the "Widgets" page, so it felt clear to me that it was in the context of widgets. It also adds "keybindings" to the table of contents for the page, which I felt was important for discoverability.. "how do I add keybindings to my widget" feels like the "question" I'd be looking to an answer for, and having headings suggest that there might be answer contained within is important.
Its just that prior to this heading, we've already introduced focus and keybindings.
That was on a different docs page (a couple of pages back in the guide), before we'd introduced how to create a widget.
| @@ -190,6 +190,67 @@ If the supplied text is too long to fit within the widget, it will be cropped (a | |||
| There are a number of styles that influence how titles are displayed (color and alignment). | |||
| See the [style reference](../styles/index.md) for details. | |||
|
|
|||
| ## Focus & keybindings | |||
|
|
|||
| Widgets can have a list of associated key [bindings](../guide/input.md#bindings), | |||
There was a problem hiding this comment.
This feels like repetition, since we have just been explaining it.
There was a problem hiding this comment.
It certainly is repetition, but our last mention of this stuff was quite some time ago (note that there are 2 files changed in this PR - this change is in "Widgets", but the stuff you're referring to is in "Input".) and repetition is sometimes important to build context or refresh memories.
My thought was someone unfamiliar with Textual and reading this for the first time would appreciate a 1-sentence refresher as well as a link back to the "main" explanation.
docs/guide/widgets.md
Outdated
|
|
||
| To demonstrate, let's design a simple interactive counter widget which can be incremented and decremented using the keyboard. | ||
|
|
||
| In the following example, we define a simple `Counter` widget with `can_focus=True`, and some CSS to make it stand out when focused. |
There was a problem hiding this comment.
the can_focus=True is a really important takeaway here. It's what we were lacking, and why we keep getting asked. Here it seems too much of a sidenote.
"Widgets aren't focusable by default. In order for a widget to be focusable we need to set can_focus=True when we define a widget subclass. Here's an example of a focusable widget ..."
There was a problem hiding this comment.
I think this is clearer in the rendered docs, as the example app below has a single highlighted line for the can_focus=True as well as a popup explaining it. The whole purpose of the example is to draw attention to the can_focus=True.
Have reworded to try and emphasise it more.
Co-authored-by: Will McGugan <[email protected]>
…into docs-updates-11sep24
Closes #4918.
Also noticed that we only seem to give examples of "global"/
App-level bindings, so I've added a couple of sentences explaining how the focused widget is checked first, followed by a look upwards through the DOM.@willmcgugan You mentioned in the issue to add it to the "widget" guide, but it seemed like the "input" when I checked as that's where most of the discussion around focus happens. Let me know if you disagree.