<?xml version="1.0" encoding="utf-8"?>
<page xmlns="http://projectmallard.org/1.0/" type="topic" id="search" xml:lang="pt-BR">

  <info>
    <link type="guide" xref="patterns#primary"/>
    <desc>Find and filter content by typing</desc> 
    <credit type="author">
      <name>Allan Day</name>
      <email>aday@gnome.org</email>
    </credit>
    <include xmlns="http://www.w3.org/2001/XInclude" href="legal.xml"/>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Georges Neto</mal:name>
      <mal:email>georges.stavracas@gmail.com</mal:email>
      <mal:years>2014.</mal:years>
    </mal:credit>
  
    <mal:credit xmlns:mal="http://projectmallard.org/1.0/" type="translator copyright">
      <mal:name>Rafael Fontenelle</mal:name>
      <mal:email>rafaelff@gnome.org</mal:email>
      <mal:years>2017</mal:years>
    </mal:credit>
  </info>

<title>Search</title>

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

<p>Search allows content items to be located by filtering content that is displayed on screen. It is distinct from find, which involves moving or highlighting the content that is being searched for, rather than filtering.</p>

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

<p>Provide search whenever a large collection of content is presented, and those content items have a textual component. This could be a collection of actual content items, such as documents, contacts or videos, or a list of options.</p>

<p>Search is a great way to make it easy for users to find what it is they are looking for, and its consistent availability means that users can rely on and expect it to be present.</p>

<p>However, while search can be highly effective, and some users will use it, others will not. Therefore, try to supplement other means for finding content items with search, rather than relying on it exclusively.</p>

</section>

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

<p>The standard pattern for search in GNOME 3 utilizes a special search bar which slides down from beneath the header bar.

In primary windows, the search bar is typically hidden until it is activated by the user. There are three common ways to activate search in this context:</p>

<list>
<item><p>Typing when a text entry field is not focused should activate search, and the entered text should be added to the search field. This is called “type to search”.</p></item>
<item><p>The keyboard shortcut for search (<keyseq><key>Ctrl</key><key>F</key></keyseq>).</p></item>
<item><p>A search button in the header bar should allow the search bar to be displayed (the search button should toggle).</p></item>
</list>

<p>If search is a primary method for finding content in your application, you can make the search bar permanently visible, or visible when the application is first started.</p>

</section>

<section id="search-results">
<title>Search results</title>

<list>
<item><p>Search should be “live” wherever possible - the content view should update to display search results as they are entered.</p></item>
<item><p>In order to be effective, it is important that search results are quickly returned.</p></item>
<item><p>If a search term does not return any results, ensure that feedback is given in the content view. Often a simple "No results" label is sufficient.</p></item>
</list>

</section>

<section id="additional-guidance">
<title>Guia adicional</title>

<list>
<item><p>Be tolerant of mistakes in search terms. Matching misspellings or incorrect terminology is one way to do this. Presenting suggestions for similar matches or related content is another.</p></item>
<item><p>Permit a broad range of matching search terms. This helps people who are unsure of the exact term they require but who do know characteristics associated with the item they want to find. A list of cities could return matches for country or region, for example.</p></item>
<item><p>Results should be ordered in a way that ensures that the most relevant items are displayed first.</p></item>
</list>

</section>

<section id="api-reference">
<title>Referência de API</title>
<list>
<item><p><link href="https://developer.gnome.org/gtk3/stable/GtkSearchEntry.html">GtkSearchEntry</link></p></item>
</list>
</section>

</page>