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

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

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

<title>Tabs</title>

<p>Tabs provide a way to break down a window into a series of views. They come in two primary forms: fixed and dynamic.</p>

<p>Fixed tabs provide an immutable set of predefined views, and are primarily used in dialog windows. Dynamic tabs allow a window to contain mutable selection of content items, such as pages, documents or images. They are primarily used within <link xref="primary-windows">primary windows</link>, as a part of editor or browser applications.</p>

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

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

<p>Use fixed tabs when a <link xref="dialogs">dialog window</link> contains too many controls (or too much information) to be comfortably presented at once.</p>

<p>Dynamic tabs are primarily useful for browser or editor applications, where a user might want to use several locations or content items simultaneously.</p>

</section>

<section id="fixed">
<title>Fixed tabs</title>

<list>
<item><p>Do not use too many tabs. If you cannot see all the tabs without scrolling or splitting them into multiple rows, you are probably using too many and should use a list control instead.</p></item>
<item><p>Label tabs with <link xref="writing-style#capitalization">header capitalization</link>, and use nouns rather than verbs, for example <gui>Font</gui> or <gui>Alignment</gui>. Try to give tab labels a similar length.</p></item>
<item><p>Do not design tabs such that changing controls on one page affects the controls on any other page. Users are unlikely to discover such dependencies.</p></item>
<item><p>If a control affects every tab, place it outside the tabs.</p></item>
<item><p>With fixed tabs, make the width of each tab proportional to the width of its label. Don’t just set all the tabs to the same width, as this makes them harder to scan visually, and limits the number of tabs you can display without scrolling.</p></item>
</list>

</section>

<section id="dynamic">
<title>Dynamic tabs</title>

<list>
<item><p>Tabs often have a constrained width, so ensure that tab labels are short and concise, and that the most useful part of the label is displayed first. This ensures that the label continues to be useful even when ellipsized.</p></item>
<item><p>If the content of a tab changes or requires attention, a visual hint can be displayed.</p></item>
<item><p>Provide a context menu on each tab. This menu should only include actions for manipulating the tab itself, such as <gui>Move Left</gui>, <gui>Move Right</gui>, <gui>Move to New Window</gui>, and <gui>Close</gui>.</p></item>
<item><p>If tabs are an important part of the application, a new tab button can be placed in the header bar or toolbar. Do not show a new tab button in applications where tabs will not always be used - keyboard shortcuts and/or menu items are sufficient in these cases.</p></item>
</list>

<section id="keyboard-shortcuts">
<title>Standard Keyboard Shortcuts</title>

<p>When using dynamic tabs, ensure that the standard keyboard shortcuts are supported.</p>

<table>
<tr>
<td><p><keyseq><key>Ctrl</key><key>T</key></keyseq></p></td>
<td><p>Create a new tab</p></td>
</tr>
<tr>
<td><p><keyseq><key>Ctrl</key><key>W</key></keyseq></p></td>
<td><p>Close the current tab</p></td>
</tr>
<tr>
<td><p><keyseq><key>Ctrl</key><key>Page Up</key></keyseq></p></td>
<td><p>Switch to the next tab</p></td>
</tr>
<tr>
<td><p><keyseq><key>Ctrl</key><key>Page Down</key></keyseq></p></td>
<td><p>Switch to the previous tab</p></td>
</tr>
</table>

</section>

</section>

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

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

</section>
</page>
