diff options
Diffstat (limited to 'docs/html/guide/topics/ui/notifiers/toasts.jd')
| -rw-r--r-- | docs/html/guide/topics/ui/notifiers/toasts.jd | 154 |
1 files changed, 154 insertions, 0 deletions
diff --git a/docs/html/guide/topics/ui/notifiers/toasts.jd b/docs/html/guide/topics/ui/notifiers/toasts.jd new file mode 100644 index 0000000..a800c3c --- /dev/null +++ b/docs/html/guide/topics/ui/notifiers/toasts.jd @@ -0,0 +1,154 @@ +page.title=Creating Toast Notifications +parent.title=Notifying the User +parent.link=index.html +@jd:body + +<div id="qv-wrapper"> + <div id="qv"> + <h2>Key classes</h2> + <ol> + <li>{@link android.widget.Toast}</li> + </ol> + <h2>In this document</h2> + <ol> + <li><a href="#Basics">The Basics</a></li> + <li><a href="#Position">Positioning your Toast</a></li> + <li><a href="#CustomToastView">Creating a Custom Toast View</a></li> + </ol> + </div> +</div> + +<p>A toast notificaiton is a message that pops up on the surface of the window. +It only fills the amount of space required for the message and the user's current +activity remains visible and interactive. The notification automatically fades in and +out, and does not accept interaction events.</p> + +<p>The screenshot below shows an example toast notification from the Alarm application. +Once an alarm is turned on, a toast is displayed to assure you that the +alarm was set.</p> +<img src="{@docRoot}images/toast.png" alt="" /> + +<p>A toast can be created and displayed from an {@link android.app.Activity} or +{@link android.app.Service}. If you create a toast notification from a Service, it +appears in front of the Activity currently in focus.</p> + +<p>If user response to the notification is required, consider using a +<a href="notifications.html">Status Bar Notification</a>.</p> + + +<h2 id="Basics">The Basics</h2> + +<p>First, instantiate a {@link android.widget.Toast} +object with one of the {@link android.widget.Toast#makeText(Context,int,int) makeText()} methods. +This method takes three parameters: the application {@link android.content.Context}, +the text message, and the duration for the toast. It returns a properly initialized Toast +object. You can display the toast notification with {@link android.widget.Toast#show()}, +as shown in the following example:</p> + +<pre> +Context context = getApplicationContext(); +CharSequence text = "Hello toast!"; +int duration = Toast.LENGTH_SHORT; + +Toast toast = Toast.makeText(context, text, duration); +toast.show(); +</pre> + +<p>This example demonstrates everything you need for most toast notifications. +You should rarely need anything else. You may, however, want to position the +toast differently or even use your own layout instead of a simple text message. +The following sections describe how you can do these things.</p> + +<p>You can also chain your methods and avoid holding on to the Toast object, like this:</p> +<pre>Toast.makeText(context, text, duration).show();</pre> + + +<h2 id="Positioning">Positioning your Toast</h2> + +<p>A standard toast notification appears near the bottom of the screen, centered horizontally. +You can change this position with the {@link android.widget.Toast#setGravity(int,int,int)} +method. This accepts three parameters: a {@link android.view.Gravity} constant, +an x-position offset, and a y-position offset.</p> + +<p>For example, if you decide that the toast should appear in the top-left corner, you can set the +gravity like this:</p> +<pre> +toast.setGravity(Gravity.TOP|Gravity.LEFT, 0, 0); +</pre> + +<p>If you want to nudge the position to the right, increase the value of the second parameter. +To nudge it down, increase the value of the last parameter. + + +<h2 id="CustomToastView">Creating a Custom Toast View</h2> + +<img src="{@docRoot}images/custom_toast.png" alt="" style="float:right" /> + +<p>If a simple text message isn't enough, you can create a customized layout for your +toast notification. To create a custom layout, define a View layout, +in XML or in your application code, and pass the root {@link android.view.View} object +to the {@link android.widget.Toast#setView(View)} method.</p> + +<p>For example, you can create the layout for the toast visible in the screenshot to the right +with the following XML (saved as <em>toast_layout.xml</em>):</p> +<pre> +<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" + android:id="@+id/toast_layout_root" + android:orientation="horizontal" + android:layout_width="fill_parent" + android:layout_height="fill_parent" + android:padding="10dp" + android:background="#DAAA" + > + <ImageView android:id="@+id/image" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:layout_marginRight="10dp" + /> + <TextView android:id="@+id/text" + android:layout_width="wrap_content" + android:layout_height="fill_parent" + android:textColor="#FFF" + /> +</LinearLayout> +</pre> + +<p>Notice that the ID of the LinearLayout element is "toast_layout". You must use this +ID to inflate the layout from the XML, as shown here:</p> + +<pre> +LayoutInflater inflater = getLayoutInflater(); +View layout = inflater.inflate(R.layout.toast_layout, + (ViewGroup) findViewById(R.id.toast_layout_root)); + +ImageView image = (ImageView) layout.findViewById(R.id.image); +image.setImageResource(R.drawable.android); +TextView text = (TextView) layout.findViewById(R.id.text); +text.setText("Hello! This is a custom toast!"); + +Toast toast = new Toast(getApplicationContext()); +toast.setGravity(Gravity.CENTER_VERTICAL, 0, 0); +toast.setDuration(Toast.LENGTH_LONG); +toast.setView(layout); +toast.show(); +</pre> + +<p>First, retrieve the {@link android.view.LayoutInflater} with +{@link android.app.Activity#getLayoutInflater()} +(or {@link android.content.Context#getSystemService(String) getSystemService()}), +and then inflate the layout from XML using +{@link android.view.LayoutInflater#inflate(int, ViewGroup)}. The first parameter +is the layout resource ID and the second is the root View. You can use +this inflated layout to find more View objects in the layout, so now capture and +define the content for the ImageView and TextView elements. Finally, create +a new Toast with {@link android.widget.Toast#Toast(Context)} and set some properties +of the toast, such as the gravity and duration. Then call +{@link android.widget.Toast#setView(View)} and pass it the inflated layout. +You can now display the toast with your custom layout by calling +{@link android.widget.Toast#show()}.</p> + +<p class="note"><strong>Note:</strong> Do not use the public constructor for a Toast +unless you are going to define the layout with {@link android.widget.Toast#setView(View)}. +If you do not have a custom layout to use, you must use +{@link android.widget.Toast#makeText(Context,int,int)} to create the Toast.</p> + |