:right-sidebar: True

OverlaySplitView
===================================================================

.. currentmodule:: gi.repository.Adw


.. versionadded:: 1.4




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


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



Implemented Interfaces: :class:`~gi.repository.Adw.Swipeable`, :class:`~gi.repository.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`



A widget presenting sidebar and content side by side or as an overlay.

.. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/overlay-split-view-collapsed.png

``AdwOverlaySplitView`` has two children: sidebar and content, and displays
them side by side.

When :obj:`~gi.repository.Adw.OverlaySplitView.props.collapsed` is set to ``TRUE``\, the sidebar is
instead shown as an overlay above the content widget.

The sidebar can be hidden or shown using the
:obj:`~gi.repository.Adw.OverlaySplitView.props.show_sidebar` property.

Sidebar can be displayed before or after the content, this can be controlled
with the :obj:`~gi.repository.Adw.OverlaySplitView.props.sidebar_position` property.

Collapsing the split view automatically hides the sidebar widget, and
uncollapsing it shows the sidebar. If this behavior is not desired, the
:obj:`~gi.repository.Adw.OverlaySplitView.props.pin_sidebar` property can be used to override it.

``AdwOverlaySplitView`` supports an edge swipe gesture for showing the sidebar,
and a swipe from the sidebar for hiding it. Gestures are only supported on
touchscreen, but not touchpad. Gestures can be controlled with the
:obj:`~gi.repository.Adw.OverlaySplitView.props.enable_show_gesture` and
:obj:`~gi.repository.Adw.OverlaySplitView.props.enable_hide_gesture` properties.

See also :obj:`~gi.repository.Adw.NavigationSplitView`\.

``AdwOverlaySplitView`` is typically used together with an :obj:`~gi.repository.Adw.Breakpoint`
setting the ``collapsed`` property to ``TRUE`` on small widths, as follows:


.. code-block:: xml
    :dedent:

    <object class="AdwWindow">
      <property name="default-width">800</property>
      <property name="default-height">800</property>
      <child>
        <object class="AdwBreakpoint">
          <condition>max-width: 400sp</condition>
          <setter object="split_view" property="collapsed">True</setter>
        </object>
      </child>
      <property name="content">
        <object class="AdwOverlaySplitView" id="split_view">
          <property name="sidebar">
            <!-- ... -->
          </property>
          <property name="content">
            <!-- ... -->
          </property>
        </object>
      </property>
    </object>

``AdwOverlaySplitView`` is often used for implementing the
`utility pane <https://developer.gnome.org/hig/patterns/containers/utility-panes.html>`__
pattern.

Sizing
--------------------------------------------------------------------------------

When not collapsed, ``AdwOverlaySplitView`` changes the sidebar width
depending on its own width.

If possible, it tries to allocate a fraction of the total width, controlled
with the :obj:`~gi.repository.Adw.OverlaySplitView.props.sidebar_width_fraction` property.

The sidebar also has minimum and maximum sizes, controlled with the
:obj:`~gi.repository.Adw.OverlaySplitView.props.min_sidebar_width` and
:obj:`~gi.repository.Adw.OverlaySplitView.props.max_sidebar_width` properties.

The minimum and maximum sizes are using the length unit specified with the
:obj:`~gi.repository.Adw.OverlaySplitView.props.sidebar_width_unit`\.

By default, sidebar is using 25% of the total width, with 180sp as the
minimum size and 280sp as the maximum size.

When collapsed, the preferred width fraction is ignored and the sidebar uses
:obj:`~gi.repository.Adw.OverlaySplitView.props.max_sidebar_width` when possible.

Header Bar Integration
--------------------------------------------------------------------------------

When used inside ``AdwOverlaySplitView``\, :obj:`~gi.repository.Adw.HeaderBar` will automatically
hide the window buttons in the middle.


--------------------------------------------------------------------------------

The ``AdwOverlaySplitView`` implementation of the :obj:`~gi.repository.Gtk.Buildable`
interface supports setting the sidebar widget by specifying “sidebar” as the
“type” attribute of a ``<child>`` element, Specifying “content” child type or
omitting it results in setting the content widget.

CSS nodes
--------------------------------------------------------------------------------

``AdwOverlaySplitView`` has a single CSS node with the name
``overlay-split-view``\.

It contains two nodes with the name ``widget``\, containing the sidebar and
content children.

When not collapsed, they have the ``.sidebar-view`` and ``.content-view`` style
classes respectively.


.. code-block::
    :dedent:

    overlay-split-view
    ├── widget.sidebar-pane
    │   ╰── [sidebar child]
    ╰── widget.content-pane
        ╰── [content child]

When collapsed, the one containing the sidebar child has the ``.background``
style class and the other one has no style classes.


.. code-block::
    :dedent:

    overlay-split-view
    ├── widget.background
    │   ╰── [sidebar child]
    ╰── widget
        ╰── [content child]

Accessibility
--------------------------------------------------------------------------------

``AdwOverlaySplitView`` uses the ``GTK_ACCESSIBLE_ROLE_GROUP`` role.


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

.. rst-class:: interim-class

.. class:: OverlaySplitView
   :no-index:


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

      Creates a new ``AdwOverlaySplitView``\.


      .. versionadded:: 1.4












Methods
-------

.. rst-class:: interim-class

.. class:: OverlaySplitView
   :no-index:


   .. method:: get_collapsed() -> bool

      Gets whether ``self`` is collapsed.


      .. versionadded:: 1.4








   .. method:: get_content() -> ~gi.repository.Gtk.Widget | None

      Gets the content widget for ``self``\.


      .. versionadded:: 1.4








   .. method:: get_enable_hide_gesture() -> bool

      Gets whether ``self`` can be closed with a swipe gesture.


      .. versionadded:: 1.4








   .. method:: get_enable_show_gesture() -> bool

      Gets whether ``self`` can be opened with an edge swipe gesture.


      .. versionadded:: 1.4








   .. method:: get_max_sidebar_width() -> float

      Gets the maximum sidebar width for ``self``\.


      .. versionadded:: 1.4








   .. method:: get_min_sidebar_width() -> float

      Gets the minimum sidebar width for ``self``\.


      .. versionadded:: 1.4








   .. method:: get_pin_sidebar() -> bool

      Gets whether the sidebar widget is pinned for ``self``\.


      .. versionadded:: 1.4








   .. method:: get_show_sidebar() -> bool

      Gets whether the sidebar widget is shown for ``self``\.


      .. versionadded:: 1.4








   .. method:: get_sidebar() -> ~gi.repository.Gtk.Widget | None

      Gets the sidebar widget for ``self``\.


      .. versionadded:: 1.4








   .. method:: get_sidebar_position() -> ~gi.repository.Gtk.PackType

      Gets the sidebar position for ``self``\.


      .. versionadded:: 1.4








   .. method:: get_sidebar_width_fraction() -> float

      Gets the preferred sidebar width fraction for ``self``\.


      .. versionadded:: 1.4








   .. method:: get_sidebar_width_unit() -> ~gi.repository.Adw.LengthUnit

      Gets the length unit for minimum and maximum sidebar widths.


      .. versionadded:: 1.4








   .. method:: set_collapsed(collapsed: bool) -> None

      Sets whether ``self`` view is collapsed.

      When collapsed, the sidebar widget is presented as an overlay above the
      content widget, otherwise they are displayed side by side.


      .. versionadded:: 1.4





      :param collapsed: whether ``self`` is collapsed




   .. method:: set_content(content: ~gi.repository.Gtk.Widget | None = None) -> None

      Sets the content widget for ``self``\.


      .. versionadded:: 1.4





      :param content: the content widget




   .. method:: set_enable_hide_gesture(enable_hide_gesture: bool) -> None

      Sets whether ``self`` can be closed with a swipe gesture.

      Only touchscreen swipes are supported.


      .. versionadded:: 1.4





      :param enable_hide_gesture: whether ``self`` can be closed with a swipe gesture




   .. method:: set_enable_show_gesture(enable_show_gesture: bool) -> None

      Sets whether ``self`` can be opened with an edge swipe gesture.

      Only touchscreen swipes are supported.


      .. versionadded:: 1.4





      :param enable_show_gesture: whether ``self`` can be opened with a swipe gesture




   .. method:: set_max_sidebar_width(width: float) -> None

      Sets the maximum sidebar width for ``self``\.

      Maximum width is affected by :obj:`~gi.repository.Adw.OverlaySplitView.props.sidebar_width_unit`\.

      The sidebar widget can still be allocated with larger width if its own
      minimum width exceeds it.


      .. versionadded:: 1.4





      :param width: the maximum width




   .. method:: set_min_sidebar_width(width: float) -> None

      Sets the minimum sidebar width for ``self``\.

      Minimum width is affected by :obj:`~gi.repository.Adw.OverlaySplitView.props.sidebar_width_unit`\.

      The sidebar widget can still be allocated with larger width if its own
      minimum width exceeds it.


      .. versionadded:: 1.4





      :param width: the minimum width




   .. method:: set_pin_sidebar(pin_sidebar: bool) -> None

      Sets whether the sidebar widget is pinned for ``self``\.

      By default, collapsing ``self`` automatically hides the sidebar widget, and
      uncollapsing it shows the sidebar. If set to ``TRUE``\, sidebar visibility never
      changes on its own.


      .. versionadded:: 1.4





      :param pin_sidebar: whether to pin the sidebar widget




   .. method:: set_show_sidebar(show_sidebar: bool) -> None

      Sets whether the sidebar widget is shown for ``self``\.


      .. versionadded:: 1.4





      :param show_sidebar: whether to show the sidebar widget




   .. method:: set_sidebar(sidebar: ~gi.repository.Gtk.Widget | None = None) -> None

      Sets the sidebar widget for ``self``\.


      .. versionadded:: 1.4





      :param sidebar: the sidebar widget




   .. method:: set_sidebar_position(position: ~gi.repository.Gtk.PackType) -> None

      Sets the sidebar position for ``self``\.

      If it's set to ``GTK_PACK_START``\, the sidebar is displayed before the content,
      if ``GTK_PACK_END``\, it's displayed after the content.


      .. versionadded:: 1.4





      :param position: the new position




   .. method:: set_sidebar_width_fraction(fraction: float) -> None

      Sets the preferred sidebar width as a fraction of the total width of ``self``\.

      The preferred width is additionally limited by
      :obj:`~gi.repository.Adw.OverlaySplitView.props.min_sidebar_width` and
      :obj:`~gi.repository.Adw.OverlaySplitView.props.max_sidebar_width`\.

      The sidebar widget can be allocated with larger width if its own minimum
      width exceeds the preferred width.


      .. versionadded:: 1.4





      :param fraction: the preferred width fraction




   .. method:: set_sidebar_width_unit(unit: ~gi.repository.Adw.LengthUnit) -> None

      Sets the length unit for minimum and maximum sidebar widths.

      See :obj:`~gi.repository.Adw.OverlaySplitView.props.min_sidebar_width` and
      :obj:`~gi.repository.Adw.OverlaySplitView.props.max_sidebar_width`\.


      .. versionadded:: 1.4





      :param unit: the length unit








Properties
----------

.. rst-class:: interim-class

.. class:: OverlaySplitView
   :no-index:
   

   .. attribute:: props.collapsed
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.content
      :type: ~gi.repository.Gtk.Widget

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.enable_hide_gesture
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.enable_show_gesture
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.max_sidebar_width
      :type: float

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.min_sidebar_width
      :type: float

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.pin_sidebar
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.show_sidebar
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.sidebar
      :type: ~gi.repository.Gtk.Widget

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.sidebar_position
      :type: ~gi.repository.Gtk.PackType

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.sidebar_width_fraction
      :type: float

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.sidebar_width_unit
      :type: ~gi.repository.Adw.LengthUnit

      The type of the None singleton.



      .. versionadded:: 1.4