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

  <info>
    <link type="guide" xref="patterns#primary"/>
    <desc>Grids of thumbnails or icons</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>Grids</title>

<media type="image" mime="image/svg" src="figures/patterns/grid.svg"/>

<p>A grid is one of the primary methods of presenting collections of content in GNOME 3. Grids are often combined with a number of the other design patterns, including <link xref="search">search</link> and <link xref="selection-mode">selection mode</link>.</p>

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

<p>Since the grid view utilizes an image for each item it presents, it is best suited to content that has a visual component, such as documents or photos. If content items don't have a visual component, a <link xref="lists">list view</link> might be more appropriate.</p>

<p>Grids and lists can be combined, to offer different views of the same content. This can be useful if content items have additional metadata associated with them, such as creation dates or authorship.</p>

</section>

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

<list>
<item><p>Wherever possible, each item of content should have a unique thumbnail.</p></item>
<item><p>Order the items in the grid according to what will be most useful to people using your application. Ordering content according to most recently used is often the best arrangement.</p></item>
<item><p>Selecting an item in the grid will typically switch to a dedicated view of that item.</p></item>
<item><p>Consider combining the grid view search, selection mode and collections.</p></item>
</list>

</section>

<section id="api-reference">
<title>API reference</title>
<list>
<item><p><link href="https://developer.gnome.org/gtk3/stable/GtkFlowBox.html">GtkFlowBox</link></p></item>
<item><p><link href="https://developer.gnome.org/gtk3/stable/GtkIconView.html">GtkIconView</link></p></item>
</list>
</section>

</page>