<page xmlns="http://projectmallard.org/1.0/" xmlns:uix="http://projectmallard.org/experimental/ui/" type="topic" id="text-fields" xml:lang="pt-BR">

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

    <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>Text fields</title>

A text entry field is an interface element for entering or editing text. It is a basic element with a variety of uses, including search entry, settings and preferences, or account configuration and setup. A text entry field can be prefilled with text, and can include additional buttons or icons.

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

<section id="general-guidelines">

<title>Diretrizes gerais</title>

<list>

<item>
Size text fields according to the likely size of the content they will contain. This gives a useful visual cue to the amount of input expected and prevents overflow.
</item>

<item>
In an <link xref="dialogs#instant-and-explicit-apply">instant-apply dialog</link>, validate the contents of the entry field when it loses focus or when the window is closed, not after each keypress. Exception: if the field accepts only a fixed number of characters, such as a hexadecimal color code, validate and apply the change as soon as that number of characters have been entered.
</item>

<item>
If you implement an entry field that only accepts certain characters, such as digits, play the system warning beep when the user tries to type an invalid character.
</item>

<item>
Normally, pressing <key>Tab</key> in a single-line entry field should move focus to the next control, and in a multi-line entry field it should insert a tab character. Pressing <keyseq><key>Ctrl</key><key>Tab</key></keyseq> in a multi-line entry field should move focus to the next control.
</item>

<item>
If you need to provide a keyboard shortcut that inserts a tab character into a single line entry field, use <keyseq><key>Ctrl</key><key>Tab</key></keyseq>. You are unlikely to find many situations where this is useful, however.
</item>

</list>

</section>

<section id="embedding-info-and-controls">

<title>Embedding information and controls</title>

A variety of additional information or controls can be inserted within a text entry field.

Icons or icon buttons can be placed inside a text field to provide status information or additional controls.

<list>

<item>
An icon at the beginning of the entry can be used to indicate its purpose - replacing the need for the entry to be labelled. Search entry fields are the classic example of this, where a search icon is placed on the left side of the entry field.
</item>

<item>
If the text to be entered is case sensitive, a warning icon can be shown inside the text field if caps lock is on. This is typically shown on the right side of the entry.
</item>

<item>
If it is common for the text field to be cleared, a clear icon button can be placed inside the field, at the right side.
</item>

<item>
If you place an icon in a text entry field (either as an indicator or a button), use its symbolic variant from the GNOME Symbolic Icon Theme.
</item>

</list>

When a user would benefit from additional information in order to use a text entry field, it can be prefilled with a hint text. As with any decision to display additional information, this should only be done when it is necessary.

</section>

<section id="api-reference">

<title>Referência de API</title>

<list>

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

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

</list>

</section>

</page>