| Name | textual-autocomplete JSON |
| Version |
1.0.1b0
JSON |
| download |
| home_page | |
| Summary | Easily add autocomplete dropdowns to your Textual apps. |
| upload_time | 2023-01-27 00:20:21 |
| maintainer | |
| docs_url | None |
| author | Darren Burns |
| requires_python | >=3.7.8,<4.0.0 |
| license | |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# textual-autocomplete
textual-autocomplete is a Python library for creating dropdown autocompletion menus in
Textual applications, allowing users to quickly select from a list of suggestions as
they type.
<img width="554" alt="image" src="https://user-images.githubusercontent.com/5740731/205718538-5599a9db-48a2-49dd-99c3-34d43459b81a.png">
<details>
<summary>Video example</summary>
https://user-images.githubusercontent.com/5740731/205718330-a9364894-9133-40ca-8249-6e3dcc13f456.mov
</details>
## Quickstart
Simply wrap a Textual `Input` widget as follows:
```python
from textual.app import ComposeResult
from textual.widgets import Input
from textual_autocomplete import AutoComplete, Dropdown, DropdownItem
def compose(self) -> ComposeResult:
yield AutoComplete(
Input(placeholder="Type to search..."),
Dropdown(items=[
DropdownItem("Glasgow"),
DropdownItem("Edinburgh"),
DropdownItem("Aberdeen"),
DropdownItem("Dundee"),
]),
)
```
There are more complete examples [here](./examples).
## Installation
`textual-autocomplete` can be installed from PyPI using your favourite dependency
manager.
## Usage
### Wrapping your `Input`
As shown in the quickstart, you can wrap the Textual builtin `Input` widget with
`AutoComplete`, and supply a `Dropdown`.
The `AutoComplete` manages communication between the `Input` and the `Dropdown`.
The `Dropdown` is the widget you see on screen, as you type into the input.
The `DropdownItem`s contain up to 3 columns. All must contain a "main" column, which
is the central column used in the filtering. They can also optionally contain a left and right metadata
column.
### Supplying data to `Dropdown`
You can supply the data for the dropdown via a list or a callback function.
#### Using a list
The easiest way to use textual-autocomplete is to pass in a list of `DropdownItem`s,
as shown in the quickstart.
#### Using a callable
Instead of passing a list of `DropdownItems`, you can supply a callback function
which will be called with the current value and cursor position in the input.
See [here](./examples/custom_meta.py) for a usage example.
### Keyboard control
- Press the Up/Down arrow keys to navigate.
- Press Enter to select the item in the dropdown and fill it in.
- Press Tab to fill in the selected item, and move focus.
- Press Esc to hide the dropdown.
- Press the Up/Down arrow keys to force the dropdown to appear.
### Styling
The `Dropdown` itself can be styled using Textual CSS.
For more fine-grained control over styling, you can target the following CSS classes:
- `.autocomplete--highlight-match`: the highlighted portion of a matching item
- `.autocomplete--selection-cursor`: the item the selection cursor is on
- `.autocomplete--left-column`: the left metadata column, if it exists
- `.autocomplete--right-column`: the right metadata column, if it exists
Since the 3 columns in `DropdownItem` support Rich `Text` objects, they can be styled dynamically.
The [custom_meta.py](./examples/custom_meta.py) file is an example of this, showing how the rightmost column is coloured dynamically based on the city population.
The [examples directory](./examples) contains multiple examples of custom styling.
### Messages
When you select an item in the dropdown, a `Dropdown.Selected` event is emitted.
You can declare a handler for this event `on_dropdown_selected(self, event)` to respond
to an item being selected.
An item is selected when it's highlighted in the dropdown, and you press Enter or Tab.
Pressing Enter simply fills the value in the dropdown, whilst Tab fills the value
and then shifts focus from the input.
## Other notes
- textual-autocomplete will create a new layer at runtime on the `Screen` that the `AutoComplete` is on. The `Dropdown` will be rendered on this layer.
- The position of the dropdown is currently fixed _below_ the value entered into the `Input`. This means if your `Input` is at the bottom of the screen, it's probably not going to be much use for now. I'm happy to discuss or look at PRs that offer a flag for having it float above.
- There's currently no special handling for when the dropdown meets the right-hand side of the screen.
- Do not apply `margin` to the `Dropdown`. The position of the dropdown is updated by applying margin to the top/left of it.
- There's currently no debouncing support, but I'm happy to discuss or look at PRs for this.
- There are a few known issues/TODOs in the code, which will later be transferred to GitHub.
- Test coverage is currently non-existent - sorry!
Raw data
{
"_id": null,
"home_page": "",
"name": "textual-autocomplete",
"maintainer": "",
"docs_url": null,
"requires_python": ">=3.7.8,<4.0.0",
"maintainer_email": "",
"keywords": "",
"author": "Darren Burns",
"author_email": "darrenb900@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/82/51/b92cbb6df2064febfc566cd301598d4901c97403f53de70048f0423f0539/textual_autocomplete-1.0.1b0.tar.gz",
"platform": null,
"description": "# textual-autocomplete\n\ntextual-autocomplete is a Python library for creating dropdown autocompletion menus in\nTextual applications, allowing users to quickly select from a list of suggestions as\nthey type.\n\n<img width=\"554\" alt=\"image\" src=\"https://user-images.githubusercontent.com/5740731/205718538-5599a9db-48a2-49dd-99c3-34d43459b81a.png\">\n\n<details>\n<summary>Video example</summary>\n\nhttps://user-images.githubusercontent.com/5740731/205718330-a9364894-9133-40ca-8249-6e3dcc13f456.mov\n\n</details>\n\n## Quickstart\n\nSimply wrap a Textual `Input` widget as follows:\n\n```python\nfrom textual.app import ComposeResult\nfrom textual.widgets import Input\nfrom textual_autocomplete import AutoComplete, Dropdown, DropdownItem\n\ndef compose(self) -> ComposeResult:\n yield AutoComplete(\n Input(placeholder=\"Type to search...\"),\n Dropdown(items=[\n DropdownItem(\"Glasgow\"),\n DropdownItem(\"Edinburgh\"),\n DropdownItem(\"Aberdeen\"),\n DropdownItem(\"Dundee\"),\n ]),\n )\n```\n\nThere are more complete examples [here](./examples).\n\n## Installation\n\n`textual-autocomplete` can be installed from PyPI using your favourite dependency\nmanager.\n\n## Usage\n\n### Wrapping your `Input`\n\nAs shown in the quickstart, you can wrap the Textual builtin `Input` widget with\n`AutoComplete`, and supply a `Dropdown`. \nThe `AutoComplete` manages communication between the `Input` and the `Dropdown`.\n\nThe `Dropdown` is the widget you see on screen, as you type into the input.\n\nThe `DropdownItem`s contain up to 3 columns. All must contain a \"main\" column, which\nis the central column used in the filtering. They can also optionally contain a left and right metadata\ncolumn.\n\n### Supplying data to `Dropdown`\n\nYou can supply the data for the dropdown via a list or a callback function.\n\n#### Using a list\n\nThe easiest way to use textual-autocomplete is to pass in a list of `DropdownItem`s, \nas shown in the quickstart.\n\n#### Using a callable\n\nInstead of passing a list of `DropdownItems`, you can supply a callback function\nwhich will be called with the current value and cursor position in the input.\n\nSee [here](./examples/custom_meta.py) for a usage example.\n\n### Keyboard control\n\n- Press the Up/Down arrow keys to navigate.\n- Press Enter to select the item in the dropdown and fill it in.\n- Press Tab to fill in the selected item, and move focus.\n- Press Esc to hide the dropdown.\n- Press the Up/Down arrow keys to force the dropdown to appear.\n\n### Styling\n\nThe `Dropdown` itself can be styled using Textual CSS.\n\nFor more fine-grained control over styling, you can target the following CSS classes:\n\n- `.autocomplete--highlight-match`: the highlighted portion of a matching item\n- `.autocomplete--selection-cursor`: the item the selection cursor is on\n- `.autocomplete--left-column`: the left metadata column, if it exists\n- `.autocomplete--right-column`: the right metadata column, if it exists\n\nSince the 3 columns in `DropdownItem` support Rich `Text` objects, they can be styled dynamically.\nThe [custom_meta.py](./examples/custom_meta.py) file is an example of this, showing how the rightmost column is coloured dynamically based on the city population.\n\nThe [examples directory](./examples) contains multiple examples of custom styling.\n\n### Messages\n\nWhen you select an item in the dropdown, a `Dropdown.Selected` event is emitted.\n\nYou can declare a handler for this event `on_dropdown_selected(self, event)` to respond\nto an item being selected.\n\nAn item is selected when it's highlighted in the dropdown, and you press Enter or Tab.\n\nPressing Enter simply fills the value in the dropdown, whilst Tab fills the value\nand then shifts focus from the input.\n\n## Other notes\n\n- textual-autocomplete will create a new layer at runtime on the `Screen` that the `AutoComplete` is on. The `Dropdown` will be rendered on this layer.\n- The position of the dropdown is currently fixed _below_ the value entered into the `Input`. This means if your `Input` is at the bottom of the screen, it's probably not going to be much use for now. I'm happy to discuss or look at PRs that offer a flag for having it float above.\n- There's currently no special handling for when the dropdown meets the right-hand side of the screen.\n- Do not apply `margin` to the `Dropdown`. The position of the dropdown is updated by applying margin to the top/left of it.\n- There's currently no debouncing support, but I'm happy to discuss or look at PRs for this.\n- There are a few known issues/TODOs in the code, which will later be transferred to GitHub.\n- Test coverage is currently non-existent - sorry!\n",
"bugtrack_url": null,
"license": "",
"summary": "Easily add autocomplete dropdowns to your Textual apps.",
"version": "1.0.1b0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3f57057c9bfebe73a13ce093e6f3917d524a4c88177b37d5b4a81869fd11d19c",
"md5": "7b27ae2fe5ff46edefa142f18001a9e5",
"sha256": "358a5583229bc4b92f4420922be88d9a70f931249f4a682daf9bce28fe9e8d75"
},
"downloads": -1,
"filename": "textual_autocomplete-1.0.1b0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7b27ae2fe5ff46edefa142f18001a9e5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7.8,<4.0.0",
"size": 8175,
"upload_time": "2023-01-27T00:20:20",
"upload_time_iso_8601": "2023-01-27T00:20:20.056604Z",
"url": "https://files.pythonhosted.org/packages/3f/57/057c9bfebe73a13ce093e6f3917d524a4c88177b37d5b4a81869fd11d19c/textual_autocomplete-1.0.1b0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "8251b92cbb6df2064febfc566cd301598d4901c97403f53de70048f0423f0539",
"md5": "b3ca93fec903d58908a4a4d2f45c9adb",
"sha256": "5578de956aae7e979d44570a9c18ebc86b42d197d6b31f185f3d9f2f4dce7308"
},
"downloads": -1,
"filename": "textual_autocomplete-1.0.1b0.tar.gz",
"has_sig": false,
"md5_digest": "b3ca93fec903d58908a4a4d2f45c9adb",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7.8,<4.0.0",
"size": 8487,
"upload_time": "2023-01-27T00:20:21",
"upload_time_iso_8601": "2023-01-27T00:20:21.647952Z",
"url": "https://files.pythonhosted.org/packages/82/51/b92cbb6df2064febfc566cd301598d4901c97403f53de70048f0423f0539/textual_autocomplete-1.0.1b0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-01-27 00:20:21",
"github": false,
"gitlab": false,
"bitbucket": false,
"lcname": "textual-autocomplete"
}
