: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 ``GTK_ACCESSIBLE_ROLE_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: Title :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 type of the None singleton. .. attribute:: props.decoration_layout :type: str The type of the None singleton. .. attribute:: props.show_back_button :type: bool The type of the None singleton. .. versionadded:: 1.4 .. attribute:: props.show_end_title_buttons :type: bool The type of the None singleton. .. attribute:: props.show_start_title_buttons :type: bool The type of the None singleton. .. attribute:: props.show_title :type: bool The type of the None singleton. .. versionadded:: 1.4 .. attribute:: props.title_widget :type: ~gi.repository.Gtk.Widget The type of the None singleton.