xmlns:uix="http://projectmallard.org/experimental/ui/"

      type="topic"

      id="header-bars">

  <info>

    <link type="guide" xref="patterns#primary"/>

    <desc>Element that runs along the top of windows</desc>

    <credit type="author">

      <name>Allan Day</name>

      <email>aday@gnome.org</email>

    </credit>

    <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude"/>

  </info>

<title>Header bars</title>

<media type="image" mime="image/svg" src="figures/patterns/header-bar.svg"/>

Header bars are a common horizontal element which are placed at the top of windows. They play a number of roles:

<list>

<item>
Window controls - header bars allow windows to be moved by dragging, include window control buttons (typically a single close button), and provide access to a window controls menu.
</item>

<item>
Headings - a key role of a header bar is to provide context for the content of the window, either through a heading or view switcher.
</item>

<item>
Controls - header bars provide a place for key controls, typically in the form of buttons.
</item>

</list>

<section id="when-to-use">

<title>When to use</title>

Header bars are recommended for all application windows. They provide a number of advantages over the traditional combination of title bar, menu bar and toolbar, including a smaller vertical footprint, and dynamic navigation and mode changes (such as with <link xref="selection-mode">selection mode</link>).

Header bars are incompatible with menu bars. If your application already incorporates a menu bar, you should evaluate the alternatives suggested in these guidelines. See the <link xref="menu-bars">menu bar guidelines</link> for more details on this.

</section>

<section id="controls">

<title>Controls</title>

Header bars can contain key controls for the window, which can be placed on the left and right-hand side of the header bar. Examples of these controls include buttons for navigating back and forward, search, and selecting content.

Ensure that your header bar only contains a small number of key controls - this will help users to understand the primary functionality provided by the window, and will ensure that the window can be resized to narrow widths.

If a window requires more controls than can be comfortably accommodated within the header bar, additional functionality can be included within a header bar menu.

</section>

<section id="dynamic">

<title>Header bars are dynamic</title>

A header bar can - and should - update along with view or mode changes. This ensures that header bar controls are always relevant to the current context.

If the window includes multiple views (accessed through a <link xref="view-switchers">view switcher</link>), the header bar can include different controls for each view.

If the window incorporates navigation, different controls can be shown depending on the location displayed in the window itself. It is common to show a back button on the left side of the header bar when navigating.

</section>

<section id="additional-guidance">

<title>Additional guidance</title>

<list>

<item>
A header bar should always provide context for the window it belongs to. This aids window identification, and clarifies what is displayed in the window itself. This can either be done by placing a heading in the center of the header bar, or by including a <link xref="view-switchers">view switcher</link>.
</item>

<item>
Arrange controls within the header bar according to the three alignment points described in the <link xref="visual-layout">visual layout guidelines</link> - left, center and right.
</item>

<item>
<gui>New</gui> and back buttons should be placed on the left side of the header bar.
</item>

<item>
Always ensure that there is room for a header bar to be dragged. This is necessary to enable windows to be moved or resized.
</item>

</list>

</section>

<section id="api-reference">

<title>API reference</title>

<list>

<item>
<link href="https://developer.gnome.org/gtk3/stable/GtkHeaderBar.html">GtkHeaderBar</link>
</item>

</list>

</section>

</page>