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

  <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/toolbar.svg"/>

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

<title>Toolbars</title>

<p>A toolbar is a strip of controls that allows convenient access to commonly-used functions. Most toolbars only contain graphical buttons, but in more complex applications, other types of controls such as drop-down lists, can also be useful.</p>

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

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

<p>Use a toolbar to provide access to common actions, tools or options in primary windows. <link xref="header-bars">Header bars</link> also perform this role, and a toolbar is generally not required if you are using header bars.</p>

<p>While toolbars are a common approach, there are cases where they are not the most effective. Interfaces that focus on direct manipulation, or which make heavy use of progressive disclosure, may provide a better alternative. Each of these approaches requires more time and effort at the design stage, and should only be pursued by those who are confident in pursuing more original design solutions.</p>

</section>

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

<list>
<item><p>Only include controls for the most important functions. Having too many toolbar controls reduces their efficiency by making them harder to find, and too many rows of toolbars reduces the amount of screen space available to the rest of the application.</p></item>
<item><p>Utilize conventions for toolbars to increase familiarity. For example, the main toolbar in an office application will nearly always have new, open and save as its first three toolbar buttons. Similarly, the first buttons in a browser application should be back and forward.</p></item>
<item><p>Place only the most commonly-used application functions on your toolbars. Don’t just add buttons for every menu item.</p></item>
<item><p>If you are using a <link xref="menu-bars">menu bar</link>, ensure that it includes all the functions that appear on you toolbar, either directly (i.e. an equivalent menu item) or indirectly (e.g. in the <guiseq><gui>Options</gui><gui>Settings</gui></guiseq> dialog).</p></item>
<item><p>Toolbars shouldn’t include buttons for <gui>Help</gui>, <gui>Close</gui> or <gui>Quit</gui>, as these are rarely used and the space is better used for more useful controls. Similarly, only provide buttons for <gui>Undo</gui>, <gui>Redo</gui> and the standard clipboard functions if there is space on the toolbar to do so without sacrificing more useful, application-specific controls.</p></item>
<item><p>Toolbar <link xref="buttons">buttons</link> should have a relief, and icon buttons should use <link xref="icons-and-artwork#color-vs-symbolic">symbolic icons</link>.</p></item>
</list>

</section>

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

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

</section>

</page>