Textual – How to Add Widgets to a Container (Part I)
Textual is an excellent Python package for creating beautiful user interfaces in your terminal. By default, Textual will arrange your widgets starting at the top of the screen and appending them in a vertically oriented stack. Each GUI or TUI toolkit provides a way to lay out your widgets. Textual is no different in this respect. They use an object called a container.
You can use containers to create the following types of layouts:
Vertical layout
Horizontal layout
Grid layout
and more!
You will be learning how to use all three of these types of layouts. You will also learn how to add more widgets at runtime.
Let’s get started!
Creating a Vertical Layout
The default orientation in Textual is to arrange widgets vertically. You don’t even need to use a CSS file to apply this orientation.
But what does a vertical layout mean anyway? A vertical layout is when you add widgets to your application vertically, from top to bottom. Here is an illustration of what that might look like:
Adding widgets to a Textual application will lay out the widgets similarly to the image above. If you want to see that for yourself, then open up your Python editor and create a new file named `vertical.py`.
Then enter the following code into your new script:
Now open up a terminal and run your code. When you do so, you will see three buttons onscreen, with the topmost being your “OK” button and the bottom being the “Go!” button.
Here is a screenshot of the application to give you an idea of what it looks like:
You can change the widget size, color, and more using each widget’s styles attribute, but using CSS is simpler. Let’s update the code above to use a vertical.tcss file:
Now that you are referring to a CSS file, you should go ahead and write one. If you don’t, you will get an error when you attempt to run the code that says the CSS file could not be found.
Go ahead and open your favorite text editor or use your Python editor to create a file named `vertical.tcss`. Then enter the following code:
You do not need the Screen portion of the CSS since that is technically taken care of automatically by Textual. Remember, Screen is the default widget when you launch an application. However, it is always good to be explicit so you understand what is happening. If you want the output to look exactly like the previous example, you can delete this CSS’s Button portion and try running the code that way.
If you decide to include the Button portion of the CSS, you will make all of the Button widgets 100% wide, which means they will all stretch across the entire width of the screen. The CSS also defines the button text to be yellow and the buttons themselves to have a read background color.
When you run this code, you will see something like the following:
That’s a fun way to change your vertically oriented widget layout. But what happens if you set the height of the Button widgets to 50%? Well, you have three widgets. Three times 50 will be 150%, which is greater than what can be shown all at once. Textual will add a scrollbar if you add widgets that go off-screen.
Try adding that setting to your CSS and re-run the code. You should see something like the following:
You should spend a few moments trying out various width and height sizes. Remember, you don’t have to use percentages. You can also use Textual’s other unit types.
Note: All style attributes can be adjusted at runtime, which means you can modify the layout at runtime, too. Use this wisely so as not to confuse the user!
When you finish experimenting, you will be ready to learn how horizontal layouts work!
Wrapping Up
In part 1, you learned how to create a vertical layout for widgets in your Textual UI. Next week, you will learn how to do a horizontal layout as well as some of Textual’s built-in containers.
See you then!