Writing Your First TUI

00:00 In the previous lesson, I gave an overview of the course. In this lesson, I’ll show you how to get started with Textual and write your first app.

00:09 You create a Textual app by inheriting from Textual’s App class. You subclass the app and override certain key methods to create an interface.

00:18 Then instantiate your class and call its .run() method to get it going. Your app will be comprised of widgets, some of which are interactive like buttons, and some which aren’t, like text labels.

00:31 You tell Textual what widgets you want by defining a .compose() method. Inside of that, you yield the widgets you want to include.

00:39 Once you’ve done that, the built-in .run() method takes care of everything else.

00:44 Since Textual is a third-party library, you’ll need to pip install to get it going. As always, you should use a virtual environment when dealing with third-party libraries.

00:54 I won’t show it here, but if you want to see what Textual is capable of, you can execute the Textual module using python -m once you’ve got Textual installed.

01:04 Running -m textual starts a demo application that shows off the different widgets and features. Let me go open an editor and show you a Textual “Hello world!” application.

01:16 These eleven lines are all you need for your first Textual app. It isn’t particularly fancy, but hey, “Hello world!” isn’t meant to be rocket surgery. To build a Textual app, you need to define a class that inherits from Textual’s App class.

01:31 The widgets module is where you find a rich set of widgets that you can use, no pun intended. You’ll get that later. There are a couple of different widgets for displaying text.

01:42 For your first app, I’m going to use the one known as Static, as in static text. As I’ve said, you declare an app by inheriting from Textual's app class, which is what I’ve done here, and then the compose() method is where you declare your interface.

01:58 Whatever components you want are created here. Note, this doesn’t actually display the components, it just registers them for later. In a later lesson, I’ll demonstrate how you have one more chance to do things to your widgets before the app gets displayed.

02:12 Textual treats the compose() method as a generator. When the app gets started, it uses the object sent out of the method to create the interface.

02:20 If you’ve never played with generators before, you don’t really have to understand how this works under the covers. As long as you know you need to yield each widget that you want in your interface.

02:31 The only widget in this first app is the static text widget. Here I’m constructing a new instance, passing in the text I want to display, sticking with tradition, and that text is “Hello world!”

02:44 As this script is both declarative and runnable, I’m nesting the running part inside of a __main__ check. If you’ve never seen this before, __name__ gets set to __main__ when your script is run from the command line.

02:58 If this file were merely imported, this if clause wouldn’t get triggered. For a Textual app, this isn’t really all that important. You’re almost always using it as a script, but I’m sticking with best practices here.

03:11 To run your TUI, you simply need to instantiate your new App class, and then call its inherited .run() method. Let’s try this out.

03:23 Running the code, and there you go. You’ve said hello. There’s not much to see here, but notice a subtle difference from, say, just printing out the string.

03:34 If you had printed the string out, the text would’ve appeared below the execution line. The reason “Hello world!” is at the top here is because Textual clears the terminal and the application takes over the terminal window.

03:45 For me, this is in my subwindow below the line, but it’s taking over everything it can control. To exit a Textual application, you press Ctrl + Q. I actually don’t really like that, and we’ll show you how to change it later, but for now, let me Ctrl + Q to get out of here.

04:03 Okay, you’ve seen your first app. In the next lesson, I’ll dive a little deeper into displaying text widgets on the screen.