Text Area wrapping

CHANGELOG.md

@@ -9,6 +9,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 ### Changed
 
+- Breaking change: Significant changes to `TextArea.__init__` default values/behaviour https://github.com/Textualize/textual/pull/3933
+  - `soft_wrap=True` - soft wrapping is now enabled by default.
+  - `show_line_numbers=False` - line numbers are now disabled by default.
+  - `tab_behaviour="focus"` - pressing the tab key now switches focus instead of indenting by default. 
 - Breaking change: `DOMNode.has_pseudo_class` now accepts a single name only https://github.com/Textualize/textual/pull/3970
 - Made `textual.cache` (formerly `textual._cache`) public https://github.com/Textualize/textual/pull/3976
 - `Tab.label` can now be used to change the label of a tab https://github.com/Textualize/textual/pull/3979
@@ -18,6 +22,11 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 
 - Added `DOMNode.has_pseudo_classes` https://github.com/Textualize/textual/pull/3970
 - Added `Widget.allow_focus` and `Widget.allow_focus_children` https://github.com/Textualize/textual/pull/3989
+- Added `TextArea.soft_wrap` reactive attribute added https://github.com/Textualize/textual/pull/3933
+- Added `TextArea.tab_behaviour` reactive attribute added https://github.com/Textualize/textual/pull/3933
+- Added `TextArea.code_editor` classmethod/alternative constructor https://github.com/Textualize/textual/pull/3933
+- Added `TextArea.wrapped_document` attribute which can convert between wrapped visual coordinates and locations https://github.com/Textualize/textual/pull/3933
+- Added `show_line_numbers` to `TextArea.__init__` https://github.com/Textualize/textual/pull/3933
 - Added `Query.blur` and `Query.focus` https://github.com/Textualize/textual/pull/4012
 - Added `MessagePump.message_queue_size` https://github.com/Textualize/textual/pull/4012
 - Added `TabbedContent.active_pane` https://github.com/Textualize/textual/pull/4012
@@ -30,10 +39,10 @@ and this project adheres to [Semantic Versioning](http://semver.org/).
 - `SelectionList` option IDs are usable as soon as the widget is instantiated https://github.com/Textualize/textual/issues/3903
 - Fix issue with `Strip.crop` when crop window start aligned with strip end https://github.com/Textualize/textual/pull/3998
 - Fixed Strip.crop_extend https://github.com/Textualize/textual/pull/4011
+- Fixed a crash if the `TextArea` language was set but tree-sitter language binaries were not installed https://github.com/Textualize/textual/issues/4045
+- Ensuring `TextArea.SelectionChanged` message only sends when the updated selection is different https://github.com/Textualize/textual/pull/3933
 - Fixed declaration after nested rule set causing a parse error https://github.com/Textualize/textual/pull/4012
 - ID and class validation was too lenient https://github.com/Textualize/textual/issues/3954
-- Fixed a crash if the `TextArea` language was set but tree-sitter lanuage binaries were not installed https://github.com/Textualize/textual/issues/4045
-
 
 ## [0.47.1] - 2023-01-05
 

docs/widgets/text_area.md

@@ -1,17 +1,26 @@
 
 # TextArea
 
-!!! tip "Added in version 0.38.0"
+!!! tip 
+
+    Added in version 0.38.0. Soft wrapping added in version 0.48.0.
 
 A widget for editing text which may span multiple lines.
-Supports syntax highlighting for a selection of languages.
+Supports text selection, soft wrapping, optional syntax highlighting with tree-sitter
+and a variety of keybindings.
 
 - [x] Focusable
 - [ ] Container
 
-
 ## Guide
 
+### Code editing vs plain text editing
+
+By default, the `TextArea` widget is a standard multi-line input box with soft-wrapping enabled.
+
+If you're interested in editing code, you may wish to use the [`TextArea.code_editor`] convenience constructor.
+This is a method which, by default, returns a new `TextArea` with soft-wrapping disabled, line numbers enabled, and the tab key behavior configured to insert `\t`.
+
 ### Syntax highlighting dependencies
 
 To enable syntax highlighting, you'll need to install the `syntax` extra dependencies:
@@ -29,7 +38,8 @@ To enable syntax highlighting, you'll need to install the `syntax` extra depende
     ```
 
 This will install `tree-sitter` and `tree-sitter-languages`.
-These packages are distributed as binary wheels, so it may limit your applications ability to run in environments where these wheels are not supported.
+These packages are distributed as binary wheels, so it may limit your applications ability to run in environments where these wheels are not available.
+After installing, you can set the [`language`][textual.widgets._text_area.TextArea.language] reactive attribute on the `TextArea` to enable highlighting.
 
 ### Loading text
 
@@ -46,8 +56,7 @@ In this example we load some initial text into the `TextArea`, and set the langu
     --8<-- "docs/examples/widgets/text_area_example.py"
     ```
 
-To load content into the `TextArea` after it has already been created,
-use the [`load_text`][textual.widgets._text_area.TextArea.load_text] method.
+To update the content programmatically, set the [`text`][textual.widgets._text_area.TextArea.text] property to a string value.
 
 To update the parser used for syntax highlighting, set the [`language`][textual.widgets._text_area.TextArea.language] reactive attribute:
 
@@ -82,7 +91,7 @@ Some other convenient methods are available, such as [`insert`][textual.widgets.
 #### Moving the cursor
 
 The cursor location is available via the [`cursor_location`][textual.widgets._text_area.TextArea.cursor_location] property, which represents
-the location of the cursor as a tuple `(row_index, column_index)`. These indices are zero-based.
+the location of the cursor as a tuple `(row_index, column_index)`. These indices are zero-based and represent the position of the cursor in the content.
 Writing a new value to `cursor_location` will immediately update the location of the cursor.
 
 ```python
@@ -262,6 +271,12 @@ This immediately updates the appearance of the `TextArea`:
 ```{.textual path="docs/examples/widgets/text_area_custom_theme.py" columns="42" lines="8"}
 ```
 
+### Tab behaviour
+
+Pressing the ++tab++ key will shift focus to the next widget in your application by default.
+This matches how other widgets work in Textual.
+To have ++tab++ insert a `\t` character, set the `tab_behaviour` attribute to the string value `"indent"`.
+
 ### Indentation
 
 The character(s) inserted when you press tab is controlled by setting the `indent_type` attribute to either `tabs` or `spaces`.
@@ -315,7 +330,7 @@ Let's extend `TextArea` to add a feature which automatically closes parentheses
 This intercepts the key handler when `"("` is pressed, and inserts `"()"` instead.
 It then moves the cursor so that it lands between the open and closing parentheses.
 
-Typing `def hello(` into the `TextArea` results in the bracket automatically being closed:
+Typing "`def hello(`" into the `TextArea` now results in the bracket automatically being closed:
 
 ```{.textual path="docs/examples/widgets/text_area_extended.py" columns="36" lines="4" press="d,e,f,space,h,e,l,l,o,left_parenthesis"}
 ```
@@ -430,17 +445,28 @@ If you notice some highlights are missing after registering a language, the issu
     The names assigned in tree-sitter highlight queries are often reused across multiple languages.
     For example, `@string` is used in many languages to highlight strings.
 
+
+#### Navigation and wrapping information
+
+If you're building functionality on top of `TextArea`, it may be useful to inspect the `navigator` and `wrapped_document` attributes.
+
+- `navigator` is a [`DocumentNavigator`][textual.widgets.text_area.DocumentNavigator] instance which can give us general information about the cursor's location within a document, as well as where the cursor will move to when certain actions are performed.
+- `wrapped_document` is a [`WrappedDocument`][textual.widgets.text_area.WrappedDocument] instance which can be used to convert document locations to visual locations, taking wrapping into account. It also offers a variety of other convenience methods and properties.
+
+A detailed view of these classes is out of scope, but do note that a lot of the functionality of `TextArea` exists within them, so inspecting them could be worthwhile.
+
 ## Reactive attributes
 
-| Name                   | Type                     | Default            | Description                                      |
-|------------------------|--------------------------|--------------------|--------------------------------------------------|
-| `language`             | `str | None`             | `None`               | The language to use for syntax highlighting.     |
-| `theme`                | `str | None`             | `TextAreaTheme.default()` | The theme to use for syntax highlighting.         |
-| `selection`            | `Selection`              | `Selection()`      | The current selection.                           |
-| `show_line_numbers`    | `bool`                   | `True`             | Show or hide line numbers.                       |
-| `indent_width`         | `int`                    | `4`                | The number of spaces to indent and width of tabs. |
-| `match_cursor_bracket` | `bool`                   | `True`            | Enable/disable highlighting matching brackets under cursor. |
-| `cursor_blink`         | `bool`                   | `True`            | Enable/disable blinking of the cursor when the widget has focus. |
+| Name                   | Type                     | Default       | Description                                                      |
+|------------------------|--------------------------|---------------|------------------------------------------------------------------|
+| `language`             | `str | None`         | `None`                                                           | The language to use for syntax highlighting.     |
+| `theme`                | `str | None`         | `TextAreaTheme.default()`                                        | The theme to use for syntax highlighting.         |
+| `selection`            | `Selection`              | `Selection()` | The current selection.                                           |
+| `show_line_numbers`    | `bool`                   | `False`       | Show or hide line numbers.                                       |
+| `indent_width`         | `int`                    | `4`           | The number of spaces to indent and width of tabs.                |
+| `match_cursor_bracket` | `bool`                   | `True`        | Enable/disable highlighting matching brackets under cursor.      |
+| `cursor_blink`         | `bool`                   | `True`        | Enable/disable blinking of the cursor when the widget has focus. |
+| `soft_wrap`            | `bool`                   | `True`        | Enable/disable soft wrapping.                                    |
 
 ## Messages
 
@@ -465,8 +491,10 @@ Styling should be done exclusively via [`TextAreaTheme`][textual.widgets.text_ar
 
 ## See also
 
-- [`Input`][textual.widgets.Input] - for single-line text input.
-- [`TextAreaTheme`][textual.widgets.text_area.TextAreaTheme] - for theming the `TextArea`.
+- [`Input`][textual.widgets.Input] - single-line text input widget
+- [`TextAreaTheme`][textual.widgets.text_area.TextAreaTheme] - theming the `TextArea`
+- [`DocumentNavigator`][textual.widgets.text_area.DocumentNavigator] - guides cursor movement 
+- [`WrappedDocument`][textual.widgets.text_area.WrappedDocument] - manages wrapping the document 
 - The tree-sitter documentation [website](https://tree-sitter.github.io/tree-sitter/).
 - The tree-sitter Python bindings [repository](https://github.com/tree-sitter/py-tree-sitter).
 - `py-tree-sitter-languages` [repository](https://github.com/grantjenks/py-tree-sitter-languages) (provides binary wheels for a large variety of tree-sitter languages).