Merge branch 'main' into footer-scroll

Author: willmcgugan

CHANGELOG.md

@@ -7,10 +7,23 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ## Unreleased
 
+
+### Fixed
+
+- Fixed `Pilot.click` not working with `times` parameter https://github.com/Textualize/textual/pull/5398
+
+### Added
+
+- Added `from_app_focus` to `Focus` event to indicate if a widget is being focused because the app itself has regained focus or not https://github.com/Textualize/textual/pull/5379
+- - Added `Select.type_to_search` which allows you to type to move the cursor to a matching option https://github.com/Textualize/textual/pull/5403
+
 ### Changed
 
+- The content of an `Input` will now only be automatically selected when the widget is focused by the user, not when the app itself has regained focus (similar to web browsers). https://github.com/Textualize/textual/pull/5379
+- Updated `TextArea` and `Input` behavior when there is a selection and the user presses left or right https://github.com/Textualize/textual/pull/5400
 - Footer can now be scrolled horizontally without holding `shift` https://github.com/Textualize/textual/pull/5404
 
+
 ## [1.0.0] - 2024-12-12
 
 ### Added
@@ -20,7 +33,8 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - Added `system` boolean to Binding, which hides the binding from the help panel https://github.com/Textualize/textual/pull/5352
 - Added support for double/triple/etc clicks via `chain` attribute on `Click` events https://github.com/Textualize/textual/pull/5369
 - Added `times` parameter to `Pilot.click` method, for simulating rapid clicks https://github.com/Textualize/textual/pull/5369
-  
+- Text can now be select using mouse or keyboard in the Input widget https://github.com/Textualize/textual/pull/5340
+
 ### Changed
 
 - Breaking change: Change default quit key to `ctrl+q` https://github.com/Textualize/textual/pull/5352

docs/guide/queries.md

@@ -1,6 +1,6 @@
 # DOM Queries
 
-In the previous chapter we introduced the [DOM](../guide/CSS.md#the-dom) which is how Textual apps keep track of widgets. We saw how you can apply styles to the DOM with CSS [selectors](./CSS.md#selectors).
+In the [CSS chapter](./CSS.md) we introduced the [DOM](../guide/CSS.md#the-dom) which is how Textual apps keep track of widgets. We saw how you can apply styles to the DOM with CSS [selectors](./CSS.md#selectors).
 
 Selectors are a very useful idea and can do more than apply styles. We can also find widgets in Python code with selectors, and make updates to widgets in a simple expressive way. Let's look at how!
 
@@ -19,7 +19,7 @@ We could do this with the following line of code:
 send_button = self.query_one("#send")
 ```
 
-This will retrieve a widget with an ID of `send`, if there is exactly one.
+This will retrieve the first widget discovered with an ID of `send`.
 If there are no matching widgets, Textual will raise a [NoMatches][textual.css.query.NoMatches] exception.
 
 You can also add a second parameter for the expected type, which will ensure that you get the type you are expecting.
@@ -41,6 +41,15 @@ For instance, the following would return a `Button` instance (assuming there is
 my_button = self.query_one(Button)
 ```
 
+`query_one` searches the DOM *below* the widget it is called on, so if you call `query_one` on a widget, it will only find widgets that are descendants of that widget.
+
+If you wish to search the entire DOM, you should call `query_one` on the `App` or `Screen` instance.
+
+```python
+# Search the entire Screen for a widget with an ID of "send-email"
+self.screen.query_one("#send-email")
+```
+
 ## Making queries
 
 Apps and widgets also have a [query][textual.dom.DOMNode.query] method which finds (or queries) widgets. This method returns a [DOMQuery][textual.css.query.DOMQuery] object which is a list-like container of widgets.

docs/widgets/select.md

@@ -88,13 +88,15 @@ The following example presents a `Select` created using the `from_values` class
 
 ## Blank state
 
-The widget `Select` has an option `allow_blank` for its constructor.
+The `Select` widget has an option `allow_blank` for its constructor.
 If set to `True`, the widget may be in a state where there is no selection, in which case its value will be the special constant [`Select.BLANK`][textual.widgets.Select.BLANK].
 The auxiliary methods [`Select.is_blank`][textual.widgets.Select.is_blank] and [`Select.clear`][textual.widgets.Select.clear] provide a convenient way to check if the widget is in this state and to set this state, respectively.
 
+## Type to search
 
-## Reactive Attributes
+The `Select` widget has a `type_to_search` attribute which allows you to type to move the cursor to a matching option when the widget is expanded. To disable this behavior, set the attribute to `False`.
 
+## Reactive Attributes
 
 | Name       | Type                           | Default                                        | Description                         |
 |------------|--------------------------------|------------------------------------------------|-------------------------------------|

src/textual/app.py

@@ -4052,7 +4052,9 @@ def _watch_app_focus(self, focus: bool) -> None:
                     # ...settle focus back on that widget.
                     # Don't scroll the newly focused widget, as this can be quite jarring
                     self.screen.set_focus(
-                        self._last_focused_on_app_blur, scroll_visible=False
+                        self._last_focused_on_app_blur,
+                        scroll_visible=False,
+                        from_app_focus=True,
                     )
             except NoScreen:
                 pass

src/textual/command.py

@@ -776,7 +776,7 @@ def compose(self) -> ComposeResult:
         with Vertical(id="--container"):
             with Horizontal(id="--input"):
                 yield SearchIcon()
-                yield CommandInput(placeholder=self._placeholder)
+                yield CommandInput(placeholder=self._placeholder, select_on_focus=False)
                 if not self.run_on_select:
                     yield Button("\u25b6")
             with Vertical(id="--results"):

src/textual/css/stylesheet.py

@@ -437,7 +437,7 @@ def _check_rule(
     # These shouldn't be used in a cache key
     _EXCLUDE_PSEUDO_CLASSES_FROM_CACHE: Final[set[str]] = {
         "first-of-type",
-        "last-of_type",
+        "last-of-type",
         "odd",
         "even",
         "focus-within",

src/textual/events.py

@@ -722,8 +722,22 @@ class Focus(Event, bubble=False):
 
     - [ ] Bubbles
     - [ ] Verbose
+
+    Args:
+        from_app_focus: True if this focus event has been sent because the app itself has
+            regained focus (via an AppFocus event). False if the focus came from within
+            the Textual app (e.g. via the user pressing tab or a programmatic setting
+            of the focused widget).
     """
 
+    def __init__(self, from_app_focus: bool = False) -> None:
+        self.from_app_focus = from_app_focus
+        super().__init__()
+
+    def __rich_repr__(self) -> rich.repr.Result:
+        yield from super().__rich_repr__()
+        yield "from_app_focus", self.from_app_focus
+
 
 class Blur(Event, bubble=False):
     """Sent when a widget is blurred (un-focussed).

src/textual/pilot.py

@@ -442,7 +442,8 @@ async def _post_mouse_events(
                 # the driver works and emits a click event.
                 kwargs = message_arguments
                 if mouse_event_cls is Click:
-                    kwargs["chain"] = chain
+                    kwargs = {**kwargs, "chain": chain}
+
                 widget_at, _ = app.get_widget_at(*offset)
                 event = mouse_event_cls(**kwargs)
                 # Bypass event processing in App.on_event. Because App.on_event

src/textual/screen.py

@@ -869,12 +869,20 @@ def _update_focus_styles(
                 [widget for widget in widgets if widget._has_focus_within], animate=True
             )
 
-    def set_focus(self, widget: Widget | None, scroll_visible: bool = True) -> None:
+    def set_focus(
+        self,
+        widget: Widget | None,
+        scroll_visible: bool = True,
+        from_app_focus: bool = False,
+    ) -> None:
         """Focus (or un-focus) a widget. A focused widget will receive key events first.
 
         Args:
             widget: Widget to focus, or None to un-focus.
             scroll_visible: Scroll widget in to view.
+            from_app_focus: True if this focus is due to the app itself having regained
+                focus. False if the focus is being set because a widget within the app
+                regained focus.
         """
         if widget is self.focused:
             # Widget is already focused
@@ -899,7 +907,7 @@ def set_focus(self, widget: Widget | None, scroll_visible: bool = True) -> None:
                 # Change focus
                 self.focused = widget
                 # Send focus event
-                widget.post_message(events.Focus())
+                widget.post_message(events.Focus(from_app_focus=from_app_focus))
                 focused = widget
 
                 if scroll_visible:

src/textual/widgets/_input.py

@@ -641,7 +641,7 @@ def _on_blur(self, event: Blur) -> None:
 
     def _on_focus(self, event: Focus) -> None:
         self._restart_blink()
-        if self.select_on_focus:
+        if self.select_on_focus and not event.from_app_focus:
             self.selection = Selection(0, len(self.value))
         self.app.cursor_position = self.cursor_screen_offset
         self._suggestion = ""
@@ -761,27 +761,33 @@ def action_cursor_left(self, select: bool = False) -> None:
         Args:
             select: If `True`, select the text to the left of the cursor.
         """
+        start, end = self.selection
         if select:
-            start, end = self.selection
             self.selection = Selection(start, end - 1)
         else:
-            self.cursor_position -= 1
+            if self.selection.is_empty:
+                self.cursor_position -= 1
+            else:
+                self.cursor_position = min(start, end)
 
     def action_cursor_right(self, select: bool = False) -> None:
         """Accept an auto-completion or move the cursor one position to the right.
 
         Args:
             select: If `True`, select the text to the right of the cursor.
         """
+        start, end = self.selection
         if select:
-            start, end = self.selection
             self.selection = Selection(start, end + 1)
         else:
             if self._cursor_at_end and self._suggestion:
                 self.value = self._suggestion
                 self.cursor_position = len(self.value)
             else:
-                self.cursor_position += 1
+                if self.selection.is_empty:
+                    self.cursor_position += 1
+                else:
+                    self.cursor_position = max(start, end)
 
     def action_home(self, select: bool = False) -> None:
         """Move the cursor to the start of the input.

src/textual/widgets/_select.py

@@ -13,6 +13,7 @@
 from textual.css.query import NoMatches
 from textual.message import Message
 from textual.reactive import var
+from textual.timer import Timer
 from textual.widgets import Static
 from textual.widgets._option_list import Option, OptionList
 
@@ -59,6 +60,57 @@ class UpdateSelection(Message):
         option_index: int
         """The index of the new selection."""
 
+    def __init__(self, type_to_search: bool = True) -> None:
+        super().__init__()
+        self._type_to_search = type_to_search
+        """If True (default), the user can type to search for a matching option and the cursor will jump to it."""
+
+        self._search_query: str = ""
+        """The current search query used to find a matching option and jump to it."""
+
+        self._search_reset_delay: float = 0.7
+        """The number of seconds to wait after the most recent key press before resetting the search query."""
+
+    def on_mount(self) -> None:
+        def reset_query() -> None:
+            self._search_query = ""
+
+        self._search_reset_timer = Timer(
+            self, self._search_reset_delay, callback=reset_query
+        )
+
+    def watch_has_focus(self, value: bool) -> None:
+        self._search_query = ""
+        if value:
+            self._search_reset_timer._start()
+        else:
+            self._search_reset_timer.reset()
+            self._search_reset_timer.stop()
+        super().watch_has_focus(value)
+
+    async def _on_key(self, event: events.Key) -> None:
+        if not self._type_to_search:
+            return
+
+        self._search_reset_timer.reset()
+
+        if event.character is not None and event.is_printable:
+            event.time = 0
+            event.stop()
+            event.prevent_default()
+
+            # Update the search query and jump to the next option that matches.
+            self._search_query += event.character
+            index = self._find_search_match(self._search_query)
+            if index is not None:
+                self.select(index)
+
+    def check_consume_key(self, key: str, character: str | None = None) -> bool:
+        """Check if the widget may consume the given key."""
+        return (
+            self._type_to_search and character is not None and character.isprintable()
+        )
+
     def select(self, index: int | None) -> None:
         """Move selection.
 
@@ -68,6 +120,38 @@ def select(self, index: int | None) -> None:
         self.highlighted = index
         self.scroll_to_highlight()
 
+    def _find_search_match(self, query: str) -> int | None:
+        """A simple substring search which favors options containing the substring
+        earlier in the prompt.
+
+        Args:
+            query: The substring to search for.
+
+        Returns:
+            The index of the option that matches the query, or `None` if no match is found.
+        """
+        best_match: int | None = None
+        minimum_index: int | None = None
+
+        query = query.lower()
+        for index, option in enumerate(self._options):
+            prompt = option.prompt
+            if isinstance(prompt, Text):
+                lower_prompt = prompt.plain.lower()
+            elif isinstance(prompt, str):
+                lower_prompt = prompt.lower()
+            else:
+                continue
+
+            match_index = lower_prompt.find(query)
+            if match_index != -1 and (
+                minimum_index is None or match_index < minimum_index
+            ):
+                best_match = index
+                minimum_index = match_index
+
+        return best_match
+
     def action_dismiss(self) -> None:
         """Dismiss the overlay."""
         self.post_message(self.Dismiss())
@@ -295,6 +379,7 @@ def __init__(
         prompt: str = "Select",
         allow_blank: bool = True,
         value: SelectType | NoSelection = BLANK,
+        type_to_search: bool = True,
         name: str | None = None,
         id: str | None = None,
         classes: str | None = None,
@@ -313,6 +398,7 @@ def __init__(
             value: Initial value selected. Should be one of the values in `options`.
                 If no initial value is set and `allow_blank` is `False`, the widget
                 will auto-select the first available option.
+            type_to_search: If `True`, typing will search for options.
             name: The name of the select control.
             id: The ID of the control in the DOM.
             classes: The CSS classes of the control.
@@ -327,6 +413,7 @@ def __init__(
         self.prompt = prompt
         self._value = value
         self._setup_variables_for_options(options)
+        self._type_to_search = type_to_search
         if tooltip is not None:
             self.tooltip = tooltip
 
@@ -338,6 +425,7 @@ def from_values(
         prompt: str = "Select",
         allow_blank: bool = True,
         value: SelectType | NoSelection = BLANK,
+        type_to_search: bool = True,
         name: str | None = None,
         id: str | None = None,
         classes: str | None = None,
@@ -357,6 +445,7 @@ def from_values(
             value: Initial value selected. Should be one of the values in `values`.
                 If no initial value is set and `allow_blank` is `False`, the widget
                 will auto-select the first available value.
+            type_to_search: If `True`, typing will search for options.
             name: The name of the select control.
             id: The ID of the control in the DOM.
             classes: The CSS classes of the control.
@@ -372,6 +461,7 @@ def from_values(
             prompt=prompt,
             allow_blank=allow_blank,
             value=value,
+            type_to_search=type_to_search,
             name=name,
             id=id,
             classes=classes,
@@ -496,7 +586,7 @@ def _watch_value(self, value: SelectType | NoSelection) -> None:
     def compose(self) -> ComposeResult:
         """Compose Select with overlay and current value."""
         yield SelectCurrent(self.prompt)
-        yield SelectOverlay()
+        yield SelectOverlay(type_to_search=self._type_to_search)
 
     def _on_mount(self, _event: events.Mount) -> None:
         """Set initial values."""