1 page.title=Building and Displaying a Pop-Up Message 2 page.tags="Snackbar" "popup" "pop-up" 3 helpoutsWidget=true 4 trainingnavtop=true 5 6 @jd:body 7 8 <div id="tb-wrapper"> 9 <div id="tb"> 10 11 <h2>This lesson teaches you to</h2> 12 13 <ol> 14 <li><a href="#coordinator">Use a CoordinatorLayout</a></li> 15 <li><a href="#display">Display a Message</a></li> 16 </ol> 17 18 <h2>You should also read</h2> 19 <ul> 20 <li><a href="{@docRoot}tools/support-library/setup.html" 21 >Support Library Setup</a></li> 22 </ul> 23 </div> 24 </div> 25 26 27 <p> 28 You can use a {@link android.support.design.widget.Snackbar} to display a brief 29 message to the user. The message automatically goes away after a short 30 period. A {@link android.support.design.widget.Snackbar} is ideal 31 for brief messages that the user doesn't necessarily need to act on. For 32 example, an email app could use a {@link 33 android.support.design.widget.Snackbar} to tell the user that the app 34 successfully sent an email. 35 </p> 36 37 <h2 id="coordinator">Use a CoordinatorLayout</h2> 38 39 <p> 40 A {@link android.support.design.widget.Snackbar} is attached to a view. The 41 {@link android.support.design.widget.Snackbar} provides basic functionality 42 if it is attached to any object derived from the {@link android.view.View} 43 class, such as any of the common layout objects. However, if the 44 {@link android.support.design.widget.Snackbar} 45 is attached to a {@link android.support.design.widget.CoordinatorLayout}, the 46 {@link android.support.design.widget.Snackbar} gains additional features: 47 </p> 48 49 <ul> 50 <li>The user can dismiss the {@link android.support.design.widget.Snackbar} 51 by swiping it away. 52 </li> 53 54 <li>The layout moves some other UI elements when the {@link 55 android.support.design.widget.Snackbar} appears. For example, if the layout 56 has a {@link android.support.design.widget.FloatingActionButton}, the layout 57 moves the button up when it shows a {@link 58 android.support.design.widget.Snackbar}, instead of drawing the {@link 59 android.support.design.widget.Snackbar} on top of the button. You can see how 60 this looks in Figure 1. 61 </li> 62 </ul> 63 64 <p> 65 The {@link android.support.design.widget.CoordinatorLayout} class provides a superset 66 of the functionality of {@link android.widget.FrameLayout}. If your app 67 already uses a {@link android.widget.FrameLayout}, you can just replace that 68 layout with a {@link android.support.design.widget.CoordinatorLayout} to 69 enable the full {@link android.support.design.widget.Snackbar} functionality. 70 If your app uses other layout objects, the simplest thing to do is wrap your 71 existing layout elements in a {@link 72 android.support.design.widget.CoordinatorLayout}, as in this example: 73 </p> 74 75 <pre><android.support.design.widget.CoordinatorLayout 76 android:id="@+id/myCoordinatorLayout" 77 xmlns:android="http://schemas.android.com/apk/res/android" 78 xmlns:app="http://schemas.android.com/apk/res-auto" 79 android:layout_width="match_parent" 80 android:layout_height="match_parent"> 81 82 <!-- Here are the existing layout elements, now wrapped in 83 a CoordinatorLayout --> 84 <LinearLayout 85 android:layout_width="match_parent" 86 android:layout_height="match_parent" 87 android:orientation="vertical"> 88 89 <!-- Toolbar, other layouts, other elements --> 90 91 </LinearLayout> 92 93 </android.support.design.widget.CoordinatorLayout></pre> 94 95 <p> 96 Make sure to set an <code>android:id</code> tag for your {@link 97 android.support.design.widget.CoordinatorLayout}. You need the layout's ID 98 when you display the message. 99 </p> 100 101 <div class="framed-nexus5-port-span-5" id="video-coord"> 102 <video class="play-on-hover" autoplay loop 103 alt="If the Snackbar is attached to a CoordinatorLayout, the layout 104 moves other elements up when it shows the Snackbar."> 105 <!-- Preferred video size 216x384 (portrait) --> 106 <source src="{@docRoot}images/training/snackbar/snackbar_button_move.mp4"> 107 </video> 108 </div> 109 110 <p class="img-caption"> 111 <strong>Figure 1.</strong> The {@link android.support.design.widget.CoordinatorLayout} 112 moves the {@link android.support.design.widget.FloatingActionButton} up 113 when the {@link android.support.design.widget.Snackbar} appears. 114 </p> 115 116 <h2 id="display"> 117 Display a Message 118 </h2> 119 120 <p> 121 There are two steps to displaying a message. First, you create a {@link 122 android.support.design.widget.Snackbar} object with the message text. Then, 123 you call that object's {@link android.support.design.widget.Snackbar#show 124 show()} method to display the message to the user. 125 </p> 126 127 <h3 id="create-snackbar">Creating a Snackbar object</h3> 128 129 <p> 130 Create a {@link android.support.design.widget.Snackbar} object by 131 calling the static {@link android.support.design.widget.Snackbar#make 132 Snackbar.make()} method. When you create the {@link 133 android.support.design.widget.Snackbar}, you specify both the message it 134 displays, and the length of time to show the message: 135 </p> 136 137 <pre>Snackbar mySnackbar = Snackbar.make(viewId, stringId, duration);</pre> 138 139 <dl> 140 <dt> 141 <em>viewId</em> 142 </dt> 143 144 <dd> 145 The view to attach the {@link android.support.design.widget.Snackbar} to. 146 The method actually searches up the view hierarchy from the passed 147 <em>viewId</em> until it reaches either a {@link 148 android.support.design.widget.CoordinatorLayout}, or the window decor's 149 content view. Ordinarily, it's simplest to just pass the ID of the {@link 150 android.support.design.widget.CoordinatorLayout} enclosing your content. 151 </dd> 152 153 <dt> 154 <em>stringId</em> 155 </dt> 156 157 <dd> 158 The resource ID of the message you want to display. This can be formatted 159 or unformatted text. 160 </dd> 161 162 <dt> 163 <em>duration</em> 164 </dt> 165 166 <dd> 167 The length of time to show the message. This can be either {@link 168 android.support.design.widget.Snackbar#LENGTH_SHORT LENGTH_SHORT} or {@link 169 android.support.design.widget.Snackbar#LENGTH_LONG LENGTH_LONG}. 170 </dd> 171 </dl> 172 173 <h3 id="show-snackbar">Showing the message to the user</h3> 174 175 <p> 176 Once you have created the {@link android.support.design.widget.Snackbar}, 177 call its {@link android.support.design.widget.Snackbar#show show()} method to 178 display the {@link android.support.design.widget.Snackbar} to the user: 179 </p> 180 181 <pre>mySnackbar.show();</pre> 182 183 <p> 184 The system does not show multiple {@link 185 android.support.design.widget.Snackbar} objects at the same time, so if the 186 view is currently displaying another {@link 187 android.support.design.widget.Snackbar}, the system queues your {@link 188 android.support.design.widget.Snackbar} and displays it after the current 189 {@link android.support.design.widget.Snackbar} expires or is dismissed. 190 </p> 191 192 <p> 193 If you just want to show a message to the user and won't need to call any of 194 the {@link android.support.design.widget.Snackbar} object's utility methods, 195 you don't need to keep the reference to the {@link 196 android.support.design.widget.Snackbar} after you call {@link 197 android.support.design.widget.Snackbar#show show()}. For this reason, it's 198 common to use method chaining to create and show a {@link 199 android.support.design.widget.Snackbar} in one statement: 200 </p> 201 202 <pre>Snackbar.make(findViewById(R.id.myCoordinatorLayout), R.string.email_sent, 203 Snackbar.LENGTH_SHORT) 204 .show();</pre> 205
