gtk:widget, gobject:initially-unowned, gtk:accessible, gtk:buildable, gtk:constraint-target, gobject:object, common-lisp:standard-object, common-lisp:t

None

The gtk:header-bar widget is similar to a horizontal gtk:box widget. It allows children to be placed at the start or the end. In addition, it allows a title and subtitle to be displayed.

Figure: GtkHeaderBar

The title will be centered with respect to the width of the box, even if the children at either side take up different amounts of space.

The gtk:header-bar widget can add typical window frame controls, such as Minimize, Maximize and Close buttons, or the window icon.

For these reasons, the gtk:header-bar widget is the natural choice for use as the custom titlebar widget of a gtk:window widget, see the gtk:window-titlebar function, as it gives features typical of titlebars while allowing the addition of child widgets. The gtk:header-bar widget implementation of the gtk:buildable interface supports adding children at the start or end sides by specifying "start" or "end" as the "type" attribute of a <child> element, or setting the title widget by specifying "title" value.

By default the gtk:header-bar widget uses a gtk:label widget displaying the title of the window it is contained in as the title widget, equivalent to the following UI definition:

<object class="GtkHeaderBar">
  <property name="title-widget">
    <object class="GtkLabel">
      <property name="label" translatable="yes">Label</property>
      <property name="single-line-mode">True</property>
      <property name="ellipsize">end</property>
      <property name="width-chars">5</property>
      <style>
        <class name="title"/>
      </style>
    </object>
  </property>
</object>    

headerbar
╰── windowhandle
    ╰── box
        ├── box.start
        │   ├── windowcontrols.start
        │   ╰── [other children]
        ├── [Title Widget]
        ╰── box.end
            ├── [other children]
            ╰── windowcontrols.end    

The gtk:header-bar implementation has a CSS node with the name headerbar. It contains a windowhandle subnode, which contains a box subnode, which contains two box subnodes at the start and end of the header bar, as well as a center node that represents the title.

Each of the boxes contains a windowcontrols subnode, see the gtk:window-controls widget for details, as well as other children. The gtk:header-bar implementation uses the :group role of the gtk:accessible-role enumeration.