Panda3D Manual: Event Handlers
  <<prev top next>>  

Events occur when the user does something, such as clicking a mouse or pressing a key. When an event occurs, Panda's "messenger" will check to see if you have written an "event handler" routine. If so, your event handler will be called. The messenger system is object-oriented, to create an event handler, you have to first create a class that inherits from DirectObject. Your event handler will be a method of your class.

Defining a class that can Handle Events

The first step is to import class DirectObject:

from direct.showbase import DirectObject

With DirectObject loaded, it is possible to create a subclass of DirectObject. This allows the class to inherit the messaging API and thus listen for events.

class myClassName(DirectObject.DirectObject):

The sample below creates a class that can listen for events. The "accept" function notifies panda that the printHello method is an event handler for the mouse1 event. The "accept" function and the various event names will be explained in detail later.

class Hello(DirectObject.DirectObject):
  def __init__(self):
    self.accept('mouse1',self.printHello)
  def printHello(self):
    print 'Hello!'
h = Hello()

Event Handling Functions

Events first go to a mechanism built into panda called the "Messenger." The messenger may accept or ignore events that it receives. If it accepts an event, then an event handler will be called. If ignored, then no handler will be called. Key and mouse depressions and releases are events that may be sent. Typically, depressions are labeled as whatever key or button was hit. Releases are labeled as the key or button plus “-up.” So when checking to see if the escape key is hit, an object would listen for “escape.” If checking to see if it was released, then the object listens to “escape-up.” Not all events have to be key and mouse hits. One may create their own event and send it to the messenger.

An object may accept an event an infinite number of times or accept it only once. If checking for an accept within the object listening to it, it should be prefixed with self. If the accept command occurs outside the class, then the variable the class is associated with should be used.

myDirectObject.accept('Event Name',myDirectObjectMethod)
myDirectObject.acceptOnce('Event Name',myDirectObjectMethod)

It is also possible to send an event to the messenger without any sort of outside input.

messenger.send('Event Name')

Specific events may be ignored, so that no message is sent. Also, all events coming from an object may be ignored.

myDirectObject.ignore('Event Name')
myDirectObject.ignoreAll()

Finally, there are some useful utility functions for debugging. The messenger typically does not print out when every event occurs. Toggling verbose mode will make the messenger print every event it receives. Toggling it again will revert it to the default. A number of methods exist for checking to see what object is checking for what event, but the print method will show who is accepting each event. Also, if accepts keep changing to the point where it is too confusing, the clear method will start the messenger over with a clear dictionary.

messenger.toggleVerbose()
print messenger
messenger.clear()

  <<prev top next>>