<page xmlns="http://projectmallard.org/1.0/"
      xmlns:uix="http://projectmallard.org/experimental/ui/"
      type="topic"
      id="secondary-menus">

  <info>
    <link type="guide" xref="patterns#primary"/>
    <desc>The application's secondary menu, denoted by three stacked horizontal dots</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>Secondary menus</title>

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

<p>Secondary menus are located in the header bar and include menu items for the current view or content item. This differentiates them from <link xref="primary-menus">primary menus</link>, which include menu items that relate to an entire application (such as <gui>Preferences</gui> and <gui>About "Name"</gui>).</p>

<section id="when-to-use">
<title>When to use</title>

<p>Secondary menus can be used to host controls that relate to a particular content item which is being displayed in the application window (such as a document, contact, conversation or photo). They are typically used in combination with in-window navigation or <link xref="sidebar-lists">sidebar lists</link>, since both these arrangements feature separate views or areas for content items to be shown.</p>

<p>Secondary menus are optional and only need to be used if there are enough controls to require a menu.</p>

</section>

<section id="guidance">
<title>Guidance</title>

<list>
<item><p>Secondary menus generally shouldn't reproduce menu items that are included in <link xref="primary-menus">primary menus</link>, like <gui>Preferences</gui> and <gui>About</gui>. However, it can sometimes be useful to show <gui>Help</gui>.</p></item>
<item><p>The <link xref="menus">standard guidelines for menus</link> can be followed when designing secondary menus.</p></item>
<item><p>A secondary 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.</p></item>
<item><p>Secondary menus shouldn’t include menu items for close or quit.</p></item>
</list>

</section>

<section id="api-reference">
<title>API reference</title>

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

</section>

</page>
