:right-sidebar: True SidebarSection =================================================================== .. currentmodule:: gi.repository.Adw .. versionadded:: 1.9 .. class:: SidebarSection(**properties: ~typing.Any) :no-contents-entry: Superclasses: :class:`~gi.repository.GObject.Object` Implemented Interfaces: :class:`~gi.repository.Gtk.Buildable` A section within :obj:`~gi.repository.Adw.Sidebar`\. ``AdwSidebarSection`` contains :obj:`~gi.repository.Adw.SidebarItem` objects. Section can optionally have a title, set with the :obj:`~gi.repository.Adw.SidebarSection.props.title` property. If a title is not set, the section will have a separator in front of it, or just spacing in the :obj:`~gi.repository.Adw.SidebarMode.page` mode. To add items, use :obj:`~gi.repository.SidebarSection.append`\, :obj:`~gi.repository.SidebarSection.prepend` or :obj:`~gi.repository.SidebarSection.insert`\. To remove items, use :obj:`~gi.repository.SidebarSection.remove` or :obj:`~gi.repository.SidebarSection.remove_all`\. To inspect the items, use :obj:`~gi.repository.SidebarSection.get_item` or :obj:`~gi.repository.Adw.SidebarSection.props.items`\. To get the sidebar the section is in, use:obj:`~gi.repository.Adw.SidebarSection.props.sidebar`\. Binding models -------------------------------------------------------------------------------- ``AdwSidebarSection`` can show items from a provided :obj:`~gi.repository.Gio.ListModel`\, using :obj:`~gi.repository.SidebarSection.bind_model`\. It works the same way as :obj:`~gi.repository.Gtk.ListBox.bind_model`\, except the provided function creates an :obj:`~gi.repository.Adw.SidebarItem` rather than a :obj:`~gi.repository.Gtk.ListBoxRow`\. While a model is bound, adding or removing items manually is not allowed. Inspecting them is still allowed, but discouraged. -------------------------------------------------------------------------------- ``AdwSidebarSection`` allows adding items as children. Example of an ``AdwSidebarSection`` UI definition: .. code-block:: xml :dedent: Places Music folder-music-symbolic Pictures folder-pictures-symbolic Videos folder-videos-symbolic Result: .. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/sidebar-section.png Constructors ------------ .. rst-class:: interim-class .. class:: SidebarSection :no-index: .. classmethod:: new() -> ~gi.repository.Adw.SidebarSection Creates a new ``AdwSidebarSection``\. .. versionadded:: 1.9 Methods ------- .. rst-class:: interim-class .. class:: SidebarSection :no-index: .. method:: append(item: ~gi.repository.Adw.SidebarItem) -> None Appends ``item`` to ``self``\. Cannot be used while a model is bound via :obj:`~gi.repository.SidebarSection.bind_model`\. .. versionadded:: 1.9 :param item: an item to append .. method:: bind_model(model: ~gi.repository.Gio.ListModel | None = None, create_item_func: ~collections.abc.Callable[[~gi.repository.GObject.Object, ~typing.Any], ~gi.repository.Adw.SidebarItem] | None = None, user_data: ~typing.Any = None) -> None Binds ``model`` to ``self``\. If ``self`` was already bound to a model, that previous binding is destroyed. The contents of ``self`` are cleared and then filled with items that represent items from ``model``\. ``self`` is updated whenever ``model`` changes. If ``model`` is ``NULL``\, ``self`` is left empty. Calling :obj:`~gi.repository.SidebarSection.prepend`\, :obj:`~gi.repository.SidebarSection.insert`\, :obj:`~gi.repository.SidebarSection.append`\, :obj:`~gi.repository.SidebarSection.remove` or :obj:`~gi.repository.SidebarSection.remove_all` while a model is bound is not allowed. Accessing items and modifying them is allowed, but the changes will be erased whenever that part of the model changes, so it's not recommended. .. versionadded:: 1.9 :param model: the model to be bound :param create_item_func: a function that creates :obj:`~gi.repository.Adw.SidebarItem` for model items, or ``NULL`` in case ``model`` is also ``NULL`` :param user_data: user data passed to ``create_widget_func`` .. method:: get_item(index: int) -> ~gi.repository.Adw.SidebarItem | None Gets the item at ``index`` within ``self``\. The index starts from 0 at the top of the section, and is same as the one returned by :obj:`~gi.repository.SidebarItem.get_section_index`\. Can return ``NULL`` if ``index`` is larger or equal to the number of items. .. versionadded:: 1.9 :param index: index of the item .. method:: get_items() -> ~gi.repository.Gio.ListModel Gets a list model with ``self``\'s items. This can be used to keep an up-to-date view. .. versionadded:: 1.9 .. method:: get_menu_model() -> ~gi.repository.Gio.MenuModel | None Gets the context menu model for ``self``\'s items. .. versionadded:: 1.9 .. method:: get_sidebar() -> ~gi.repository.Adw.Sidebar | None Gets the sidebar ``self`` is in. .. versionadded:: 1.9 .. method:: get_title() -> str | None Gets the title of ``self``\. .. versionadded:: 1.9 .. method:: insert(item: ~gi.repository.Adw.SidebarItem, position: int) -> None Inserts ``item`` at ``position`` to ``self``\. If ``position`` is -1, or larger than the total number of items in ``self``\, the item will be appended to the end. Cannot be used while a model is bound via :obj:`~gi.repository.SidebarSection.bind_model`\. .. versionadded:: 1.9 :param item: an item to insert :param position: position to insert ``item`` at .. method:: prepend(item: ~gi.repository.Adw.SidebarItem) -> None Prepends ``item`` to ``self``\. Cannot be used while a model is bound via :obj:`~gi.repository.SidebarSection.bind_model`\. .. versionadded:: 1.9 :param item: an item to prepend .. method:: remove(item: ~gi.repository.Adw.SidebarItem) -> None Removes ``item`` from ``self``\. Cannot be used while a model is bound via :obj:`~gi.repository.SidebarSection.bind_model`\. .. versionadded:: 1.9 :param item: an item to remove .. method:: remove_all() -> None Removes all items from ``self``\. Cannot be used while a model is bound via :obj:`~gi.repository.SidebarSection.bind_model`\. .. versionadded:: 1.9 .. method:: set_menu_model(menu_model: ~gi.repository.Gio.MenuModel | None = None) -> None Sets the context menu model for ``self``\'s items. When a context menu is shown for an item, it will be constructed from the provided menu model. Use the :obj:`~gi.repository.Adw.Sidebar.signals.setup_menu` signal to set up the menu actions for the particular item. If not set, :obj:`~gi.repository.Adw.Sidebar.props.menu_model` will be used instead. .. versionadded:: 1.9 :param menu_model: a menu model .. method:: set_title(title: str | None = None) -> None Sets the title of ``self``\. If set, it will be displayed instead of the separator before the section. .. versionadded:: 1.9 :param title: the title Properties ---------- .. rst-class:: interim-class .. class:: SidebarSection :no-index: .. attribute:: props.items :type: ~gi.repository.Gio.ListModel The type of the None singleton. .. versionadded:: 1.9 .. attribute:: props.menu_model :type: ~gi.repository.Gio.MenuModel The type of the None singleton. .. versionadded:: 1.9 .. attribute:: props.sidebar :type: ~gi.repository.Adw.Sidebar The type of the None singleton. .. versionadded:: 1.9 .. attribute:: props.title :type: str The type of the None singleton. .. versionadded:: 1.9