Event-Handler

This is an archived page! This page is very old and the content is not up to date. Not everything (if any) which is written here will be in the final game!

Maintainer: Patrick Boenzli, boenzli at orxonox.ethz.ch

Overview

All files used for event handling are located in the ./src/util/event directory. Here a short overview:

• event_handler.{cc, h} - this is where all the event handling is going on: signals from the SDL env are interpreted and transmitted to the registered event listener
• event_listener.{cc, h} - this is an abstract class. A class that extends it will have to implement all abstract functions (process(...)) and will be able to register itself to the EventHandler to receive events.
• event.{cc, h} - a small class representing an event, that has occured
• key_mapper.{cc, h} - a parser, that reads in the orxonox.conf file and translates the keynames to key-ids used in orxonox
• key_names.{cc, h} - a file containig all key names with key-ids

Usage

The usage of the EventHandler System is realy stright forward: consider a case, where you have a !PNode, that wants to receive some key-events:
The pilot_me.h could look like this:

#include "p_node.h"
#include "event_listener.h"

class Event;                                         // forward declaration of a Event class

class PilotMe : public PNode, public EventListener   // extending EventListener
{
   PilotMe();
   virtual ~PilotMe();

   void process(const Event &event);                // abstract process class

};

The pilot_me.cc class could look like this:

#include "pilot_me.h"
#include "event_listener.h"                        //the event listener interface
#include "event.h"                                 //the event structure

PilotMe::PilotMe()
{
  EventHandler::getInstance()->subscribe(this, ES_GAME, SDLK_LEFT);  //subscribe this class to the left-key  
  EventHandler::getInstance()->subscribe(this, ES_GAME, SDLK_RIGHT); //subscribe this class to the right-key
}

PilotMe::~PilotMe()
{
  EventHandler::getInstance()->unsubscribe(this);  //just unsubscribe all subscribtions of this class
}
.
void PilotMe::process(const Event &event)
{
  if( event.type == SDLK_LEFT)
  {
    if( event.bPressed == true)
      // whatever you want to do, when the left button is pressed 
    else 
      // whatever you want to do, when the left button is released 
  }
  else if( event.type == SDLK_RIGHT)
  {  
    if( event.bPressed == true)
      // whatever you want to do, when the right button is pressed 
    else
      // whatever you want to do, when the right button is released 

  }
}

As you have seen, the whole event-management system is very simple, let's review all the necessary steps:

1. Extend EventListener with any class that want to receive events.

2. Implement the void process(const Event &event); function.

3. Subscribe for an event EventHandler::subscribe(EventListener* el, elState state, int keyID).
   You will find the complete list of all SDL Commands in the usr/include/SDL/SDL_keysym.h file. Orxonox has extended the list with some other events, that you will find in ./src/util/event/event_def.h. The elState describes the state of the event handler: When the menu is displayed, there are is a diffrent key mapping than when you are playing the game. So this means that there are different states of the eventhandler: {ES_GAME, ES_MENU, ES_ALL} . So if you subscribe to an event for the state ES_GAME this event will only shoot, if the eventhandler is in this state.

4. Don't forget to unsubscribe the event again via EventHandler::unsubscribe(EventListener* el)
   . If you forget to do this, there will be a reference to an object that is probably not existent anymore, this will most certanly cause a segfault

Advanced

There is some more stuff to say . Its possible to define KeyAliases in the orxonox.conf file. These aliases are wrapped in the KeyMapper class and are available from this class as static variables: Eg:

• KeyMapper::PEV_UP - is the Up Key defined in the config file
• KeyMapper::PEV_FIRE1 - is the fire button defined in the config file
• KeyMapper::PEV_VIEW0 - is the view nr zero key
• …

To see the whole list (and to extend it) read the ./src/util/event/key_mapper.{cc, h} files, they are very short. To subscribe to such an event, you can use the code from above and alter it just a little:

  //subscribe this class to the orxonox.conf left
  EventHandler::getInstance()->subscribe(this, ES_GAME, KeyMapper::PEV_LEFT); 
  //subscribe this class to the orxonox.conf right
  EventHandler::getInstance()->subscribe(this, ES_GAME, KeyMapper::PEV_RIGHT); 

References

To see more references, look at some source code files, eg:

• ./src/world_entities/camera.{cc, h} - the camera can change the view by pressing some keys
• ./src/world_entities/player.{cc, h} - the player shoots and changes location