# Textual Textarea
## Note: This is **NOT** the official TextArea widget!
With v0.38.0, Textual added a built-in TextArea widget. You probably want to use
that widget instead of this one. This project predated the official widget; versions < v0.8.0
had a completely separate implmentation.
Since v0.8.0, this project uses the built-in TextArea widget, but adds the features outlined below.
## Installation
```
pip install textual-textarea
```
## Features
Full-featured text editor experience with VS-Code-like bindings, in your Textual App:
- Syntax highlighting and support for Pygments themes.
- Move cursor and scroll with mouse or keys (including <kbd>ctrl+arrow</kbd>, <kbd>PgUp/Dn</kbd>, <kbd>ctrl+Home/End</kbd>).
- Open (<kbd>ctrl+o</kbd>) and save (<kbd>ctrl+s</kbd>) files.
- Cut (<kbd>ctrl+x</kbd>), copy (<kbd>ctrl+c</kbd>), paste (<kbd>ctrl+u/v</kbd>), optionally using the system clipboard.
- Comment selections with <kbd>ctrl+/</kbd>.
- Indent and dedent (optionally for a multiline selection) to tab stops with <kbd>Tab</kbd> and <kbd>shift+Tab</kbd>.
- Automatic completions of quotes and brackets.
- Select text by double-, triple-, or quadruple-clicking.
- Quit with <kbd>ctrl+q</kbd>.
## Usage
### Initializing the Widget
The TextArea is a Textual Widget. You can add it to a Textual
app using `compose` or `mount`:
```python
from textual_textarea import TextEditor
from textual.app import App, ComposeResult
class TextApp(App, inherit_bindings=False):
def compose(self) -> ComposeResult:
yield TextEditor(text="hi", language="python", theme="nord-darker", id="ta")
def on_mount(self) -> None:
editor = self.query_one("#id", expect_type=TextEditor)
editor.focus()
app = TextApp()
app.run()
```
In addition to the standard Widget arguments, TextArea accepts three additional, optional arguments when initializing the widget:
- language (str): Must be `None` or the short name of a [Pygments lexer](https://pygments.org/docs/lexers/), e.g., `python`, `sql`, `as3`. Defaults to `None`.
- theme (str): Must be name of a [Pygments style](https://pygments.org/styles/), e.g., `bw`, `github-dark`, `solarized-light`. Defaults to `monokai`.
- use_system_clipboard (bool): Set to `False` to make the TextArea's copy and paste operations ignore the system clipboard. Defaults to `True`. Some Linux users may need to apt-install `xclip` or `xsel` to enable the system clipboard features.
The TextArea supports many actions and key bindings. **For proper binding of `ctrl+c` to the COPY action,
you must initialize your App with `inherit_bindings=False`** (as shown above), so that `ctrl+c` does not quit the app. The TextArea implements `ctrl+q` as quit; you way wish to mimic that in your app so that other in-focus widgets use the same behavior.
### Interacting with the Widget
#### Getting and Setting Text
The TextArea exposes a `text` property that contains the full text contained in the widget. You can retrieve or set the text by interacting with this property:
```python
editor = self.query_one(TextEditor)
old_text = editor.text
editor.text = "New Text!\n\nMany Lines!"
```
Similarly, the TextEditor exposes a `selected_text` property (read-only):
```python
editor = self.query_one(TextEditor)
selection = editor.selected_text
```
#### Inserting Text
You can insert text at the current selection:
```python
editor = self.query_one(TextEditor)
editor.text = "01234"
editor.selection = Selection((0, 2), (0, 2))
editor.insert_text_at_selection("\nabc\n")
assert editor.text == "01\nabc\n234"
assert editor.selection == Selection((2, 0), (2, 0))
```
#### Getting and Setting The Cursor Position
The TextEditor exposes a `selection` property that returns a textual.widgets.text_area.Selection:
```python
editor = self.query_one(TextEditor)
old_selection = editor.selection
editor.selection = Selection((999, 0),(999, 0)) # the cursor will move as close to line 999, pos 0 as possible
cursor_line_number = editor.selection.end[0]
cursor_x_position = editor.selection.end[1]
```
#### Getting and Setting The Language
Syntax highlighting and comment insertion depends on the configured language for the TextEditor.
The TextArea exposes a `language` property that returns `None` or a string that is equal to the short name of an installed tree-sitter language:
```python
editor = self.query_one(TextEditor)
old_language = editor.language
editor.language = "python"
```
#### Getting Theme Colors
If you would like the rest of your app to match the colors from the TextArea's theme, they are exposed via the `theme_colors` property.
```python
editor = self.query_one(TextEditor)
color = editor.theme_colors.contrast_text_color
bgcolor = editor.theme_colors.bgcolor
highlight = editor.theme_colors.selection_bgcolor
```
#### Adding Bindings and other Behavior
You can subclass TextEditor to add your own behavior. This snippet adds an action that posts a Submitted message containing the text of the TextEditor when the user presses <kbd>ctrl+j</kbd>:
```python
from textual.message import Message
from textual_textarea import TextEditor
class CodeEditor(TextEditor):
BINDINGS = [
("ctrl+j", "submit", "Run Query"),
]
class Submitted(Message, bubble=True):
def __init__(self, text: str) -> None:
super().__init__()
self.text = text
async def action_submit(self) -> None:
self.post_message(self.Submitted(self.text))
```
Raw data
{
"_id": null,
"home_page": "https://github.com/tconbeer/textual-textarea",
"name": "textual-textarea",
"maintainer": null,
"docs_url": null,
"requires_python": "<4.0,>=3.8",
"maintainer_email": null,
"keywords": null,
"author": "Ted Conbeer",
"author_email": "tconbeer@users.noreply.github.com",
"download_url": "https://files.pythonhosted.org/packages/58/ea/0b9edcdc13dbf23389980be7e9c2aa9fe3bedd3958138a28294e364651b5/textual_textarea-0.14.4.tar.gz",
"platform": null,
"description": "# Textual Textarea\n\n\n## Note: This is **NOT** the official TextArea widget!\n\nWith v0.38.0, Textual added a built-in TextArea widget. You probably want to use \nthat widget instead of this one. This project predated the official widget; versions < v0.8.0\nhad a completely separate implmentation.\n\nSince v0.8.0, this project uses the built-in TextArea widget, but adds the features outlined below.\n\n## Installation\n\n```\npip install textual-textarea\n```\n\n## Features\nFull-featured text editor experience with VS-Code-like bindings, in your Textual App:\n- Syntax highlighting and support for Pygments themes.\n- Move cursor and scroll with mouse or keys (including <kbd>ctrl+arrow</kbd>, <kbd>PgUp/Dn</kbd>, <kbd>ctrl+Home/End</kbd>).\n- Open (<kbd>ctrl+o</kbd>) and save (<kbd>ctrl+s</kbd>) files.\n- Cut (<kbd>ctrl+x</kbd>), copy (<kbd>ctrl+c</kbd>), paste (<kbd>ctrl+u/v</kbd>), optionally using the system clipboard.\n- Comment selections with <kbd>ctrl+/</kbd>.\n- Indent and dedent (optionally for a multiline selection) to tab stops with <kbd>Tab</kbd> and <kbd>shift+Tab</kbd>.\n- Automatic completions of quotes and brackets.\n- Select text by double-, triple-, or quadruple-clicking.\n- Quit with <kbd>ctrl+q</kbd>.\n\n## Usage\n\n### Initializing the Widget\n\nThe TextArea is a Textual Widget. You can add it to a Textual\napp using `compose` or `mount`:\n\n```python\nfrom textual_textarea import TextEditor\nfrom textual.app import App, ComposeResult\n\nclass TextApp(App, inherit_bindings=False):\n def compose(self) -> ComposeResult:\n yield TextEditor(text=\"hi\", language=\"python\", theme=\"nord-darker\", id=\"ta\")\n\n def on_mount(self) -> None:\n editor = self.query_one(\"#id\", expect_type=TextEditor)\n editor.focus()\n\napp = TextApp()\napp.run()\n```\n\nIn addition to the standard Widget arguments, TextArea accepts three additional, optional arguments when initializing the widget:\n\n- language (str): Must be `None` or the short name of a [Pygments lexer](https://pygments.org/docs/lexers/), e.g., `python`, `sql`, `as3`. Defaults to `None`.\n- theme (str): Must be name of a [Pygments style](https://pygments.org/styles/), e.g., `bw`, `github-dark`, `solarized-light`. Defaults to `monokai`.\n- use_system_clipboard (bool): Set to `False` to make the TextArea's copy and paste operations ignore the system clipboard. Defaults to `True`. Some Linux users may need to apt-install `xclip` or `xsel` to enable the system clipboard features.\n\nThe TextArea supports many actions and key bindings. **For proper binding of `ctrl+c` to the COPY action,\nyou must initialize your App with `inherit_bindings=False`** (as shown above), so that `ctrl+c` does not quit the app. The TextArea implements `ctrl+q` as quit; you way wish to mimic that in your app so that other in-focus widgets use the same behavior.\n\n### Interacting with the Widget\n\n#### Getting and Setting Text\n\nThe TextArea exposes a `text` property that contains the full text contained in the widget. You can retrieve or set the text by interacting with this property:\n\n```python\neditor = self.query_one(TextEditor)\nold_text = editor.text\neditor.text = \"New Text!\\n\\nMany Lines!\"\n```\n\nSimilarly, the TextEditor exposes a `selected_text` property (read-only):\n```python\neditor = self.query_one(TextEditor)\nselection = editor.selected_text\n```\n\n#### Inserting Text\n\nYou can insert text at the current selection:\n```python\neditor = self.query_one(TextEditor)\neditor.text = \"01234\"\neditor.selection = Selection((0, 2), (0, 2))\neditor.insert_text_at_selection(\"\\nabc\\n\")\nassert editor.text == \"01\\nabc\\n234\"\nassert editor.selection == Selection((2, 0), (2, 0))\n```\n\n#### Getting and Setting The Cursor Position\n\nThe TextEditor exposes a `selection` property that returns a textual.widgets.text_area.Selection:\n\n```python\neditor = self.query_one(TextEditor)\nold_selection = editor.selection\neditor.selection = Selection((999, 0),(999, 0)) # the cursor will move as close to line 999, pos 0 as possible\ncursor_line_number = editor.selection.end[0]\ncursor_x_position = editor.selection.end[1]\n```\n\n\n#### Getting and Setting The Language\n\nSyntax highlighting and comment insertion depends on the configured language for the TextEditor.\n\nThe TextArea exposes a `language` property that returns `None` or a string that is equal to the short name of an installed tree-sitter language:\n\n```python\neditor = self.query_one(TextEditor)\nold_language = editor.language\neditor.language = \"python\"\n```\n\n#### Getting Theme Colors\n\nIf you would like the rest of your app to match the colors from the TextArea's theme, they are exposed via the `theme_colors` property.\n\n```python\neditor = self.query_one(TextEditor)\ncolor = editor.theme_colors.contrast_text_color\nbgcolor = editor.theme_colors.bgcolor\nhighlight = editor.theme_colors.selection_bgcolor\n```\n\n\n#### Adding Bindings and other Behavior\n\nYou can subclass TextEditor to add your own behavior. This snippet adds an action that posts a Submitted message containing the text of the TextEditor when the user presses <kbd>ctrl+j</kbd>:\n\n```python\nfrom textual.message import Message\nfrom textual_textarea import TextEditor\n\n\nclass CodeEditor(TextEditor):\n BINDINGS = [\n (\"ctrl+j\", \"submit\", \"Run Query\"),\n ]\n\n class Submitted(Message, bubble=True):\n def __init__(self, text: str) -> None:\n super().__init__()\n self.text = text\n\n async def action_submit(self) -> None:\n self.post_message(self.Submitted(self.text))\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A text area (multi-line input) with syntax highlighting for Textual",
"version": "0.14.4",
"project_urls": {
"Homepage": "https://github.com/tconbeer/textual-textarea",
"Repository": "https://github.com/tconbeer/textual-textarea"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "fc2d89de92f025a0d09a61b4cb83e1960abb6f99ea6518ef97ed3ef09b119ef1",
"md5": "e737d1eb5afbe2af0bf421d4745d2360",
"sha256": "fc669a0faa689278379dc9a6557a3bb63a3b93fe4b63e62069a97b5ae00973fc"
},
"downloads": -1,
"filename": "textual_textarea-0.14.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e737d1eb5afbe2af0bf421d4745d2360",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.8",
"size": 26615,
"upload_time": "2024-10-09T21:44:05",
"upload_time_iso_8601": "2024-10-09T21:44:05.078283Z",
"url": "https://files.pythonhosted.org/packages/fc/2d/89de92f025a0d09a61b4cb83e1960abb6f99ea6518ef97ed3ef09b119ef1/textual_textarea-0.14.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "58ea0b9edcdc13dbf23389980be7e9c2aa9fe3bedd3958138a28294e364651b5",
"md5": "281f36abffdf0dc8132daf2178415477",
"sha256": "560489179b19426b8546b8521750acde22f57021b3afc08b0643557048fb7315"
},
"downloads": -1,
"filename": "textual_textarea-0.14.4.tar.gz",
"has_sig": false,
"md5_digest": "281f36abffdf0dc8132daf2178415477",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.8",
"size": 24834,
"upload_time": "2024-10-09T21:44:06",
"upload_time_iso_8601": "2024-10-09T21:44:06.749868Z",
"url": "https://files.pythonhosted.org/packages/58/ea/0b9edcdc13dbf23389980be7e9c2aa9fe3bedd3958138a28294e364651b5/textual_textarea-0.14.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-09 21:44:06",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tconbeer",
"github_project": "textual-textarea",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "textual-textarea"
}
JSON
