# Class pyglet.event.EventDispatcher

Known Subclasses:
  sprite.Sprite, media.Player, window.Window, text.layout.IncrementalTextLayout, text.document.AbstractDocument, app.EventLoop

Generic event dispatcher interface.

See the module docstring for usage.

## Methods

| register_event_type(cls, name) Register an event type with the dispatcher.
| push_handlers(self, *args, **kwargs) Push a level onto the top of the handler stack, then attach zero or more event handlers.
| set_handlers(self, *args, **kwargs) Attach one or more event handlers to the top level of the handler stack.
| set_handler(self, name, handler) Attach a single event handler.
| pop_handlers(self) Pop the top level of event handlers off the stack.
| remove_handlers(self, *args, **kwargs) Remove event handlers from the event stack.
| remove_handler(self, name, handler) Remove a single event handler.
| dispatch_event(self, event_type, *args) Dispatch a single event to the attached handlers.
| event(self, *args) Function decorator for an event handler.

## Method Details

### register_event_type

Class Method register_event_type(cls, name)

Register an event type with the dispatcher.

Registering event types allows the dispatcher to validate event handler names as they are attached, and to search attached objects for suitable handlers.

Parameters:
  name : str
    Name of the event to register.

### push_handlers

push_handlers(self, *args, **kwargs)

Push a level onto the top of the handler stack, then attach zero or more event handlers.

If keyword arguments are given, they name the event type to attach. Otherwise, a callable's `__name__` attribute will be used. Any other object may also be specified, in which case it will be searched for callables with event names.

### set_handlers

set_handlers(self, *args, **kwargs)

Attach one or more event handlers to the top level of the handler stack.

See push_handlers for the accepted argument types.

### set_handler

set_handler(self, name, handler)
Attach a single event handler.

Parameters:
  name : str
    Name of the event type to attach to.
  handler : callable
    Event handler to attach.

### remove_handlers

remove_handlers(self, *args, **kwargs)

Remove event handlers from the event stack.

See push_handlers for the accepted argument types. All handlers are removed from the first stack frame that contains any of the given handlers. No error is raised if any handler does not appear in that frame, or if no stack frame contains any of the given handlers.

If the stack frame is empty after removing the handlers, it is removed from the stack. Note that this interferes with the expected symmetry of push_handlers and pop_handlers.

### remove_handler

remove_handler(self, name, handler)

Remove a single event handler.

The given event handler is removed from the first handler stack frame it appears in. The handler must be the exact same callable as passed to set_handler, set_handlers or push_handlers; and the name must match the event type it is bound to.

No error is raised if the event handler is not set.

Parameters:
  name : str
    Name of the event type to remove.
  handler : callable
    Event handler to remove.

### dispatch_event

dispatch_event(self, event_type, *args)

Dispatch a single event to the attached handlers.

The event is propogated to all handlers from from the top of the stack until one returns EVENT_HANDLED. This method should be used only by EventDispatcher implementors; applications should call the `dispatch_events` method.

Parameters:
  event_type : str
    Name of the event.
  args : sequence
    Arguments to pass to the event handler.

### event

event(self, *args)

Function decorator for an event handler.

Usage:

    win = window.Window()

    @win.event
    def on_resize(self, width, height):
        # ...

or:

    @win.event('on_resize')
    def foo(self, width, height):
        # ...