Actions¶
Actions are allow-listed functions with a string syntax you can embed in links and bind to keys. In this chapter we 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.
Information
Action methods may be coroutines (defined with the async keyword).
Let's write an app with a simple action method.
from textual.app import App
from textual import events
class ActionsApp(App):
def action_set_background(self, color: str) -> None:
self.screen.styles.background = color
def on_key(self, event: events.Key) -> None:
if event.key == "r":
self.action_set_background("red")
if __name__ == "__main__":
app = ActionsApp()
app.run()
The action_set_background method is an action method which sets the background of the screen. The key handler above will call this action method if you press the R key.
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 which would call self.action_set_background('red').
The following example replaces the immediate call with a call to run_action() which parses an action string and dispatches it to the appropriate method.
from textual import events
from textual.app import App
class ActionsApp(App):
def action_set_background(self, color: str) -> None:
self.screen.styles.background = color
async def on_key(self, event: events.Key) -> None:
if event.key == "r":
await self.run_action("set_background('red')")
if __name__ == "__main__":
app = ActionsApp()
app.run()
Note that the run_action() method is a coroutine so on_key needs to be prefixed with the async keyword.
You will not typically need this in a real app as Textual will run actions in links or key bindings. Before we discuss these, let's have a closer look at the syntax for action strings.
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 to compile action strings.
Action strings have the following format:
- The name of an action on its own will call the action method with no parameters. For example, an action string of
"bell"will callaction_bell(). - Action strings may be followed by parenthesis containing Python objects. For example, the action string
set_background("red")will callaction_set_background("red"). - Action strings may be prefixed with a namespace (see below) and a dot.
Parameters¶
If the action string 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.
Links¶
Actions may be embedded in markup with the @click tag.
The following example mounts simple static text with embedded action links:
from textual.app import App, ComposeResult
from textual.widgets import Static
TEXT = """
[b]Set your background[/b]
[@click=app.set_background('red')]Red[/]
[@click=app.set_background('green')]Green[/]
[@click=app.set_background('blue')]Blue[/]
"""
class ActionsApp(App):
def compose(self) -> ComposeResult:
yield Static(TEXT)
def action_set_background(self, color: str) -> None:
self.screen.styles.background = color
if __name__ == "__main__":
app = ActionsApp()
app.run()
When you click any of the links, Textual runs the "set_background" action to change the background to the given color.
Bindings¶
Textual will run actions bound to keys. The following example adds key bindings for the R, G, and B keys which call the "set_background" action.