From dfe5c204403bc56c29bb36410574eab8b1950417 Mon Sep 17 00:00:00 2001 From: Scott Main Date: Tue, 8 Jun 2010 15:54:52 -0700 Subject: docs: lots of additions to the resources docs new drawable resources add and to layout resource update drawable class descriptioons to point to resources guide add ID resource type Change-Id: I733eec50bb2671f28c9e6dd7dec14eb6586f5193 --- core/java/android/view/View.java | 4 +- .../guide/topics/resources/available-resources.jd | 17 - .../guide/topics/resources/drawable-resource.jd | 1347 +++++++++++++++++--- .../html/guide/topics/resources/layout-resource.jd | 81 +- docs/html/guide/topics/resources/menu-resource.jd | 12 +- docs/html/guide/topics/resources/more-resources.jd | 125 +- docs/html/images/resources/clip.png | Bin 0 -> 2464 bytes docs/html/images/resources/layers.png | Bin 0 -> 8248 bytes .../graphics/drawable/AnimationDrawable.java | 2 + .../android/graphics/drawable/BitmapDrawable.java | 4 +- .../android/graphics/drawable/ClipDrawable.java | 9 +- .../java/android/graphics/drawable/Drawable.java | 7 +- .../graphics/drawable/GradientDrawable.java | 4 +- .../android/graphics/drawable/InsetDrawable.java | 4 +- .../android/graphics/drawable/LayerDrawable.java | 5 +- .../graphics/drawable/LevelListDrawable.java | 5 +- .../android/graphics/drawable/RotateDrawable.java | 4 +- .../android/graphics/drawable/ScaleDrawable.java | 4 +- .../android/graphics/drawable/ShapeDrawable.java | 4 + .../graphics/drawable/StateListDrawable.java | 4 +- .../graphics/drawable/TransitionDrawable.java | 8 +- 21 files changed, 1418 insertions(+), 232 deletions(-) create mode 100644 docs/html/images/resources/clip.png create mode 100644 docs/html/images/resources/layers.png diff --git a/core/java/android/view/View.java b/core/java/android/view/View.java index 11e5ad138807..f9abe60b47c6 100644 --- a/core/java/android/view/View.java +++ b/core/java/android/view/View.java @@ -7890,7 +7890,9 @@ public class View implements Drawable.Callback, KeyEvent.Callback, Accessibility * without resorting to another data structure. * * The specified key should be an id declared in the resources of the - * application to ensure it is unique. Keys identified as belonging to + * application to ensure it is unique (see the ID resource type). + * Keys identified as belonging to * the Android framework or not associated with any package will cause * an {@link IllegalArgumentException} to be thrown. * diff --git a/docs/html/guide/topics/resources/available-resources.jd b/docs/html/guide/topics/resources/available-resources.jd index 09c55a5a1ab0..19babee6c922 100644 --- a/docs/html/guide/topics/resources/available-resources.jd +++ b/docs/html/guide/topics/resources/available-resources.jd @@ -18,23 +18,6 @@ of application resource that you can provide in your resources directory ({@code

Here's a brief summary of each resource type:

-
-
-

{@code R.id} Is Not a Resource

- -

You will often use an {@code R.id} integer to handle {@link android.view.View} objects in -your UI. Although the {@code id} is a subclass of the {@code R} class, it is not considered a -"resource" because it is not a reference to an externalized application resource. The {@code id} -is simply a unique identifier that allows you to handle elements in your UI by instantiating -objects with {@link android.app.Activity#findViewById(int) findViewById()}.

- -

For information about using {@code R.id} with your UI, see Declaring Layout.

- -
-
- -
Animation Resources
Define pre-determined animations.
diff --git a/docs/html/guide/topics/resources/drawable-resource.jd b/docs/html/guide/topics/resources/drawable-resource.jd index d8de16a42999..1e4cca7c171d 100644 --- a/docs/html/guide/topics/resources/drawable-resource.jd +++ b/docs/html/guide/topics/resources/drawable-resource.jd @@ -18,32 +18,50 @@ and draw on the screen. There are several different types of drawables:

Bitmap File
A bitmap graphic file ({@code .png}, {@code .jpg}, or {@code .gif}). - A {@link android.graphics.drawable.BitmapDrawable}.
+ Creates a {@link android.graphics.drawable.BitmapDrawable}.
Nine-Patch File
A PNG file with stretchable regions to allow image resizing based on content ({@code -.9.png}). A {@link android.graphics.drawable.NinePatchDrawable}.
- +.9.png}). Creates a {@link android.graphics.drawable.NinePatchDrawable}. +
Layer List
+
A Drawable that manages an array of other Drawables. These are drawn in array order, so the +element with the largest index is be drawn on top. Creates a {@link +android.graphics.drawable.LayerDrawable}.
State List
An XML file that references different bitmap graphics for different states (for example, to use a different image when a button is pressed). - A {@link android.graphics.drawable.StateListDrawable}.
-
Color
-
A resource defined in XML that specifies a rectangle of color, with - optionally rounded corners. A {@link android.graphics.drawable.PaintDrawable}.
-
Shape
+ Creates a {@link android.graphics.drawable.StateListDrawable}. +
Level List
+
An XML file that defines a Drawable that manages a number of alternate Drawables, each +assigned a maximum numerical value. Creates a {@link +android.graphics.drawable.LevelListDrawable}.
+
Transition Drawable
+
An XML file that defines a Drawable that can cross-fade between two drawable resources. +Creates a {@link android.graphics.drawable.TransitionDrawable}.
+
Clip Drawable
+
An XML file that defines a drawable that clips another Drawable based on this Drawable's +current level value. Creates a {@link android.graphics.drawable.ClipDrawable}.
+
Scale Drawable
+
An XML file that defines a drawable that changes the size of another Drawable based on its +current level value. Creates a {@link android.graphics.drawable.ScaleDrawable}
+
Shape Drawable
An XML file that defines a geometric shape, including colors and gradients. - A {@link android.graphics.drawable.ShapeDrawable}.
+ Creates a {@link android.graphics.drawable.ShapeDrawable}.
-

Documentation for the {@link android.graphics.drawable.AnimationDrawable} resource -is in the Animation Resource document.

+

Also see the Animation Resource document for how to +create an {@link android.graphics.drawable.AnimationDrawable}.

+ + + -

Bitmap File

+

Bitmap

-

A basic bitmap image. Android supports basic bitmap files in a few different formats: +

A bitmap image. Android supports bitmap files in a three formats: {@code .png} (preferred), {@code .jpg} (acceptable), {@code .gif} (discouraged).

+

You can reference a bitmap file directly, using the filename as the resource ID, or create an +alias resource ID in XML.

+

Note: Bitmap files may be automatically optimized with lossless image compression by the aapt tool. For example, a true-color PNG that does not require more than 256 colors may be converted to an 8-bit @@ -52,11 +70,18 @@ memory. So be aware that the image binaries placed in this directory can change you plan on reading an image as a bit stream in order to convert it to a bitmap, put your images in the res/raw/ folder instead, where they will not be optimized.

+ +

Bitmap File

+ +

A bitmap file is a {@code .png}, {@code .jpg}, or {@code .gif} file. Android creates a {@link +android.graphics.drawable.Drawable} +resource for any of these files when you save them in the {@code res/drawable/} directory.

+
file location:
res/drawable/filename.png ({@code .png}, {@code .jpg}, or {@code .gif})
-The filename will be used as the resource ID.
+The filename is used as the resource ID.
compiled resource datatype:
Resource pointer to a {@link android.graphics.drawable.BitmapDrawable}.
@@ -68,15 +93,16 @@ In XML: @[package:]drawable/filename
example:
-
With an image saved at res/drawable/myimage.png, this layout XML will apply + +
With an image saved at res/drawable/myimage.png, this layout XML applies the image to a View: 
 <ImageView
     android:layout_height="wrap_content"
     android:layout_width="wrap_content"
-    android:src="@drawable/myimage" />
+    android:src="@drawable/myimage" />
-

This application code will retrieve the image as a {@link +

The following application code retrieves the image as a {@link android.graphics.drawable.Drawable}:

 Resources res = {@link android.content.Context#getResources()};
@@ -97,50 +123,218 @@ Drawable drawable = res.{@link android.content.res.Resources#getDrawable(int) ge
 
 
 
+
XML Bitmap

+
+
An XML bitmap is a resource defined in XML that points to a bitmap file. The effect is an alias for a
+raw bitmap file. The XML can specify additional properties for the bitmap such as dithering and tiling.

+
+
Note: You can use a {@code <bitmap>} element as a child of
+an {@code <item>} element. For
+example, when creating a state list or layer list,
+you can exclude the {@code android:drawable}
+attribute from an {@code <item>} element and nest a {@code <bitmap>} inside it
+that defines the drawable item.

+
+

+
+
file location:

+
res/drawable/filename.xml

+The filename is used as the resource ID.

+
+
compiled resource datatype:

+
Resource pointer to a {@link android.graphics.drawable.BitmapDrawable}.

+
+
resource reference:

+

+In Java: R.drawable.filename

+In XML: @[package:]drawable/filename
+

+
+
syntax:

+

+
+<?xml version="1.0" encoding="utf-8"?>
+<bitmap
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:src="@[package:]drawable/drawable_resource"
+    android:antialias=["true" | "false"]
+    android:dither=["true" | "false"]
+    android:filter=["true" | "false"]
+    android:gravity=["top" | "bottom" | "left" | "right" | "center_vertical" |
+                      "fill_vertical" | "center_horizontal" | "fill_horizontal" |
+                      "center" | "fill" | "clip_vertical" | "clip_horizontal"]
+    android:tileMode=["disabled" | "clamp" | "repeat" | "mirror"] />
+

+

+
+
+
elements:

+

+

+
+  
<bitmap>

+    
Defines the bitmap source and its properties.
+      
attributes:

+      

+        
xmlns:android

+          
String. Defines the XML namespace, which must be
+          "http://schemas.android.com/apk/res/android". This is required only if the
+<bitmap> is the root element—it is not needed when the
+<bitmap> is nested inside an <item>.

+        
android:src

+          
Drawable resource. Required. Reference to a drawable
+resource.

+        
android:antialias

+          
Boolean. Enables or disables antialiasing.

+        
android:dither

+          
Boolean. Enables or disables dithering of the bitmap if the bitmap does not
+have the same pixel configuration as the screen (for instance: a ARGB 8888 bitmap with an RGB 565
+screen).

+        
android:filter

+          
Boolean. Enables or disables bitmap filtering. Filtering is used when the
+bitmap is shrunk or stretched to smooth its apperance.

+        
android:gravity

+          
Keyword. Defines the gravity for the bitmap. The gravity indicates where to
+position the drawable in its container if the bitmap is smaller than the container.
+            
Must be one or more (separated by '|') of the following constant values:

+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
ValueDescription
topPut the object at the top of its container, not changing its size.
bottomPut the object at the bottom of its container, not changing its size. 
leftPut the object at the left edge of its container, not changing its size. 
rightPut the object at the right edge of its container, not changing its size. 
center_verticalPlace object in the vertical center of its container, not changing its size. 
fill_verticalGrow the vertical size of the object if needed so it completely fills its container. 
center_horizontalPlace object in the horizontal center of its container, not changing its size. 
fill_horizontalGrow the horizontal size of the object if needed so it completely fills its container.
+
centerPlace the object in the center of its container in both the vertical and horizontal axis, not
+changing its size. 
fillGrow the horizontal and vertical size of the object if needed so it completely fills its
+container. This is the default.
clip_verticalAdditional option that can be set to have the top and/or bottom edges of the child clipped to
+its container's bounds. The clip is based on the vertical gravity: a top gravity clips the
+bottom edge, a bottom gravity clips the top edge, and neither clips both edges.
+
clip_horizontalAdditional option that can be set to have the left and/or right edges of the child clipped to
+its container's bounds. The clip is based on the horizontal gravity: a left gravity clips
+the right edge, a right gravity clips the left edge, and neither clips both edges.
+

+          

+        
android:tileMode

+          
Keyword. Defines the tile mode. When the tile mode is enabled, the bitmap is
+repeated. Gravity is ignored when the tile mode is enabled.
+            
Must be one of the following constant values:

+
+
+
+
+
+
+
+
+
+
+
ValueDescription
disabledDo not tile the bitmap. This is the default value.
clampReplicates the edge color if the shader draws outside of its original bounds
repeatRepeats the shader's image horizontally and vertically.
mirrorRepeats the shader's image horizontally and vertically, alternating mirror images so that
+adjacent images always seam.

+
+          

+      

+    

+
+

+
 
+
+
example:

+

+
+<?xml version="1.0" encoding="utf-8"?>
+<bitmap xmlns:android="http://schemas.android.com/apk/res/android"
+    android:src="@drawable/icon"
+    android:tileMode="repeat" />
+

+
+

+
+
see also:

+

+
+

+
+

+
+
+
 
 
 
-
Nine-Patch File

+
Nine-Patch

 
 
A {@link android.graphics.NinePatch} is a PNG image in which you can define stretchable regions
-that Android will scale when content within the View exceeds the normal image bounds. You will
+that Android scales when content within the View exceeds the normal image bounds. You
 typically assign this type of image as the background of a View that has at least one dimension set
 to {@code "wrap_content"}, and when the View grows to accomodate the content, the Nine-Patch image
-will also be scaled to match the size of the View. An example use of a Nine-Patch image is the
+is also scaled to match the size of the View. An example use of a Nine-Patch image is the
 background used by Android's standard {@link android.widget.Button} widget, which must stretch to
 accommodate the text (or image) inside the button.

 
-
For a complete discussion about how to define a Nine-Patch file with stretchable regions,
+
Same as with a normal bitmap, you can reference a Nine-Patch file directly
+or from a resource defined by XML.

+
+
For a complete discussion about how to create a Nine-Patch file with stretchable regions,
 see the 2D Graphics
 document.

 
+
+
Nine-Patch File

+
 

 
 
file location:

 
res/drawable/filename.9.png

-The filename will be used as the resource ID.

+The filename is used as the resource ID.
compiled resource datatype:
Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable}.
resource reference:
+
In Java: R.drawable.filename
In XML: @[package:]drawable/filename
example:
-
With an image saved at res/drawable/myninepatch.9.png, this layout XML will -apply the Nine-Patch to a View: + +
With an image saved at res/drawable/myninepatch.9.png, this layout XML +applies the Nine-Patch to a View: 
 <Button
     android:layout_height="wrap_content"
     android:layout_width="wrap_content"
-    android:background="@drawable/myninepatch" />
+    android:background="@drawable/myninepatch" />
see also:
+
  • 2D Graphics
    • @@ -153,6 +347,238 @@ apply the Nine-Patch to a View: +

    XML Nine-Patch

    + +

    An XML Nine-Patch is a resource defined in XML that points to a Nine-Patch file. The XML can +specify dithering for the image.

    + +
    + +
    file location:
    +
    res/drawable/filename.xml
    +The filename is used as the resource ID.
    + +
    compiled resource datatype:
    +
    Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable}.
    + +
    resource reference:
    + +
    +In Java: R.drawable.filename
    +In XML: @[package:]drawable/filename +
    + + +
    syntax:
    + +
    +
    +<?xml version="1.0" encoding="utf-8"?>
+<nine-patch
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:src="@[package:]drawable/drawable_resource"
+    android:dither=["true" | "false"] />
+
    +
    + + +
    elements:
    + +
    +
    + +
    <bitmap>
    +
    Defines the bitmap source and its properties. +

    attributes:

    +
    +
    xmlns:android
    +
    String. Required. Defines the XML namespace, which must be + "http://schemas.android.com/apk/res/android". +
    android:src
    +
    Drawable resource. Required. Reference to a Nine-Patch +file.
    +
    android:dither
    +
    Boolean. Enables or disables dithering of the bitmap if the bitmap does not +have the same pixel configuration as the screen (for instance: a ARGB 8888 bitmap with an RGB 565 +screen).
    +
    +
    +
    +
    + + +
    example:
    + +
    +
    +<?xml version="1.0" encoding="utf-8"?>
+<nine-patch xmlns:android="http://schemas.android.com/apk/res/android"
+    android:src="@drawable/myninepatch"
+    android:dither="false" />
+
    +
    +
    + + + + + + +

    Layer List

    + +

    A {@link android.graphics.drawable.LayerDrawable} is a drawable object +that manages an array of other drawables. Each drawable in the list is drawn in the order of the +list—the last drawable in the list is drawn on top.

    + +

    Each drawable is represented by an {@code <item>} element inside a single {@code +<layer-list>} element.

    + +
    + +
    file location:
    +
    res/drawable/filename.xml
    +The filename is used as the resource ID.
    + +
    compiled resource datatype:
    +
    Resource pointer to a {@link android.graphics.drawable.LayerDrawable}.
    + +
    resource reference:
    + +
    +In Java: R.drawable.filename
    +In XML: @[package:]drawable/filename +
    + +
    syntax:
    + +
    +
    +<?xml version="1.0" encoding="utf-8"?>
+<layer-list
+    xmlns:android="http://schemas.android.com/apk/res/android" >
+    <item
+        android:drawable="@[package:]drawable/drawable_resource"
+        android:id="@[+][package:]id/resource_name"
+        android:top="dimension"
+        android:right="dimension"
+        android:bottom="dimension"
+        android:left="dimension" />
+</selector>
+
    +
    + +
    elements:
    + +
    +
    + +
    <layer-list>
    +
    Required. This must be the root element. Contains one or more {@code +<item>} elements. +

    attributes:

    +
    +
    xmlns:android
    +
    String. Required. Defines the XML namespace, which must be + "http://schemas.android.com/apk/res/android". +
    +
    +
    <item>
    +
    Defines a drawable to place in the layer drawable, in a position defined by its attributes. +Must be a child of a <selector> element. Accepts child {@code <bitmap>} +elements. +

    attributes:

    +
    +
    android:drawable
    +
    Drawable resource. Required. Reference to a drawable +resource.
    +
    android:id
    +
    Resource ID. A unique resource ID for this drawable. To create a new resource +ID for this item, use the form: +"@+id/name". The plus symbol indicates that this should be created as a new +ID. You can use this identifier to +retrieve and modify the drawable with {@link android.view.View#findViewById(int) +View.findViewById()} or {@link android.app.Activity#findViewById(int) Activity.findViewById()}.
    +
    android:top
    +
    Integer. The top offset in pixels.
    +
    android:right
    +
    Integer. The right offset in pixels.
    +
    android:bottom
    +
    Integer. The bottom offset in pixels.
    +
    android:left
    +
    Integer. The left offset in pixels.
    +
    +

    All drawable items are scaled to fit the size of the containing View, by default. Thus, +placing your images in a layer list at different positions might increase the size of the View and +some images scale as appropriate. To avoid +scaling items in the list, use a {@code <bitmap>} element inside the {@code +<item>} element to specify the drawable and define the gravity to something that does not +scale, such as {@code "center"}. For example, the following {@code <item>} defines an item +that scales to fit its container View:

    +
    +<item android:drawable="@drawable/image" />
+
    + +

    To avoid scaling, the following example uses a {@code <bitmap>} element with centered +gravity:

    +
    +<item>
+  <bitmap android:src="@drawable/image"
+          android:gravity="center" />
+</item>
+
    +
    + +
    +
    + +
    example:
    + +
    XML file saved at res/drawable/layers.xml: +
    +<?xml version="1.0" encoding="utf-8"?>
+<layer-list xmlns:android="http://schemas.android.com/apk/res/android">
+    <item>
+      <bitmap android:src="@drawable/android_red"
+        android:gravity="center" />
+    </item>
+    <item android:top="10dp" android:left="10dp">
+      <bitmap android:src="@drawable/android_green"
+        android:gravity="center" />
+    </item>
+    <item android:top="20dp" android:left="20dp">
+      <bitmap android:src="@drawable/android_blue"
+        android:gravity="center" />
+    </item>
+</layer-list>
+
    +

    Notice that this example uses a nested {@code <bitmap>} element to define the drawable +resource for each item with a "center" gravity. This ensures that none of the images are scaled to +fit the size of the container, due to resizing caused by the offset images.

    + +

    This layout XML applies the drawable to a View:

    +
    +<ImageView
+    android:layout_height="wrap_content"
+    android:layout_width="wrap_content"
+    android:src="@drawable/layers" />
+
    + +

    The result is a stack of increasingly offset images:

    + +
    + +
    see also:
    +
    +
      +
    • {@link android.graphics.drawable.LayerDrawable}
      • +
    +
    + +
    + + + + @@ -163,33 +589,36 @@ apply the Nine-Patch to a View: that uses a several different images to represent the same graphic, depending on the state of the object. For example, a {@link android.widget.Button} widget can exist in one of several different states (pressed, focused, -or niether) and, using a state list drawable, you can provide a different button image for each +or niether) and, using a state list drawable, you can provide a different background image for each state.

    You can describe the state list in an XML file. Each graphic is represented by an {@code <item>} element inside a single {@code <selector>} element. Each {@code <item>} uses various attributes to describe the state in which it should be used as the graphic for the drawable.

    +

    During each state change, the state list is traversed top to bottom and the first item that -matches the current state will be used—the selection is not based on the "best +matches the current state is used—the selection is not based on the "best match," but simply the first item that meets the minimum criteria of the state.

    file location:
    res/drawable/filename.xml
    -The filename will be used as the resource ID.
    +The filename is used as the resource ID.
compiled resource datatype:
Resource pointer to a {@link android.graphics.drawable.StateListDrawable}.
resource reference:
+
In Java: R.drawable.filename
In XML: @[package:]drawable/filename
syntax:
+ 
 <?xml version="1.0" encoding="utf-8"?>
@@ -212,6 +641,7 @@ In XML: @[package:]drawable/filename
elements:
+
@@ -224,8 +654,8 @@ In XML: @[package:]drawable/filename
String. Required. Defines the XML namespace, which must be "http://schemas.android.com/apk/res/android".
android:constantSize
-
Boolean. "true" if the drawable's reported internal size will remain constant as the state -changes (the size will be the maximum of all of the states); "false" if the size will vary based on +
Boolean. "true" if the drawable's reported internal size remains constant as the state +changes (the size is the maximum of all of the states); "false" if the size varies based on the current state. Default is false.
android:dither
Boolean. "true" to enable dithering of the bitmap if the bitmap does not have the same pixel @@ -270,9 +700,9 @@ receiving touch/click events); "false" if it should be used when the object is d application is in the foreground), "false" if this item should be used when the application window does not have focus (for example, if the notification shade is pulled down or a dialog appears).
-

Note:Remember that the first item in the state list that -matches the current state of the object will be applied. So if the first item in the list contains -none of the state attributes above, then it will be applied every time, which is why your +

Note: Remember that Android applies the first item in the state list that +matches the current state of the object. So, if the first item in the list contains +none of the state attributes above, then it is applied every time, which is why your default value should always be last (as demonstrated in the following example).

@@ -280,6 +710,7 @@ default value should always be last (as demonstrated in the following example).<
example:
+
XML file saved at res/drawable/button.xml: 
 <?xml version="1.0" encoding="utf-8"?>
@@ -292,12 +723,12 @@ default value should always be last (as demonstrated in the following example).<
 </selector>
-

This layout XML will apply the drawable to a View:

+

This layout XML applies the drawable to a View:

 <ImageView
     android:layout_height="wrap_content"
     android:layout_width="wrap_content"
-    android:src="@drawable/button" />
+    android:src="@drawable/button" />
@@ -317,106 +748,237 @@ default value should always be last (as demonstrated in the following example).< +

Level List

- - - - - -

Color

- -

This is a color defined in XML that's used as a drawable to fill a rectangular space, -with optionally rounded corners. This kind of drawable behaves like a color fill.

- -

Note: A color drawable is a simple resource that is referenced -using the value provided in the {@code name} attribute (not the name of the XML file). As -such, you can combine a color drawable resources with other simple resources in the one XML file, -under one {@code <resources>} element.

- +

A Drawable that manages a number of alternate Drawables, each assigned a maximum numerical +value. Setting the level value of the drawable with {@link +android.graphics.drawable.Drawable#setLevel(int) setLevel()} loads the drawable resource in the +level list that has a {@code android:maxLevel} value greater than or equal to the value +passed to the method.

file location:
-
res/drawable/filename.png
-The filename is arbitrary. The element's {@code name} will be used as the resource ID.
+
res/drawable/filename.xml
+The filename is used as the resource ID.
compiled resource datatype:
-
Resource pointer to a {@link android.graphics.drawable.PaintDrawable}.
+
Resource pointer to a {@link android.graphics.drawable.LevelListDrawable}.
resource reference:
+
-In Java: R.drawable.color_name
-In XML: @[package:]drawable/color_name +In Java: R.drawable.filename
+In XML: @[package:]drawable/filename
syntax:
+ 
-<?xml version="1.0" encoding="utf-8"?>
-<resources>
-    <drawable
-        name="color_name"
-        >color</drawable>
-</resources>
+<?xml version="1.0" encoding="utf-8"?>
+<level-list
+    xmlns:android="http://schemas.android.com/apk/res/android" >
+    <item
+        android:drawable="@drawable/drawable_resource"
+        android:maxLevel="integer"
+        android:minLevel="integer" />
+</level-list>
elements:
+
-
<resources>
-
Required. This must be the root node. -

No attributes.

-
-
<drawable>
-
A color to use as a drawable rectangle. The value can be - any valid hexadecimal color value or a color - resource. A color value always begins with a pound (#) character, followed - by the Alpha-Red-Green-Blue information in one of the following formats: - #RGB, #RRGGBB, #ARGB, or #AARRGGBB. -

attributes:

-
-
name
-
String. Required. - A name for the color. This name will be used as the resource ID.
-
- -
- +
<level-list>
+
This must be the root element. Contains one or more {@code <item>} elements. +

attributes:

+
+
xmlns:android
+
String. Required. Defines the XML namespace, which must be + "http://schemas.android.com/apk/res/android". +
+
+ +
<item>
+
Defines a drawable to use at a certain level. +

attributes:

+
+
android:drawable
+
Drawable resource. Required. Reference to a drawable +resource to be inset.
+
android:maxLevel
+
Integer. The maximum level allowed for this item.
+
android:minLevel
+
Integer. The minimum level allowed for this item.
+
+
-
+ +
example:
-
XML file saved at res/drawable/colors.xml: + +
+ 
 <?xml version="1.0" encoding="utf-8"?>
-<resources>
-    <drawable name="solid_red">#f00</drawable>
-    <drawable name="solid_blue">#0000ff</drawable>
-</resources>
-
-

This layout XML will apply a color drawable to a View:

-
-<TextView
-    android:layout_width="fill_parent"
-    android:layout_height="wrap_content"
-    android:background="@drawable/solid_blue" />
+<level-list xmlns:android="http://schemas.android.com/apk/res/android" >
+    <item
+        android:drawable="@drawable/status_off"
+        android:maxLevel="0" />
+    <item
+        android:drawable="@drawable/status_on"
+        android:maxLevel="1" />
+</level-list>
+
+

Once this is applied to a {@link android.view.View}, the level can be changed with {@link +android.graphics.drawable.Drawable#setLevel(int) setLevel()} or {@link +android.widget.ImageView#setImageLevel(int) setImageLevel()}.

+ +
+ +
see also:
+ +
+
    +
  • {@link android.graphics.drawable.LevelListDrawable}
    • +
+
+ +
+ + + + + + +

Transition Drawable

+ +

A {@link android.graphics.drawable.TransitionDrawable} is a drawable object +that can cross-fade between the two drawable resources.

+ +

Each drawable is represented by an {@code <item>} element inside a single {@code +<transition>} element. No more than two items are supported. To transition forward, call +{@link android.graphics.drawable.TransitionDrawable#startTransition(int) startTransition()}. To +transition backward, call {@link android.graphics.drawable.TransitionDrawable#reverseTransition(int) +reverseTransition()}.

+ +
+ +
file location:
+
res/drawable/filename.xml
+The filename is used as the resource ID.
+ +
compiled resource datatype:
+
Resource pointer to a {@link android.graphics.drawable.TransitionDrawable}.
+ +
resource reference:
+ +
+In Java: R.drawable.filename
+In XML: @[package:]drawable/filename +
+ +
syntax:
+ +
+
+<?xml version="1.0" encoding="utf-8"?>
+<layer-list
+xmlns:android="http://schemas.android.com/apk/res/android" >
+    <item
+        android:drawable="@[package:]drawable/drawable_resource"
+        android:id="@[+][package:]id/resource_name"
+        android:top="dimension"
+        android:right="dimension"
+        android:bottom="dimension"
+        android:left="dimension" />
+</selector>
+
+
+ +
elements:
+ +
+
+ +
<transition>
+
Required. This must be the root element. Contains one or more {@code +<item>} elements. +

attributes:

+
+
xmlns:android
+
String. Required. Defines the XML namespace, which must be + "http://schemas.android.com/apk/res/android". +
+
+
<item>
+
Defines a drawable to place in the layer drawable, in a position defined by its attributes. +Must be a child of a <selector> element. Accepts child {@code <bitmap>} +elements. +

attributes:

+
+
android:drawable
+
Drawable resource. Required. Reference to a drawable +resource.
+
android:id
+
Resource ID. A unique resource ID for this drawable. To create a new resource +ID for this item, use the form: +"@+id/name". The plus symbol indicates that this should be created as a new +ID. You can use this identifier to +retrieve and modify the drawable with {@link android.view.View#findViewById(int) +View.findViewById()} or {@link android.app.Activity#findViewById(int) Activity.findViewById()}.
+
android:top
+
Integer. The top offset in pixels.
+
android:right
+
Integer. The right offset in pixels.
+
android:bottom
+
Integer. The bottom offset in pixels.
+
android:left
+
Integer. The left offset in pixels.
+
+
+ +
+
+ +
example:
+ +
XML file saved at res/drawable/transition.xml: +
+<?xml version="1.0" encoding="utf-8"?>
+<transition xmlns:android="http://schemas.android.com/apk/res/android">
+    <item android:drawable="@drawable/on" />
+    <item android:drawable="@drawable/off" />
+</layer-list>
+
+ +

This layout XML applies the drawable to a View:

+
+<ImageButton
+    android:id="@+id/button"
+    android:layout_height="wrap_content"
+    android:layout_width="wrap_content"
+    android:src="@drawable/transition" />
+
+ +

And the following code performs a 500ms transition from the first item to the second:

+
+ImageButton button = (ImageButton) findViewById(R.id.button);
+TransitionDrawable drawable = (TransitionDrawable) button.getDrawable();
+drawable.startTransition(500);
-

This application code will get a color drawable and apply it to a View:

-
-Resources res =  {@link android.content.Context#getResources()};
-Drawable redDrawable = res.{@link android.content.res.Resources#getDrawable(int) getDrawable}(R.drawable.solid_red);
 
-TextView tv = (TextView) findViewByID(R.id.text);
-tv.setBackground(redDrawable);
-
see also:
+
    -
  • {@link android.graphics.drawable.PaintDrawable}
    • +
  • {@link android.graphics.drawable.TransitionDrawable}
@@ -429,11 +991,416 @@ tv.setBackground(redDrawable); +

Inset Drawable

+ +

A drawable defined in XML that insets another drawable by a specified distance. This is used when +a View needs a background that is smaller than the View's actual bounds.

+ +
+ +
file location:
+
res/drawable/filename.xml
+The filename is used as the resource ID.
+ +
compiled resource datatype:
+
Resource pointer to a {@link android.graphics.drawable.InsetDrawable}.
+
resource reference:
+
+In Java: R.drawable.filename
+In XML: @[package:]drawable/filename +
+
syntax:
-

Shape

+
+
+<?xml version="1.0" encoding="utf-8"?>
+<inset
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:drawable="@drawable/drawable_resource"
+    android:insetTop="dimension"
+    android:insetRight="dimension"
+    android:insetBottom="dimension"
+    android:insetLeft="dimension" />
+
+
+ +
elements:
+ +
+
+ +
<inset>
+
Defines the inset drawable. This must be the root element. +

attributes:

+
+
xmlns:android
+
String. Required. Defines the XML namespace, which must be + "http://schemas.android.com/apk/res/android". +
android:drawable
+
Drawable resource. Required. Reference to a drawable +resource to be inset.
+
android:insetTop
+
Dimension. The top inset, as a dimension value or dimension resource
+
android:insetRight
+
Dimension. The right inset, as a dimension value or dimension resource
+
android:insetBottom
+
Dimension. The bottom inset, as a dimension value or dimension resource
+
android:insetLeft
+
Dimension. The left inset, as a dimension value or dimension resource
+
+
+
+ +
+ +
example:
+ +
+
+<?xml version="1.0" encoding="utf-8"?>
+<inset xmlns:android="http://schemas.android.com/apk/res/android"
+    android:drawable="@drawable/background"
+    android:insetTop="10dp"
+    android:insetLeft="10dp" />
+
+
+ +
see also:
+ +
+
    +
  • {@link android.graphics.drawable.InsetDrawable}
    • +
+
+ +
+ + + + + + + + +

Clip Drawable

+ +

A drawable defined in XML that clips another drawable based on this Drawable's current level. You +can control how much the child drawable gets clipped in width and height based on the level, as well +as a gravity to control where it is placed in its overall container. Most often used to implement +things like progress bars.

+ +
+ +
file location:
+
res/drawable/filename.xml
+The filename is used as the resource ID.
+ +
compiled resource datatype:
+
Resource pointer to a {@link android.graphics.drawable.ClipDrawable}.
+ +
resource reference:
+ +
+In Java: R.drawable.filename
+In XML: @[package:]drawable/filename +
+ +
syntax:
+ +
+
+<?xml version="1.0" encoding="utf-8"?>
+<clip
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:drawable="@drawable/drawable_resource"
+    android:clipOrientation=["horizontal" | "vertical"]
+    android:gravity=["top" | "bottom" | "left" | "right" | "center_vertical" |
+                     "fill_vertical" | "center_horizontal" | "fill_horizontal" |
+                     "center" | "fill" | "clip_vertical" | "clip_horizontal"] />
+
+
+ +
elements:
+ +
+
+ +
<clip>
+
Defines the clip drawable. This must be the root element. +

attributes:

+
+
xmlns:android
+
String. Required. Defines the XML namespace, which must be + "http://schemas.android.com/apk/res/android". +
android:drawable
+
Drawable resource. Required. Reference to a drawable +resource to be clipped.
+
android:clipOrientation
+
Keyword. The orientation for the clip. +

Must be one of the following constant values:

+ + + + + + +
ValueDescription
horizontalClip the drawable horizontally.
verticalClip the drawable vertically.
+
+
android:gravity
+
Keyword. Specifies where to clip within the drawable. +

Must be one or more (separated by '|') of the following constant values:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
topPut the object at the top of its container, not changing its size. When {@code +clipOrientation} is {@code "vertical"}, clipping occurs at the bottom of the drawable.
bottomPut the object at the bottom of its container, not changing its size. When {@code +clipOrientation} is {@code "vertical"}, clipping occurs at the top of the drawable.
leftPut the object at the left edge of its container, not changing its size. This is the +default. When {@code clipOrientation} is {@code "horizontal"}, clipping occurs at the right side of +the drawable. This is the default.
rightPut the object at the right edge of its container, not changing its size. When {@code +clipOrientation} is {@code "horizontal"}, clipping occurs at the left side of +the drawable.
center_verticalPlace object in the vertical center of its container, not changing its size. Clipping behaves +the same as when gravity is {@code "center"}.
fill_verticalGrow the vertical size of the object if needed so it completely fills its container. When {@code +clipOrientation} is {@code "vertical"}, no clipping occurs because the drawable fills the +vertical space (unless the drawable level is 0, in which case it's not visible).
center_horizontalPlace object in the horizontal center of its container, not changing its size. +Clipping behaves the same as when gravity is {@code "center"}.
fill_horizontalGrow the horizontal size of the object if needed so it completely fills its container. When +{@code clipOrientation} is {@code "horizontal"}, no clipping occurs because the drawable fills the +horizontal space (unless the drawable level is 0, in which case it's not visible). +
centerPlace the object in the center of its container in both the vertical and horizontal axis, not +changing its size. When {@code +clipOrientation} is {@code "horizontal"}, clipping occurs on the left and right. When {@code +clipOrientation} is {@code "vertical"}, clipping occurs on the top and bottom.
fillGrow the horizontal and vertical size of the object if needed so it completely fills its +container. No clipping occurs because the drawable fills the +horizontal and vertical space (unless the drawable level is 0, in which case it's not +visible).
clip_verticalAdditional option that can be set to have the top and/or bottom edges of the child clipped to +its container's bounds. The clip is based on the vertical gravity: a top gravity clips the +bottom edge, a bottom gravity clips the top edge, and neither clips both edges. +
clip_horizontalAdditional option that can be set to have the left and/or right edges of the child clipped to +its container's bounds. The clip is based on the horizontal gravity: a left gravity clips +the right edge, a right gravity clips the left edge, and neither clips both edges. +
+
+
+
+ +
+ +
example:
+ +
XML file saved at res/drawable/clip.xml: +
+<?xml version="1.0" encoding="utf-8"?>
+<shape xmlns:android="http://schemas.android.com/apk/res/android"
+    android:drawable="@drawable/android"
+    android:clipOrientation="horizontal"
+    android:gravity="left" />
+</shape>
+
+

The following layout XML applies the clip drawable to a View:

+
+<ImageView
+    android:id="@+id/image"
+    android:background="@drawable/clip"
+    android:layout_height="wrap_content"
+    android:layout_width="wrap_content" />
+
+ +

The following code gets the drawable and increases the amount of clipping in order to +progressively reveal the image:

+
+ImageView imageview = (ImageView) findViewById(R.id.image);
+ClipDrawable drawable = (ClipDrawable) imageview.getDrawable();
+drawable.setLevel(drawable.getLevel() + 1000);
+
+ +

Increasing the level reduces the amount of clipping and slowly reveals the image. Here it is +at a level of 7000:

+ + +

Note: The default level is 0, which is fully clipped so the image +is not visible. When the level is 10,000, the image is not clipped and completely visible.

+
+ +
see also:
+ +
+
    +
  • {@link android.graphics.drawable.ClipDrawable}
    • +
+
+ +
+ + + + + + + + + +

Scale Drawable

+ +

A drawable defined in XML that changes the size of another drawable based on its current +level.

+ +
+ +
file location:
+
res/drawable/filename.xml
+The filename is used as the resource ID.
+ +
compiled resource datatype:
+
Resource pointer to a {@link android.graphics.drawable.ScaleDrawable}.
+ +
resource reference:
+ +
+In Java: R.drawable.filename
+In XML: @[package:]drawable/filename +
+ +
syntax:
+ +
+
+<?xml version="1.0" encoding="utf-8"?>
+<scale
+    xmlns:android="http://schemas.android.com/apk/res/android"
+    android:drawable="@drawable/drawable_resource"
+    android:scaleGravity=["top" | "bottom" | "left" | "right" | "center_vertical" |
+                          "fill_vertical" | "center_horizontal" | "fill_horizontal" |
+                          "center" | "fill" | "clip_vertical" | "clip_horizontal"]
+    android:scaleHeight="percentage"
+    android:scaleWidth="percentage" />
+
+
+ +
elements:
+ +
+
+ +
<scale>
+
Defines the scale drawable. This must be the root element. +

attributes:

+
+
xmlns:android
+
String. Required. Defines the XML namespace, which must be + "http://schemas.android.com/apk/res/android". +
android:drawable
+
Drawable resource. Required. Reference to a drawable +resource.
+
android:scaleGravity
+
Keyword. Specifies the gravity position after scaling. +

Must be one or more (separated by '|') of the following constant values:

+ + + + + + + + + + + + + + + + + + + + + + + + + + +
ValueDescription
topPut the object at the top of its container, not changing its size.
bottomPut the object at the bottom of its container, not changing its size.
leftPut the object at the left edge of its container, not changing its size. This is the +default.
rightPut the object at the right edge of its container, not changing its size.
center_verticalPlace object in the vertical center of its container, not changing its size.
fill_verticalGrow the vertical size of the object if needed so it completely fills its container.
center_horizontalPlace object in the horizontal center of its container, not changing its size.
fill_horizontalGrow the horizontal size of the object if needed so it completely fills its container. +
centerPlace the object in the center of its container in both the vertical and horizontal axis, not +changing its size.
fillGrow the horizontal and vertical size of the object if needed so it completely fills its +container.
clip_verticalAdditional option that can be set to have the top and/or bottom edges of the child clipped to +its container's bounds. The clip is based on the vertical gravity: a top gravity clips the +bottom edge, a bottom gravity clips the top edge, and neither clips both edges. +
clip_horizontalAdditional option that can be set to have the left and/or right edges of the child clipped to +its container's bounds. The clip is based on the horizontal gravity: a left gravity clips +the right edge, a right gravity clips the left edge, and neither clips both edges. +
+
android:scaleHeight
+
Percentage. The scale height, expressed as a percentage of the drawable's +bound. The value's format is XX%. For instance: 100%, 12.5%, etc.
+
android:scaleWidth
+
Percentage. The scale width, expressed as a percentage of the drawable's +bound. The value's format is XX%. For instance: 100%, 12.5%, etc.
+
+
+
+ +
+ +
example:
+ +
+
+<?xml version="1.0" encoding="utf-8"?>
+<scale xmlns:android="http://schemas.android.com/apk/res/android"
+    android:drawable="@drawable/logo"
+    android:scaleGravity="center_vertical|center_horizontal"
+    android:scaleHeight="80%"
+    android:scaleWidth="80%" />
+
+
+ +
see also:
+
+
    +
  • {@link android.graphics.drawable.ScaleDrawable}
    • +
+
+ +
+ + + + + + + +

Shape Drawable

This is a generic shape defined in XML.

@@ -441,23 +1408,32 @@ tv.setBackground(redDrawable);
file location:
res/drawable/filename.xml
-The filename will be used as the resource ID.
+The filename is used as the resource ID.
compiled resource datatype:
Resource pointer to a {@link android.graphics.drawable.ShapeDrawable}.
resource reference:
+
In Java: R.drawable.filename
In XML: @[package:]drawable/filename
syntax:
+ 
 <?xml version="1.0" encoding="utf-8"?>
-<shape xmlns:android="http://schemas.android.com/apk/res/android"
+<shape
+    xmlns:android="http://schemas.android.com/apk/res/android"
     android:shape=["rectangle" | "oval" | "line" | "ring"] >
+    <corners
+        android:radius="integer"
+        android:topLeftRadius="integer"
+        android:topRightRadius="integer"
+        android:bottomLeftRadius="integer"
+        android:bottomRightRadius="integer" />
     <gradient
         android:angle="integer"
         android:centerX="integer"
@@ -467,37 +1443,40 @@ In XML: @[package:]drawable/filename
         android:gradientRadius="integer"
         android:startColor="color"
         android:type=["linear" | "radial" | "sweep"]
-        android:usesLevel=["true" | "false"] />
+        android:usesLevel=["true" | "false"] />
+    <padding
+        android:left="integer"
+        android:top="integer"
+        android:right="integer"
+        android:bottom="integer" />
+    <size
+        android:width="integer"
+        android:color="color"
+        android:dashWidth="integer"
+        android:dashGap="integer" />
     <solid
-        android:color="color" />
+        android:color="color" />
     <stroke
         android:width="integer"
         android:color="color"
         android:dashWidth="integer"
-        android:dashGap="integer" />
-    <padding
-        android:left="integer"
-        android:top="integer"
-        android:right="integer"
-        android:bottom="integer" />
-    <corners
-        android:radius="integer"
-        android:topLeftRadius="integer"
-        android:topRightRadius="integer"
-        android:bottomLeftRadius="integer"
-        android:bottomRightRadius="integer" />
+        android:dashGap="integer" />
 </shape>
elements:
+
<shape>
-
Required. This must be the root element. +
The shape drawable. This must be the root element.

attributes:

+
xmlns:android
+
String. Required. Defines the XML namespace, which must be + "http://schemas.android.com/apk/res/android".
android:shape
Keyword. Defines the type of shape. Valid values are: @@ -525,7 +1504,7 @@ href="more-resources.html#Dimension">dimension resource.
Float. The radius for the inner part of the ring, expressed as a ratio of the ring's width. For instance, if {@code android:innerRadiusRatio="5"}, then the inner radius equals the ring's width divided by 5. This -value will be overridden by {@code android:innerRadius}. Default value is 9.
+value is overridden by {@code android:innerRadius}. Default value is 9.
android:thickness
Dimension. The thickness of the ring, as a dimension value or dimension resource.
android:thicknessRatio
Float. The thickness of the ring, expressed as a ratio of the ring's width. For instance, if {@code android:thicknessRatio="2"}, then -the thickness equals the ring's width divided by 2. This value will be overridden by {@code +the thickness equals the ring's width divided by 2. This value is overridden by {@code android:innerRadius}. Default value is 3.
android:useLevel
Boolean. "true" if this is used as a {@link android.graphics.drawable.LevelListDrawable}. This should normally be "false" or your shape may not appear.
+
<corners>
+
Creates rounded corners for the shape. Applies only when the shape is a rectangle. +

attributes:

+
+
android:radius
+
Dimension. The radius for all corners, as a dimension value or dimension resource. This is overridden for each +corner by the following attributes.
+
android:topLeftRadius
+
Dimension. The radius for the top-left corner, as a dimension value or dimension resource.
+
android:topRightRadius
+
Dimension. The radius for the top-right corner, as a dimension value or dimension resource.
+
android:bottomLeftRadius
+
Dimension. The radius for the bottom-left corner, as a dimension value or dimension resource.
+
android:bottomRightRadius
+
Dimension. The radius for the bottom-right corner, as a dimension value or dimension resource.
+
+

Note: Every corner must (initially) be provided a corner +radius greater than 1, or else no corners are rounded. If you want specific corners +to not be rounded, a work-around is to use {@code android:radius} to set a default corner +radius greater than 1, but then override each and every corner with the values you really +want, providing zero ("0dp") where you don't want rounded corners.

+
<gradient>
Specifies a gradient color for the shape.

attributes:

@@ -582,6 +1588,42 @@ value or color resource.
android.graphics.drawable.LevelListDrawable}. +
<padding>
+
Padding to apply to the containing View element (this pads the position of the View +content, not the shape). +

attributes:

+
+
android:left
+
Dimension. Left padding, as a dimension value or dimension resource.
+
android:top
+
Dimension. Top padding, as a dimension value or dimension resource.
+
android:right
+
Dimension. Right padding, as a dimension value or dimension resource.
+
android:bottom
+
Dimension. Bottom padding, as a dimension value or dimension resource.
+
+
+
<size>
+
The size of the shape. +

attributes:

+
+
android:height
+
Dimension. The height of the shape, as a dimension value or dimension resource.
+
android:width
+
Dimension. The width of the shape, as a dimension value or dimension resource.
+
+

Note: The shape scales to the size of the container +View proportionate to the dimensions defined here, by default. When you use the shape in an {@link +android.widget.ImageView}, you can restrict scaling by setting the {@code +android:scaleType} to {@code "center"}.

+
<solid>
A solid color to fill the shape.

attributes:

@@ -611,57 +1653,12 @@ href="more-resources.html#Dimension">dimension resource. Only valid if {@cod android:dashGap} is set.
-
<padding>
-
Padding to apply to the containing View element (this pads the position of the View -content, not the shape). -

attributes:

-
-
android:left
-
Dimension. Left padding, as a dimension value or dimension resource.
-
android:top
-
Dimension. Top padding, as a dimension value or dimension resource.
-
android:right
-
Dimension. Right padding, as a dimension value or dimension resource.
-
android:bottom
-
Dimension. Bottom padding, as a dimension value or dimension resource.
-
-
-
<corners>
-
Creates rounded corners for the shape. Applies only when the shape is a rectangle. -

attributes:

-
-
android:radius
-
Dimension. The radius for all corners, as a dimension value or dimension resource. This will be overridden for each -corner by the following attributes.
-
android:topLeftRadius
-
Dimension. The radius for the top-left corner, as a dimension value or dimension resource.
-
android:topRightRadius
-
Dimension. The radius for the top-right corner, as a dimension value or dimension resource.
-
android:bottomLeftRadius
-
Dimension. The radius for the bottom-left corner, as a dimension value or dimension resource.
-
android:bottomRightRadius
-
Dimension. The radius for the bottom-right corner, as a dimension value or dimension resource.
-
-

Note: Every corner must (initially) be provided a corner -radius greater than zero, or else no corners will be rounded. If you want specific corners -to not be rounded, a work-around is to use {@code android:radius} to set a default corner -radius greater than zero, but then override each and every corner with the values you really -want, providing zero ("0dp") where you don't want rounded corners.

-
example:
+
XML file saved at res/drawable/gradient_box.xml: 
 <?xml version="1.0" encoding="utf-8"?>
@@ -678,14 +1675,16 @@ want, providing zero ("0dp") where you don't want rounded corners.

     <corners android:radius="8dp" />
 </shape>
-

This layout XML will apply the shape drawable to a View:

+ +

This layout XML applies the shape drawable to a View:

 <TextView
     android:background="@drawable/gradient_box"
     android:layout_height="wrap_content"
     android:layout_width="wrap_content" />
-

This application code will get the shape drawable and apply it to a View:

+ +

This application code gets the shape drawable and applies it to a View:

 Resources res = {@link android.content.Context#getResources()};
 Drawable shape = res. {@link android.content.res.Resources#getDrawable(int) getDrawable}(R.drawable.gradient_box);
@@ -695,6 +1694,14 @@ tv.setBackground(shape);
+
see also:
+ +
+
    +
  • {@link android.graphics.drawable.ShapeDrawable}
    • +
+
+ diff --git a/docs/html/guide/topics/resources/layout-resource.jd b/docs/html/guide/topics/resources/layout-resource.jd index 0688a181f11c..111851c0c60e 100644 --- a/docs/html/guide/topics/resources/layout-resource.jd +++ b/docs/html/guide/topics/resources/layout-resource.jd @@ -35,12 +35,12 @@ In XML: @[package:]layout/filename
 <?xml version="1.0" encoding="utf-8"?>
 <ViewGroup xmlns:android="http://schemas.android.com/apk/res/android"
-    android:id="@+id/name"
+    android:id="@[+][package:]id/resource_name"
     android:layout_height=["dimension" | "fill_parent" | "wrap_content"]
     android:layout_width=["dimension" | "fill_parent" | "wrap_content"]
     [ViewGroup-specific attributes] >
     <View
-        android:id="@+id/name"
+        android:id="@[+][package:]id/resource_name"
         android:layout_height=["dimension" | "fill_parent" | "wrap_content"]
         android:layout_width=["dimension" | "fill_parent" | "wrap_content"]
         [View-specific attributes] >
@@ -49,10 +49,12 @@ In XML: @[package:]layout/filename
     <ViewGroup >
         <View />
     </ViewGroup>
+    <include layout="@layout/layout_resource"/>
 </ViewGroup>

Note: The root element can be either a -{@link android.view.ViewGroup} or a {@link android.view.View}, but there must be only +{@link android.view.ViewGroup}, a {@link android.view.View}, or a {@code <merge>} element, but there must be only one root element and it must contain the {@code xmlns:android} attribute with the {@code android} namespace as shown.

@@ -74,10 +76,9 @@ namespace as shown.

attributes:

android:id
-
Resource name. A unique resource name for the element, which you can -use to obtain a reference to the {@link android.view.ViewGroup} from your application. - The value takes the form: "@+id/name". See more about the - value for {@code android:id} below. +
Resource ID. A unique resource name for the element, which you can +use to obtain a reference to the {@link android.view.ViewGroup} from your application. See more +about the value for {@code android:id} below.
android:layout_height
Dimension or keyword. Required. The height for the group, as a @@ -107,10 +108,9 @@ attributes).

attributes:

android:id
-
Resource name. A unique resource name for the element, which you can use to - obtain a reference to the {@link android.view.View} from your application. - The value takes the form: "@+id/name". See more about the - value for {@code android:id} below. +
Resource ID. A unique resource name for the element, which you can use to + obtain a reference to the {@link android.view.View} from your application. See more about +the value for {@code android:id} below.
android:layout_height
Dimension or keyword. Required. The height for the element, as @@ -137,20 +137,71 @@ or {@code "wrap_content"}). See the valid values bel which gives it's parent initial focus on the screen. You can have only one of these elements per file.
+
<include>
+
Includes a layout file into this layout. +

attributes:

+
+
layout
+
Layout resource. Required. Reference to a layout +resource.
+
android:id
+
Resource ID. Overrides the ID given to the root view in the included layout. +
+
android:layout_height
+
Dimension or keyword. Overrides the height given to the root view in the +included layout. +
+
android:layout_width
+
Dimension or keyword. Overrides the width given to the root view in the +included layout. +
+
+

You can include any other layout attributes in the <include> that are +supported by the root element in the included layout and they will override those defined in the +root element.

+ +

Another way to include a layout is to use {@link android.view.ViewStub}. It is a lightweight +View that consumes no layout space until you explicitly inflate it, at which point, it includes a +layout file defined by its {@code android:layout} attribute. For more information about using {@link +android.view.ViewStub}, read Layout +Tricks: ViewStubs.

+
+ +
<merge>
+
An alternative root element that is not drawn in the layout hierarchy. Using this as the +root element is useful when you know that this layout will be placed into a layout +that already contains the appropriate parent View to contain the children of the +<merge> element. This is particularly useful when you plan to include this layout +in another layout file using <include> and +this layout doesn't require a different {@link android.view.ViewGroup} container. For more +information about merging layouts, read Layout +Tricks: Merging.
+
+ +

Value for android:id

-

For the ID value, you should use this syntax form: "@+id/name". The plus symbol, -{@code +}, indicates that this is a new resource ID and the aapt tool will create -a new resource number to the {@code R.java} class, if it doesn't already exist. For example:

+

For the ID value, you should usually use this syntax form: "@+id/name". The +plus symbol, {@code +}, indicates that this is a new resource ID and the aapt tool will +create a new resource integer in the {@code R.java} class, if it doesn't already exist. For +example:

 <TextView android:id="@+id/nameTextbox"/>
-

You can then refer to it this way in Java:

+

The nameTextbox name is now a resource ID attached to this element. You can then +refer to the {@link android.widget.TextView} to which the ID is associated in Java:

 findViewById(R.id.nameTextbox);
+

This code returns the {@link android.widget.TextView} object.

+ +

However, if you have already defined an ID resource (and it is not +already used), then you can apply that ID to a {@link android.view.View} element by excluding the +plus symbol in the android:id value.

Value for android:layout_height and android:layout_width:

diff --git a/docs/html/guide/topics/resources/menu-resource.jd b/docs/html/guide/topics/resources/menu-resource.jd index badc40328a54..cde72bdf37db 100644 --- a/docs/html/guide/topics/resources/menu-resource.jd +++ b/docs/html/guide/topics/resources/menu-resource.jd @@ -35,7 +35,7 @@ In XML: @[package:]menu.filename 
 <?xml version="1.0" encoding="utf-8"?>
 <menu xmlns:android="http://schemas.android.com/apk/res/android">
-    <item android:id="@+id/id_name"
+    <item android:id="@[+][package:]id/resource_name"
           android:menuCategory=["container" | "system" | "secondary" | "alternative"]
           android:orderInCategory="integer"
           android:title="string"
@@ -46,7 +46,7 @@ In XML: @[package:]menu.filename
           android:checkable=["true" | "false"]
           android:visible=["visible" | "invisible" | "gone"]
           android:enabled=["enabled" | "disabled"] />
-    <group android:id="resource ID"
+    <group android:id="@[+][package:]id/resource name"
            android:menuCategory=["container" | "system" | "secondary" | "alternative"]
            android:orderInCategory="integer"
            android:checkableBehavior=["none" | "all" | "single"]
@@ -84,8 +84,8 @@ child of a <menu> element.
       
attributes:

       

         
android:id

-        
Resource name. A unique resource name. The value takes the form:
-"@+id/name".

+        
Resource ID. A unique resource ID. To create a new resource ID for this item, use the form:
+"@+id/name". The plus symbol indicates that this should be created as a new ID.

         
android:menuCategory

           
Keyword. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*}
           constants, which define the group's priority. Valid values:
@@ -124,8 +124,8 @@ on the data that is currently displayed.
       
attributes:

       

         
android:id

-        
Resource name. A unique resource name. The value takes the form:
-"@+id/name".

+        
Resource ID. A unique resource ID. To create a new resource ID for this item, use the form:
+"@+id/name". The plus symbol indicates that this should be created as a new ID.

         
android:menuCategory

           
Keyword. Value corresponding to {@link android.view.Menu} {@code CATEGORY_*}
           constants, which define the item's priority. Valid values:
diff --git a/docs/html/guide/topics/resources/more-resources.jd b/docs/html/guide/topics/resources/more-resources.jd
index 0e2b30bed807..22abbb2c51ed 100644
--- a/docs/html/guide/topics/resources/more-resources.jd
+++ b/docs/html/guide/topics/resources/more-resources.jd
@@ -12,6 +12,9 @@ parent.link=available-resources.html
     
XML resource that carries a color value (a hexadecimal color).

   
Dimension

     
XML resource that carries a dimension value (with a unit of measure).

+  
ID

+    
XML resource that provides a unique identifier for application resources and
+components.

   
Integer

     
XML resource that carries an integer value.

   
Integer Array

@@ -111,8 +114,8 @@ boolean screenIsSmall = res.{@link android.content.res.Resources#getBoolean(int)
 
Color

 
 
A color value defined in XML.
-The color is specified with an RGB value and alpha channel. A color resource can be used
-any place that expects a hexadecimal color value.

+The color is specified with an RGB value and alpha channel. You can use color resource
+any place that accepts a hexadecimal color value.

 
 
The value always begins with a pound (#) character and then followed by the
 Alpha-Red-Green-Blue information in one of the following formats:

@@ -318,6 +321,118 @@ float fontSize = res.{@link android.content.res.Resources#getDimension(int) getD
 
 
 
+
ID

+
+
A unique resource ID defined in XML. Using the name you provide in the {@code <item>}
+element, the Android developer tools create a unique integer in your project's {@code
+R.java} class, which you can use as an
+identifier for an application resources (for example, a {@link android.view.View} in your UI layout)
+or a unique integer for use in your application code (for example, as an ID for a dialog or a
+result code).

+
+
Note: An ID is a simple resource that is referenced
+using the value provided in the {@code name} attribute (not the name of the XML file). As
+such, you can combine ID resources with other simple resources in the one XML file,
+under one {@code <resources>} element. Also, remember that an ID resources does not reference
+an actual resource item; it is simply a unique ID that you can attach to other resources or use
+as a unique integer in your application.

+
+

+
+
file location:

+
res/values/filename.xml

+The filename is arbitrary.

+
+
resource reference:

+

+In Java: R.id.name

+In XML: @[package:]id/name
+

+
+
syntax:

+

+
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <item
+        type="id"
+        name="id_name" />
+</resources>
+

+

+
+
elements:

+

+

+
+  
<resources>

+    
Required. This must be the root node.
+      
No attributes.

+    

+  
<integer>

+    
Defines a unique ID. Takes no value, only attributes.
+      
attributes:

+      

+        
type

+        
Must be "id".

+        
name

+        
String. A unique name for the ID.

+      

+    

+
+

+
 
+
+
example:

+

+  
XML file saved at res/values/ids.xml:

+
+<?xml version="1.0" encoding="utf-8"?>
+<resources>
+    <item type="id" name="button_ok" />
+    <item type="id" name="dialog_exit" />
+</resources>
+

+
+    
Then, this layout snippet uses the "button_ok" ID for a Button widget:

+
+<Button android:id="@id/button_ok"
+    style="@style/button_style" />
+

+
+    
Notice that the {@code android:id} value does not include the plus sign in the ID reference,
+because the ID already exists, as defined in the {@code ids.xml} example above. (When you specify an
+ID to an XML resource using the plus sign—in the format {@code
+android:id="@+id/name"}—it means that the "name" ID does not exist and should be created.)

+
+  
As another example, the following code snippet uses the "dialog_exit" ID as a unique identifier
+for a dialog:

+
+{@link android.app.Activity#showDialog(int) showDialog}(R.id.dialog_exit);
+

+  
In the same application, the "dialog_exit" ID is compared when creating a dialog:

+
+protected Dialog {@link android.app.Activity#onCreateDialog(int)}(int id) {
+    Dialog dialog;
+    switch(id) {
+    case R.id.dialog_exit:
+        ...
+        break;
+    default:
+        dialog = null;
+    }
+    return dialog;
+}
+

+
 
+
+
+

+
+
+
+
+
 
Integer

 
 
An integer defined in XML.

@@ -347,7 +462,7 @@ In XML: @[package:]integer/integer_name
 <resources>
     <integer
         name="integer_name"
-        >integer</dimen>
+        >integer</integer>
 </resources>
@@ -379,8 +494,8 @@ In XML: @[package:]integer/integer_name 
 <?xml version="1.0" encoding="utf-8"?>
 <resources>
-    <integer name="max_speed">75</dimen>
-    <integer name="min_speed">5</dimen>
+    <integer name="max_speed">75</integer>
+    <integer name="min_speed">5</integer>
 </resources>

This application code retrieves an integer:

diff --git a/docs/html/images/resources/clip.png b/docs/html/images/resources/clip.png new file mode 100644 index 000000000000..9196b3f53913 Binary files /dev/null and b/docs/html/images/resources/clip.png differ diff --git a/docs/html/images/resources/layers.png b/docs/html/images/resources/layers.png new file mode 100644 index 000000000000..f7e69295759a Binary files /dev/null and b/docs/html/images/resources/layers.png differ diff --git a/graphics/java/android/graphics/drawable/AnimationDrawable.java b/graphics/java/android/graphics/drawable/AnimationDrawable.java index fdc4c92e178d..e275ba8941dd 100644 --- a/graphics/java/android/graphics/drawable/AnimationDrawable.java +++ b/graphics/java/android/graphics/drawable/AnimationDrawable.java @@ -64,6 +64,8 @@ import android.util.AttributeSet; * // Start the animation (looped playback by default). * frameAnimation.start() * + *

For more information, see the guide to Animation Resources.

* * @attr ref android.R.styleable#AnimationDrawable_visible * @attr ref android.R.styleable#AnimationDrawable_variablePadding diff --git a/graphics/java/android/graphics/drawable/BitmapDrawable.java b/graphics/java/android/graphics/drawable/BitmapDrawable.java index 29e14d2b2ebe..32111e83cfc1 100644 --- a/graphics/java/android/graphics/drawable/BitmapDrawable.java +++ b/graphics/java/android/graphics/drawable/BitmapDrawable.java @@ -40,7 +40,9 @@ import java.io.IOException; * A Drawable that wraps a bitmap and can be tiled, stretched, or aligned. You can create a * BitmapDrawable from a file path, an input stream, through XML inflation, or from * a {@link android.graphics.Bitmap} object. - *

It can be defined in an XML file with the <bitmap> element.

+ *

It can be defined in an XML file with the <bitmap> element. For more + * information, see the guide to Drawable Resources.

*

* Also see the {@link android.graphics.Bitmap} class, which handles the management and * transformation of raw bitmap graphics, and should be used when drawing to a diff --git a/graphics/java/android/graphics/drawable/ClipDrawable.java b/graphics/java/android/graphics/drawable/ClipDrawable.java index c387a9ba7d5f..a772871554ba 100644 --- a/graphics/java/android/graphics/drawable/ClipDrawable.java +++ b/graphics/java/android/graphics/drawable/ClipDrawable.java @@ -32,9 +32,14 @@ import java.io.IOException; * level value. You can control how much the child Drawable gets clipped in width * and height based on the level, as well as a gravity to control where it is * placed in its overall container. Most often used to implement things like - * progress bars. + * progress bars, by increasing the drawable's level with {@link + * android.graphics.drawable.Drawable#setLevel(int) setLevel()}. + *

Note: The drawable is clipped completely and not visible when + * the level is 0 and fully revealed when the level is 10,000.

* - *

It can be defined in an XML file with the <clip> element.

+ *

It can be defined in an XML file with the <clip> element. For more + * information, see the guide to Drawable Resources.

* * @attr ref android.R.styleable#ClipDrawable_clipOrientation * @attr ref android.R.styleable#ClipDrawable_gravity diff --git a/graphics/java/android/graphics/drawable/Drawable.java b/graphics/java/android/graphics/drawable/Drawable.java index 6a7b2d1ae922..31253215f908 100644 --- a/graphics/java/android/graphics/drawable/Drawable.java +++ b/graphics/java/android/graphics/drawable/Drawable.java @@ -93,8 +93,8 @@ import android.util.TypedValue; * whose overall size is modified based on the current level. * *

For information and examples of creating drawable resources (XML or bitmap files that - * can be loaded in code), see Resources - * and Internationalization. + * can be loaded in code), see Drawable Resources. */ public abstract class Drawable { private static final Rect ZERO_BOUNDS_RECT = new Rect(); @@ -709,8 +709,7 @@ public abstract class Drawable { /** * Create a drawable from an XML document. For more information on how to * create resources in XML, see - * Resources and - * Internationalization. + * Drawable Resources. */ public static Drawable createFromXml(Resources r, XmlPullParser parser) throws XmlPullParserException, IOException { diff --git a/graphics/java/android/graphics/drawable/GradientDrawable.java b/graphics/java/android/graphics/drawable/GradientDrawable.java index 63d14463cdc7..33ecbea910ed 100644 --- a/graphics/java/android/graphics/drawable/GradientDrawable.java +++ b/graphics/java/android/graphics/drawable/GradientDrawable.java @@ -42,7 +42,9 @@ import java.io.IOException; /** * A Drawable with a color gradient for buttons, backgrounds, etc. * - *

It can be defined in an XML file with the <shape> element.

+ *

It can be defined in an XML file with the <shape> element. For more + * information, see the guide to Drawable Resources.

* * @attr ref android.R.styleable#GradientDrawable_visible * @attr ref android.R.styleable#GradientDrawable_shape diff --git a/graphics/java/android/graphics/drawable/InsetDrawable.java b/graphics/java/android/graphics/drawable/InsetDrawable.java index 4fa9d44f1332..a9c983e1548d 100644 --- a/graphics/java/android/graphics/drawable/InsetDrawable.java +++ b/graphics/java/android/graphics/drawable/InsetDrawable.java @@ -32,7 +32,9 @@ import java.io.IOException; * This is used when a View needs a background that is smaller than * the View's actual bounds. * - *

It can be defined in an XML file with the <inset> element.

+ *

It can be defined in an XML file with the <inset> element. For more + * information, see the guide to Drawable Resources.

* * @attr ref android.R.styleable#InsetDrawable_visible * @attr ref android.R.styleable#InsetDrawable_drawable diff --git a/graphics/java/android/graphics/drawable/LayerDrawable.java b/graphics/java/android/graphics/drawable/LayerDrawable.java index 389fd4075b22..8047dd4cb08c 100644 --- a/graphics/java/android/graphics/drawable/LayerDrawable.java +++ b/graphics/java/android/graphics/drawable/LayerDrawable.java @@ -32,8 +32,9 @@ import java.io.IOException; * order, so the element with the largest index will be drawn on top. *

* It can be defined in an XML file with the <layer-list> element. - * Each Drawable in the layer is defined in a nested <item>. - *

+ * Each Drawable in the layer is defined in a nested <item>. For more + * information, see the guide to Drawable Resources.

* * @attr ref android.R.styleable#LayerDrawableItem_left * @attr ref android.R.styleable#LayerDrawableItem_top diff --git a/graphics/java/android/graphics/drawable/LevelListDrawable.java b/graphics/java/android/graphics/drawable/LevelListDrawable.java index ae8f224c80df..21be9838ee6e 100644 --- a/graphics/java/android/graphics/drawable/LevelListDrawable.java +++ b/graphics/java/android/graphics/drawable/LevelListDrawable.java @@ -47,7 +47,10 @@ import android.util.AttributeSet; *

With this XML saved into the res/drawable/ folder of the project, it can be referenced as * the drawable for an {@link android.widget.ImageView}. The default image is the first in the list. * It can then be changed to one of the other levels with - * {@link android.widget.ImageView#setImageLevel(int)}.

+ * {@link android.widget.ImageView#setImageLevel(int)}. For more + * information, see the guide to Drawable Resources.

+ * * @attr ref android.R.styleable#LevelListDrawableItem_minLevel * @attr ref android.R.styleable#LevelListDrawableItem_maxLevel * @attr ref android.R.styleable#LevelListDrawableItem_drawable diff --git a/graphics/java/android/graphics/drawable/RotateDrawable.java b/graphics/java/android/graphics/drawable/RotateDrawable.java index 2083e051bc03..9c47dabaefc1 100644 --- a/graphics/java/android/graphics/drawable/RotateDrawable.java +++ b/graphics/java/android/graphics/drawable/RotateDrawable.java @@ -35,7 +35,9 @@ import java.io.IOException; * value. The start and end angles of rotation can be controlled to map any * circular arc to the level values range.

* - *

It can be defined in an XML file with the <rotate> element.

+ *

It can be defined in an XML file with the <rotate> element. For more + * information, see the guide to Animation Resources.

* * @attr ref android.R.styleable#RotateDrawable_visible * @attr ref android.R.styleable#RotateDrawable_fromDegrees diff --git a/graphics/java/android/graphics/drawable/ScaleDrawable.java b/graphics/java/android/graphics/drawable/ScaleDrawable.java index 275e36f4730f..b623d8002590 100644 --- a/graphics/java/android/graphics/drawable/ScaleDrawable.java +++ b/graphics/java/android/graphics/drawable/ScaleDrawable.java @@ -34,7 +34,9 @@ import java.io.IOException; * placed in its overall container. Most often used to implement things like * progress bars. * - *

It can be defined in an XML file with the <scale> element.

+ *

It can be defined in an XML file with the <scale> element. For more + * information, see the guide to Drawable Resources.

* * @attr ref android.R.styleable#ScaleDrawable_scaleWidth * @attr ref android.R.styleable#ScaleDrawable_scaleHeight diff --git a/graphics/java/android/graphics/drawable/ShapeDrawable.java b/graphics/java/android/graphics/drawable/ShapeDrawable.java index c699a82f0ccd..be1892e1839b 100644 --- a/graphics/java/android/graphics/drawable/ShapeDrawable.java +++ b/graphics/java/android/graphics/drawable/ShapeDrawable.java @@ -34,6 +34,10 @@ import java.io.IOException; * the ShapeDrawable will default to a * {@link android.graphics.drawable.shapes.RectShape}. * + *

It can be defined in an XML file with the <shape> element. For more + * information, see the guide to Drawable Resources.

+ * * @attr ref android.R.styleable#ShapeDrawablePadding_left * @attr ref android.R.styleable#ShapeDrawablePadding_top * @attr ref android.R.styleable#ShapeDrawablePadding_right diff --git a/graphics/java/android/graphics/drawable/StateListDrawable.java b/graphics/java/android/graphics/drawable/StateListDrawable.java index b94df84fc42f..239be409ffc1 100644 --- a/graphics/java/android/graphics/drawable/StateListDrawable.java +++ b/graphics/java/android/graphics/drawable/StateListDrawable.java @@ -31,7 +31,9 @@ import android.util.StateSet; * ID value. *

*

It can be defined in an XML file with the <selector> element. - * Each state Drawable is defined in a nested <item> element.

+ * Each state Drawable is defined in a nested <item> element. For more + * information, see the guide to Drawable Resources.

* * @attr ref android.R.styleable#StateListDrawable_visible * @attr ref android.R.styleable#StateListDrawable_variablePadding diff --git a/graphics/java/android/graphics/drawable/TransitionDrawable.java b/graphics/java/android/graphics/drawable/TransitionDrawable.java index 97b45d8edae9..4470356adf36 100644 --- a/graphics/java/android/graphics/drawable/TransitionDrawable.java +++ b/graphics/java/android/graphics/drawable/TransitionDrawable.java @@ -26,8 +26,10 @@ import android.os.SystemClock; * display just the first layer, call {@link #resetTransition()}. *

* It can be defined in an XML file with the <transition> element. - * Each Drawable in the transition is defined in a nested <item>. - *

+ * Each Drawable in the transition is defined in a nested <item>. For more + * information, see the guide to Drawable Resources.

+ * * @attr ref android.R.styleable#LayerDrawableItem_left * @attr ref android.R.styleable#LayerDrawableItem_top * @attr ref android.R.styleable#LayerDrawableItem_right @@ -212,7 +214,7 @@ public class TransitionDrawable extends LayerDrawable implements Drawable.Callba * Enables or disables the cross fade of the drawables. When cross fade * is disabled, the first drawable is always drawn opaque. With cross * fade enabled, the first drawable is drawn with the opposite alpha of - * the second drawable. + * the second drawable. Cross fade is disabled by default. * * @param enabled True to enable cross fading, false otherwise. */ -- cgit v1.2.3-59-g8ed1b