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

  <info>
    <credit type="author">
      <name>Allan Day</name>
      <email>aday@gnome.org</email>
    </credit>
    <credit>
      <name>Calum Benson</name>
    </credit>
    <credit>
      <name>Adam Elman</name>
    </credit>
    <credit>
      <name>Seth Nickell</name>
    </credit>
    <credit>
      <name>Colin Robertson</name>
    </credit>

    <link type="guide" xref="ui-elements"/>
    <uix:thumb mime="image/svg" src="figures/ui-elements/menu-bar.svg"/>

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

<title>Menu bars</title>

<p>A menu bar incorporates a strip of drop-down menus. It is typically located at the top of a primary window, below a window title bar.</p>

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

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

<p>Menu bars increase the vertical footprint of an application’s user interface, introduce a large number of disclosure points, and function as a fixed set of inflexible options. For these reasons, <link xref="header-bars">header bars</link> and <link xref="header-bar-menus">header bar menus</link> are generally recommended over menu bars, along with other design patterns for exposing controls on demand, such as <link xref="selection-mode">selection mode</link>, <link xref="action-bars">action bars</link>, and <link xref="popovers">popovers</link>.</p>

<p>At the same time, it can be appropriate for complex applications that already include a menu bar to retain it. Additionally, some platforms also incorporate space for a menu bar in their user environment, and a menu model can be desirable for cross-platform integration purposes.</p>

</section>

<section id="standard-menus">
<title>Standard menus</title>

<p>This section details the most common menus and menu items in a menu bar. For details on the standard items to include in each of these menus, see <link xref="keyboard-input#application-shortcuts">keyboard input</link>.</p>

<table>
<tr>
<td><p><gui>File</gui></p></td>
<td><p>Commands that operate on the current document or content item as a whole. It is the left-most item in the menubar because of its importance and frequency of use, and because it is a relevant menu in many applications.</p>
<p>If your application does not operate on files, name this menu for the type of object it displays. For example, a music player could have a <gui>Music</gui> instead of a <gui>File</gui> menu.</p></td>
</tr>
<tr>
<td><p><gui>Edit</gui></p></td>
<td><p>The <gui>Edit</gui> menu contains items relating to editing the document, such as clipboard handling, find and replace, and inserting objects.</p></td>
</tr>
<tr>
<td><p><gui>View</gui></p></td>
<td><p>Includes items that affect the user’s view, such as of the current document or page, or how items are presented for browsing. Do not place any items on the <gui>View</gui> menu that affect content items.</p></td>
</tr>
<tr>
<td><p><gui>Insert</gui></p></td>
<td><p>Lists the types of objects that can be inserted into the current document, such as images, links or page breaks. Only provide this menu if you have more than about six types of object that can be inserted, otherwise place individual items for each type on the <gui>Edit</gui> menu.</p></td>
</tr>
<tr>
<td><p><gui>Format</gui></p></td>
<td><p>Includes commands to change the visual appearance of the document. For example, changing the font, color, or line spacing of a text selection.</p>
<p>The difference between these commands and those on the <gui>View</gui> menu is that changes made with <gui>Format</gui> commands are persistent and saved as part of the document.</p>
<p>Items found on the Format menu are very application-specific.</p></td>
</tr>
<tr>
<td><p><gui>Bookmarks</gui></p></td>
<td><p>Provide a Bookmarks menu in any application that allows the user to browse files and folders, help documents, web pages or any other large information space.</p></td>
</tr>
<tr>
<td><p><gui>Go</gui></p></td>
<td><p>A <gui>Go</gui> menu provides commands for quickly navigating around a document or collection of documents, or an information space such as a directory structure or the web.</p>
<p>The contents of the menu will vary depending on the type of application.</p></td>
</tr>
<tr>
<td><p><gui>Windows</gui></p></td>
<td><p>Commands that apply to all of the application’s open windows. You may also label this menu <gui>Documents</gui>, <gui>Buffers</gui>, or similar according to the type of document handled by your application.</p>
<p>The last items on this menu are a numbered list of the application’s primary windows, for example <gui>1shoppinglist.abw</gui>. Selecting one of these items raises the corresponding window.</p></td>
</tr>
</table>

</section>

<section id="general-guidelines">
<title>General guidelines</title>

<list>
<item><p>The menubar is normally visible at all times and is always accessible from the keyboard, so make all the commands available in your application available on the menubar. (This guideline is unique to menu bars - other menus should not seek to reproduce functionality that is made available by other controls).</p></item>
<item><p>Treat <link xref="application-menus">application menus</link> as part of the menu bar - it is not necessary to reproduce items from the application menu in other menus.</p></item>
<item><p>Do not disable menu titles. Allow the user to explore the menu, even though there might be no available items on it at that time.</p></item>
<item><p>Menu titles on a menubar are single words with their first letter capitalized. Do not use spaces in menu titles, as this makes them easily-mistaken for two separate menu titles. Do not use compound words (such as <gui>WindowOptions</gui>) or hyphens (such as <gui>Window-Options</gui>) to circumvent this guideline.</p></item>
<item><p>Do not provide a mechanism for hiding the menubar, as this may be activated accidentally. Some users will not be able to figure out how to get the menu bar back in this case.</p></item>
</list>

</section>

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

<list>
<item><p><link href="https://developer.gnome.org/gtk3/stable/GtkMenu.html">GtkMenu</link></p></item>
<item><p><link href="https://developer.gnome.org/gtk3/stable/GtkMenuBar.html">GtkMenuBar</link></p></item>
<item><p><link href="https://developer.gnome.org/gtk3/stable/GtkMenuItem.html">GtkMenuItem</link></p></item>
<item><p><link href="https://developer.gnome.org/gtk3/stable/GtkRadioMenuItem.html">GtkRadioMenuItem</link></p></item>
<item><p><link href="https://developer.gnome.org/gtk3/stable/GtkCheckMenuItem.html">GtkCheckMenuItem</link></p></item>
<item><p><link href="https://developer.gnome.org/gtk3/stable/GtkSeparatorMenuItem.html">GtkSeparatorMenuItem</link></p></item>
</list>
</section>

</page>
