Textual - Creating a Custom Checkbox
Textual is a great Python user interface package. Textual lets you create a GUI-like interface in your terminal.
You can use many different widgets in Textual. However, the widget you will be focusing on in this tutorial is the humble checkbox.
Checkboxes are used for Boolean choices. They return a True if checked and a False if unchecked. You can use a checkbox as a clear visual cue to indicate whether one or more options are enabled or disabled.
In this tutorial, you will learn the following:
How to create a standard checkbox
How to customize the checkbox widget
Let’s get started!
How to Create a Standard Checkbox
You should always start with the default widget to see if it works for you. With that in mind, open up your favorite Python IDE and create a new file with the following code in it:
The example above is based on a code example from the Textual documentation. You don’t have to use a VerticalScroll container here, but it is convenient when adding a series of widgets to the container.
Your main focus should be on the Checkbox itself. Here, you simply yield it from compose(), and then you catch the Checkbox.Changed event. When the event is fired, you display a notification to the user indicating that they have changed the checkbox value.
When you run this code, you will see something like this:
The default checkbox is kind of hard to see since the background is very dark and most terminals are black by default. If you squint, you can see that Textual uses an “X” for its check symbol.
If you select the checkbox and toggle it, you can see it a bit better:
However, if you want to make the widget’s borders always visible, then you’ll need to add a border to the widget.
But what if you want the checkbox to be completely empty, too, rather than a greyed-out “X”? That is what you will learn how to do in the next section!
How to Customize the Checkbox Widget
Having a greyed out “X” isn’t necessarily bad thing if you have set up your Textual application to have a lighter background. But if you are using a default or dark background, then you will have some contrast issues.
Many GUI toolkits will show a checkbox as empty for its False state, though, while Textual defaults to a greyed-out “X.” If you want to change the character that is shown or make it an empty box like other toolkits, then you will need to learn how to customize the widget itself.
Fortunately, making a custom widget in Textual is very straightforward. Create a new Python file in your IDE and enter the following code:
When you want to customize a pre-existing widget in Textual, you will almost always subclass it. So here, you subclass the Checkbox class to create a new CustomCheck class. Next, you override the BUTTON_INNER class attribute as well as the toggle() method.
If you go looking at the source code, you will find that BUTTON_INNER defaults to the “X” so here you are defaulting it to an empty string. Then you update toggle() to swap the “X” in when it is checked, and swap it back out when it is unchecked.
The other change is to use the new widget class in your application code.
To increase the widget's visibility, you can add a border using Textual CSS. Create a new file called checkbox.tcss and add the following code to it:
Make sure you save this file in the same folder as your Python file.
Now, when you run this code, you will see the following:
Good job! You now have a custom checkbox.
Wrapping Up
Textual is a great way for you to create beautiful user interfaces in your terminal. In this tutorial, you learned how to create a regular checkbox widget and then learned how to create a custom checkbox.
You can apply this knowledge to customize other widgets in Textual. You will need to study the widget’s code closely to understand how it works so you can modify it successfully. You may have to go through several iterations to get exactly what you want.
Don’t give up! You’ll get there eventually, and then you will be proud of yourself for sticking to it!
Learn More
If you thought this article was interesting you and you want to learn more about Textual, check out the following links:
The Textual website