:right-sidebar: True

SignalListItemFactory
===================================================================

.. currentmodule:: gi.repository.Gtk





.. class:: SignalListItemFactory(**properties: ~typing.Any)
   :no-contents-entry:


Superclasses: :class:`~gi.repository.Gtk.ListItemFactory`, :class:`~gi.repository.GObject.Object`





``GtkSignalListItemFactory`` is a ``GtkListItemFactory`` that emits signals
to manage listitems.

Signals are emitted for every listitem in the same order:

 1. :obj:`~gi.repository.Gtk.SignalListItemFactory.signals.setup` is emitted to set up permanent
 things on the listitem. This usually means constructing the widgets used in
 the row and adding them to the listitem.

 2. :obj:`~gi.repository.Gtk.SignalListItemFactory.signals.bind` is emitted to bind the item passed
 via :obj:`~gi.repository.Gtk.ListItem.props.item` to the widgets that have been created in
 step 1 or to add item-specific widgets. Signals are connected to listen to
 changes - both to changes in the item to update the widgets or to changes
 in the widgets to update the item. After this signal has been called, the
 listitem may be shown in a list widget.

 3. :obj:`~gi.repository.Gtk.SignalListItemFactory.signals.unbind` is emitted to undo everything
 done in step 2. Usually this means disconnecting signal handlers. Once this
 signal has been called, the listitem will no longer be used in a list
 widget.

 4. :obj:`~gi.repository.Gtk.SignalListItemFactory.signals.bind` and
 :obj:`~gi.repository.Gtk.SignalListItemFactory.signals.unbind` may be emitted multiple times
 again to bind the listitem for use with new items. By reusing listitems,
 potentially costly setup can be avoided. However, it means code needs to
 make sure to properly clean up the listitem in step 3 so that no information
 from the previous use leaks into the next use.

5. :obj:`~gi.repository.Gtk.SignalListItemFactory.signals.teardown` is emitted to allow undoing
the effects of :obj:`~gi.repository.Gtk.SignalListItemFactory.signals.setup`. After this signal
was emitted on a listitem, the listitem will be destroyed and not be used again.

Note that during the signal emissions, changing properties on the
listitems passed will not trigger notify signals as the listitem's
notifications are frozen. See :func:`~gi.repository.GObject.GObject.Object.freeze_notify` for details.

For tracking changes in other properties in the listitem, the
::notify signal is recommended. The signal can be connected in the
:obj:`~gi.repository.Gtk.SignalListItemFactory.signals.setup` signal and removed again during
:obj:`~gi.repository.Gtk.SignalListItemFactory.signals.teardown`.



Constructors
------------

.. rst-class:: interim-class

.. class:: SignalListItemFactory
   :no-index:


   .. classmethod:: new() -> ~gi.repository.Gtk.ListItemFactory

      Creates a new ``GtkSignalListItemFactory``.

      You need to connect signal handlers before you use it.


















Signals
-------

.. rst-class:: interim-class

.. class:: SignalListItemFactory.signals
   :no-index:
   

   .. method:: bind(object: ~gi.repository.GObject.Object) -> None

      Emitted when an object has been bound, for example when a
      new :obj:`~gi.repository.Gtk.ListItem.props.item` has been set on a
      listitem and should be bound for use.

      After this signal was emitted, the object might be shown in
      a :obj:`~gi.repository.Gtk.ListView` or other widget.

      The :obj:`~gi.repository.Gtk.SignalListItemFactory.signals.unbind` signal is the
      opposite of this signal and can be used to undo everything done
      in this signal.







      :param object: The ``GObject`` to bind





   .. method:: setup(object: ~gi.repository.GObject.Object) -> None

      Emitted when a new listitem has been created and needs to be setup for use.

      It is the first signal emitted for every listitem.

      The :obj:`~gi.repository.Gtk.SignalListItemFactory.signals.teardown` signal is the opposite
      of this signal and can be used to undo everything done in this signal.







      :param object: The ``GObject`` to set up





   .. method:: teardown(object: ~gi.repository.GObject.Object) -> None

      Emitted when an object is about to be destroyed.

      It is the last signal ever emitted for this ``object``.

      This signal is the opposite of the :obj:`~gi.repository.Gtk.SignalListItemFactory.signals.setup`
      signal and should be used to undo everything done in that signal.







      :param object: The ``GObject`` to tear down





   .. method:: unbind(object: ~gi.repository.GObject.Object) -> None

      Emitted when an object has been unbound from its item, for example when
      a listitem was removed from use in a list widget
      and its :obj:`~gi.repository.Gtk.ListItem.props.item` is about to be unset.

      This signal is the opposite of the :obj:`~gi.repository.Gtk.SignalListItemFactory.signals.bind`
      signal and should be used to undo everything done in that signal.







      :param object: The ``GObject`` to unbind