:right-sidebar: True
HeaderBar
===================================================================
.. currentmodule:: gi.repository.Adw
.. class:: HeaderBar(**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 title bar widget.
.. image:: https://gnome.pages.gitlab.gnome.org/libadwaita/doc/1-latest/header-bar.png
``AdwHeaderBar`` is similar to :obj:`~gi.repository.Gtk.HeaderBar`\, but provides additional
features compared to it. Refer to ``GtkHeaderBar`` for details. It is typically
used as a top bar within :obj:`~gi.repository.Adw.ToolbarView`\.
Dialog Integration
--------------------------------------------------------------------------------
When placed inside an :obj:`~gi.repository.Adw.Dialog`\, ``AdwHeaderBar`` will display the dialog
title instead of window title. It will also adjust the decoration layout to
ensure it always has a close button and nothing else. Set
:obj:`~gi.repository.Adw.HeaderBar.props.show_start_title_buttons` and
:obj:`~gi.repository.Adw.HeaderBar.props.show_end_title_buttons` to ``FALSE`` to remove it if it's
unwanted.
Navigation View Integration
--------------------------------------------------------------------------------
When placed inside an :obj:`~gi.repository.Adw.NavigationPage`\, ``AdwHeaderBar`` will display the
page title instead of window title.
When used together with :obj:`~gi.repository.Adw.NavigationView` or :obj:`~gi.repository.Adw.NavigationSplitView`\,
it will also display a back button that can be used to go back to the previous
page. The button also has a context menu, allowing to pop multiple pages at
once, potentially across multiple navigation views.
Set :obj:`~gi.repository.Adw.HeaderBar.props.show_back_button` to ``FALSE`` to disable this behavior
in rare scenarios where it's unwanted.
Split View Integration
--------------------------------------------------------------------------------
When placed inside :obj:`~gi.repository.Adw.NavigationSplitView` or :obj:`~gi.repository.Adw.OverlaySplitView`\,
``AdwHeaderBar`` will automatically hide the title buttons other than at the
edges of the window.
Bottom Sheet Integration
--------------------------------------------------------------------------------
When played inside :obj:`~gi.repository.Adw.BottomSheet`\, ``AdwHeaderBar`` will not show the title
unless :obj:`~gi.repository.Adw.BottomSheet.props.show_drag_handle` is set to ``FALSE``\, regardless
of :obj:`~gi.repository.Adw.HeaderBar.props.show_title`\. This only applies to the default title,
titles set with :obj:`~gi.repository.Adw.HeaderBar.props.title_widget` will still be shown.
Centering Policy
--------------------------------------------------------------------------------
:obj:`~gi.repository.Adw.HeaderBar.props.centering_policy` allows to enforce strict centering of
the title widget. This can be useful for entries inside :obj:`~gi.repository.Adw.Clamp`\.
Title Buttons
--------------------------------------------------------------------------------
Unlike ``GtkHeaderBar``\, ``AdwHeaderBar`` allows to toggle title button
visibility for each side individually, using the
:obj:`~gi.repository.Adw.HeaderBar.props.show_start_title_buttons` and
:obj:`~gi.repository.Adw.HeaderBar.props.show_end_title_buttons` properties.
CSS nodes
--------------------------------------------------------------------------------
.. code-block::
:dedent:
headerbar
╰── windowhandle
╰── box
├── widget
│ ╰── box.start
│ ├── windowcontrols.start
│ ├── widget
│ │ ╰── [button.back]
│ ╰── [other children]
├── widget
│ ╰── [Title Widget]
╰── widget
╰── box.end
├── [other children]
╰── windowcontrols.end
``AdwHeaderBar``\'s CSS node is called ``headerbar``\. It contains a ``windowhandle``
subnode, which contains a ``box`` subnode, which contains three ``widget``
subnodes at the start, center and end of the header bar. The start and end
subnodes contain a ``box`` subnode with the ``.start`` and ``.end`` style classes
respectively, and the center node contains a node that represents the title.
Each of the boxes contains a ``windowcontrols`` subnode, see
:obj:`~gi.repository.Gtk.WindowControls` for details, as well as other children.
When :obj:`~gi.repository.Adw.HeaderBar.props.show_back_button` is ``TRUE``\, the start box also
contains a node with the name ``widget`` that contains a node with the name
``button`` and ``.back`` style class.
Accessibility
--------------------------------------------------------------------------------
``AdwHeaderBar`` uses the :obj:`~gi.repository.Gtk.AccessibleRole.group` role.
Constructors
------------
.. rst-class:: interim-class
.. class:: HeaderBar
:no-index:
.. classmethod:: new() -> ~gi.repository.Gtk.Widget
Creates a new ``AdwHeaderBar``\.
Methods
-------
.. rst-class:: interim-class
.. class:: HeaderBar
:no-index:
.. method:: get_centering_policy() -> ~gi.repository.Adw.CenteringPolicy
Gets the policy for aligning the center widget.
.. method:: get_decoration_layout() -> str | None
Gets the decoration layout for ``self``\.
.. method:: get_show_back_button() -> bool
Gets whether ``self`` can show the back button.
.. versionadded:: 1.4
.. method:: get_show_end_title_buttons() -> bool
Gets whether to show title buttons at the end of ``self``\.
.. method:: get_show_start_title_buttons() -> bool
Gets whether to show title buttons at the start of ``self``\.
.. method:: get_show_title() -> bool
Gets whether the title widget should be shown.
.. versionadded:: 1.4
.. method:: get_title_widget() -> ~gi.repository.Gtk.Widget | None
Gets the title widget widget of ``self``\.
.. method:: pack_end(child: ~gi.repository.Gtk.Widget) -> None
Adds ``child`` to ``self``\, packed with reference to the end of ``self``\.
:param child: the widget to be added to ``self``
.. method:: pack_start(child: ~gi.repository.Gtk.Widget) -> None
Adds ``child`` to ``self``\, packed with reference to the start of the ``self``\.
:param child: the widget to be added to ``self``
.. method:: remove(child: ~gi.repository.Gtk.Widget) -> None
Removes a child from ``self``\.
The child must have been added with :obj:`~gi.repository.HeaderBar.pack_start`\,
:obj:`~gi.repository.HeaderBar.pack_end` or :obj:`~gi.repository.Adw.HeaderBar.props.title_widget`\.
:param child: the child to remove
.. method:: set_centering_policy(centering_policy: ~gi.repository.Adw.CenteringPolicy) -> None
Sets the policy for aligning the center widget.
:param centering_policy: the centering policy
.. method:: set_decoration_layout(layout: str | None = None) -> None
Sets the decoration layout for ``self``\.
If this property is not set, the
:obj:`~gi.repository.Gtk.Settings.props.gtk_decoration_layout` setting is used.
The format of the string is button names, separated by commas. A colon
separates the buttons that should appear at the start from those at the end.
Recognized button names are minimize, maximize, close and icon (the window
icon).
For example, “icon:minimize,maximize,close” specifies an icon at the start,
and minimize, maximize and close buttons at the end.
:param layout: a decoration layout
.. method:: set_show_back_button(show_back_button: bool) -> None
Sets whether ``self`` can show the back button.
The back button will never be shown unless the header bar is placed inside an
:obj:`~gi.repository.Adw.NavigationView`\. Usually, there is no reason to set it to ``FALSE``\.
.. versionadded:: 1.4
:param show_back_button: whether to show the back button
.. method:: set_show_end_title_buttons(setting: bool) -> None
Sets whether to show title buttons at the end of ``self``\.
See :obj:`~gi.repository.Adw.HeaderBar.props.show_start_title_buttons` for the other side.
Which buttons are actually shown and where is determined by the
:obj:`~gi.repository.Adw.HeaderBar.props.decoration_layout` property, and by the state of the
window (e.g. a close button will not be shown if the window can't be closed).
:param setting: ``TRUE`` to show standard title buttons
.. method:: set_show_start_title_buttons(setting: bool) -> None
Sets whether to show title buttons at the start of ``self``\.
See :obj:`~gi.repository.Adw.HeaderBar.props.show_end_title_buttons` for the other side.
Which buttons are actually shown and where is determined by the
:obj:`~gi.repository.Adw.HeaderBar.props.decoration_layout` property, and by the state of the
window (e.g. a close button will not be shown if the window can't be closed).
:param setting: ``TRUE`` to show standard title buttons
.. method:: set_show_title(show_title: bool) -> None
Sets whether the title widget should be shown.
.. versionadded:: 1.4
:param show_title: whether the title widget is visible
.. method:: set_title_widget(title_widget: ~gi.repository.Gtk.Widget | None = None) -> None
Sets the title widget for ``self``\.
When set to ``NULL``\, the header bar will display the title of the window it
is contained in.
To use a different title, use :obj:`~gi.repository.Adw.WindowTitle`\:
.. code-block:: xml
:dedent:
:param title_widget: a widget to use for a title
Properties
----------
.. rst-class:: interim-class
.. class:: HeaderBar
:no-index:
.. attribute:: props.centering_policy
:type: ~gi.repository.Adw.CenteringPolicy
The policy for aligning the center widget.
.. attribute:: props.decoration_layout
:type: str
The decoration layout for buttons.
If this property is not set, the
:obj:`~gi.repository.Gtk.Settings.props.gtk_decoration_layout` setting is used.
The format of the string is button names, separated by commas. A colon
separates the buttons that should appear at the start from those at the
end. Recognized button names are minimize, maximize, close and icon (the
window icon).
For example, “icon:minimize,maximize,close” specifies an icon at the start,
and minimize, maximize and close buttons at the end.
.. attribute:: props.show_back_button
:type: bool
Whether the header bar can show the back button.
The back button will never be shown unless the header bar is placed inside an
:obj:`~gi.repository.Adw.NavigationView`\. Usually, there is no reason to set this to ``FALSE``\.
.. versionadded:: 1.4
.. attribute:: props.show_end_title_buttons
:type: bool
Whether to show title buttons at the end of the header bar.
See :obj:`~gi.repository.Adw.HeaderBar.props.show_start_title_buttons` for the other side.
Which buttons are actually shown and where is determined by the
:obj:`~gi.repository.Adw.HeaderBar.props.decoration_layout` property, and by the state of the
window (e.g. a close button will not be shown if the window can't be
closed).
.. attribute:: props.show_start_title_buttons
:type: bool
Whether to show title buttons at the start of the header bar.
See :obj:`~gi.repository.Adw.HeaderBar.props.show_end_title_buttons` for the other side.
Which buttons are actually shown and where is determined by the
:obj:`~gi.repository.Adw.HeaderBar.props.decoration_layout` property, and by the state of the
window (e.g. a close button will not be shown if the window can't be
closed).
.. attribute:: props.show_title
:type: bool
Whether the title widget should be shown.
.. versionadded:: 1.4
.. attribute:: props.title_widget
:type: ~gi.repository.Gtk.Widget
The title widget to display.
When set to ``NULL``\, the header bar will display the title of the window it
is contained in.
To use a different title, use :obj:`~gi.repository.Adw.WindowTitle`\:
.. code-block:: xml
:dedent: