Skip to content

Commit fde2373

Browse files
committed
Mention can_focus in docs, note on how bindings are checked
1 parent 295f95b commit fde2373

File tree

1 file changed

+10
-6
lines changed

1 file changed

+10
-6
lines changed

docs/guide/input.md

Lines changed: 10 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -113,20 +113,21 @@ The app splits the screen in to quarters, with a `RichLog` widget in each quarte
113113

114114
You can move focus by pressing the ++tab++ key to focus the next widget. Pressing ++shift+tab++ moves the focus in the opposite direction.
115115

116+
### Focusable widgets
117+
118+
Each widget has a boolean `can_focus` attribute which determines if it is capable of receiving focus.
119+
Note that `can_focus=True` does not mean the widget will _always_ be focusable.
120+
For example, a disabled widget cannot receive focus even if `can_focus` is `True`.
121+
116122
### Controlling focus
117123

118124
Textual will handle keyboard focus automatically, but you can tell Textual to focus a widget by calling the widget's [focus()][textual.widget.Widget.focus] method.
125+
By default, Textual will focus the first focusable widget when the app starts.
119126

120127
### Focus events
121128

122129
When a widget receives focus, it is sent a [Focus](../events/focus.md) event. When a widget loses focus it is sent a [Blur](../events/blur.md) event.
123130

124-
### Focusable widgets
125-
126-
Each widget has a boolean `can_focus` attribute which determines if it is capable of receiving focus.
127-
Note that `can_focus=True` does not mean the widget will _always_ be focusable.
128-
For example, a disabled widget cannot receive focus even if `can_focus` is `True`.
129-
130131
## Bindings
131132

132133
Keys may be associated with [actions](../guide/actions.md) for a given widget. This association is known as a key _binding_.
@@ -160,6 +161,9 @@ Note how the footer displays bindings and makes them clickable.
160161
Multiple keys can be bound to a single action by comma-separating them.
161162
For example, `("r,t", "add_bar('red')", "Add Red")` means both ++r++ and ++t++ are bound to `add_bar('red')`.
162163

164+
When you press a key, Textual will first check for a matching binding in the `BINDINGS` list of the currently focused widget.
165+
If no match is found, it will search upwards through the DOM all the way up to the `App` looking for a match.
166+
163167
### Binding class
164168

165169
The tuple of three strings may be enough for simple bindings, but you can also replace the tuple with a [Binding][textual.binding.Binding] instance which exposes a few more options.

0 commit comments

Comments
 (0)