path: root/docs/html/guide/topics/resources/available-resources.jd

page.title=Available Resource Types
parent.title=Resources and Assets
parent.link=index.html
@jd:body

<div id="qv-wrapper">
<div id="qv">

  <h2>Key classes</h2>
  <ol>
    <li>{@link android.content.res.Resources}</li>
    <li>{@link android.content.res.AssetManager}</li>
  </ol>

  <h2>In this document</h2>
  <ol>
    <li><a href="#simplevalues">Simple Values</a>
      <ol>
          <li><a href="#colorvals">Color Values</a></li>
          <li><a href="#stringresources">Strings and Styled Text</a></li>
          <li><a href="#dimension">Dimension Values</a></li>
      </ol>
    </li>
    <li><a href="#drawables">Drawables</a>
      <ol>
          <li><a href="#imagefileresources">Bitmap Files</a></li>
          <li><a href="#colordrawableresources">Color Drawables</a></li>
          <li><a href="#ninepatch">Nine-Patch (Stretchable) Images</a></li>
      </ol>
    </li>
    <li><a href="#animation">Animation</a></li>
    <li><a href="#menus">Menus</a></li>
    <li><a href="#layoutresources">Layout</a>
      <ol>
          <li><a href="#customresources">Custom Layout Resources</a>
      </ol>
    </li>
    <li><a href="#stylesandthemes">Styles and Themes</a></li>
    <li><a href="#Searchable">Searchable</a></li>
  </ol>

</div>
</div>

<p>This page describes the different types of resources that you can
externalize from your code and package with your application. </p>


<p>For more details on how to use resources in your application, please see the
    <a href="resources-i18n.html">Resources and Internationalization</a>
    documentation.</p>


<h2 id="simplevalues">Simple Values</h2>

<p>All simple resource values can be expressed as a string, using various
formats to unambiguously indicate the type of resource being created.  For
this reason, these values can be defined both as standard resources
(under res/values/), as well as direct values supplied for
mappings in <a href="#stylesandthemes">styles and themes</a>, and attributes in
XML files such as <a href="#layoutresources">layouts</a>.</p>



<h3 id="colorvals">Color Values</h3>
<p>
    A color value specifies an RGB value with an alpha channel, which can
    be used in various places such as specifying a solid color for a {@link android.graphics.drawable.Drawable}
    or the color to use for text.  A color value always begins with
    a pound (#) character and then followed by the Alpha-Red-Green-Blue information
    in one of the following formats:
</p>
<ul>
<li> #RGB
<li> #ARGB
<li> #RRGGBB
<li> #AARRGGBB
</ul>
<p>
    If you want to retrieve the color represented by a resource ID, you can call
    the {@link android.content.res.Resources#getColor(int) Resources.getColor()} method.
</p>
<p>
    <strong>Source file format:</strong> XML file requiring a
    <code>&lt;?xml version="1.0" encoding="utf-8"?&gt;</code> declaration, and
    a root <code>&lt;resources&gt;</code> element containing one or more
    <code>&lt;color&gt;</code> tags.
</p>
<p>
    <strong>Resource source file location</strong>: {@code res/values/<em>colors</em>.xml} (File name is arbitrary.)
</p>
<p>
    <strong>Compiled resource datatype:</strong> Resource pointer to a Java int.
</p>
<p>
    <strong>Resource reference name:</strong>
</p>
<ul>
    <li>
        <strong>Java:</strong> <code>R.color.<em>some_name</em></code>
    </li>
    <li>
        <strong>XML:</strong> <code>@[<em>package</em>:]color/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific color)
    </li>
</ul>
<p>
    <strong>Syntax</strong>
</p>
<pre>
&lt;color name=<em>color_name</em>&gt;<em>#color_value</em>&lt;/color&gt;
</pre>
<dl>
    <dt>
        &lt;color&gt;
    </dt>
    <dd>
        Value is a color, using web-style syntax, as describe above. Has only one attribute:
        <ul>
            <li>
                <em>name</em> - The name used in referring to this color.
            </li>
        </ul>
    </dd>
</dl>
<p>
    <strong>Example XML Declaration</strong>
</p>
<p>
    The following code declares two colors, the first fully opaque, and the
    second translucent.
</p>
<pre>
&lt;resources&gt;
   &lt;color name="opaque_red"&gt;#f00&lt;/color&gt;
   &lt;color name="translucent_red"&gt;#80ff0000&lt;/color&gt;
&lt;/resources&gt;
</pre>
<p>
    <strong>Example Code Use</strong>
</p>
<p>
    Example Java code
</p>
<pre>
// Retrieve a color value.
int color = getResources.getColor(R.color.opaque_red);
</pre>
<p>
    Example XML code
</p>
<pre>
&lt;TextView android:layout_width="fill_parent"
          android:layout_height="wrap_content"
          android:textAlign="center"
          android:textColor="@color/translucent_red"
          android:text="Some Text"/&gt;
</pre>



<h3 id="stringresources">Strings and Styled Text</h3>
<p>
    Strings, with optional <a href="#styledtext">simple formatting</a>, can be 
stored and retrieved as resources. You can add formatting to your string by 
using three standard HTML tags: &lt;b&gt;, &lt;i&gt;, and &lt;u&gt;. To 
guarantee getting an unstyled string only (the raw text) call the 
<code>toString()</code> method of the retrieved CharSequence object. 
Methods that accept string resources should be able to process these styling 
tags.
</p>
<p>
    If you want to retrieve the String represented by a resource ID, you can call the {@link android.content.Context#getString(int) Context.getString()} method.
</p>
<p>
    <strong>Note:</strong> If you use an apostrophe or a quote in your string, you must either escape it or enclose the whole string in the other kind of enclosing quotes:
</p>
<pre>
&lt;string name="good_example"&gt;"This'll work"&lt;/string&gt;
&lt;string name="good_example_2"&gt;This\'ll also work&lt;/string&gt;
&lt;string name="bad_example"&gt;This won't work!&lt;/string&gt;
&lt;string name="bad_example_2"&gt;XML encodings won&amp;apos;t work either!&lt;/string&gt;
</pre>
<p>
    <strong>Source file format:</strong> XML file requiring a <code>&lt;?xml version="1.0" encoding="utf-8"?&gt;</code> declaration, and a root <code>&lt;resources&gt;</code> element containing one or more <code>&lt;string&gt;</code> tags.
</p>
<p>
    <strong>Resource source file location</strong>: {@code res/values/<em>strings</em>.xml} (File name is arbitrary.)
</p>
<p>
    <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence.
</p>
<p>
    <strong>Resource reference name:</strong>
</p>
<ul>
    <li>
        <strong>Java:</strong> <code>R.string.<em>some_name</em></code>
    </li>
    <li>
        <strong>XML:</strong> <code>@[<em>package</em>:]string/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific string)
    </li>
</ul>
<p>
    <strong>Syntax</strong>
</p>
<pre>
&lt;string name=<em>string_name</em>&gt;<em>string_value</em>&lt;/string&gt;
</pre>
<dl>
    <dt>
        &lt;string&gt;
    </dt>
    <dd>
        Value is a string, with optional styling tags. Has only one attribute:
        <ul>
            <li>
                <em>name</em> - The name used in referring to this string.
            </li>
        </ul>
    </dd>
</dl>
<p>
    <strong>Example XML Declaration</strong>
</p>
<p>
    The following declares two strings: the first &mdash; simple text with no
    formatting (resulting in a CharSequence that is simply a String object) &mdash; the second includes formatting information in the string (resulting
    in a CharSequence that is a complex data structure). If you are using the custom editor for string files in Eclipse, the HTML formatting tags will automatically be escaped and you will need to use {@link android.content.Context#getString(int) Context.getString()} and {@link android.text.Html#fromHtml} to retrieve the resource and then convert it to formatted text.
</p>
<pre>
&lt;resources&gt;
   &lt;string name="simple_welcome_message"&gt;Welcome!&lt;/string&gt;
   &lt;string name="styled_welcome_message"&gt;We are &lt;b&gt;&lt;i&gt;so&lt;/i&gt;&lt;/b&gt; glad to see you.&lt;/string&gt;
&lt;/resources&gt;
</pre>
<p>
    <strong>Example Code Use</strong>
</p>
<p>
    Example Java code
</p>
<pre>
// Assign a styled string resource to a TextView
// on the current screen.
CharSequence str = getString(R.string.styled_welcome_message);
TextView tv = (TextView)findViewByID(R.id.text);
tv.setText(str);
</pre>
<p>
    Example XML code
</p>
<pre>
&lt;TextView android:layout_width="fill_parent"
          android:layout_height="wrap_content"
          android:textAlign="center"
          android:text="@string/simple_welcome_message"/&gt; 
</pre>


<h4 id="styledtext">Using Styled Text as a Format String</h4>
<p>
Sometimes you may want to create a styled text resource that is also used as a 
format string. This cannot be done directly because there is no way of passing 
the styled text as the format string argument of String.format() 
without stripping out the style information. The workaround is to store the 
style tags as escaped HTML tags, and then convert the escaped HTML string into 
a styled text after formatting has taken place.
</p>
<p>
To use styled text as a format string, do the following.
</p>
<ol>
  <li>Store your styled text resource as an escaped string, so that the HTML tags in your text resource are not interpreted as if they were XML tags:
<pre>
&lt;resources&gt;
  &lt;string name="search_results_resultsTextFormat"&gt;%1$d results for &amp;lt;b>&amp;amp;quot;%2$s&amp;amp;quot;&amp;lt;/b>&lt;/string&gt;
&lt;/resources&gt;
</pre>
<p>
In this example the format string has two arguments: <code>%1$d</code> is a decimal number, <code>%2$s</code> is a string.
</p>
</li>
<li>
  Make sure any String arguments are properly escaped if they might contain '&lt;' or '&amp;' characters. 
The {@link android.text.TextUtils#htmlEncode} method will do this:
<pre>
String escapedTitle = TextUtil.htmlEncode(title);
</pre>
</li>
<li>
 Use String.format() to format the HTML text, then use {@link android.text.Html#fromHtml} to convert the HTML text into styled text:
<pre>
String resultsTextFormat = getContext().getResources().getString(R.string.search_results_resultsTextFormat);
String resultsText = String.format(resultsTextFormat, count, escapedTitle);
CharSequence styledResults = Html.fromHtml(resultsText);
</pre>
</li>
</ol>


<h3 id="dimension"Dimension Values</h3>
<p>You can create common dimensions to use for various screen elements by
defining dimension values in XML. A dimension resource is a number followed by
a unit of measurement. For example: 10px, 2in, 5sp. Here are the units of
measurement supported by Android:</p>
<dl>
    <dt>px</dt>
    <dd>Pixels - corresponds to actual pixels on the screen.</dd>

    <dt>in</dt>
    <dd>Inches - based on the physical size of the screen.</dd>

    <dt>mm</dt>
    <dd>Millimeters - based on the physical size of the screen.</dd>

    <dt>pt</dt>
    <dd>Points - 1/72 of an inch based on the physical size of the screen.</dd>

    <dt>dp</dt>
    <dd>Density-independent Pixels - an abstract unit that is based on the
    physical density of the screen. These units are relative to a 160 dpi
    screen, so one dp is one pixel on a 160 dpi screen. The ratio of
    dp-to-pixel will change with the screen density, but not necessarily
    in direct proportion. <strong>Note:</strong> The compiler accepts both "dip" and "dp", though "dp" is more consistent with "sp".</dd>

    <dt>sp</dt>
    <dd>Scale-independent Pixels - this is like the dp unit, but it is also
    scaled by the user's font size preference. It is recommend you use this
    unit when specifying font sizes, so they will be adjusted for both the
    screen density and user's preference.</dd>
</dl>

<p>Dimension values are not normally used as raw resources, but rather as
attribute values in XML files. You can, however, create plain resources
containing this data type.</p>

<p><strong>Source file format:</strong> XML file requiring a <code>&lt;?xml
version="1.0" encoding="utf-8"?&gt;</code> declaration, and a root
<code>&lt;resources&gt;</code> element containing one or more
<code>&lt;dimen&gt;</code> tags.</p>

<p><strong>Resource source file location</strong>: {@code res/values/dimens.xml} (File
name is arbitrary, but standard practice is to put all dimensions in one file
devoted to dimensions.)</p>
<p><strong>Compiled resource datatype:</strong> Resource pointer to a
dimension.</p>
<p>
    <strong>Resource reference name:</strong>
</p>
<ul>
    <li>
        <strong>Java:</strong> <code>R.dimen.<em>some_name</em></code>
    </li>
    <li>
        <strong>XML:</strong> <code>@[<em>package</em>:]dimen/<em>some_name</em></code> (where <em>some_name</em> is the <em>name</em> of a specific <code>&lt;dimen&gt;</code> element)
    </li>
</ul>
<p>
    <strong>Syntax</strong>
</p>
<pre>
&lt;dimen name=<em>dimen_name</em>&gt;<em>dimen_value</em>&lt;/dimen&gt;
</pre>
<dl>
    <dt>
        &lt;dimen&gt;
    </dt>
    <dd>
        A valid dimension value.
        <ul>
            <li>
                <em>name</em> - The name used in referring to this dimension.
            </li>
        </ul>
    </dd>
</dl>
<p>
    <strong>Example XML Declaration</strong>
</p>
<p>
    The following code declares several dimension values.
</p>
<pre>
&lt;resources&gt;
    &lt;dimen name="one_pixel"&gt;1px&lt;/dimen&gt;
    &lt;dimen name="double_density"&gt;2dp&lt;/dimen&gt;
    &lt;dimen name="sixteen_sp"&gt;16sp&lt;/dimen&gt;
&lt;/resources&gt;
</pre>
<p>
    <strong>Example Code Use</strong>
</p>
<p>
    Example Java code:
</p>
<pre>
float dimen = Resources.getDimen(R.dimen.one_pixel);
</pre>
<p>
    Example XML code:
</p>
<pre>
&lt;TextView android:layout_width="fill_parent"
          android:layout_height="wrap_content"
          android:textSize="@dimen/sixteen_sp"/&gt;
</pre>


<h2 id="drawables">Drawables</h2>

<p>A {@link android.graphics.drawable.Drawable} is a type of resource that
you retrieve with {@link android.content.res.Resources#getDrawable
Resources.getDrawable()} and use to draw to the screen.  There are a
number of drawable resources that can be created.</p>



<h3 id="imagefileresources">Bitmap Files</h3>
<p>Android supports bitmap resource files in a few different formats: png
(preferred), jpg (acceptable), gif (discouraged). The bitmap file itself is
compiled and referenced by the file name without the extension (so
res/drawable/my_picture.png would be referenced as R.drawable.my_picture).</p>

<p>
    <strong>Source file formats:</strong> png (preferred), jpg (acceptable), gif (discouraged). One resource per file.
</p>
<p>
    <strong>Resource file location</strong>: {@code res/drawable/<em>some_file</em>.png}
</p>
<p>
    <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.BitmapDrawable BitmapDrawable}.
</p>
<p>
    <strong>Resource reference name:</strong>
</p>
<ul>
    <li>
        <strong>Java:</strong> <code>R.drawable.<em>some_file</em></code>
    </li>
    <li>
        <strong>XML:</strong> <code>@[<em>package</em>:]drawable/<em>some_file</em></code>
    </li>
</ul>

<p>For more discussion and examples using drawable resources, see the discussion in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#drawable-resource#drawables">2D Graphics</a>.</p>


<h3 id="colordrawableresources">Color Drawables</h3>
<p>You can create a {@link android.graphics.drawable.PaintDrawable} object that is a rectangle of color,
with optionally rounded corners. This element can be defined in any of the
files inside res/values/.</p>
<p><strong>Source file format:</strong> XML file requiring a <code>&lt;?xml
version="1.0" encoding="utf-8"?&gt;</code> declaration, and a root
<code>&lt;resources&gt;</code> element containing one or more
<code>&lt;drawable&gt;</code> tags.</p>
<p>
    <strong>Resource source file location</strong>: {@code res/values/colors.xml} (File name is arbitrary, but standard practice is to put the PaintDrawable 
    items in the file along with the <a href="resources-i18n.html#numericcolorresources">numeric color values</a>.)
</p>
<p>
    <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.PaintDrawable}.
</p>
<p>
    <strong>Resource reference name:</strong>
</p>
<ul>
    <li>
        <strong>Java:</strong>  <code>R.drawable.<em>some_name</em></code>
    </li>
    <li>
        <strong>XML:</strong>  <code>@[<em>package</em>:]drawable/<em>some_name</em></code>  (where <em>some_name</em> is the name of a specific resource)
    </li>
</ul>
<p>
    <strong>Syntax</strong>
</p>
<pre>
&lt;drawable name=<em>color_name</em>&gt;<em>color_value</em>&lt;/drawable&gt;
</pre>
<dl>
    <dt>
        &lt;drawable&gt;
    </dt>
    <dd>
        A valid <a href="#colorvals">color value</a>.
        <ul>
            <li>
                <em>name</em> - The name used in referring to this drawable.
            </li>
        </ul>
    </dd>
</dl>
<p>
    <strong>Example XML Declaration</strong>
</p>
<p>
    The following code declares several color drawables.
</p>
<pre>
&lt;resources&gt;
    &lt;drawable name="solid_red"&gt;#f00&lt;/drawable&gt;
    &lt;drawable name="solid_blue"&gt;#0000ff&lt;/drawable&gt;
    &lt;drawable name="solid_green"&gt;#f0f0&lt;/drawable&gt;
&lt;/resources&gt;
</pre>
<p>
    <strong>Example Code Use</strong>
</p>
<p>
    Example Java code
</p>
<pre>
// Assign a PaintDrawable as the background to
// a TextView on the current screen.
Drawable redDrawable = Resources.getDrawable(R.drawable.solid_red);
TextView tv = (TextView)findViewByID(R.id.text);
tv.setBackground(redDrawable);
</pre>
<p>
    Example XML code
</p>
<pre>
&lt;TextView android:layout_width="fill_parent"
          android:layout_height="wrap_content"
          android:textAlign="center"
          android:background="@drawable/solid_red"/&gt;
</pre>


<h3 id="ninepatch">Nine-Patch (stretchable) Images</h3>
<p>
    Android supports a stretchable bitmap image, called a 
    {@link android.graphics.NinePatch} graphic. This is a PNG image in which 
    you define stretchable sections that Android will resize to fit the object 
    at display time to accommodate variable sized sections, such as text strings. 
    You typically assign this resource to the View's background. An example use 
    of a stretchable image is the button backgrounds that Android uses; buttons 
    must stretch to accommodate strings of various lengths.
</p>

<p>
    <strong>Source file format:</strong> PNG &mdash; one resource per file
</p>
<p>
    <strong>Resource source file location</strong>: {@code res/drawable/<em>some_name</em>.9.png} (Filename must end in {@code .9.png})
</p>
<p>
    <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable NinePatchDrawable}.
</p>
<p>
    <strong>Resource reference name:</strong>
</p>
<ul>
    <li>
        <strong>Java:</strong> <code>R.drawable.<em>some_file</em></code>
    </li>
    <li>
        <strong>XML:</strong> <code>@[<em>package</em>:]drawable.<em>some_file</em></code>
    </li>
</ul>


<p>For more information and examples using NinePatch drawables, see the discussion
in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Graphics</a>.</p>



<h2 id="animation">Animation</h2>

<h3 id="tweenedanimation">Tweened Animation</h3>
<p>
    Android can perform simple animation on a graphic, or a series of graphics. These include rotations, fading, moving, and stretching.
</p>
<p>
    <strong>Source file format:</strong> XML file, one resource per file, one root tag with no <code>&lt;?xml&gt;</code> declaration
</p>
<p>
    <strong>Resource file location</strong>: {@code res/anim/<em>some_file</em>.xml}
</p>
<p>
    <strong>Compiled resource datatype:</strong> Resource pointer to an {@link android.view.animation.Animation}.
</p>
<p>
    <strong>Resource reference name:</strong>
</p>
<ul>
    <li>
        <strong>Java:</strong> <code>R.anim.<em>some_file</em></code>
    </li>
    <li>
        <strong>XML:</strong> <code>@[<em>package</em>:]anim/<em>some_file</em></code>
    </li>
</ul>
<p>
    <strong>Syntax</strong>
</p>
<p>
    The file must have a single root element: this will be either a single <code>&lt;alpha&gt;</code>, <code>&lt;scale&gt;</code>, <code>&lt;translate&gt;</code>, <code>&lt;rotate&gt;</code>, interpolator element, or <code>&lt;set&gt;</code> element that holds groups of these elements (which may include another <code>&lt;set&gt;</code>). By default, all elements are applied simultaneously. To have them occur sequentially, you must specify the <code>startOffset</code> attribute.
</p>
<pre>
&lt;set android:shareInterpolator=boolean&gt;  // Only required if multiple tags are used.
   &lt;alpha android:fromAlpha=float
          android:toAlpha=float &gt;   |
   &lt;scale android:fromXScale=float
          android:toXScale=float
          android:fromYScale=float
          android:toYScale=float
          android:pivotX=string
          android:pivotY=string &gt;    |
   &lt;translate android:fromX=string
              android:toX=string
              android:fromY=string
              android:toY=string &gt;   |
   &lt;rotate android:fromDegrees=float
           android:toDegrees=float
           android:pivotX=string
           android:pivotY=string &gt; |
   &lt;<em>interpolator tag</em>&gt;
   &lt;set&gt;
&lt;/set&gt;
</pre>
<p>
    <strong>Elements and Attributes</strong>
</p>
<dl>
    <dt>
        &lt;set&gt;
    </dt>
    <dd>
        A container that can recursively hold itself or other animations.
        Represents an {@link android.view.animation.AnimationSet}. 
        You can include as many child elements of the same or different types as you like. 
        Supports the following attribute:
        <ul>
            <li>
                <em>shareInterpolator</em> - Whether to share the same Interpolator among all immediate child elements.
            </li>
        </ul>
    </dd>
    <dt>
        &lt;alpha&gt;
    </dt>
    <dd>
        A fading animation. Represents an {@link android.view.animation.AlphaAnimation}. 
        Supports the following attributes:
        <ul>
            <li>
                <em>fromAlpha</em> - 0.0 to 1.0, where 0.0 is transparent.
            </li>
            <li>
                <em>toAlpha</em> - 0.0 to 1.0, where 0.0 is transparent.
            </li>
        </ul>
    </dd>
    <dt>
        &lt;scale&gt;
    </dt>
    <dd>
        A resizing animation. Represents a {@link android.view.animation.ScaleAnimation}.
         You can specify what is the center point of the image (the pinned center), from which it grows outward (or inward), by specifying pivotX and pivotY. So, for example, if these were 0, 0 (top left corner), all growth would be down and to the right. <code>scale</code> supports the following attributes:
        <ul>
            <li>
                <em>fromXScale</em> - Starting X size, where 1.0 is no change.
            </li>
            <li>
                <em>toXScale</em> - Ending X size, where 1.0 is no change.
            </li>
            <li>
                <em>fromYScale</em> - Starting Y size, where 1.0 is no change.
            </li>
            <li>
                <em>toYScale</em> - Ending Y size, where 1.0 is no change.
            </li>
            <li>
                <em>pivotX</em> - The X coordinate of the pinned center.
            </li>
            <li>
                <em>pivotY</em> - The Y coordinate of the pinned center.
            </li>
        </ul>
    </dd>
    <dt>
        &lt;translate&gt;
    </dt>
    <dd>
        A vertical/horizontal motion animation.
        Represents a {@link android.view.animation.TranslateAnimation}. 
Supports the following attributes in any of the following three formats: values from -100 to 100, ending with "%", indicating a percentage relative to itself; values from -100 to 100, ending in "%p", indicating a percentage relative to its parent; a float with no suffix, indicating an absolute value.
        <ul>
            <li>
                <em>fromXDelta</em> - Starting X location.
            </li>
            <li>
                <em>toXDelta</em> - Ending X location.
            </li>
            <li>
                <em>fromYDelta</em> - Starting Y location.
            </li>
            <li>
                <em>toYDelta</em> - Ending Y location.
            </li>
        </ul>
    </dd>
    <dt>
        &lt;rotate&gt;
    </dt>
    <dd>
        A rotation animation. Represents a {@link android.view.animation.RotateAnimation}.
         Supports the following attributes:
        <ul>
            <li>
                <em>fromDegrees</em> - Starting rotation, in degrees.
            </li>
            <li>
                <em>toDegrees</em> - Ending rotation, in degrees.
            </li>
            <li>
                <em>pivotX</em> - The X coordinate of the center of rotation, in pixels, where (0,0) is the top left corner.
            </li>
            <li>
                <em>pivotY</em> - The Y coordinate of the center of rotation, in pixels, where (0,0) is the top left corner.
            </li>
        </ul>
    </dd>
    <dt>
        <em>&lt;interpolator tag&gt;</em>
    </dt>
    <dd>
        You can also use any of the interpolator subclass elements defined in {@link android.R.styleable}. Examples include &lt;CycleInterpolator&gt;, &lt;EaseInInterpolator&gt;, and &lt;EaseOutInterpolator&gt;. These objects define a velocity curve that describes how quickly a visual action takes place on a timeline (fast at first and slow later, slow at first and gradually faster, and so on).
    </dd>
</dl>
<p>
In addition to the attributes defined for each element above, the elements 
<code>&lt;alpha&gt;</code>, <code>&lt;scale&gt;</code>, <code>&lt;translate&gt;</code>,
<code>&lt;rotate&gt;</code>, and <code>&lt;set></code> all support the following attributes (inherited
from the {@link android.view.animation.Animation} class):
</p>
<dl>
    <dt><em>{@link android.R.attr#duration duration}</em></dt>
    <dd>
        Duration, in milliseconds, for this effect. 
    </dd>
    <dt><em>{@link android.R.attr#startOffset startOffset}</em></dt>
    <dd>
        Offset start time for this effect, in milliseconds. 
    </dd>
    <dt><em>{@link android.R.attr#fillBefore fillBefore}</em></dt>
    <dd>
        When set true, the animation transformation is applied before the animation begins.
    </dd>
    <dt><em>{@link android.R.attr#fillAfter fillAfter}</em></dt>
    <dd>
        When set true, the animation transformation is applied after the animation ends.
    </dd>
    <dt><em>{@link android.R.attr#repeatCount repeatCount}</em></dt>
    <dd>
        Defines the number of times the animation should repeat.
    </dd>
    <dt><em>{@link android.R.attr#repeatMode repeatMode}</em></dt>
    <dd>
        Defines the animation behavior when it reaches the end and the repeat count is greater than 0.
        Options are to either restart or reverse the animation.
    </dd>
    <dt><em>{@link android.R.attr#zAdjustment zAdjustment}</em></dt>
    <dd>
        Defines the z-axis ordering mode to use when running the animation (normal, top, or bottom).
    </dd>
    <dt><em>{@link android.R.attr#interpolator interpolator}</em></dt>
    <dd>
        You can optionally set an interpolator for each element to determine how quickly or slowly it performs its effect over time. For example, slow at the beginning and faster at the end for EaseInInterpolator, and the reverse for EaseOutInterpolator. A list of interpolators is given in {@link android.R.anim}. To specify these, use the syntax @android:anim/<em>interpolatorName</em>.
    </dd>
</dl>

<p>For more discussion and animation code samples, see the discussion in the 
<a href="{@docRoot}guide/topics/graphics/2d-graphics.html#tween-animation">2D Graphics</a> document.</p>



<h2 id="menus">Menus</h2>
<p>Application menus (Options Menu, Context Menu, or Sub Menu) can be defined as
XML resources and inflated by your application using {@link android.view.MenuInflater}.</p>

<p><strong>Source file format:</strong> XML file, one resource per file, one root tag, 
<code>&lt;?xml></code> declaration not required.</p>
<p><strong>Resource file location:</strong> res/menu/<em>some_file</em>.xml</p>
<p><strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.Menu} (or subclass) resource.</p>
<p><strong>Resource reference name:</strong> </p>
<ul><li><strong>Java:</strong> <code>R.menu.<em>some_file</em></code></li></ul>

<h3>Syntax</h3>
<p>The file must have a single root element: a <code>&lt;menu></code> element. In all,
there are three valid elements: <code>&lt;menu></code>, <code>&lt;group></code> and <code>&lt;item></code>. The
<code>&lt;item></code> and <code>&lt;group></code> elements must be the children of a <code>&lt;menu></code>, but <code>&lt;item></code>
elements can also be the children of a <code>&lt;group></code>, and another <code>&lt;menu></code> element may be the child
of an <code>&lt;item></code> (to create a Sub Menu).</p>
<pre>
&lt;menu xmlns:android="http://schemas.android.com/apk/res/android">

    &lt;item android:id="@+id/<em>example_item</em>
          android:title="<em>Example Item</em>"
          android:icon="<em>@drawable/example_item_icon</em>" />

    &lt;group android:id="@+id/<em>example_group</em>">
        &lt;item android:id="@+id/<em>example_item2</em>
              android:title="<em>Example Item 2</em>"
              android:icon="<em>@drawable/example_item2_icon</em>" />
    &lt;/group>

    &lt;item android:id="@+id/<em>example_submenu</em>
          android:title="<em>Example Sub Menu</em>" >
        &lt;menu>
            &lt;item android:id="@+id/<em>example_submenu_item</em>
                  android:title="<em>Example Sub Menu Item</em>" />
        &lt;/menu>
    &lt;/item>

&lt;/menu>
</pre>

<h3>Elements and Attributes</h3>
<p>All attributes must be defined with the <em>android</em> namespace (e.g., <em>android:icon="@drawable/icon"</em>).</p>
<dl>
  <dt>&lt;menu></dt>
    <dd>The root of a menu. Contains <code>&lt;item></code> and <code>&lt;group></code> nodes. No attributes.</dd>
  <dt>&lt;group></dt>
    <dd>A menu group. Contains <code>&lt;item></code> elements. Valid attributes:
      <ul>
        <li><em>id</em> - A unique integer ID for the group.</li>
        <li><em>menuCategory</em> - Value corresponding to Menu CATEGORY_* constants &mdash; defines the priority of the group. Valid values: 
          <em>container</em>, <em>system</em>, <em>secondary</em>, and <em>alternative</em>.</li>
        <li><em>orderInCategory</em> - An integer that defines the default order of the items within the category.</li>
        <li><em>checkableBehavior</em> - Whether the items are checkable. Valid values: 
          <em>none</em>, <em>all</em> (exclusive / radio buttons), <em>single</em> (non-exclusive / checkboxes)</li>
        <li><em>visible</em> - Whether the group is visible. <em>true</em> or <em>false</em>.</li>
        <li><em>enabled</em> - Whether the group is enabled. <em>true</em> or <em>false</em>.</li>
      </ul>
    </dd>
  <dt>&lt;item></dt>
    <dd>A menu item. May contain a <code>&lt;menu></code> element (for a Sub Menu). Valid attributes:
      <ul>
        <li><em>id</em> - A unique resource ID for the item.</li>
        <li><em>menuCategory</em> - Used to define the menu category.</li>
        <li><em>orderInCategory</em> - Used to define the order of the item, within a group.</li>
        <li><em>title</em> - A string for the menu title.</li>
        <li><em>titleCondensed</em> - A condensed string title, for situations in which the normal title is too long.</li>
        <li><em>icon</em> - A resource identifier for a drawable icon.</li>
        <li><em>alphabeticShortcut</em> - A character for the alphabetic shortcut key.</li>
        <li><em>numericShortcut</em> - A number for the numeric shortcut key.</li>
        <li><em>checkable</em> - Whether the item is checkable. <em>true</em> or <em>false</em>.</li>
        <li><em>checked</em> - Whether the item is checked by default. <em>true</em> or <em>false</em>.</li>
        <li><em>visible</em> - Whether the item is visible by default. <em>true</em> or <em>false</em>.</li>
        <li><em>enabled</em> - Whether the item is enabled by default. <em>true</em> or <em>false</em>.</li>
      </ul>
    </dd>
</dl>

<p>For more discussion on how to create menus in XML and inflate them in your application, 
read <a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a>.</p>



<h2 id="layoutresources">Layout</h2>
<p>Android lets you specify screen layouts using XML elements inside an XML
file, similar to designing screen layout for a webpage in an HTML file. Each
file contains a whole screen or a part of a screen, and is compiled into a
View resource that can be passed in to 
{@link android.app.Activity#setContentView(int) Activity.setContentView} or used as a
reference by other layout resource elements. Files are saved in the
<code>res/layout/</code> folder of your project, and compiled by the Android resource
compiler, aapt. </p> 

<p> Every layout XML file must evaluate to a single root
element. First we'll describe how to use the standard XML tags understood by
Android as it is shipped, and then we'll give a little information on how you
can define your own custom XML elements for custom View objects.

<p> The root element must have
the Android namespace "http://schemas.android.com/apk/res/android" defined in
the root element.</p>

<p>For a complete discussion on creating layouts, see the 
<a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> topic.</p>

<p> <strong>Source file format:</strong> XML file
requiring a <code>&lt;?xml version="1.0" encoding="utf-8"?&gt;</code>
declaration, and a root element of one of the supported XML layout elements.
</p> 


<p><strong>Resource file location</strong>:
res/layout/<em>some_file</em>.xml.</p>
<p>
    <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource.
</p>
<p>
    <strong>Resource reference name:</strong>
</p>
<ul>
    <li>
        <strong>Java:</strong> <code>R.layout.<em>some_file</em></code>
    </li>
    <li>
        <strong>XML:</strong> <code>@[<em>package</em>:]layout/<em>some_file</em></code>
    </li>
</ul>
<p>
    <strong>Syntax</strong>
</p>
<pre>
&lt;<em>ViewGroupClass</em> xmlns:android="http://schemas.android.com/apk/res/android"
                android:id="@+id/<em>string_name</em>" (attributes)&gt;
   &lt;<em>widget</em> or other nested <em>ViewGroupClass</em>&gt;+
   &lt;requestFocus/&gt;(0 or 1 per layout file, assigned to any element)
&lt;/<em>ViewGroupClass</em>&gt;
</pre>
<dl>
    <dt>
        &lt;<em>ViewGroupClass</em>&gt;
    </dt>
    <dd>
        <p>The file must have a single root element. This can be a ViewGroup class that contains other elements, or a widget (or custom item) if it's only one object. By default, you can use any (case-sensitive) Android {@link android.widget widget} or {@link android.view.ViewGroup ViewGroup} class name as an element. These elements support attributes that apply to the underlying class, but the naming is not as clear. How to discover what attributes are supported for what tags is discussed below. You should not assume that any nesting is valid (for example you cannot enclose <code>&lt;TextView&gt;</code> elements inside a <code>&lt;ListLayout&gt;</code>).</p>
        <p>If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <code>&lt;EditText&gt;</code> is the corresponding XML element for the EditText class. It exposes its own unique attributes (<code>EditText_numeric</code>), as well as all attributes supported by <code>&lt;TextView&gt;</code> and <code>&lt;View&gt;</code>. For the <em>id</em> attribute of a tag in XML, you should use a special syntax: "@+id/<em>somestringvalue</em>". The "@+" syntax creates a resource number in the R.id class, if one doesn't exist, or uses it, if it does exist. When declaring an ID value for an XML tag, use this syntax. Example: <code>&lt;TextView android:id="@+id/nameTextbox"/&gt;</code>, and refer to it this way in Java: <code>findViewById(R.id.nameTextbox)</code>. All elements support the following values:</p>
        <ul>
            <li>
                <em>id</em> - An ID value used to access this element in Java. Typically you will use the syntax @+id/<em>string_name</em> to generate an ID for you in the id.xml file if you haven't created one yourself.
            </li>
            <li>
                <code>xmlns:android="http://schemas.android.com/apk/res/android"</code> - <em><strong>Required for the root element only.</strong></em>
            </li>
        </ul>
    </dd>
    <dt>
        &lt;requestFocus&gt;
    </dt>
    <dd>
        Any element representing a View object can include this empty element, which gives it's parent tag initial focus on the screen. You can have only one of these elements per file.
    </dd>
</dl>
<p>
    <strong>What Attributes Are Supported for What Elements?</strong>
</p>
<p>
    Android uses the {@link android.view.LayoutInflater} class at run time to load an XML layout resource and translate it into visual elements. By default, all widget class names are supported directly as tags, but a full list of supported tags and attributes is listed in the {@link android.R.styleable} reference page. However, the attribute names are somewhat obscure. If an underscore appears in the name, this indicates that it is an attribute &mdash; typically of the element before the underscore. So, for example, <code>EditText_autoText</code> means that the <code>&lt;EditText&gt;</code> tag supports an attribute <em>autoText</em>. When you actually use the attribute in that element, use only the portion after the last underscore, and prefix the attribute with the prefix "<code>android:</code>". So, for example, if {@link android.R.styleable} lists the following values:
</p>
<ul>
    <li>
        <code>TextView</code>
    </li>
    <li>
        <code>TextView_lines</code>
    </li>
    <li>
        <code>TextView_maxlines</code>
    </li>
</ul>
<p>
    You could create an element like this:
</p>
<pre>
&lt;TextView android:lines="10" android:maxlines="20"/&gt;
</pre>
<p>
    This would create a {@link android.widget.TextView} object and set its lines and maxlines properties.
</p>
<p>
    Attributes come from three sources:
</p>
<ul>
    <li>
        <strong>Attributes exposed directly by the element.</strong> For example, <code>TextView</code> supports <code>TextView_text</code>, as discussed above.
    </li>
    <li>
        <strong>Attributes exposed by all the superclasses of that element.</strong> For example, the TextView class extends the View class, so the <code>&lt;TextView&gt;</code> element supports all the attributes that the <code>&lt;View&gt;</code> element exposes &mdash; a long list, including <code>View_paddingBottom</code> and <code>View_scrollbars</code>. These too are used without the class name: <code>&lt;TextView android:paddingBottom="20" android:scrollbars="horizontal" /&gt;</code>.
    </li>
    <li>
        <strong>Attributes of the object's {@link android.view.ViewGroup.LayoutParams} subclass.</strong> All View objects support a LayoutParams member (see <a href="{@docRoot}guide/topics/ui/declaring-layout.html#layout-params">Declaring Layout</a>). To set properties on an element's LayoutParams member, the attribute to use is "android:layout_<em>layoutParamsProperty</em>". For example: <code>android:layout_gravity</code> for an object wrapped by a <code>&lt;LinearLayout&gt;</code> element. Remember that each LayoutParams subclass also supports inherited attributes. Attributes exposed by each subclass are given in the format <em>someLayoutParamsSubclass</em>_Layout_layout_<em>someproperty</em>. This defines an attribute "android:layout_<em>someproperty</em>". Here is an example of how Android documentation lists the properties of the {@link android.widget.LinearLayout.LayoutParams LinearLayout.LayoutParams} class:
    </li>
</ul>
<ul>
    <li>LinearLayout_Layout // The actual object &mdash; not used.
    </li>
    <li>LinearLayout_Layout_layout_gravity // Exposes a <code>gravity</code> attribute
    </li>
    <li>LinearLayout_Layout_layout_height // Exposes a <code>height</code> attribute
    </li>
    <li>LinearLayout_Layout_layout_weight // Exposes a <code>weight</code> attribute
    </li>
    <li>LinearLayout_Layout_layout_width // Exposes a <code>width</code> attribute
    </li>
</ul>
<p>
    Here is an example that sets some of these values on a few objects, including direct attributes, inherited attributes, and LayoutParams attributes:
</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;!-- res/main_screen.xml --&gt;
&lt;LinearLayout xmlns:android="http://schemas.android.com/apk/res/android"
              android:orientation="vertical"    // The object's own orientation property
              android:padding="4"               // Inherited View property
              android:gravity="center"          // The object's own property
              android:layout_width="fill_parent"  // Parent object's LinearLayout.LayoutParams.width
              android:layout_height="fill_parent"&gt; // Parent object's LinearLayout.LayoutParams.height

   &lt;TextView android:layout_width="fill_parent"   // TextView.LayoutParams.width
             android:layout_height="wrap_content" // TextView.LayoutParams.height
             android:layout_weight="0"            // TextView.LayoutParams.weight
             android:paddingBottom="4"            // TextView.paddingBottom
             android:text="@string/redirect_getter"/&gt; // TextView.text

   &lt;EditText android:id="@+id/text"
             android:layout_width="fill_parent"   // EditText.LayoutParams.width
             android:layout_height="wrap_content" // EditText.LayoutParams.height
             android:layout_weight="0"            // EditText.LinearLayoutParams.weight
             android:paddingBottom="4"&gt;           // EditText.paddingBottom
       &lt;requestFocus /&gt;
   &lt;/EditText&gt;

   &lt;Button android:id="@+id/apply"
           android:layout_width="wrap_content"  // Button.LayoutParams.width
           android:layout_height="wrap_content" // Button.LayoutParams.height
           android:text="@string/apply" /&gt;      // TextView.text
&lt;/LinearLayout&gt;
</pre>
<p>
    <strong>Example Code Use</strong>
</p>
<p>
    The most common use is to load the XML file (located at <em>res/main_screen.xml</em>) and use it as the current screen, as shown here with the preceding file:
</p>
<pre>
setContentView(R.layout.main_screen); 
</pre>
<p>
    However, layout elements can also represent repeating elements used as templates.
</p>

<p>Also see <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> for more information on layouts.</p>



<h3 id="customresources">Custom Layout Resources</h3>
<p>
    You can define custom elements to use in layout resources. These custom elements can then be used the same as any Android layout elements: that is, you can use them and specify their attributes in other resources. The ApiDemos sample application has an example of creating a custom layout XML tag, LabelView. To create a custom element, you will need the following files:
</p>
<ul>
    <li>
        <strong>Java implementation file</strong> - The implementation file. The class must extend {@link android.view.View View} or a subclass. See LabelView.java in ApiDemos.
    </li>
    <li>
        <strong>res/values/attrs.xml</strong> - Defines the XML element, and the attributes that it supports, for clients to use to instantiate your object in their layout XML file. Define your element in a <code>&lt;declare-styleable name=<em>your_java_class_name</em>&gt;</code>. See res/values/attrs.xml in ApiDemos.
    </li>
    <li>
        <strong>res/layout/<em>your_class</em>.xml</strong> [<em>optional</em>] - An optional XML file to describe the layout of your object. This could also be done in Java. See custom_view_1.xml in ApiDemos.
    </li>
</ul>
<p>
    <strong>Source file format:</strong> XML file without an <code>&lt;?xml&gt;</code> declaration, and a <code>&lt;resources&gt;</code> root element containing one or more custom element tags.
</p>
<p>
    <strong>Resource file location</strong>: {@code res/values/<em>attrs</em>.xml} (File name is arbitrary.)
</p>
<p>
    <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource.
</p>
<p>
    <strong>Resource reference name:</strong> R.styleable.<em>some_file</em> (Java).
</p>



<h2 id="stylesandthemes">Styles and Themes</h2>
<p>
    A <em>style</em> is one or more attributes applied to a single element (for example, 10 point red Arial font, applied to a TextView). A style is applied as an attribute to an element in a layout XML file.
</p>
<p>
    A <em>theme</em> is one or more attributes applied to a whole screen &mdash; for example, you might apply the stock Android Theme.dialog theme to an activity designed to be a floating dialog box. A theme is assigned as an attribute to an Activity in the manifest file.
</p>
<p>
    Both styles and themes are defined in a <code>&lt;style&gt;</code> block containing one or more string or numerical values (typically color values), or references to other resources (drawables and so on). These elements support inheritance, so you could have MyBaseTheme, MyBaseTheme.Fancy, MyBaseTheme.Small, and so on.
</p>

<p>For a complete discussion on styles and themes, read 
<a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p>

<p>
    <strong>Source file format:</strong> XML file requiring a <code>&lt;?xml version="1.0" encoding="utf-8"?&gt;</code> declaration, and a root <code>&lt;resources&gt;</code> element containing one or more <code>&lt;style&gt;</code> tags.
</p>
<p>
    <strong>Resource source file location</strong>: {@code res/values/styles.xml} (File name is arbitrary, but standard practice is to put all styles into a file named styles.xml.)
</p>
<p>
    <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence.
</p>
<p>
    <strong>Resource reference name:</strong>
</p>
<ul>
    <li>
        <strong>Java:</strong> <code>R.style.<em>styleID</em></code> for the whole style, <code>R.style.<em>styleID</em>.<em>itemID</em></code> for an individual setting
    </li>
    <li>
        <strong>XML:</strong> <code>@[<em>package</em>:]style/<em>styleID</em></code> for a whole style, <code>@[<em>package</em>:]style/<em>styleID</em>/<em>itemID</em></code> for an individual item. <strong>Note</strong>: to refer to a value in the <em>currently</em> applied theme, use "?" instead of "@" as described below (XML).
    </li>
</ul>
<p>
    <strong>Syntax</strong>
</p>
<pre>
&lt;style name=<em>string</em> [parent=<em>string</em>] &gt;
   &lt;item name=<em>string</em>&gt;<em>Hex value | string value | reference</em>&lt;/item&gt;+<em>
</em>&lt;/style&gt;
</pre>
<dl>
    <dt>
        &lt;style&gt;
    </dt>
    <dd>
        Holds one or more &lt;item&gt; elements, each describing one value. This style, which is a bundle of values, can be referred to as a <em>theme</em>.
        <ul>
            <li>
                <em>name</em> - The name used in referring to this theme.
            </li>
            <li>
                <em>parent</em> - An optional parent theme. All values from the specified theme will be inherited into this theme. Any values with identical names that you specify will override inherited values. The name must be qualified by the package, but you don't need the /style directive (for example, <code>android:Theme</code> for the base Android theme, or <code>MyTheme</code> for a theme defined in your package).
            </li>
        </ul>
    </dd>
    <dt>
        &lt;item&gt;
    </dt>
    <dd>
        A value to use in this theme. It can be a standard string, a hex color value, or a reference to any other resource type.
    </dd>
</dl>

<p>For examples of how to declare and apply styles and themes, read 
<a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p>



<h2 id="Searchable">Searchable</h2>

<p>To make search appear to the user as a seamless system-wide feature, the Android framework 
offers APIs that let applications control how they are searched.
Applications can customize how search is invoked, how the search dialog looks, and what type of 
search results are available, including suggestions that are shown as the user types.</p>

<p>In order to utilize the Android search framework, an application must provide a search configuration
in the form of an XML resource.
This section describes the search configuration XML in terms of its syntax and usage. For a more
complete discussion about how to implement search features for your application, see
<!-- <a href="{@docRoot}guide/topics/search/index.html">Search</a> -->
{@link android.app.SearchManager}.</p>

<p>
  <strong>Source file format:</strong> 
  XML file requiring a <code>&lt;?xml version="1.0" encoding="utf-8"?&gt;</code> 
  declaration, and a root <code>&lt;searchable&gt;</code> element.
</p>

<p>
  <strong>Resource source file location</strong>: {@code res/xml/searchable.xml} 
  (The file name is arbitrary, but standard practice is to use searchable.xml.)
</p>

<p>
  <strong>Compiled resource datatype:</strong> 
  Resource pointer to an xml object.
</p>

<p>
  <strong>Resource reference name:</strong>
</p>

<ul>
  <li>
    <strong>Java:</strong> 
    <code>R.xml.<em>filename</em></code>.
  </li>
  <li>
    <strong>XML:</strong> 
    <code>@[<em>package</em>:]xml/<em>filename</em></code> (e.g., <code>@xml/searchable</code>).
  </li>
</ul>

<p>
  <strong>Syntax</strong>
</p>

<pre>
&lt;searchable xmlns:android="http://schemas.android.com/apk/res/android
     android:label="@string/search_label" 
     ... &gt;
     <em>&lt;actionkey
          android:keycode="KEYCODE_CALL"
          ... &gt;</em>     
&lt;/searchable&gt;
</pre>

<dl>
  <dt>
    &lt;searchable&gt;
  </dt>
  <dd>
    Defines all application search configurations, including settings for text and voice searches
    performed within the application. It accepts the following attributes:
    <ul>
      <li>
        <em>label</em> - <strong>Required</strong>. This is the name for your application, as it 
        will appear to the user. This will be visible only if <em>searchMode</em> is set to 
        "showSearchLabelAsBadge" (see below).
      </li>
      <li>
        <em>hint</em> -	This is the text to display in the search text field when no text has 
        been entered. This is recommended in order to provide context to the search about to be 
        performed (e.g., "Search the Dictionary").
      </li>
      <li>
        <em>searchMode</em> - If provided and non-zero, this sets additional modes for control
        of the search presentation. The following mode values are accepted: 
        <ul>
          <li>
            <em>showSearchLabelAsBadge</em> - If set, this enables the display of the 
            search target (label) within the search bar.
          </li>
          <li>
            <em>queryRewriteFromData</em> - If set, this causes the suggestion column 
            SUGGEST_COLUMN_INTENT_DATA to be considered as the text for suggestion query 
            rewriting. This should only be used when the values in 
            SUGGEST_COLUMN_INTENT_DATA are suitable for user inspection and editing -
            typically, HTTP/HTTPS Uri's.
          </li>
          <li>
            <em>queryRewriteFromText</em> - If set, this causes the suggestion 
            column SUGGEST_COLUMN_TEXT_1 to be considered as the text for suggestion query
            rewriting. This should be used for suggestions in which no query 
            text is provided and the SUGGEST_COLUMN_INTENT_DATA values are not suitable 
            for user inspection and editing.
          </li>
        </ul>
        <p>More than one of the above values for <em>searchMode</em> can be used at once. For 
        example, you can declare two modes at once, like this:
        <code>searchMode="queryRewriteFromData|queryRewriteFromText"</code>
      </li>
      <li>
        <em>inputType</em> - If provided, supplies a hint about the type of search text 
        the user will be entering. For most searches, in which free form text is expected, 
        this attribute is not needed. See
        {@link android.R.attr#inputType} for a list of suitable values for this attribute.
      </li>
      <li>
        <em>imeOptions</em> - If provided, supplies additional options for the input method. 
        For most searches, in  which free form text is expected, this attribute is not needed, 
        and will default to "actionSearch". See 
        {@link android.R.attr#imeOptions} for a list of suitable values for this attribute.
      </li>
    </ul>
    
    <p>If you have defined a content provider to generate search suggestions, you need to
    provide some more searchable metadata in order to configure communications with the content
    provider. The following are additional {@code &lt;searchable>} attributes for use when 
    providing search suggestions:</p>
    
    <ul>
      <li>
        <em>searchSuggestAuthority</em> - <strong>Required to provide search suggestions</strong>. 
        This value must match the authority string provided in the provider section of your manifest.
      </li>
      <li>
        <em>searchSuggestPath</em> - If provided, this path will be inserted in the suggestions 
        query Uri, after the authority you have provide but before the standard suggestions path.
        This is only required if you have a single content provider issuing different types 
        of suggestions (e.g. for different data types) and you need 
        a way to disambiguate the suggestions queries when they are received.
      </li>
      <li>
        <em>searchSuggestSelection</em> - If provided, this value will be passed into your 
        query function as the selection parameter. Typically this will be a WHERE clause for 
        your database, and will contain a single question mark, which represents the actual query
        string that has been typed by the user. However, you can also use any non-null value to simply
        trigger the delivery of the query text (via selection arguments), and then use the query 
        text in any way appropriate for your provider (ignoring the actual text of the selection parameter.)
      </li>
      <li>
        <em>searchSuggestIntentAction</em> - The default Intent action to be used when a user 
        clicks on a search suggestion.
        If provided, and not overridden by the selected suggestion, this value will 
        be placed in the action field of the {@link android.content.Intent} when the 
        user clicks a suggestion.
      </li>
      <li>
        <em>searchSuggestIntentData</em> - The default Intent data to be used when a user 
        clicks on a search suggestion.
        If provided, and not overridden by the selected suggestion, this value will be 
        placed in the data field of the {@link android.content.Intent} when the user clicks 
        a suggestion.
      </li>
    </ul>
    
    <p>Beyond providing search suggestions while using your application's local search, you 
    can also configure your search suggestions to be made available to Quick Search Box, 
    which will allow users so receive search suggestions from your application content from outside
    your application. The following are additional {@code &lt;searchable>} attributes for use when 
    providing search suggestions to Quick Search Box:</p>
    
    <ul>
      <li>
        <em>includeInGlobalSearch</em> - <strong>Required to provide search suggestions in
        Quick Search Box</strong>. If true, this indicates the search suggestions provided by your 
        application should be included in the globally accessible Quick Search Box. The user must
        still enable your application as a searchable item in the system search settings in order
        for your suggestions to appear in Quick Search Box.
      </li>
      <li>
        <em>searchSettingsDescription</em> - If provided, this provides a brief description
        of the search suggestions that you provide to Quick Search Box, 
        and will be displayed in the search settings entry for your application.
      </li>
      <li>
        <em>queryAfterZeroResults</em> - Indicates whether a source should be invoked for 
        supersets of queries it has returned zero results for in the past. For example, if a
        source returned zero results for "bo", it would be ignored for "bob". If set to false,
        this source will only be ignored for a single session; the next time the search dialog
        is invoked, all sources will be queried. The default value is false.
      </li>
      <li>
        <em>searchSuggestThreshold</em> - Indicates the minimum number of characters needed to
        trigger a source lookup from Quick Search Box. Only guarantees that a source will not be
        queried for anything shorter than the threshold. The default value is 0.
      </li>
    </ul>
    
    <p>To enable voice search for your Activity, you can add fields to the searchable metadata 
    that enable and configure voice search. The following are additional {@code &lt;searchable>} 
    attributes for use when implementing voice search:</p>
    
    <ul>
        <li>
          <em>voiceSearchMode</em> -  <strong>Required to provide voice search 
          capabilities</strong>. 
          If provided and non-zero, enables voice search. 
          (Voice search may not be provided by the device, in which case these flags will
          have no effect.) The following mode values are accepted:
          <ul>
            <li>
              <em>showVoiceSearchButton</em> - If set, display a voice search button. This only 
              takes effect if voice search is available on the device. If set, then "launchWebSearch" 
              or "launchRecognizer" must also be set.
            </li>
            <li>
              <em>launchWebSearch</em> - If set, the voice search button will take the user directly 
              to a built-in voice web search activity. Most applications will not use this flag, as 
              it will take the user away from the activity in which search was invoked.
            </li>
            <li>
              <em>launchRecognizer</em> - If set, the voice search button will take 
              the user directly to a built-in voice recording activity. This activity 
              will prompt the user to speak, transcribe the spoken text, and forward the resulting 
              query text to the searchable activity, just as if the user had typed it into the 
              search UI and clicked the search button.
            </li>
          </ul>
        </li>
        <li>
          <em>voiceLanguageModel</em> - A string constant from 
          {@link android.speech.RecognizerIntent}.
          If provided, this specifies the language model that 
          should be used by the voice recognition system. See 
          {@link android.speech.RecognizerIntent#EXTRA_LANGUAGE_MODEL } for more 
          information. If not provided, the default value 
          {@link android.speech.RecognizerIntent#LANGUAGE_MODEL_FREE_FORM } will be used.
        </li>
        <li>
          <em>voicePromptText</em> - A string. If provided, this specifies a prompt 
          that will be displayed during voice input. If not provided, a default prompt 
          will be displayed.
        </li>
        <li>
          <em>voiceLanguage</em> - A string constant from {@link java.util.Locale}. 
          If provided, this specifies the spoken language to be expected. 
          This is only needed if it is different from the current value of 
          {@link java.util.Locale#getDefault()}. 
        </li>
        <li>
          <em>voiceMaxResults</em> - If provided, enforces the maximum number of results to return, 
          including the "best" result which will always be provided as the SEARCH intent's primary 
          query. Must be one or greater. Use EXTRA_RESULTS to get the results from the intent. 
          If not provided, the recognizer will choose how many results to return.
        </li>
    </ul>
  </dd>
  
  <dt>
      &lt;actionkey&gt;
  </dt>
  <dd>
    Defines a shortcut key for a search action.
    <ul>
      <li>
        <em>keycode</em> - <strong>Required</strong>. This attribute denotes the action key
        you wish to respond to. Note that not all action keys are actually supported using 
        this mechanism, as many of them are used for typing, 
        navigation, or system functions. This will be added to the 
        {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is passed to your 
        searchable Activity. To examine the key code, use 
        {@link android.content.Intent#getIntExtra getIntExtra(SearchManager.ACTION_KEY)}.
        Note that, in addition to the keycode, you must also provide one or more of 
        the action specifier attributes below.
      </li>
      <li>
        <em>queryActionMsg</em> - If you wish to handle an action key during normal 
        search query entry, you must define an action string here. This will be added to the
        {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} Intent that is 
        passed to your searchable Activity. To examine the string, use 
        {@link android.content.Intent#getStringExtra
        getStringExtra(SearchManager.ACTION_MSG)}.
      </li>
      <li>
        <em>suggestActionMsg</em> - If you wish to handle an action key while a 
        suggestion is being displayed and selected, there are two ways to handle this. 
        If all of your suggestions can handle the action key, you can simply define 
        the action message using this attribute. This will be added to the 
        {@link android.content.Intent#ACTION_SEARCH} Intent that is passed to your 
        searchable Activity. To examine the string, 
        use {@link android.content.Intent#getStringExtra 
        getStringExtra(SearchManager.ACTION_MSG)}.
      </li>
      <li>
        <em>suggestActionMsgColumn</em> - If you wish to handle an action key while
        a suggestion is being displayed and selected, but you do not wish to enable
        this action key for every suggestion, then you can use this attribute to control 
        it on a suggestion-by-suggestion basis. First, you must define a column 
        (and name it here) where your suggestions will include the action string. Then,
        in your content provider, you must provide this column, and when desired, 
        provide data in this column. The search manager will look at your suggestion cursor, 
        using the string provided here in order to select a column, and will use 
        that to select a string from the cursor. That string will be added to the 
        {@link android.content.Intent#ACTION_SEARCH ACTION_SEARCH} 
        Intent that is passed to your searchable Activity. To examine 
        the string, use {@link android.content.Intent#getStringExtra 
        getStringExtra(SearchManager.ACTION_MSG)}. If the data does not exist for the 
        selection suggestion, the action key will be ignored.
      </li>
    </ul>
  </dd>
</dl>