OcempGUI Manual

The following applications and libraries are needed before OcempGUI can be installed:

Please refer to the documentation of the respective package about how to install it.

OcempGUI is not provided as binary package by the author. However it might be that someone else set up such a package for your wanted operating system or distribution. Those packages are usually not supported by the author, what means that installation problems or similar issues, which do not target the library directly, should be escalated to the respective supplier of that package.

The unpacked package contains two possibilities of building and installing it. Both ways are mostly identical but the one or other user might tend to prefer a specific way. The first is the python way of installing software, the second follows the tradition of the unix environment and uses a Makefile (which actually simply starts the python way). While being in the top source directory, it is possible to type either

make install

for the traditional unix way or

python setup.py install

for the python way.

The package might have some special options, which are described in the README file shipped with it.

Using the latest development sources is possible via CVS. More information about how to use the SourceForge repository can be found on SourceForge.

The following OcempGUI modules are currently available:

The ocempgui.access module provides a wrapper around the ATK accessibility library and several classes to ease the development of accessible applications. To serve different ability ranges, objects can be aware, the ATK developers use an C interface system, that has to be implemented for each toolkit. OcempGUI implements those interfaces using the AtkObject only and flags, that will enable or disable certain interfaces within that instance.

To use accessibility features in your code, you have to import the module using:

import
        ocempgui.access

import ocempgui.access.papi

class A11yObject (IAccessible):
    def __init__ (self):
        IAccessible.__init__ (self)
        ...
    def get_accessible (self):
        obj = AtkObject (...)
        ...
        return obj
        

# papi test example.
import ocempgui.access.papi as papi
import atexit

# Main object - somewhat similar to the GailTopLevel object.
application = papi.AtkObject ()
application.name = "Application object"
application.description = "Application description"
application.role = papi.ATK_ROLE_APPLICATION
application.parent = None

def get_application ():
    global application
    return application

# Register the interfaces and initialize the atk-bridge.
papi.set_atk_root (get_application)
atexit.register (papi.shutdown)
papi.init ()

class SimpleA11y (papi.AtkObject):
    def __init__ (self):
        ifaces = papi.ATK_IFACE_COMPONENT | papi.ATK_IFACE_ACTION
        papi.AtkObject.__init__ (self, ifaces)

        # Implement some interfaces of ATK_IFACE_ACTION and
        # ATK_IFACE_COMPONENT.
        self.action_get_n_actions = self.__get_n_actions
        self.action_get_description = self.__get_description
        self.action_get_name = self.__get_name
        self.component_get_extents = self.__get_pos

    def __get_pos (self, coords):
        return 10, 10, 99, 99
    
    def __get_n_actions (self):
        return 1

    def __get_description (self, i):
        return "Example action."

    def __get_name (self, i):
        return "Example action name"
    
# Window dummy as child of the toplevel application object.
window = SimpleA11y ()

# Retrieve the state set, so we can set it active.
set = window.ref_state_set ()
set.add_state (papi.ATK_STATE_ACTIVE)

# Set some necessary information for accessibility applications.
window.role  = papi.ATK_ROLE_WINDOW
window.name = "Window A11y Object"
window.description = "Window Description"

# Link it with the application object
window.parent = application

# Signal testing - window:create will cause accessibility applications
# to note, that a new window was created for the application.
window.emit ("window:create")

print "Keeping myself alive. Press CTRL-C to exit the application."
while True:
    # Iterate the main processing loop of the ATK wrapper internals,
    # so that external applications can interact with the objects.
    papi.iterate ()

The Magnifier class of the ocempgui.access module is a screen magnification tool for pygame screens. It allows users to zoom portions of the current pygame screen, which are determined by the mouse cursor position. It allows different magnification factors and a variable sizing of the area to zoom.

The Magnifier can be integrated easily into any pygame mainloop and adjusted with minimal effort. To create a new instance of it, you simply can invoke its constructor with no arguments.

magnifier = Magnifier ()
        

# Use a magnification area of 100, 100 and a factor of 3.
magnifier = Magnifier (100, 100, 3)
        

The zoom factor can be adjusted using the factor attribute and set_factor() method.

magnifier.factor = 5.2
magnifier.set_factor (0.5)
        

The size of the area around the mouse cursor, which should be magnified, can be adjusted using the size attribute and set_size() method.

magnifier.size = 50, 50
magnifier.set_size (40, 70)
        

Integrating the Magnifier in a pygame application is done by just adding one or two lines of code. The most important line is to notify it about the available pygame events.

while True:
    events = pygame.event.get ()
    magnifier.notify (*events)
    ...
        

If the pygame display is manipulated directly and thus needs to contain its original surface information (without the magnified area), the restore() method should be invoked before the manipulation occurs.

while True:
    events = pygame.event.get ()

    magnifier.restore ()

    # Display manipulation
    ....
    
    magnifier.notify (*events)
    ...
        

The Magnifier allows you to setup your own zoom function for best results when zooming parts of your application screen. The zoom_func attribute and set_zoom_func() method allow you to provide an own zoom function, which has to return the zoomed surface. It receives additional arguments, which are explained in detail in the inline documentation of the Magnifier class.

Implementing the Magnifier's default zoom function could be achieved using the following code.

def own_zoom_func (screen, mousepos, resultsize, size, factor):
    offset = mousepos[0] - size[0] / 2, mousepos[1] - size[1] / 2
    # Create zoomable surface.
    surface = pygame.Surface ((size[0], size[1]))
    surface.blit (screen, (0, 0), (offset[0], offset[1], size[0], size[1]))
    # Zoom and blit.
    return pygame.transform.scale (surface, (resultsize[0], resultsize[1]))

# Assign the new zoom function.
magnifier.zoom_func = own_zoom_func
        

The ocempgui.draw.Draw submodule contains several functions for geometric objects. Although most of them are only wrappers around the respective pygame functions, some of them can be used to create more complex geometric objects. The following list gives an overview about the functions defined within this submodule.

The ocempgui.draw.Image submodule contains image related functions, such as loading or saving image data.

The ocempgui.draw.String submodule contains functions, which allow the creation and manipulation of fonts and string surfaces. It includes a simple font caching system, which provides a fast availability of fonts, which were created earlier. Besides this feature, the string surface related functions are mostly wrappers around the respective pygame functions.

The ocempgui.draw.Complex module contains more advanced drawing objects, that implement interesting features for 2D graphics.

The FaderSurface class enhances the pygame.Surface class by some additional attributes and methods to support fade-in/fade-out operations. You can adjust them to fit its behaviour to your needs, such as setting the current transparency value using the alpha attribute

surface.alpha = 0 # Make it completely transparent
        

surface.step = 5
        

# Complex.FaderSurface usage example.
import pygame, pygame.locals
from ocempgui.draw import Complex, Image

# Initialize the drawing window.
pygame.init ()
screen = pygame.display.set_mode ((120, 100))
screen.fill ((180, 180, 180))
pygame.display.set_caption ('Complex.FaderSurface')

# Create a surface we can use to display.
image = Image.load_image ("./image.png")
r = image.get_rect ()

# Create a new FaderSurface with the same dimensions and an initial
# transparency of 1.
surface = Complex.FaderSurface (r.width, r.height, 1)

# Blit the original on the FaderSurface.
surface.blit (image, (0, 0))

# The default step value is -1, but we want to fade the image in.
surface.step = 1

# Loop until the FaderSurface reached the maximum or minimum alpha
# transparency value.
while surface.update ():

    # Clean up and blit the surface..
    screen.fill ((180, 180, 180))
    screen.blit (surface, (10, 10))
    pygame.display.flip ()

    # Check the bounds. We have to check the maximum values - 1, because
    # 255 and 0 cause the surface to return False and we would exit the
    # loop.
    if surface.alpha == 254 or surface.alpha == 1:
        surface.step = -surface.step

    pygame.time.delay (50 / 4)
    
    # Wait for input.
    if pygame.event.get ([pygame.locals.QUIT]):
        break

The event management system of OcempGUI uses a simple approach using signal slots. This means, that objects will register themselves only for specific event types, of which they want to be notified. Any other event will not be sent to them.This reduces the overhead of events the objects have to deal with (either by dropping or processing them) and improves the performance and scalability of the event management system (especially with many objects).

Figure 1. Event management

An object, which shall be event aware, should inherit from the INotifyable class and implement its notify() method, which will receive events distributed by the EventManager. The signature of the method looks like the following:

class OwnObject (INotifyable):
    ...
    def notify (self, event):
        ...
      

The event argument of the method will be an Event object, which can be used to perform certain actions within the method body then:

class OwnObject (INotifyable):
    ...
    def move (self, coords):
       # Moves the object to the desired coordinates (x, y).
       self.x = coords[0]
       self.y = coords[1]
       print "Moved to %d,%d" % (self.x, self.y)

    def notify (self, event):
        # Check the event signal and run a certain action with its data.
        if event.signal == "clicked":
           print "Something was clicked!"
        elif event.signal == "move":
           # Assuming that the event.data contains a coordinate tuple.
           self.move (event.data)
        

Setting up the main event management is nearly as easy as enhancing the objects. To add objects to the EventManager, the add_object() method has to be invoked. It receives the object to add and a list of signal ids as arguments. The signal ids will cause the object to be registered in specific queues, to which events with matching signal ids then will be sent.

Objects can be removed from the EventManager using the remove_object() method. The method allows you to either remove the object from specific slots or from all slots, it is registered for, at once.

# Create an EventManager and OwnObject instance.
manager = EventManager ()
myobj = OwnObject ()

# Add the object to the EventManager.
manager.add_object (myobj, "move", "clicked")

# Remove the object from the 'clicked' slot.
manager.remove_object (myobj, "clicked")

# Remove the object from _all_ slots it still listens on.
manager.remove_object (myobj)
        

Now let us proceed to the most important: sending events. To send events to the objects of the EventManager, you can use the emit() method. It receives two arguments, which will become the signal and data of a Event object. The Event will be created by the EventManager and then sent to the matching objects. So all you have to do is to pass the emit() method the correct information for the event.

Both arguments the emit() receives, have no limitations of type, length or whatsoever. It is up to you to to send correct information through the event management system and to check for correct information on the object side.

# Send events to the registered objects via the emit() method.
manager.emit ("clicked", None)
manager.emit ("move", (10, 10))
        

The BaseObject is event driven, which means, that it acts and reacts upon events it receives and that it can raise events. Hereby you have to distinguish between Signals and Events. Signals are certain identifiers, a BaseObject can listen to, while Events are a combination of a Signal and additional data.

What does that mean in practice? As you already know from the section called “Building event driven systems”, objects will register themselves at an event manager with a specific signal, they listen to. Events in turn carry a specific signal id and additional data. A BaseObject will register itself at an event manager with its signals. If events are passed to the event manager, it will distribute them to the object, if needed. The object in turn will react according to its programming instructions.

To allow your object to react according to the application needs on certain events easily, the BaseObject supports the connection of callbacks to signals you can define for it. A callback is a method or function, which should be invoked, when the object receives a certain event.

Figure 2.  Signal handling of the BaseObject class

The first thing you should do is to let your existing object or the newly created one inherit from the BaseObject class. Afterwards you can unleash its full power by adding just a minimal set of code.

from ocempgui.object import BaseObject

class OwnObject (BaseObject):
    def __init__ (self):
        BaseObject.__init__ (self)
    
    ...
        

That is not all of course. You also have to set up the signals the object has to listen to and create callbacks. Let us create a small ping-pong example, where two objects react upon a 'ping' and 'pong' signal.

The BaseObject has a _signals attribute, which basically is a dictionary with the signal ids it listens to as keys and list for the callbacks as values. To allow your object to listen to the 'ping' or 'pong' signal, you have to add those to this dictionary.

from ocempgui.object import BaseObject

class OwnObject (BaseObject):
    def __init__ (self):
        BaseObject.__init__ (self)
        self._signals["ping"] = []
        self._signals["pong"] = []
    ...
        

Now we just need to make the notify() aware of those signal types and let it invoke the appropriate callbacks, which will be connected to those signals.

class OwnObject (BaseObject):
    ...
    def notify (self, event):
        if event.signal == "ping":
            self.run_signal_handlers ("ping")
        elif event.signal == "pong":
            self.run_signal_handlers ("pong")
        

As you see, the run_signal_handlers() takes care of invoking the connected callbacks. Now you have anything set up to allow the object to listen to specific events, to connect callbacks to it and let it invoke them, when it receives the specific signal.

To connect methods or functions as callbacks to a specific signal, the connect_signal() method of the BaseObject can be used. It allows additional data to be passed to the callback by specifiying the data right after the signal and callback. If the callbacks is not needed anymore, it can be disconnected using the disconnect_signal() method.

class OwnObject (BaseObject):
    ...

my_obj = OwnObject ()
ev_callback1 = my_obj.connect_signal ("ping", ping_callback, data)
ev_callback2 = my_obj.connect_signal ("pong", pong_callback, data1, data2)
...

my_obj.disconnect_signal (ev_callback1)
my_obj.disconnect_signal (ev_callback2)
        

Now it just needs to be connected to an event manager. In contrast to the earlier section, you do not need to register any signal of your BaseObject inheritor manually. When you connect it to an event manager, it will automatically do that for you.

class OwnObject (BaseObject):
    ...


manager = EventManager
my_obj = OwnObject ()

# Any signal of the object will be registered automatically.
my_obj.manager = manager
        

The last important thing to know about the BaseObject is its ability to emit events. If the object is connected to an event manager, you can let it send events through the manager with the object its emit() method. The syntax is the same as if you would emit events on the EventManager directly.

Now let us look at the example we just went through (the following one is slightly modified only). You can find the example as python script under examples/baseobject.py

# BaseObject usage example.
from ocempgui.object import BaseObject
from ocempgui.events import EventManager

# Callbacks, which should be invoked for the object.
def ping_callback (obj, additional_data):
    print "The object is: %s" % obj.name
    print "Passed data is: %s" % additional_data

def pong_callback ():
    print "Another callback with no arguments."

# Object implementation, which can listen to specific events.
class OwnObject (BaseObject):
    def __init__ (self, name):
        BaseObject.__init__ (self)
        self.name = name
        # The object should be able to listen to 'ping' and 'pong'
        # events.
        self._signals["ping"] = []
        self._signals["pong"] = []

    def notify (self, event):
        # This simple notify method will not be used in this
        # example. Instead, the signals are invoked directly.
        if event.signal == "ping":
            self.run_signal_handlers ("ping")
        elif event.signal == "pong":
            self.run_signal_handlers ("pong")

manager = EventManager ()

# Create an object and connect callbacks to its both events.
my_obj = OwnObject ("First object")
ev1 = my_obj.connect_signal ("ping", ping_callback, my_obj, "data")
ev2 = my_obj.connect_signal ("pong", pong_callback)

# Connect it to the event manager
my_obj.manager = manager

# Invoke the connected signals handlers for a specific event.
manager.emit ("ping", None)
manager.emit ("pong", None)

# After disconnecting a callback, it will not be invoked anymore.
my_obj.disconnect_signal (ev1)
my_obj.disconnect_signal (ev2)
manager.emit ("ping", None)
manager.emit ("pong", None)

The ocempgui.object module includes another event capable object class, the ActionListener, which inherits from the BaseObject class, but allows you to create and delete signals and listening queues as you need them without the necessity to subclass.

The ActionListener creates the signal id and a callback queue, when you connect a callback to it and registers itself for this signal automatically at its event manager. This can be extremeley useful, if a more flexible event capable object type is needed, which does not need to do any sanity checks on the event data. Instead it will send the event data to the callback as well, which then can work with it.

Once more let us create a ping-ping example using the ActionListener class instead of a BaseObject now.

# ActionListener usage example.
import sys
from ocempgui.events import EventManager
from ocempgui.object import ActionListener

count = 0

def emit_pong (event, manager):
    print "emit_pong received: [%s] - emitting pong..." % event
    manager.emit ("pong", "pong_event")

def emit_ping (event, manager):
    global count
    if count > 10:
        sys.exit ()
    count += 1
    print "emit_ping received: [%s] - emitting ping..." % event
    manager.emit ("ping", "ping_event")

# Create an event manager and two ping-pong listeners.
manager = EventManager ()

listener1 = ActionListener ()
listener1.connect_signal ("ping", emit_pong, manager)
listener1.manager = manager

listener2 = ActionListener ()
listener2.connect_signal ("pong", emit_ping, manager)
listener2.manager = manager

# start ping-pong actions
print "Starting Ping-Pong"
manager.emit ("ping", "ping_event")

Looking at the first interesting line, line eight,

def emit_pong (event, manager):
    print "emit_pong received: [%s] - emitting pong..." % event
    manager.emit ("pong", "pong_event")
        

Line twelve and following does the same, but breaks, if it was invoked more than ten times.

The next lines of interest are line twenty-three to twenty-nine,

listener1 = ActionListener ()
listener1.connect_signal ("ping", emit_pong, manager)
listener1.manager = manager
        

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 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
        

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'.

# 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 ()

The second line

from ocempgui.widgets import*
        

The fifth and sixth lines

re = Renderer ()
re.create_screen (100, 50)
        

The seventh and eight line

re.title = "Hello World"
re.color = (250, 250, 250)
        

In line ten

button = Button ("Hello World")

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

button.topleft = (10, 10)

Line twelve

re.add_widget (button)

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

re.start ()

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.

# 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 ()

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

from ocempgui.widgets.Constants import *
        

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)
        

The ocempgui.widgets module contains some globally accessed settings, that influence its complete behaviour. Those can be found in the ocempgui.widgets.base part and contain the Style, which is currently in use, the timer rate for double-clicks and a debugging flag. You can adjust those settings easily by simply binding them to new values.

Before you go ahead and change base.GlobalStyle, you should read the section called “Changing the widget appearance”.

The base.debug setting is for additional debugging output and should not be set to True usually (unless you are using a development version).

The last one, base.DoubleClickRate should be set using the base.set_doubleclick_rate() method only and denotes the maximum time to elaps between two click operations to identify them as a double-click.

A widget can be set to a specific position on the main screen using the topleft attribute.

widget.topleft = 10, 15
        

If you read the current topleft value of a widget, keep in mind, that it will return a tuple containing the both, x and y, coordinates.

Every widget supports a minimum size, that will be respected by the default drawing methods.

widget.minsize = 80, 20
        

The currently used width and height, which can differ from its minsize can be retrieved using the width and height attributes or as tuple using the size.

if (widget.width == widget.minsize[0]) and (widget.height == widget.minsize[1]):
    print "Widget does not exceed its minimum size."
        

The counterpart to the minsize attribute is maxsize. A widget will never grow beyond the values of it, if set.

To allow an easy and logical keyboard navigation, widgets have an index attribute, which influences the navigation order using the keyboard.

widget.index = 3
        

The input focus mentioned above denotes a state of the widget, in which the user can interact with it using the keyboard only. A Button widget will react upon pressing the space bar with a click while an Entry widget will let the user type text. You can set the input focus of a widget manually with the focus attribute.

widget.focus = True
        

frame = VFrame ()
focusok = frame.set_focus (True)
if not focusok:
    print "Focus could not be set."
        

Widgets can be disabled from user interaction and receiving events, if you set their sensitive attribute to False.

widget.sensitive = False
        

The renderering system of the ocempgui.widgets module can use different layers, on which widgets are drawn. This is especially useful and often necessary to place widgets above others (e.g. to place a Window widget above another one).

widget.depth = 3
        

Widgets support transparency using the alpha color channel. To set it for a widget use the opacity attribute of it. The opacity attribute accepts values betwee 0 (fully transparent) and 255 (not transparent, default).

widget.opacity = 100
        

To change the appearance of a single widget instance, the create_style() method and style attribute of a widget can be used. While create_style() will generate an instance specific style dictionary for the widget, style can be used to have quick access to it, once it is created.

# Create an instance specific style dictionary for the widget and return a
# reference to it.
style = widget.create_style()
...

# Access the created style dictionary of the widget.
widget.style[...] = ...
        

Changing instance specific styles is explained in detail in the section called “Changing the appearance of single instances”.

The Label class can display a short amount of text and allows you to control interaction with other widgets using keyboard mnemonics.

To create a Label, you typically will use

my_label = Label (text)
        

To set the text after creation, use the text attribute or set_text() method.

label.text = "New Text"
label.set_text ("New Text")
        

It is possible to have multiline text by setting the multiline attribute to True:

label.multiline = True
label.set_multiline (True)
        

Labels support keyboard accelerators, so called mnemonics, which can activate other widgets. The '#' will cause the directly following to work as mnemonic character. If you want to cause the Label to display a normal '#', use '##' in the text.

label.text = '#Mnemonic'
label.set_text ('A simple hash: ##')
        

If a mnemonic is set up, you usually have to set the widget, which should be activated by the mnemonic as well.

label.widget = another_widget
        

Below you will find an example to illustrate most of the abilities of the Label widget class. You do not need to care about other widgets like the Frame class for now as those are explained later on.

# Label examples.
import os
from ocempgui.widgets import *
from ocempgui.widgets.Constants import *

def _create_vframe (text):
    frame = VFrame (Label (text))
    frame.spacing = 5
    frame.align = ALIGN_LEFT
    return frame
    
def create_label_view ():
    states = ("STATE_NORMAL", "STATE_ENTERED", "STATE_ACTIVE",
              "STATE_INSENSITIVE")

    table = Table (2, 3)
    table.spacing = 5
    table.set_row_align (0, ALIGN_TOP)
    table.set_row_align (1, ALIGN_TOP)

    # Frame with the states.
    frm_states = _create_vframe ("States")
    for i, s in enumerate (states):
        lbl = Label (s)
        if STATE_TYPES[i] == STATE_INSENSITIVE:
            lbl.sensitive = False
        else:
            lbl.state = STATE_TYPES[i]
        frm_states.add_child (lbl)
    table.add_child (0, 0, frm_states)

    # Frame with different padding.
    frm_padding = _create_vframe ("Padding")
    for i in xrange (5):
        lbl = Label ("Padding: %dpx" % (i * 2))
        lbl.padding = i * 2
        frm_padding.add_child (lbl)
    table.add_child (0, 1, frm_padding)

    # Frame with mnemonic support.
    frm_mnemonics = _create_vframe ("Mnemonics")
    strings = ("#Simple Mnemonic", "A ## is displayed using '####'",
               "M#ultiple M#nemonics #have no #effect")
    for s in strings:
        lbl = Label (s)
        frm_mnemonics.add_child (lbl)
    table.add_child (0, 2, frm_mnemonics)

    # Frame with multiline labels.
    frm_multiline = _create_vframe ("Multiline labels")
    frm_multiline.align = ALIGN_NONE
    strings = ("Single line", "First lines\nSecond line",
               "First line\nSecond line\nThird Line",
               "Two lines with a\n#mnemonic")
    for s in strings:
        lbl = Label (s)
        lbl.multiline = True
        frm_multiline.add_child (lbl)
    table.add_child (1, 0, frm_multiline)
    return table

if __name__ == "__main__":
    # Initialize the drawing window.
    re = Renderer ()
    re.create_screen (500, 350)
    re.title = "Label examples"
    re.color = (234, 228, 223)
    re.add_widget (create_label_view ())
    # Start the main rendering loop.
    re.start ()

The ImageLabel is a decorative widget holding an image and not much functionality besides that. It does not support mnemonics nor text and is mainly used to display images in a GUI, whenever they should fit smoothly into the layout.

To create an ImageLabel, you have pass either the name of a file to load (including the full path to it) or a pygame.Surface object to display.

imagelabel = ImageLabel ("path/to/an/image.png")
imagelabel = ImageLabel (pygame_surface)
        

In contrast to the Label class, the ImageLabel supports different border styles to adjust its look and feel without the need to override its drawing methods.

imagelabel.border = BORDER_NONE
imagelabel.set_border (BORDER_NONE)
        

Below you will find an example to illustrate most of the abilities of the ImageLabel widget class. You do not need to care about other widgets like the Frame class for now as those are explained later on.

# ImageLabel examples.
import os
from ocempgui.draw import Image
from ocempgui.widgets import *
from ocempgui.widgets.Constants import *

def _create_vframe (text):
    frame = VFrame (Label (text))
    frame.spacing = 5
    frame.align = ALIGN_LEFT
    return frame
    
def create_imagelabel_view ():
    image = Image.load_image ("./image.png")
    table = Table (1, 3)
    table.spacing = 5
    table.set_row_align (0, ALIGN_TOP)

    # Frame with the states.
    frm_states = _create_vframe ("States")
    for i, s in enumerate (STATE_TYPES):
        lbl = ImageLabel (image)
        if s == STATE_INSENSITIVE:
            lbl.sensitive = False
        else:
            lbl.state = s
        frm_states.add_child (lbl)
    table.add_child (0, 0, frm_states)

    # Frame with different padding.
    frm_padding = _create_vframe ("Padding")
    for i in xrange (5):
        lbl = ImageLabel (image)
        lbl.border = BORDER_FLAT
        lbl.padding = i * 2
        frm_padding.add_child (lbl)
    table.add_child (0, 1, frm_padding)

    # Borders.
    frm_borders = _create_vframe ("Borders")
    for border in BORDER_TYPES:
        lbl = ImageLabel (image)
        lbl.border = border
        frm_borders.add_child (lbl)
    table.add_child (0, 2, frm_borders)
    return table

if __name__ == "__main__":
    # Initialize the drawing window.
    re = Renderer ()
    re.create_screen (500, 350)
    re.title = "ImageLabel examples"
    re.color = (234, 228, 223)
    re.add_widget (create_imagelabel_view ())
    # Start the main rendering loop.
    re.start ()

You already learned about the Button widget in an earlier section, so let us look at some interesting details of it now.

The Button widget is a interactive widget, which reacts upon mouse input such as clicks. Basically it is a container (which will be explained detailled later on), which holds a Label widget to display its text.

To create a Button, you usually will type

button = Button (text)
        

The usage of mnemonics for the Button is easy to achieve by simply supplying a mnemonic text as described in the section called “Label”. You can set the text directly through the text attribute or set_text() method.

button.text = "#Mnemonic"
button.set_text ("#Mnemonic")
        

The Button supports different border styles to adjust its look and feel without the need to override its drawing methods.

button.border = BORDER_NONE
button.set_border (BORDER_NONE)
        

The Button widget has some default signals, it listens to. Those are

Below you will find an example to illustrate most of the abilities of the Button widget class. You do not need to care about other widgets like the Frame class for now as those are explained later on.

# Button examples.
import os
from ocempgui.widgets import *
from ocempgui.widgets.Constants import *

def _create_vframe (text):
    frame = VFrame (Label (text))
    frame.spacing = 5
    frame.align = ALIGN_LEFT
    return frame

def create_button_view ():