Creating GUI applications

Getting started

The first thing an application using OcempGUI should do is to initialize the renderering system. The Renderer class from the ocempgui.widgets package contains all necessary parts to take care of this. It includes

  • the event mangement

  • a sprite based render engine

  • methods to create the pygame window

The Renderer can be set up with only three lines of code.

from ocempgui.widgets import *
re = Renderer ()
re.create_screen (200, 200) # Creates the pygame window
        

Example 23. Setting up the Renderer


Hello World with OcempGUI

Now that the Renderer is set up, you can start to place widgets on the pygame window by adding them using the Renderer.add_widget() method. Let us do this by building a simple (and well-known) application with a Button widget on it, that displays 'Hello World'.

You can find the example as python script under examples/hello_world.py

# Hello World example.
from ocempgui.widgets import *

# Initialize the drawing window.
re = Renderer ()
re.create_screen (100, 50)
re.title = "Hello World"
re.color = (250, 250, 250)

button = Button ("Hello World")
button.topleft = (10, 10)
re.add_widget (button)

# Start the main rendering loop.
re.start ()

Example 24. Hello World with OcempGUI


The second line

from ocempgui.widgets import*
        
is the usual directive to import anything from the ocempgui.widgets module you will need to build an application. It is also possible to use a fine grained selection of classes and submodules to import, but mostly the above code will serve well.

The fifth and sixth lines

re = Renderer ()
re.create_screen (100, 50)
        
create a new Renderer object, which takes care of updating the screen and the event management and create a pygame window with a 100x50 size.

The seventh and eight line

re.title = "Hello World"
re.color = (250, 250, 250)
        
set the the title caption of the pygame window and the background color (here as RGB value) for the window. Those are not necessary code, but at least the title will help window managers to display the pygame window correctly within their window lists, etc.

In line ten

button = Button ("Hello World")
the Button widget is created. The constructor can receive an additional argument with the text, the Button should display.

The next line will place the Button at a specific position.

button.topleft = (10, 10)
The topleft attribute always refers to the topleft corner of the widget and can be used to place widgets at the desired coordinates on the pygame window.

Line twelve

re.add_widget (button)
adds the button to the Renderer, which will enable the button to be displayed, receive events and send events.

The last line will start the main processing loop of the Renderer.

re.start ()
When the program reaches this line of code, the processing is passed to the Renderer, which will wait for events, draw and update the widgets and so on.

Events and Signals

Every widget of OcempGUI inherits from the ocempgui.object.BaseObject class and its event handling makes heavy usage of the BaseObject features.

To cause a Button to print a message upon a mouse click, you would connect a message printing function to the click signal of the Button. In turn, if this callback is not needed anymore in the later program flow, you would disconnect the function from the Button's signal.

This theoretical model is used in many different toolkits and OcempGUI stays with it. We will enhance our 'Hello world' example application from the previous chapter with a callback now, wich prints a message each time the Button is clicked.

You can find the example as python script under examples/hello_world_signals.py

# Hello World example.
from ocempgui.widgets import *
from ocempgui.widgets.Constants import *

def print_message  ():
    print "The button was clicked!"

# Initialize the drawing window.
re = Renderer ()
re.create_screen (100, 50)
re.title = "Hello World"
re.color = (250, 250, 250)

button = Button ("Hello World")
button.topleft = (10, 10)
button.connect_signal (SIG_CLICKED, print_message)
re.add_widget (button)

# Start the main rendering loop.
re.start ()

Example 25. Hello World with callbacks


The first change you note is the new import directive in line three.

from ocempgui.widgets.Constants import *
        
This will import the set of common constants used within the ocempgui.widgets module. The availabe signal identifiers used by the various widgets of OcempGUI area prefixed with SIG_.

Line five and six contain the function, which will be used as the callback for the button. It is indifferent, if the callback is a class or object method or a function. Both cases will work in the same way.

The next notably change was done in line 16

button.connect_signal (SIG_CLICKED, print_message)
        
This tells the Button to invoke the print_message function each time it is clicked. You also could send additional data to the callback as you already know from the section called “Making objects event capable - the better way”. Anything written about the signal handling of the BaseObject class applies to the widgets, too.