:right-sidebar: True

ToolbarView
===================================================================

.. currentmodule:: gi.repository.Adw


.. versionadded:: 1.4




.. class:: ToolbarView(**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.Gtk.Accessible`, :class:`~gi.repository.Gtk.Buildable`, :class:`~gi.repository.Gtk.ConstraintTarget`



A widget containing a page, as well as top and/or bottom bars.

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

``AdwToolbarView`` has a single content widget and one or multiple top and
bottom bars, shown at the top and bottom sides respectively.

Example of an ``AdwToolbarView`` UI definition:


.. code-block:: xml
    :dedent:

    <object class="AdwToolbarView">
      <child type="top">
        <object class="AdwHeaderBar"/>
      </child>
      <property name="content">
        <object class="AdwPreferencesPage">
          <!-- ... -->
        </object>
      </property>
    </object>

The following kinds of top and bottom bars are supported:

- :obj:`~gi.repository.Adw.HeaderBar`
- :obj:`~gi.repository.Adw.TabBar`
- :obj:`~gi.repository.Adw.ViewSwitcherBar`
- :obj:`~gi.repository.Gtk.ActionBar`
- :obj:`~gi.repository.Gtk.HeaderBar`
- :obj:`~gi.repository.Gtk.PopoverMenuBar`
- :obj:`~gi.repository.Gtk.SearchBar`
- Any :obj:`~gi.repository.Gtk.Box` or a similar widget with the
  ```.toolbar`` <style-classes.html#toolbars>`__ style class


By default, top and bottom bars are flat and scrolling content has a subtle
undershoot shadow, same as when using the
```.undershoot-top`` <style-classes.html#undershoot-indicators>`__ and
```.undershoot-bottom`` <style-classes.html#undershoot-indicators>`__ style
classes. This works well in most cases, e.g. with :obj:`~gi.repository.Adw.StatusPage` or
:obj:`~gi.repository.Adw.PreferencesPage`\, where the background at the top and bottom parts of
the page is uniform. Additionally, windows with sidebars should always use
this style.

:obj:`~gi.repository.Adw.ToolbarView.props.top_bar_style` and
:obj:`~gi.repository.Adw.ToolbarView.props.bottom_bar_style` properties can be used add an opaque
background and a persistent shadow to top and bottom bars, this can be useful
for content such as `utility panes <https://developer.gnome.org/hig/patterns/containers/utility-panes.html>`__\,
where some elements are adjacent to the top/bottom bars, or :obj:`~gi.repository.Adw.TabView`\,
where each page can have a different background.

<picture style="min-width: 33%; display: inline-block;">
  <source srcset="toolbar-view-flat-1-dark.png" media="(prefers-color-scheme: dark)">
  <img src="toolbar-view-flat-1.png" alt="toolbar-view-flat-1">
</picture>
<picture style="min-width: 33%; display: inline-block;">
  <source srcset="toolbar-view-flat-2-dark.png" media="(prefers-color-scheme: dark)">
  <img src="toolbar-view-flat-2.png" alt="toolbar-view-flat-2">
</picture>
<picture style="min-width: 33%; display: inline-block;">
  <source srcset="toolbar-view-raised-dark.png" media="(prefers-color-scheme: dark)">
  <img src="toolbar-view-raised.png" alt="toolbar-view-raised">
</picture>

``AdwToolbarView`` ensures the top and bottom bars have consistent backdrop
styles and vertical spacing. For comparison:

<picture style="min-width: 40%; display: inline-block;">
  <source srcset="toolbar-view-spacing-dark.png" media="(prefers-color-scheme: dark)">
  <img src="toolbar-view-spacing.png" alt="toolbar-view-spacing">
</picture>
<picture style="min-width: 40%; display: inline-block;">
  <source srcset="toolbar-view-spacing-box-dark.png" media="(prefers-color-scheme: dark)">
  <img src="toolbar-view-spacing-box.png" alt="toolbar-view-spacing-box">
</picture>

Any top and bottom bars can also be dragged to move the window, equivalent
to putting them into a :obj:`~gi.repository.Gtk.WindowHandle`\.

Content is typically place between top and bottom bars, but can also extend
behind them. This is controlled with the
:obj:`~gi.repository.Adw.ToolbarView.props.extend_content_to_top_edge` and
:obj:`~gi.repository.Adw.ToolbarView.props.extend_content_to_bottom_edge` properties.

Top and bottom bars can be hidden and revealed with an animation using the
:obj:`~gi.repository.Adw.ToolbarView.props.reveal_top_bars` and
:obj:`~gi.repository.Adw.ToolbarView.props.reveal_bottom_bars` properties.


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

The ``AdwToolbarView`` implementation of the :obj:`~gi.repository.Gtk.Buildable` interface
supports adding a top bar by specifying “top” as the “type” attribute of a
``<child>`` element, or adding a bottom bar by specifying “bottom”.

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

``AdwToolbarView`` uses the ``GTK_ACCESSIBLE_ROLE_GROUP`` role.


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

.. rst-class:: interim-class

.. class:: ToolbarView
   :no-index:


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

      Creates a new ``AdwToolbarView``\.


      .. versionadded:: 1.4












Methods
-------

.. rst-class:: interim-class

.. class:: ToolbarView
   :no-index:


   .. method:: add_bottom_bar(widget: ~gi.repository.Gtk.Widget) -> None

      Adds a bottom bar to ``self``\.


      .. versionadded:: 1.4





      :param widget: a widget




   .. method:: add_top_bar(widget: ~gi.repository.Gtk.Widget) -> None

      Adds a top bar to ``self``\.


      .. versionadded:: 1.4





      :param widget: a widget




   .. method:: get_bottom_bar_height() -> int

      Gets the current bottom bar height for ``self``\.

      Bottom bar height does change depending on
      :obj:`~gi.repository.Adw.ToolbarView.props.reveal_bottom_bars`\, including during the transition.

      See :obj:`~gi.repository.ToolbarView.get_top_bar_height`\.


      .. versionadded:: 1.4








   .. method:: get_bottom_bar_style() -> ~gi.repository.Adw.ToolbarStyle

      Gets appearance of the bottom bars for ``self``\.


      .. versionadded:: 1.4








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

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


      .. versionadded:: 1.4








   .. method:: get_extend_content_to_bottom_edge() -> bool

      Gets whether the content widget can extend behind bottom bars.


      .. versionadded:: 1.4








   .. method:: get_extend_content_to_top_edge() -> bool

      Gets whether the content widget can extend behind top bars.


      .. versionadded:: 1.4








   .. method:: get_reveal_bottom_bars() -> bool

      Gets whether bottom bars are revealed for ``self``\.


      .. versionadded:: 1.4








   .. method:: get_reveal_top_bars() -> bool

      Gets whether top bars are revealed for ``self``\.


      .. versionadded:: 1.4








   .. method:: get_top_bar_height() -> int

      Gets the current top bar height for ``self``\.

      Top bar height does change depending on
      :obj:`~gi.repository.Adw.ToolbarView.props.reveal_top_bars`\, including during the transition.

      See :obj:`~gi.repository.ToolbarView.get_bottom_bar_height`\.


      .. versionadded:: 1.4








   .. method:: get_top_bar_style() -> ~gi.repository.Adw.ToolbarStyle

      Gets appearance of the top bars for ``self``\.


      .. versionadded:: 1.4








   .. method:: remove(widget: ~gi.repository.Gtk.Widget) -> None

      Removes a child from ``self``\.


      .. versionadded:: 1.4





      :param widget: the child to be removed




   .. method:: set_bottom_bar_style(style: ~gi.repository.Adw.ToolbarStyle) -> None

      Sets appearance of the bottom bars for ``self``\.

      If set to ``ADW_TOOLBAR_FLAT``\, bottom bars are flat and scrolling content has
      a subtle undershoot shadow when touching them, same as the
      ```.undershoot-bottom`` <style-classes.html#undershoot-indicators>`__
      style class. This works well for simple content, e.g. :obj:`~gi.repository.Adw.StatusPage` or
      :obj:`~gi.repository.Adw.PreferencesPage`\, where the background at the bottom of the page is
      uniform. Additionally, windows with sidebars should always use this style.

      Undershoot shadow is only present if a bottom bar is actually present and
      visible. It is also never present if
      :obj:`~gi.repository.Adw.ToolbarView.props.extend_content_to_bottom_edge` is set to ``TRUE``\.

      If set to ``ADW_TOOLBAR_RAISED``\, bottom bars have an opaque background and a
      persistent shadow, this is suitable for content such as
      `utility panes <https://developer.gnome.org/hig/patterns/containers/utility-panes.html>`__\,
      where some elements are directly adjacent to the bottom bars, or
      :obj:`~gi.repository.Adw.TabView`\, where each page can have a different background.

      ``ADW_TOOLBAR_RAISED_BORDER`` is similar to ``ADW_TOOLBAR_RAISED``\, but the
      shadow is replaced with a more subtle border. This can be useful for
      applications like image viewers.

      See also :obj:`~gi.repository.ToolbarView.set_top_bar_style`\.


      .. versionadded:: 1.4





      :param style: bottom bar style




   .. 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_extend_content_to_bottom_edge(extend: bool) -> None

      Sets whether the content widget can extend behind bottom bars.

      This can be used in combination with :obj:`~gi.repository.Adw.ToolbarView.props.reveal_bottom_bars`
      to show and hide toolbars in fullscreen.

      See :obj:`~gi.repository.ToolbarView.set_extend_content_to_top_edge`\.


      .. versionadded:: 1.4





      :param extend: whether content extends behind bottom bars




   .. method:: set_extend_content_to_top_edge(extend: bool) -> None

      Sets whether the content widget can extend behind top bars.

      This can be used in combination with :obj:`~gi.repository.Adw.ToolbarView.props.reveal_top_bars`
      to show and hide toolbars in fullscreen.

      See :obj:`~gi.repository.ToolbarView.set_extend_content_to_bottom_edge`\.


      .. versionadded:: 1.4





      :param extend: whether content extends behind top bars




   .. method:: set_reveal_bottom_bars(reveal: bool) -> None

      Sets whether bottom bars are revealed for ``self``\.

      The transition will be animated.

      This can be used in combination with
      :obj:`~gi.repository.Adw.ToolbarView.props.extend_content_to_bottom_edge` to show and hide
      toolbars in fullscreen.

      See :obj:`~gi.repository.ToolbarView.set_reveal_top_bars`\.


      .. versionadded:: 1.4





      :param reveal: whether to reveal bottom bars




   .. method:: set_reveal_top_bars(reveal: bool) -> None

      Sets whether top bars are revealed for ``self``\.

      The transition will be animated.

      This can be used in combination with
      :obj:`~gi.repository.Adw.ToolbarView.props.extend_content_to_top_edge` to show and hide toolbars
      in fullscreen.

      See :obj:`~gi.repository.ToolbarView.set_reveal_bottom_bars`\.


      .. versionadded:: 1.4





      :param reveal: whether to reveal top bars




   .. method:: set_top_bar_style(style: ~gi.repository.Adw.ToolbarStyle) -> None

      Sets appearance of the top bars for ``self``\.

      If set to ``ADW_TOOLBAR_FLAT``\, top bars are flat and scrolling content has a
      subtle undershoot shadow when touching them, same as the
      ```.undershoot-top`` <style-classes.html#undershoot-indicators>`__
      style class. This works well for simple content, e.g. :obj:`~gi.repository.Adw.StatusPage` or
      :obj:`~gi.repository.Adw.PreferencesPage`\, where the background at the top of the page is
      uniform. Additionally, windows with sidebars should always use this style.

      Undershoot shadow is only present if a top bar is actually present and
      visible. It is also never present if
      :obj:`~gi.repository.Adw.ToolbarView.props.extend_content_to_top_edge` is set to ``TRUE``\.

      If set to ``ADW_TOOLBAR_RAISED``\, top bars have an opaque background and a
      persistent shadow, this is suitable for content such as
      `utility panes <https://developer.gnome.org/hig/patterns/containers/utility-panes.html>`__\,
      where some elements are directly adjacent to the top bars, or
      :obj:`~gi.repository.Adw.TabView`\, where each page can have a different background.

      ``ADW_TOOLBAR_RAISED_BORDER`` is similar to ``ADW_TOOLBAR_RAISED``\, but the
      shadow is replaced with a more subtle border. This can be useful for
      applications like image viewers.

      See also :obj:`~gi.repository.ToolbarView.set_bottom_bar_style`\.


      .. versionadded:: 1.4





      :param style: top bar style








Properties
----------

.. rst-class:: interim-class

.. class:: ToolbarView
   :no-index:
   

   .. attribute:: props.bottom_bar_height
      :type: int

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.bottom_bar_style
      :type: ~gi.repository.Adw.ToolbarStyle

      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.extend_content_to_bottom_edge
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.extend_content_to_top_edge
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.reveal_bottom_bars
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.reveal_top_bars
      :type: bool

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.top_bar_height
      :type: int

      The type of the None singleton.



      .. versionadded:: 1.4





   .. attribute:: props.top_bar_style
      :type: ~gi.repository.Adw.ToolbarStyle

      The type of the None singleton.



      .. versionadded:: 1.4