:right-sidebar: True SignalGroup =================================================================== .. currentmodule:: gi.repository.GObject .. versionadded:: 2.72 .. class:: SignalGroup(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` ``GSignalGroup`` manages a collection of signals on a ``GObject``\. ``GSignalGroup`` simplifies the process of connecting many signals to a ``GObject`` as a group. As such there is no API to disconnect a signal from the group. In particular, this allows you to: - Change the target instance, which automatically causes disconnection of the signals from the old instance and connecting to the new instance. - Block and unblock signals as a group - Ensuring that blocked state transfers across target instances. One place you might want to use such a structure is with ``GtkTextView`` and ``GtkTextBuffer``\. Often times, you'll need to connect to many signals on ``GtkTextBuffer`` from a ``GtkTextView`` subclass. This allows you to create a signal group during instance construction, simply bind the ``GtkTextView:buffer`` property to ``GSignalGroup:target`` and connect all the signals you need. When the ``GtkTextView:buffer`` property changes all of the signals will be transitioned correctly. Constructors ------------ .. rst-class:: interim-class .. class:: SignalGroup :no-index: .. classmethod:: new(target_type: ~gobject.GType) -> ~gi.repository.GObject.SignalGroup Creates a new :obj:`~gi.repository.GObject.SignalGroup` for target instances of ``target_type``\. .. versionadded:: 2.72 :param target_type: the :obj:`~gi.repository.GObject.Type` of the target instance. Methods ------- .. rst-class:: interim-class .. class:: SignalGroup :no-index: .. method:: block() -> None Blocks all signal handlers managed by ``self`` so they will not be called during any signal emissions. Must be unblocked exactly the same number of times it has been blocked to become active again. This blocked state will be kept across changes of the target instance. .. versionadded:: 2.72 .. method:: connect_closure(detailed_signal: str, closure: ~gi.repository.GObject.Closure, after: bool) -> None Connects ``closure`` to the signal ``detailed_signal`` on :obj:`~gi.repository.GObject.SignalGroup`\:target. You cannot connect a signal handler after :obj:`~gi.repository.GObject.SignalGroup`\:target has been set. .. versionadded:: 2.74 :param detailed_signal: a string of the form ``signal-name`` with optional ``::signal-detail`` :param closure: the closure to connect. :param after: whether the handler should be called before or after the default handler of the signal. .. method:: connect_data(detailed_signal: str, c_handler: ~typing.Callable[[], None], data: ~typing.Any, flags: ~gi.repository.GObject.ConnectFlags) -> None Connects ``c_handler`` to the signal ``detailed_signal`` on the target instance of ``self``\. You cannot connect a signal handler after :obj:`~gi.repository.GObject.SignalGroup`\:target has been set. .. versionadded:: 2.72 :param detailed_signal: a string of the form "signal-name::detail" :param c_handler: the :obj:`~gi.repository.GObject.Callback` to connect :param data: the data to pass to ``c_handler`` calls :param flags: the flags used to create the signal connection .. method:: connect_swapped(detailed_signal: str, c_handler: ~typing.Callable[[], None], data: ~typing.Any = None) -> None Connects ``c_handler`` to the signal ``detailed_signal`` on the target instance of ``self``\. The instance on which the signal is emitted and ``data`` will be swapped when calling ``c_handler``\. You cannot connect a signal handler after :obj:`~gi.repository.GObject.SignalGroup`\:target has been set. .. versionadded:: 2.72 :param detailed_signal: a string of the form "signal-name::detail" :param c_handler: the :obj:`~gi.repository.GObject.Callback` to connect :param data: the data to pass to ``c_handler`` calls .. method:: dup_target() -> ~gi.repository.GObject.Object | None Gets the target instance used when connecting signals. .. versionadded:: 2.72 .. method:: set_target(target: ~gi.repository.GObject.Object | None = None) -> None Sets the target instance used when connecting signals. Any signal that has been registered with :func:`~gi.repository.GObject.SignalGroup.connect_object` or similar functions will be connected to this object. If the target instance was previously set, signals will be disconnected from that object prior to connecting to ``target``\. .. versionadded:: 2.72 :param target: The target instance used when connecting signals. .. method:: unblock() -> None Unblocks all signal handlers managed by ``self`` so they will be called again during any signal emissions unless it is blocked again. Must be unblocked exactly the same number of times it has been blocked to become active again. .. versionadded:: 2.72 Properties ---------- .. rst-class:: interim-class .. class:: SignalGroup :no-index: .. attribute:: props.target :type: ~gi.repository.GObject.Object The type of the None singleton. .. versionadded:: 2.72 .. attribute:: props.target_type :type: ~gobject.GType The type of the None singleton. .. versionadded:: 2.72 Signals ------- .. rst-class:: interim-class .. class:: SignalGroup.signals :no-index: .. method:: bind(instance: ~gi.repository.GObject.Object) -> None The type of the None singleton. .. versionadded:: 2.72 :param instance: a :obj:`~gi.repository.GObject.Object` containing the new value for :obj:`~gi.repository.GObject.SignalGroup`\:target .. method:: unbind() -> None The type of the None singleton. .. versionadded:: 2.72