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

      type="topic"

      id="header-bar-menus">

  <info>

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

    <desc>Common menus shown on the right side of a header bar</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 bar menus</title>

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

<link xref="header-bars">Header bars</link> can include a menu which contains actions and options for the current view. These menus are located at the far right side of the header bar.

While the most frequently used actions for a view should be placed directly in the header bar, a header bar menu provides access to lesser-used actions. This ensures that the header bar isn’t overwhelmed with less interesting or useful controls.

In this way, the header bar menus help to create focused views that guide the user towards the most interesting and useful functionality.

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

<title>When to use</title>

Use a header bar menu to present additional actions or options for the current view. They are best used when those actions or options are not used the majority of the time - if there is a set of actions which deserve more prominence in the view, an <link xref="action-bars">action bar</link> might be a better choice.

Header bar menus are not a good choice for performing actions on selected content: when content hasn’t been selected, the menu will contain unhelpful insensitive menu items, and when content has been selected, possible actions will not be advertised. <link xref="selection-mode">Selection mode</link> or <link xref="popovers">popovers</link> are a better choice for this situation.

</section>

<section id="guidance">

<title>Guidance</title>

<list>

<item>
Header bar menus should only contain actions for the current view or window - this differentiates their content from application menus.
</item>

<item>
Follow the <link xref="menus">standard guidelines for menus</link>.
</item>

<item>
A header bar menu is contained within a <link xref="popovers">popover</link>. As such, a header bar menu can include a variety of controls, such as groups of buttons.
</item>

<item>
Header bar menus shouldn’t include a close menu item, since this action is already provided by the header bar. It can also be ambiguous as to what a close menu item refers to.
</item>

</list>

</section>

<section id="api-reference">

<title>API reference</title>

<list>

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

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

</list>

</section>

</page>