<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="selection-mode">

  <info>
    <link type="guide" xref="patterns#primary"/>
    <desc>Pattern for selecting content items</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>Selection mode</title>

<media type="image" mime="image/svg" src="figures/patterns/selection-mode.svg"/>

<p>Selection mode is a design pattern for allow actions to be performed on items of content. It is typically used in conjunction with lists and grids.</p>

<p>When selection mode is active, check boxes allow items to be selected, and an action bar is shown at the bottom of the view. This contains the various actions that can be performed on selected content items.</p>

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

<p>Selection mode is appropriate when:</p>

<list>
<item><p>It is common to perform actions simultaneously on multiple content items.</p></item>
<item><p>Multiple actions are available to be performed on content items.</p></item>
<item><p>It is helpful for users to be able to perform actions on content items without opening them.</p></item>
</list>

<p>If it is more typical for users to perform actions on single content items, you might want to consider another design pattern, such as a context menu. Likewise, if there is only one action that can be performed on content items, a variant of selection mode can be used (an overlaid button could allow the action to be performed on items directly, rather than requiring them to be selected first, for example).</p>

</section>

<section id="activating-selection-mode">
<title>Activating selection mode</title>

<p>The primary way of activating selection mode is through the selection mode button, which is located in the header bar and which is identified by a check mark icon. Selection mode can also be activated by rubber band selection, or by holding Ctrl or Shift and clicking/pressing content items.</p>

</section>

<section id="action-bar">
<title>The action bar</title>

<list>
<item><p>Controls in the action bar should be insensitive when no items have been selected. Sometimes actions may only be applied to multiple content items; in this case the relevant controls should only be sensitive when multiple items are selected.</p></item>
<item><p>Controls in the action toolbar can have icons or text labels.</p></item>
<item><p>Groups of actions can be distinguished by placing them at either end of the toolbar. Destructive actions, like delete, should be placed away from other controls.</p></item>
</list>

</section>
</page>