Class Callback

source code

Callback and signal support objects.

Declaring signals

Classes that want to emit signals need to inherit from the DBCallback class and ensure that its __init__ method is called. They then need to declare the signals that they can emit and the types of each callbacks arguments. For example:

   class TestSignals(Callback):

       __signals__ = {
                 'test-signal' : (int, ), 
                 'test-noarg'  : None
                }

       def __init__(self):
           Callback.__init__(self)

The type signature is a tuple of types or classes. The type checking code uses the isinstance method to check that the argument passed to the emit call is an instance of the type in the signature declaration.

If the signal does not have an argument use None as the signature.

The signals will be inherited by any subclasses. Duplicate signal names in subclasses are not alowed.

Emitting signals

Signals are emitted using the emit method. e.g.:

       def emit_signal(self):
           self.emit('test-signal', (1, ))

The parameters are passed as a tuple so a single parameter must be passed as a 1 element tuple.

Connecting callbacks to signals

Attaching a callback to the signals is similar to the gtk connect methods. e.g.:

   # connect to a function.
   def fn(i):
       print 'got signal value = ', i

   t = TestSignals()
   t.connect('test-signal', fn)

   # connect to a bound method
   class C(object):

       def cb_func(self, i):
           print 'got class signal = ', 1

   r = R()
   t.connect('test-signal', r.cb_func)

Disconnecting callbacks

If you want to disconnect a callback from a signals you must remember the key returned from the connect call. This key can be passed to the disconnect method to remove the callback from the signals callback list.

e.g.:

   t = TestSignals()

   # connect to a bound method
   class C(object):

       def cb_func(self, i):
           print 'got class signal = ', 1

   r = R()
   key = t.connect('test-signal', r.cb_func)

   ...

   t.disconnect(key)

Stopping and starting signals

Signals can be blocked on a per instance bassis or they can be blocked for all instances of the Callback class. disable_signals() can be used to block the signals for a single instance and disable_all_signals() can be used to block signals for the class:

e.g.:

      class TestSignals(Callback):

       __signals__ = {
                 'test-signal' : (int, ), 
                 'test-noarg'  : None
                }

       def __init__(self):
           Callback.__init__(self)

       def emit_signal(self):
           self.emit('test-signal', (1, ))

       t = TestSignals()

       # block signals from instance t
       t.disable_signals()

       ...
       
       # unblock
       t.enable_signals()

       # block all signals
       Callback.disable_all_signals()

       ...
       
       # unblock all signals
       Callback.enable_all_signals()

Any signals emitted whilst signals are blocked will be lost.

Debugging signal callbacks

To help with debugging the signals and callbacks you can turn on lots of logging information. To switch on logging for a single instance call self.enable_logging(), to switch it off again call self.disable_logging(). To switch on logging for all instance you can toggle Callback.__LOG_ALL to True.