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, has to implement a notify() method, which will receive events distributed by the EventManager. The signature of the method looks like the following:

class OwnObject:
    ...
    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:
    ...
    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 following example is a complete example based on the excerpts from above. You can find it as python script under examples/eventmanager.py

# EventManager usage example.
from ocempgui.events import EventManager

# Create a new event capable object. This can be acquired by adding a
# 'notify ()' method to the object, which receives a single argument.
class OwnObject:
    def __init__ (self):
        self.x = 0
        self.y = 0
    
    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)

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

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

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

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

# Send the 'clicked' event once more.
manager.emit ("clicked", None)

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

# Send the 'move' event again.
manager.emit ("move", (40, 40))