========================== ``grail.objsignal`` module ========================== .. include:: ..\version.h .. include:: ..\Library_Reference\lib-reference.h .. contents:: Table of Contents :backlinks: top ----------- Description ----------- Allows for configure objects to emit signals, and for other objects to wait on signals If you want to compose an object capable of 'emitting' signals mix in the 'Emitter' class. This class will take care of all the necessary resource acquisition/release issues for you. If you want to express interest in the emission of signals (i.e. listen or an object's signal), use the :f:`listen` function. If you want to express that you are no longer interested in a signal emitted by an object, use the :f:`ignore` function. If you want to temporarily disable listening to an object, and then enable the listening at a later time, then use the :f:`ignorelisten` and :f:`resumelisten` functions. These should be the only functions that you should use from this module. --------- Functions --------- :df:`endlisten(emitter, signal, receiver)` Removes a listener from the list of objects interested in a signal emitted by the emitter. :df:`ignorelisten(signal, callback)` Allows you to temporarily ignore a signal for a callback function. :df:`isvalidsignal(emitter, signal)` Determines if a signal is valid for a given emitter; assumes that the emitter is valid. :df:`listen(emitter, signal, receiver, callback)` Registers that when the :a:`emitter` object emits the given :a:`signal` that the objsignal module should call the given :a:`callback`. The :a:`receiver` parameter is optional an could be :d:`None` or the object containing the callback. :df:`registerCallback(emitter, signal, receiver, callback)` Register that when the :c:`Emitter` emits the given signal, that we should make the given callback for the given :a:`receiver` object. Callback should be capable of accepting the object emitter object :df:`restartregistry()` Allows one to completely tear down the old registry and start anew. *Mainly for automated testing purposes.* :df:`resumelisten(signal, callback) method of Registry instance` Allows you to resume listening to a signal that you flagged to ignore with :f:`ignoreSignal`. ------- Classes ------- The ``objsignal`` module contains two classes. The :c:`Emitter` class is a useful mix-in class to help make another object capable work within the object-signalling framework. The :c:`Registry` class is used to manage the object transmitter-receiver relationships during signal broadcasts and is typically for *internal usage only*. Emitter Class ------------- class :dc:`Emitter([SIGNALS])` Mix in class that handles all the emitter/receiver concepts. this class should be mixed into any object that will be a potential emitter. if you wish to configure your object for potential emission, it should make a call to the initialization method with a list of signals that it can emit. An example of its usage would be, .. Python:: class MyClass(Emitter): SIGNALS = ['sig1', 'sig2'] def __init__(self): Emitter.__init__(self, self.SIGNALS) def generateSignal(self): self.emit('sig1') # emits a 'sig1' from this object that would emit 'sig1' in the :f:`generateSignal()` function. :df:`emit(signal, *arguments, **keywords)` Emits the signal. :df:`signals()` Returns valid signals for this object. Registry Class --------------- class :dc:`Registry` *Internal usage only*. Class serves as the handler of all emitters, receivers, and signals. :df:`emit(emitter, signal, *args, **kws)` When an 'event' has happened, this is 'emitted'. Hunt through the available dictionary entries to see if there exists and object that can emit the given signal and can then emit that signal. :df:`getSignals(emitter)` returns a list of signals that a particular emitter emits :df:`ignorelisten(signal, callback)` Allows you to temporarily ignore a signal for a callback function. :df:`isCallbacks(emitter, signal)` Indicates if there are any callbacks dependent on the given signal. :df:`isEmitter(emitter)` Indicates if the emitter has been registered or not :df:`isIgnoreListen(signal, callback)` Indicates if the signal,callback pair is on the ignore list or not. :df:`isvalidsignal(emitter, signal)` Determines if a signal is valid for a given emitter; assumes that the emitter is valid. :df:`registerCallback(emitter, signal, receiver, callback)` Register that when the :a:`emitter` object emits the given signal that we should make the given callback for the given :a:`receiver` object. Callback should be capable of accepting the :a:`emitter` object. :df:`registerEmitter(emitter, signals)` Register a new object, and the possible signals it can make, signals must be a list. :df:`resumelisten(signal, callback)` Allows you to resume listening to a signal that you flagged to ignore with :f:`ignoreSignal`. :df:`unregisterEmitter(emitter)` Removes an object from the registry. :df:`unregisterListener(emitter, signal, receiver)` Removes a listener from the list of objects interested in a signal emitted by the emitter. --------- Exception --------- class :de:`Error` Defines errors that can be thrown by exceptions defined in this module.