"""Creates an Event Handler
This decorator can be applied to methods of classes derived from
- :class:`circuits.core.components.BaseComponent`. It marks the
+ :class:`circuits.core.components.BaseComponent`. It marks the
method as a handler for the events passed as arguments
to the ``@handler`` decorator. The events are specified by their name.
The decorated method's arguments must match the arguments passed to the
:class:`circuits.core.events.Event` on creation. Optionally, the
method may have an additional first argument named *event*. If declared,
the event object that caused the handler to be invoked is assigned to it.
- By default, the handler is invoked by the component's
+ By default, the handler is invoked by the component's
root :class:`~.manager.Manager` for events that are propagated on
the channel determined by the BaseComponent's *channel* attribute.
This may be overridden by specifying a different channel as a keyword
parameter of the decorator (``channel=...``).
Keyword argument ``priority`` influences the order in which handlers
for a specific event are invoked. The higher the priority, the earlier
A handler may also be specified as a filter by adding
the keyword argument ``filter=True`` to the decorator.
If such a handler returns a value different from ``None``, no more
handlers are invoked for the handled event. Filtering handlers are
invoked before normal handlers with the same priority (but after any
handlers with higher priority).
If you want to override a handler defined in a base class of your
component, you must specify ``override=True``, else your method becomes
an additional handler for the event.
Finally, a handler may be defined as a "tick"-handler by
Such a handler is invoked at regular intervals ("polling").
- Normally, the results returned by the handlers for an event are
- simply collected in the :class:`circuits.core.events.Event`'s
+ Normally, the results returned by the handlers for an event are
+ simply collected in the :class:`circuits.core.events.Event`'s
:attr:`value` attribute. As a special case, a handler may
return a :class:`types.GeneratorType`. This signals to the
dispatcher that the handler isn't ready to deliver a result yet.
- Rather, it has interrupted it's execution with a ``yield None``
+ Rather, it has interrupted it's execution with a ``yield None``
statement, thus preserving its current execution state.
The dispatcher saves the returned generator object as a task.
All tasks are reexamined (i.e. their :meth:`next()` method is invoked)
- when the pending events have been executed.
+ when the pending events have been executed.
This feature avoids an unnecessarily complicated chaining of event
- handlers. Imagine a handler A that needs the results from firing an
+ handlers. Imagine a handler A that needs the results from firing an
event E in order to complete. Then without this feature, the final
action of A would be to fire event E, and another handler for
an event ``SuccessE`` would be required to complete handler A's
operation, now having the result from invoking E available
(actually it's even a bit more complicated).
Using this "suspend" feature, the handler simply fires event E and
then yields ``None`` until e.g. it finds a result in E's :attr:`value`
attribute. For the simplest scenario, there even is a utility
method :meth:`circuits.core.manager.Manager.callEvent` that combines