Signals¶

GObject signals are a system for registering callbacks for specific events.

To find all signals of a class you can use the GObject.signal_list_names() function:

>>> GObject.signal_list_names(Gio.Application)
('activate', 'startup', 'shutdown', 'open', 'command-line', 'handle-local-options')
>>>

To connect to a signal, use GObject.Object.connect():

>>> app = Gio.Application()
>>> def on_activate(instance):
...     print("Activated:", instance)
...
>>> app.connect("activate", on_activate)
17L
>>> app.run()
('Activated:', <Gio.Application object at 0x7f1bbb304320 (GApplication at 0x5630f1faf200)>)
0
>>>

It returns number which identifies the connection during its lifetime and which can be used to modify the connection.

For example it can be used to temporarily ignore signal emissions using GObject.Object.handler_block():

>>> app = Gio.Application(application_id="foo.bar")
>>> def on_change(*args):
...     print(args)
...
>>> c = app.connect("notify::application-id", on_change)
>>> app.props.application_id = "foo.bar"
(<Gio.Application object at 0x7f1bbb304550 (GApplication at 0x5630f1faf2b0)>, <GParamString 'application-id'>)
>>> with app.handler_block(c):
...     app.props.application_id = "no.change"
...
>>> app.props.application_id = "change.again"
(<Gio.Application object at 0x7f1bbb304550 (GApplication at 0x5630f1faf2b0)>, <GParamString 'application-id'>)
>>>

You can define your own signals using the GObject.Signal decorator:

GObject.Signal(name='', flags=GObject.SignalFlags.RUN_FIRST, return_type=None, arg_types=None, accumulator=None, accu_data=None)¶

Parameters:

name (str) – The signal name
flags (GObject.SignalFlags) – Signal flags
return_type (GObject.GType) – Return type
arg_types (list) – List of GObject.GType argument types
accumulator (GObject.SignalAccumulator) – Accumulator function
accu_data (object) – User data for the accumulator

class MyClass(GObject.Object):

    @GObject.Signal(flags=GObject.SignalFlags.RUN_LAST, return_type=bool,
                    arg_types=(object,),
                    accumulator=GObject.signal_accumulator_true_handled)
    def test(self, *args):
        print("Handler", args)

    @GObject.Signal
    def noarg_signal(self):
        print("noarg_signal")

instance = MyClass()

def test_callback(inst, obj):
    print "Handled", inst, obj
    return True

instance.connect("test", test_callback)
instance.emit("test", object())

instance.emit("noarg_signal")