Eventbus overview

You can register your events and event handlers with the Eventbus package:

Usage

You can use your own events directly with an event handler that you register on the eventbus.

1. Import the system.eventbus package:

   from system.eventbus import eventbus
   

2. Define an event:

   class SpecialEvent:
   def __init__(self):
       pass
   
   def __str__(self):
       return "special event"
   

3. Define a synchronous or asynchronous method to be called when the event occurs:

   def handle_event(self, event):
       # do something
   

   async def handle_event_async(self, event):
       # do something
   

4. Register your event handler, for example in the __init__ method of your app with the event and the event handler. Depending on whether the event handler is a synchronous or asynchronous method call on() or on_async():

   def __init__(self):
       eventbus.on(SpecialEvent, self.handle_event, self.app)
   

   def __init__(self):
       eventbus.on_async(SpecialEvent, self.handle_event_async, self.app)
   

5. Add code to emit the event, for example in your app's update() method. Depending on whether the event handler is a synchronous or asynchronous method call emit() or emit_async():

   def update(self, delta):
       # If something happens
       eventbus.emit(SpecialEvent())
   

   async def update(self, delta):
       # If something happens
       await eventbus.emit_async(SpecialEvent())
   

6. Remove the event handler when the app is minimised or closed.

   eventbus.remove(SpecialEvent, self.handle_event, self.app)
   

   Warning

   Make sure you remove the event handler when the app is minimised or closed!

You can see a more comprehensive example in dialog.py or pingpong_app.py.

Methods

You can use the following methods on the eventbus: