Go to the latest version of this document.

# ``twisted`.`words`.`xish`.`utility`.`EventDispatcher``

class documentation

`class EventDispatcher: (source)`

Known subclasses: `twisted.words.xish.xmlstream.XmlStream`

Constructor: `EventDispatcher(eventprefix)`

View In Hierarchy

Event dispatching service.

The `EventDispatcher` allows observers to be registered for certain events that are dispatched. There are two types of events: XPath events and Named events.

Every dispatch is triggered by calling `dispatch` with a data object and, for named events, the name of the event.

When an XPath type event is dispatched, the associated object is assumed to be an `Element` instance, which is matched against all registered XPath queries. For every match, the respective observer will be called with the data object.

A named event will simply call each registered observer for that particular event name, with the data object. Unlike XPath type events, the data object is not restricted to `Element`, but can be anything.

When registering observers, the event that is to be observed is specified using an `xpath.XPathQuery` instance or a string. In the latter case, the string can also contain the string representation of an XPath expression. To distinguish these from named events, each named event should start with a special prefix that is stored in `self.prefix`. It defaults to `//event/`.

Observers registered using `addObserver` are persistent: after the observer has been triggered by a dispatch, it remains registered for a possible next dispatch. If instead `addOnetimeObserver` was used to observe an event, the observer is removed from the list of observers after the first observed event.

Observers can also be prioritized, by providing an optional `priority` parameter to the `addObserver` and `addOnetimeObserver` methods. Higher priority observers are then called before lower priority observers.

Finally, observers can be unregistered by using `removeObserver`.

Method | `__init__` | Undocumented
Method | `addObserver` | Register an observer for an event.
Method | `addOnetimeObserver` | Register a one-time observer for an event.
Method | `dispatch` | Dispatch an event.
Method | `removeObserver` | Remove callable as observer for an event.
Instance Variable | `prefix` | Undocumented
Method | `_addObserver` | Undocumented
Method | `_getEventAndObservers` | Undocumented
Instance Variable | `_dispatchDepth` | Undocumented
Instance Variable | `_eventObservers` | Undocumented
Instance Variable | `_updateQueue` | Undocumented
Instance Variable | `_xpathObservers` | Undocumented

def __init__(self, eventprefix='//event/'): (source)
overridden in `twisted.words.xish.xmlstream.XmlStream`

Undocumented

def addObserver(self, event, observerfn, priority=0, *args, **kwargs): (source)

Register an observer for an event.

Each observer will be registered with a certain priority. Higher priority observers get called before lower priority observers.

Parameters
event:`str` or `xpath.XPathQuery`. | Name or XPath query for the event to be monitored.
observerfn | Function to be called when the specified event has been triggered. This callable takes one parameter: the data object that triggered the event. When specified, the `*args` and `**kwargs` parameters to addObserver are being used as additional parameters to the registered observer callable.
priority:`int` | (Optional) priority of this observer in relation to other observer that match the same event. Defaults to `0`.
*args | Undocumented
**kwargs | Undocumented

def addOnetimeObserver(self, event, observerfn, priority=0, *args, **kwargs): (source)

Register a one-time observer for an event.

Like `addObserver`, but is only triggered at most once. See there for a description of the parameters.

def dispatch(self, obj, event=None): (source)

Dispatch an event.

When `event` is `None`, an XPath type event is triggered, and `obj` is assumed to be an instance of `Element`. Otherwise, `event` holds the name of the named event being triggered. In the latter case, `obj` can be anything.

Parameters
obj | The object to be dispatched.
event:`str` | Optional event name.

def removeObserver(self, event, observerfn): (source)

Remove callable as observer for an event.

The observer callable is removed for all priority levels for the specified event.

Parameters
event:`str` or `xpath.XPathQuery` | Event for which the observer callable was registered.
observerfn | Observer callable to be unregistered.

prefix = (source)

Undocumented

def _addObserver(self, onetime, event, observerfn, priority, *args, **kwargs): (source)

Undocumented

def _getEventAndObservers(self, event): (source)

Undocumented

_dispatchDepth: `int` = (source)

Undocumented

_eventObservers: `dict` = (source)

Undocumented

_updateQueue: `list` = (source)

Undocumented

_xpathObservers: `dict` = (source)

Undocumented