1page.title=Notifications 2parent.title=User Interface 3parent.link=../index.html 4@jd:body 5 6<p>Several types of situations may arise that require you to notify the user 7about an event that occurs in your application. Some events require the user to respond 8and others do not. For example:</p> 9<ul> 10 <li>When an event such as saving a file is complete, a small message 11should appear to confirm that the save was successful.</li> 12 <li>If the application is running in the background and needs the user's attention, 13the application should create a notification that allows the user to respond at 14his or her convenience.</li> 15 <li>If the application is 16performing work that the user must wait for (such as loading a file), 17the application should show a hovering progress wheel or bar.</li> 18</ul> 19 20<p>Each of these notification tasks can be achieved using a different technique:</p> 21<ul> 22 <li>A <a href="#Toast">Toast Notification</a>, for brief messages that come 23 from the background.</li> 24 <li>A <a href="#StatusBar">Status Bar Notification</a>, for persistent reminders 25 that come from the background and request the user's response.</li> 26 <li>A <a href="#Dialog">Dialog Notification</a>, for Activity-related notifications.</li> 27</ul> 28 29<p>This document summarizes each of these techniques for notifying the user and includes 30links to full documentation.</p> 31 32 33<h2 id="Toast">Toast Notification</h2> 34 35<img src="{@docRoot}images/toast.png" alt="" style="float:right" /> 36 37<p>A toast notification is a message that pops up on the surface of the window. 38It only fills the amount of space required for the message and the user's current 39activity remains visible and interactive. The notification automatically fades in and 40out, and does not accept interaction events. Because a toast can be created from a background 41{@link android.app.Service}, it appears even if the application isn't visible.</p> 42 43<p>A toast is best for short text messages, such as "File saved," 44when you're fairly certain the user is paying attention 45to the screen. A toast can not accept user interaction events; if you'd like 46the user to respond and take action, consider using a 47<a href="#StatusBar">Status Bar Notification</a> instead.</p> 48 49<p>For more information, refer to <a href="toasts.html">Toast Notifications</a>.</p> 50 51 52<h2 id="StatusBar">Status Bar Notification</h2> 53 54<img src="{@docRoot}images/notifications_window.png" alt="" style="float:right; clear:right;" /> 55 56<p>A status bar notification adds an icon to the system's status bar 57(with an optional ticker-text message) and an expanded message in the "Notifications" window. 58When the user selects the expanded message, Android fires an 59{@link android.content.Intent} that is defined by the notification (usually to launch an 60{@link android.app.Activity}). 61You can also configure the notification to alert the user with a sound, a vibration, and flashing 62lights on the device.</p> 63 64<p>This kind of notification is ideal when your application is working in 65a background {@link android.app.Service} and needs to 66notify the user about an event. If you need to alert the user about an event that occurs 67while your Activity is still in focus, consider using a 68<a href="#Dialog">Dialog Notification</a> instead.</p> 69 70<p>For more information, refer to 71<a href="notifications.html">Status Bar Notifications</a>.</p> 72 73 74<h2 id="Dialog">Dialog Notification</h2> 75 76<img src="{@docRoot}images/dialog_progress_spinning.png" alt="" style="float:right" /> 77 78<p>A dialog is usually a small window that appears in front of the current Activity. 79The underlying Activity loses focus and the dialog accepts all user interaction. 80Dialogs are normally used 81for notifications and short activities that directly relate to the application in progress.</p> 82 83<p>You should use a dialog when you need to show a progress bar or a short 84message that requires confirmation from the user (such as an alert with "OK" and "Cancel" buttons). 85You can use also use dialogs as integral components 86in your application's UI and for other purposes besides notifications. 87For a complete discussion on all the available types of dialogs, 88including its uses for notifications, refer to 89<a href="{@docRoot}guide/topics/ui/dialogs.html">Dialogs</a>.</p> 90 91 92 93
