The content of widget (displayed within the widget's borders) is typically specified in a call to Static.update or returned from render() in the case of custom widgets.
There are a few ways for you to specify this content.
When building a custom widget you can embed color and style information in the string returned from the Widget's render() method.
Markup is specified as a string which contains
Text enclosed in square brackets ([]) won't appear in the output, but will modify the style of the text that follows.
This is known as content markup.
Before we explore content markup in detail, let's first demonstrate some of what it can do.
In the following example, we have two widgets.
The top has content markup enabled, while the bottom widget has content markup disabled.
Notice how the markup tags change the style in the first widget, but are left unaltered in the second:
fromtextual.appimportApp,ComposeResultfromtextual.widgetsimportStaticTEXT1="""\Hello, [bold $text on $primary]World[/]![@click=app.notify('Hello, World!')]Click me[/]"""TEXT2="""\Markup will [bold]not[/bold] be displayed.Tags will be left in the output."""classContentApp(App):CSS=""" Screen { Static { height: 1fr; } #text1 { background: $primary-muted; } #text2 { background: $error-muted; } } """defcompose(self)->ComposeResult:yieldStatic(TEXT1,id="text1")yieldStatic(TEXT2,id="text2",markup=False)# (1)!if__name__=="__main__":app=ContentApp()app.run()
With markup=False, tags have no effect and left in the output.
Textual comes with a markup playground where you can enter content markup and see the result's live.
To launch the playground, run the following command:
python -m textual.markup
You can experiment with markup by entering it in to the textarea at the top of the terminal, and seeing the results in the lower pane:
You might find it helpful to try out some of the examples from this guide in the playground.
What are Variables?
You may have noticed the "Variables" tab. This allows you to experiment with variable substitution.
There are two types of tag: an opening tag which starts a style change, and a closing tag which ends a style change.
An opening tag looks like this:
[bold]
The second type of tag, known as a closing tag, is almost identical, but starts with a forward slash inside the first square bracket.
A closing tag looks like this:
[/bold]
A closing tag marks the end of a style from the corresponding opening tag.
By wrapping text in an opening and closing tag, we can apply the style to just the characters we want.
For example, the following makes just the first word in "Hello, World!" bold:
[bold]Hello[/bold], World!
Note how the tags change the style but are removed from the output:
You can use any number of tags.
If tags overlap their styles are combined.
For instance, the following combines the bold and italic styles:
[bold]Bold [italic]Bold and italic[/italic][/bold]
You can invert a style by preceding it with the word not.
This is useful if you have text with a given style, but you temporarily want to disable it.
For instance, the following starts with [bold], which would normally make the rest of the text bold.
However, the [not bold] tag disables bold until the corresponding [/not bold] tag:
[bold]This is bold [not bold]This is not bold[/not bold] This is bold.
[chartreuse]This is a green color[/]
[sienna]This is a kind of yellow-brown.[/]
Colors may also include an alpha component, which makes the color fade in to the background.
For instance, if we specify the color with rgba(...), then we can add an alpha component between 0 and 1.
An alpha of 0 is fully transparent (and therefore invisible). An alpha of 1 is fully opaque, and equivalent to a color without an alpha component.
A value between 0 and 1 results in a faded color.
In the following example we have an alpha of 0.5, which will produce a color half way between the background and solid green:
[rgba(0, 255, 0, 0.5)]Faded green (and probably hard to read)[/]
Here's the output:
Warning
Be careful when using colors with an alpha component. Text that is blended too much with the background may become hard to read.
You can also specify a color as "auto", which is a special value that tells Textual to pick either white or black text -- whichever has the best contrast.
For example, the following will produce either white or black text (I haven't checked) on a sienna background:
While you can set the opacity in the color itself by adding an alpha component to the color, you can also modify the alpha of the previous color with a percentage.
For example, the addition of 50% will result in a color half way between the background and "red":
Background colors may be specified by preceding a color with the world on.
Here's an example:
[on #ff0000]Background is bright red.
Background colors may also have an alpha component (either in the color itself or with a percentage).
This will result in a color that is blended with the widget's parent (or Screen).
Here's an example that tints the background with 20% red:
You can also use CSS variables in markup, such as those specified in the design guide.
To use any of the theme colors, simple use the name of the color including the $ at the first position.
For example, this will display text in the accent color:
[$accent]Accent color[/]
You may also use a color variable in the background position.
The following displays text in the 'warning' style on a muted 'warning' background for emphasis:
In addition to links, you can also markup content that runs actions when clicked.
To do this create a style that starts with @click= and is followed by the action you wish to run.
For instance, the following will highlight the word "bell", which plays the terminal bell sound when click:
Play the [@click=app.bell]bell[/]
Here's what it looks like:
We've used an auto-closing to close the click action here.
If you do need to close the tag explicitly, you can omit the action:
Play the [@click=app.bell]bell[/@click=]
Actions may be combined with other styles, so you could set the style of the clickable link:
If you precede an open bracket with a backslash (\), then Textual will not consider it to be a tag and the square bracket will be displayed without modification.
For example, the backslash in the following content prevents the following text from becoming bold, and the text [bold] will be in the output.
Escaping markup
You can also use the escape function to escape tags
Some methods, such as notify(), have a markup switch that you can use to disable markup.
You may want to use this if you want to output a Python repr strings, so that Textual doesn't interpret a list as a tag.
Here's an example:
# debug code: what is my_list at this point?self.notify(repr(my_list),markup=False)
Under the hood, Textual will convert markup into a Content instance.
You can also return a Content object directly from render().
This can give you more flexibility beyond the markup.
To clarify, here's a render method that returns a string with markup:
While this is straightforward and intuitive, it can potentially break in subtle ways.
If the 'name' variable contains square brackets, these may be interpreted as markup.
For instance if the user entered their name at some point as "[magenta italic]Will" then your app will display those styles where you didn't intend them to be.
We can avoid this problem by relying on the Content.from_markup method to insert the variables for us.
If you supply variables as keyword arguments, these will be substituted in the markup using the same syntax as string.Template.
Any square brackets in the variables will be present in the output, but won't change the styles.
Textual supports Rich renderables, which means you can display any object that works with Rich, such as Rich's Text object.
The Content class is preferred for simple text, as it supports more of Textual's features.
But you can display any of the objects in the Rich library (or ecosystem) within a widget.
Here's an example which displays its own code using Rich's Syntax object.
fromrich.syntaximportSyntaxfromtextual.appimportApp,ComposeResult,RenderResultfromtextual.reactiveimportreactivefromtextual.widgetimportWidgetclassCodeView(Widget):"""Widget to display Python code."""DEFAULT_CSS=""" CodeView { height: auto; } """code=reactive("")defrender(self)->RenderResult:# Syntax is a Rich renderable that displays syntax highlighted codesyntax=Syntax(self.code,"python",line_numbers=True,indent_guides=True)returnsyntaxclassCodeApp(App):"""App to demonstrate Rich renderables in Textual."""defcompose(self)->ComposeResult:withopen(__file__)asself_file:code=self_file.read()code_view=CodeView()code_view.code=codeyieldcode_viewif__name__=="__main__":app=CodeApp()app.run()