docs/guide/api/signals.rst

   1 =======
   2 Signals
   3 =======
   4
   5 GObject signals are a system for registering callbacks for specific events.
   6
   7 To find all signals of a class you can use the
   8 :func:`GObject.signal_list_names` function:
   9
  10
  11 .. code:: pycon
  12
  13     >>> GObject.signal_list_names(Gio.Application)
  14     ('activate', 'startup', 'shutdown', 'open', 'command-line', 'handle-local-options')
  15     >>>
  16
  17
  18 To connect to a signal, use :meth:`GObject.Object.connect`:
  19
  20 .. code:: pycon
  21
  22     >>> app = Gio.Application()
  23     >>> def on_activate(instance):
  24     ...     print("Activated:", instance)
  25     ...
  26     >>> app.connect("activate", on_activate)
  27     17L
  28     >>> app.run()
  29     ('Activated:', <Gio.Application object at 0x7f1bbb304320 (GApplication at 0x5630f1faf200)>)
  30     0
  31     >>>
  32
  33 It returns number which identifies the connection during its lifetime and which
  34 can be used to modify the connection.
  35
  36 For example it can be used to temporarily ignore signal emissions using
  37 :meth:`GObject.Object.handler_block`:
  38
  39 .. code:: pycon
  40
  41     >>> app = Gio.Application(application_id="foo.bar")
  42     >>> def on_change(*args):
  43     ...     print(args)
  44     ...
  45     >>> c = app.connect("notify::application-id", on_change)
  46     >>> app.props.application_id = "foo.bar"
  47     (<Gio.Application object at 0x7f1bbb304550 (GApplication at 0x5630f1faf2b0)>, <GParamString 'application-id'>)
  48     >>> with app.handler_block(c):
  49     ...     app.props.application_id = "no.change"
  50     ...
  51     >>> app.props.application_id = "change.again"
  52     (<Gio.Application object at 0x7f1bbb304550 (GApplication at 0x5630f1faf2b0)>, <GParamString 'application-id'>)
  53     >>>
  54
  55
  56 You can define your own signals using the :obj:`GObject.Signal` decorator:
  57
  58
  59 .. function:: GObject.Signal(name='', flags=GObject.SignalFlags.RUN_FIRST, \
  60     return_type=None, arg_types=None, accumulator=None, accu_data=None)
  61
  62     :param str name: The signal name
  63     :param GObject.SignalFlags flags: Signal flags
  64     :param GObject.GType return_type: Return type
  65     :param list arg_types: List of :class:`GObject.GType` argument types
  66     :param accumulator: Accumulator function
  67     :type accumulator: :obj:`GObject.SignalAccumulator`
  68     :param object accu_data: User data for the accumulator
  69
  70
  71 .. code:: python
  72
  73     class MyClass(GObject.Object):
  74
  75         @GObject.Signal(flags=GObject.SignalFlags.RUN_LAST, return_type=bool,
  76                         arg_types=(object,),
  77                         accumulator=GObject.signal_accumulator_true_handled)
  78         def test(self, *args):
  79             print("Handler", args)
  80
  81         @GObject.Signal
  82         def noarg_signal(self):
  83             print("noarg_signal")
  84
  85     instance = MyClass()
  86
  87     def test_callback(inst, obj):
  88         print "Handled", inst, obj
  89         return True
  90
  91     instance.connect("test", test_callback)
  92     instance.emit("test", object())
  93
  94     instance.emit("noarg_signal")