+ + Figure 1. A {@link android.support.design.widget.Snackbar} + shows a message at the bottom of the + activity, but the rest of the activity is still usable. +
++ You can add an action to a {@link android.support.design.widget.Snackbar}, + allowing the user to respond to your message. If you add an action to a + {@link android.support.design.widget.Snackbar}, the + {@link android.support.design.widget.Snackbar} puts a button + next to the message text. The user can trigger your action by pressing the + button. For example, an email app might put an undo button on its + "email archived" message; if the user clicks the undo button, the + app takes the email back out of the archive. +
+ +
+
++ Figure 1. This Snackbar has an Undo + button, which restores the item that was just removed. +
+ ++ To add an action to a {@link android.support.design.widget.Snackbar} message, + you need to define a listener object that implements the {@link + android.view.View.OnClickListener} interface. The system calls your + listener's {@link android.view.View.OnClickListener#onClick onClick()} method + if the user clicks on the message action. For example, this snippet shows a + listener for an undo action: +
+ +public class MyUndoListener implements View.OnClickListener{
+
+ &Override
+ public void onClick(View v) {
+
+ // Code to undo the user's last action
+ }
+}
+
++ Use one of the + {@link android.support.design.widget.Snackbar#setAction(int, android.view.View.OnClickListener) + SetAction()} methods to attach the listener to your {@link + android.support.design.widget.Snackbar}. Be sure to attach the listener + before you call {@link android.support.design.widget.Snackbar#show show()}, + as shown in this code sample: +
+ +Snackbar mySnackbar = Snackbar.make(findViewById(R.id.myCoordinatorLayout), + R.string.email_archived, Snackbar.LENGTH_SHORT); +mySnackbar.setAction(R.string.undo_string, new MyUndoListener()); +mySnackbar.show();+ +
+ Note: A {@link android.support.design.widget.Snackbar} + automatically goes away after a short time, so you can't count on the user + seeing the message or having a chance to press the button. For this reason, + you should consider offering an alternate way to perform any {@link + android.support.design.widget.Snackbar} action. +
diff --git a/docs/html/training/snackbar/index.jd b/docs/html/training/snackbar/index.jd new file mode 100644 index 0000000000000..312f10cd34ae3 --- /dev/null +++ b/docs/html/training/snackbar/index.jd @@ -0,0 +1,94 @@ +page.title=Showing Pop-Up Messages +page.tags="Snackbar","Toast" +helpoutsWidget=true +trainingnavtop=true +startpage=true + +@jd:body + ++ There are many situations where you might want your app to show a quick + message to the user, without necessarily waiting for the user to respond. + For example, when a user performs an action like sending an email or deleting + a file, your app should show a quick confirmation to the user. Often the user + doesn't need to respond to the message. The message needs to be prominent + enough that the user can see it, but not so prominent that it prevents the + user from working with your app. +
+ ++ Android provides the {@link android.support.design.widget.Snackbar} widget + for this common use case. + A {@link android.support.design.widget.Snackbar} provides a quick pop-up + message to the user. The current activity remains visible and interactive + while the {@link android.support.design.widget.Snackbar} is displayed. After a + short time, the Snackbar automatically dismisses itself. +
+ ++ This class teaches you how to use {@link + android.support.design.widget.Snackbar} to show pop-up messages. +
+ +
+ + Figure 1. A {@link android.support.design.widget.Snackbar} + shows a message at the bottom of the + activity, but the rest of the activity is still usable. +
++ Note: The {@link + android.support.design.widget.Snackbar} class supersedes {@link + android.widget.Toast}. While {@link android.widget.Toast} is currently still + supported, {@link android.support.design.widget.Snackbar} is now the + preferred way to display brief, transient messages to the user. +
+ ++ You can use a {@link android.support.design.widget.Snackbar} to display a brief + message to the user. The message automatically goes away after a short + period. A {@link android.support.design.widget.Snackbar} is ideal + for brief messages that the user doesn't necessarily need to act on. For + example, an email app could use a {@link + android.support.design.widget.Snackbar} to tell the user that the app + successfully sent an email. +
+ ++ A {@link android.support.design.widget.Snackbar} is attached to a view. The + {@link android.support.design.widget.Snackbar} provides basic functionality + if it is attached to any object derived from the {@link android.view.View} + class, such as any of the common layout objects. However, if the + {@link android.support.design.widget.Snackbar} + is attached to a {@link android.support.design.widget.CoordinatorLayout}, the + {@link android.support.design.widget.Snackbar} gains additional features: +
+ ++ The {@link android.support.design.widget.CoordinatorLayout} class provides a superset + of the functionality of {@link android.widget.FrameLayout}. If your app + already uses a {@link android.widget.FrameLayout}, you can just replace that + layout with a {@link android.support.design.widget.CoordinatorLayout} to + enable the full {@link android.support.design.widget.Snackbar} functionality. + If your app uses other layout objects, the simplest thing to do is wrap your + existing layout elements in a {@link + android.support.design.widget.CoordinatorLayout}, as in this example: +
+ +<android.support.design.widget.CoordinatorLayout + android:id="@+id/myCoordinatorLayout" + xmlns:android="http://schemas.android.com/apk/res/android" + xmlns:app="http://schemas.android.com/apk/res-auto" + android:layout_width="match_parent" + android:layout_height="match_parent"> + + <!-- Here are the existing layout elements, now wrapped in + a CoordinatorLayout --> + <LinearLayout + android:layout_width="match_parent" + android:layout_height="match_parent" + android:orientation="vertical"> + + <!-- …Toolbar, other layouts, other elements… --> + + </LinearLayout> + +</android.support.design.widget.CoordinatorLayout>+ +
+ Make sure to set an android:id tag for your {@link
+ android.support.design.widget.CoordinatorLayout}. You need the layout's ID
+ when you display the message.
+
+ Figure 1. The {@link android.support.design.widget.CoordinatorLayout} + moves the {@link android.support.design.widget.FloatingActionButton} up + when the {@link android.support.design.widget.Snackbar} appears. +
+ ++ There are two steps to displaying a message. First, you create a {@link + android.support.design.widget.Snackbar} object with the message text. Then, + you call that object's {@link android.support.design.widget.Snackbar#show + show()} method to display the message to the user. +
+ ++ Create a {@link android.support.design.widget.Snackbar} object by + calling the static {@link android.support.design.widget.Snackbar#make + Snackbar.make()} method. When you create the {@link + android.support.design.widget.Snackbar}, you specify both the message it + displays, and the length of time to show the message: +
+ +Snackbar mySnackbar = Snackbar.make(viewId, stringId, duration);+ +
+ Once you have created the {@link android.support.design.widget.Snackbar}, + call its {@link android.support.design.widget.Snackbar#show show()} method to + display the {@link android.support.design.widget.Snackbar} to the user: +
+ +mySnackbar.show();+ +
+ The system does not show multiple {@link + android.support.design.widget.Snackbar} objects at the same time, so if the + view is currently displaying another {@link + android.support.design.widget.Snackbar}, the system queues your {@link + android.support.design.widget.Snackbar} and displays it after the current + {@link android.support.design.widget.Snackbar} expires or is dismissed. +
+ ++ If you just want to show a message to the user and won't need to call any of + the {@link android.support.design.widget.Snackbar} object's utility methods, + you don't need to keep the reference to the {@link + android.support.design.widget.Snackbar} after you call {@link + android.support.design.widget.Snackbar#show show()}. For this reason, it's + common to use method chaining to create and show a {@link + android.support.design.widget.Snackbar} in one statement: +
+ +Snackbar.make(findViewById(R.id.myCoordinatorLayout), R.string.email_sent, + Snackbar.LENGTH_SHORT) + .show();diff --git a/docs/html/training/training_toc.cs b/docs/html/training/training_toc.cs index 85733bfd02e99..a99dd8975df74 100644 --- a/docs/html/training/training_toc.cs +++ b/docs/html/training/training_toc.cs @@ -1464,6 +1464,24 @@ results." +