4.6 KiB
Actions
Actions are white-listed functions with a string syntax you can embed in to links and bind to keys. In this chapter wee will discuss how to create actions and how to run them.
Action methods
Action methods are methods on your app or widgets prefixed with action_. Aside from the prefix these are regular methods which you could call directly if you wished.
Let's write an app with a simple action.
--8<-- "docs/examples/guide/actions/actions01.py"
The action_set_background method is an action which sets the background of the screen. The key handler calls this action if you press the ++r++ key, to set the background color to red.
Although it is possible (and occasionally useful) to call action methods in this way, they are intended to be parsed from an action string. For instance, the string "set_background('red')" is an action string that would call self.action_set_background('red').
The following example replaces the immediate call with a call to [action()][textual.widgets.Widget.action] which parses an action strings and dispatches it to the appropriate action method.
--8<-- "docs/examples/guide/actions/actions02.py"
Note that the action() method is a coroutine so on_key needs to be prefixed with the async key.
You will not typically need this in a real app as Textual will run actions for you from key bindings or links. Before we discuss more practical uses for action strings, let's have a look at the syntax for actions.
Action syntax
Action strings have a simple syntax, which for the most part replicates Python's function call syntax.
!!! important
As much as they look like Python code, Textual does **not** call Python's `eval` function or similar to execute action strings, as this would create a security risk.
Action strings have the following format:
- The name of an action on is own will call the action method with no parameters. For example,
"bell"will callaction_bell(). - Actions may be followed by braces containing Python objects. For example, the action string
set_background('red')will callaction_set_background("red"). - Actions may be prefixed with a namespace (see below) follow by a dot.
Action parameters
If the action strings contains parameters, these must be valid Python literals. Which means you can include numbers, strings, dicts, lists etc. but you can't include variables or references to any other python symbols.
Consequently "set_background('blue')" is a valid action string, but "set_background(new_color)" is not — because new_color is a variable and not a literal.
Actions in links
Actions may be embedded in links with console markup, which you can introduce the @click tag.
The following example mounts simple static text with embedded action links.
=== "actions03.py"
```python title="actions03.py" hl_lines="4-9 13-14"
--8<-- "docs/examples/guide/actions/actions03.py"
```
=== "Output"
```{.textual path="docs/examples/guide/actions/actions03.py"}
```
When you click any of the links, Textual runs the "set_background" action to change the background to the given color.
Actions in binding
Textual will also run actions that are bound to keys. The following example adds key bindings for the ++r++, ++g++, and ++b++ keys which call the "set_background" action.
=== "actions04.py"
```python title="actions04.py" hl_lines="13-17"
--8<-- "docs/examples/guide/actions/actions04.py"
```
=== "Output"
```{.textual path="docs/examples/guide/actions/actions04.py" press="g"}
```
If you run this example, you can change the background by pressing keys in addition to clicking links.
Action namespaces
Textual will look for action methods on the widget or app where they are used. If we were to create a custom widget with an action method, it can have its own set of actions.
The following example defines a custom widget with its own set_background action.
=== "actions05.py"
```python title="actions05.py" hl_lines="13-14"
--8<-- "docs/examples/guide/actions/actions05.py"
```
=== "actions05.py"
```sass title="actions05.css"
--8<-- "docs/examples/guide/actions/actions05.css"
```
If you click on the links, it will call the action method for the widget where the click is handler. The ++r++, ++g++, and ++b++ keys are defined on the App so will set the background for the app.