ThorPy

A GUI library for pygame

Tutorials - Hello world

In this tutorial we set a very basic menu with default style. If you need more details and more technical explanations, don't hesitate to read the user guide. Also, if you want to see an overview of most commonly used elements, please see this overview example.

Full code

The code below produces a simple, useless menu.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
#ThorPy hello world tutorial : full code
import thorpy

application = thorpy.Application(size=(300, 300), caption="Hello world")

my_button = thorpy.make_button("Hello, world!") #just a useless button
my_button.center() #center the element on the screen

menu = thorpy.Menu(my_button) #create a menu for auto events handling
menu.play() #launch the menu

application.quit()

Detailed tutorial

First of all, we declare an Application : here we give the size of the application window and its caption, though many other options can be passed (see documentation). Application object sets the pygame display surface and other variables that ThorPy needs to instantiate graphical elements. When using ThorPy, we advise to always instantiate elements after having instantiated the application. We want to see if all works well so far, so we just call a pause function, which will wait until keyboard is pressed, so you have the time to see if all is going well before application.quit() is called. The quit method will quit pygame and ThorPy in a clean way.

1
2
3
4
5
6
7
8
#ThorPy hello world tutorial : step 1
import thorpy

application = thorpy.Application(size=(300, 300), caption="Hello world")

application.pause() #pause so you have the time to see the black screen

application.quit()

Now that all is okay, we can delete line 6 and ask ThorPy for building a button for us. This is done through thorpy.make_button(text, func, params) function at line. The last two argument indicates the reaction of the button when clicked. They are optionnal, and you will learn later how and when to use them ; by default they are set to None and this is what we want for the moment. Once you have built the button, you can tell him to center on screen with my_button.center(). The method center can take an argument called element : if not None, this argument will be the element on which your button will be centered. Here we let the default None value, that has the behaviour to center the button on the screen. Of course, there are many ways to place elements and this one is not the must useful one when dealing with a lot of elements, but we show it here for its simplicity. You can check the most common individual element placing methods here in the user guide, and follow the tutorial on elements storage for learning how to easily store many elements at a time.

The button is ready now. It can be blitted, unblitted, updated, react to pygame events - well, all we need. But still, we have to handle user input. If you already know pygame, you may want to blit and update the button, make a loop over the pygame events, and tell the button to react to each event - and this would perfectly work. However, the smart way is to use a thorpy.Menu object for three reasons: firstly, it makes the code shorter and more clear. Secondly, it adds automatic events like time events that are used by some elements, for example a blinking cursor or an animated element, or printing FPS on demand, etc. Thirdly, it is optimized, in the sense that it never ask an element to react to an event if this element does not have reaction in relation with this event. If nonetheless you prefer or need to manually write a loop on pygame events, this is perfectly possible, and a tutorial on including ThorPy elements to previously coded applications is avalaible. On our side, we simply declare a menu and give it the element on top of which it will make the elements reacts, so if our button had children elements, they would also automatically react to input events. You can also give a list of element to the menu, and it will build its event handling on top of each element given. Finally, a simple call to menu.play() enters the menu. That's all, your hello world code is finised.

Go further...

Now let us try to add a few things to the hello world example: two ThorPy elements and one menu.

First we build a quit button that exit the application when clicked. Note that we indicate that the function corresponding to this button is the ThorPy built-in function thorpy.functions.quit_menu_func, which has the effect to exit the current menu. Then, we create a Background element, whose children elements are the two previously instanciated buttons. Here, we chose a certain color for this background, though we could choose any image.

We also call thorpy.store(background), whose default behaviour is to center background's children elements, instead of centering manually each element.

Finally, we construct a menu on top of the 'father element' background so it handles events for all the elements declared in this code.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
#ThorPy hello world tutorial : step 2
import thorpy

application = thorpy.Application(size=(300, 300), caption="Hello world")

my_button = thorpy.make_button("Hello world!") #just a useless button

#a button for leaving the application:
quit_button = thorpy.make_button("Quit", func=thorpy.functions.quit_menu_func)

#a background which contains quit_button and useless_button
background = thorpy.Background.make(color=(200, 200, 255),
                                    elements=[my_button, quit_button])

#automatic storage of the elements
thorpy.store(background)

menu = thorpy.Menu(background) #create a menu on top of the background
menu.play() #launch the menu

application.quit()