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

  <info>
    <link type="guide" xref="patterns#primary"/>
    <desc>System-wide event notifications</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>Notifications</title>

<p>Notifications enable you to inform the users about events when they are not using your application. They also provide the ability for users to quickly respond to those events, using notification actions.</p>

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

<p>Use notifications to inform the user about events they will be interested in while they are not using your application. This can include new messages in messaging applications, the completion of long-running tasks, reminders for calendars, and so on.</p>

<p>Notifications shouldn’t be used as a substitute for feedback that is provided by your application windows, which should be able to inform the user about events without the need for notifications.</p>

</section>

<section id="notification-elements">
<title>Notification elements</title>

<p>Notifications in GNOME 3 have a number of standard components:</p>

<table>
<thead>
<tr>
<td><p>Element</p></td><td><p>Descrição</p></td>
</tr>
</thead>
<tbody>
<tr>
<td><p>Application Icon</p></td><td><p>Indicates which application sent the notification.</p></td>
</tr>
<tr>
<td><p>Título</p></td><td><p>The heading for the notification.</p></td>
</tr>
<tr>
<td><p>Body</p></td><td><p>An optional block of text which gives extra detail about the notification. The notification body can include multiple paragraphs. For example: a snippet from the beginning of an email.</p></td>
</tr>
<tr>
<td><p>Default Action</p></td><td><p>This is the action that is triggered when the notification is activated.</p></td>
</tr>
<tr>
<td><p>Actions</p></td><td><p>Each notification can include up to three buttons.</p></td>
</tr>
</tbody>
</table>

<section id="titles">
<title>Titles</title>

<p>The title should provide a short and concise summary of the event that triggered the notification. The notification body may not always be visible, so it is important to ensure that the notification can be understood from the title alone.</p>

</section>

<section id="default-actions">
<title>Default actions</title>

<p>The default action should always dismiss the notification and raise a window belonging to the application that sent the notification. If the notification relates to a particular part of your application’s user interface, the default action should display that part of the UI. The default action for a notification about a new email should show the relevant email message when activated, for example.</p>

</section>

<section id="actions">
<title>Notification actions</title>

<p>You can provide useful functionality by embedding buttons in notifications. This allows users to quickly and easily respond to the notification.</p>

<list>
<item><p>Notification actions should be related to the content of the notification, and should not provide generic actions for your application. This ensures that each notification has a clear focus and purpose.</p></item>
<item><p>Only use notification actions when the functionality that they provide is commonly required.</p></item>
<item><p>Actions should not replace user interface controls elsewhere - it should be possible to take the same actions from your application’s windows.</p></item>
<item><p>It is not necessary to always use notification actions, and many notifications will not require them.</p></item>
<item><p>Notification actions should not duplicate the default action. For example, a new email notification does not need to include an Open button, since the default action should already perform this action.</p></item>
</list>

</section>
</section>

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

<list>
<item><p>It is important not to needlessly distract users with notifications. This can easily become annoying and frustrating, and will not incline users to like your application. Therefore, always be critical when using notifications, and question whether users really need to be informed about the events you want to communicate.</p></item>
<item><p>Applications that deal with lots of events, such as email or social media messages, run a particular risk of distracting users with too many notifications. These applications should place restrictions on how frequently they send notification messages. Instead of showing a notification for each new message, it is a good idea for each notification to provide a summary of new messages.</p></item>
<item><p>Notifications in GNOME 3 persist after they have been initially displayed. It is therefore important to remove notification messages that are no longer relevant to the user.</p>
<list>
<item><p>Your application window should provide feedback on all the events that have been communicated by notifications. As a result, when your application window is focused, notification messages should be treated as having been read, and should be removed.</p></item>
<item><p>Ensure that your application removes notifications that are no longer valid. For example, a notification for a weather warning that has been revoked should be removed.</p></item>
</list></item>
</list>

</section>

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

</page>