Android APIs
public class

TypedArray

extends Object
java.lang.Object
   ↳ android.content.res.TypedArray

Class Overview

Container for an array of values that were retrieved with obtainStyledAttributes(AttributeSet, int[], int, int) or obtainAttributes(AttributeSet, int[]). Be sure to call recycle() when done with them. The indices used to retrieve values from this structure correspond to the positions of the attributes given to obtainStyledAttributes.

Summary

Public Methods
boolean getBoolean(int index, boolean defValue)
Retrieve the boolean value for the attribute at index.
int getChangingConfigurations()
Return a mask of the configuration parameters for which the values in this typed array may change.
int getColor(int index, int defValue)
Retrieve the color value for the attribute at index.
ColorStateList getColorStateList(int index)
Retrieve the ColorStateList for the attribute at index.
float getDimension(int index, float defValue)
Retrieve a dimensional unit attribute at index.
int getDimensionPixelOffset(int index, int defValue)
Retrieve a dimensional unit attribute at index for use as an offset in raw pixels.
int getDimensionPixelSize(int index, int defValue)
Retrieve a dimensional unit attribute at index for use as a size in raw pixels.
Drawable getDrawable(int index)
Retrieve the Drawable for the attribute at index.
float getFloat(int index, float defValue)
Retrieve the float value for the attribute at index.
float getFraction(int index, int base, int pbase, float defValue)
Retrieves a fractional unit attribute at index.
int getIndex(int at)
Returns an index in the array that has data.
int getIndexCount()
Return the number of indices in the array that actually have data.
int getInt(int index, int defValue)
Retrieve the integer value for the attribute at index.
int getInteger(int index, int defValue)
Retrieve the integer value for the attribute at index.
int getLayoutDimension(int index, String name)
Special version of getDimensionPixelSize(int, int) for retrieving ViewGroup's layout_width and layout_height attributes.
int getLayoutDimension(int index, int defValue)
Special version of getDimensionPixelSize(int, int) for retrieving ViewGroup's layout_width and layout_height attributes.
String getNonResourceString(int index)
Retrieves the string value for the attribute at index, but only if that string comes from an immediate value in an XML file.
String getPositionDescription()
Returns a message about the parser state suitable for printing error messages.
int getResourceId(int index, int defValue)
Retrieves the resource identifier for the attribute at index.
Resources getResources()
Returns the Resources object this array was loaded from.
String getString(int index)
Retrieves the string value for the attribute at index.
CharSequence getText(int index)
Retrieves the styled string value for the attribute at index.
CharSequence[] getTextArray(int index)
Retrieve the CharSequence[] for the attribute at index.
int getType(int index)
Returns the type of attribute at the specified index.
boolean getValue(int index, TypedValue outValue)
Retrieve the raw TypedValue for the attribute at index.
boolean hasValue(int index)
Determines whether there is an attribute at index.
boolean hasValueOrEmpty(int index)
Determines whether there is an attribute at index, returning true if the attribute was explicitly set to @empty and false only if the attribute was undefined.
int length()
Returns the number of values in this array.
TypedValue peekValue(int index)
Retrieve the raw TypedValue for the attribute at index and return a temporary object holding its data.
void recycle()
Recycles the TypedArray, to be re-used by a later caller.
String toString()
Returns a string containing a concise, human-readable description of this object.
[Expand]
Inherited Methods
From class java.lang.Object

Public Methods

public boolean getBoolean (int index, boolean defValue)

Added in API level 1

Retrieve the boolean value for the attribute at index.

If the attribute is an integer value, this method will return whether it is equal to zero. If the attribute is not a boolean or integer value, this method will attempt to coerce it to an integer using decode(String) and return whether it is equal to zero.

Parameters
index Index of attribute to retrieve.
defValue Value to return if the attribute is not defined or cannot be coerced to an integer.
Returns
boolean Boolean value of the attribute, or defValue if the attribute was not defined or could not be coerced to an integer.
Throws
RuntimeException if the TypedArray has already been recycled.

public int getChangingConfigurations ()

Added in API level 21

Return a mask of the configuration parameters for which the values in this typed array may change.

Returns
int Returns a mask of the changing configuration parameters, as defined by ActivityInfo.
Throws
RuntimeException if the TypedArray has already been recycled.

See also:

public int getColor (int index, int defValue)

Added in API level 1

Retrieve the color value for the attribute at index. If the attribute references a color resource holding a complex ColorStateList, then the default color from the set is returned.

This method will throw an exception if the attribute is defined but is not an integer color or color state list.

Parameters
index Index of attribute to retrieve.
defValue Value to return if the attribute is not defined or not a resource.
Returns
int Attribute color value, or defValue if not defined.
Throws
RuntimeException if the TypedArray has already been recycled.
UnsupportedOperationException if the attribute is defined but is not an integer color or color state list.

public ColorStateList getColorStateList (int index)

Added in API level 1

Retrieve the ColorStateList for the attribute at index. The value may be either a single solid color or a reference to a color or complex ColorStateList description.

This method will return null if the attribute is not defined or is not an integer color or color state list.

Parameters
index Index of attribute to retrieve.
Returns
ColorStateList ColorStateList for the attribute, or null if not defined.
Throws
RuntimeException if the attribute if the TypedArray has already been recycled.
UnsupportedOperationException if the attribute is defined but is not an integer color or color state list.

public float getDimension (int index, float defValue)

Added in API level 1

Retrieve a dimensional unit attribute at index. Unit conversions are based on the current DisplayMetrics associated with the resources this TypedArray object came from.

This method will throw an exception if the attribute is defined but is not a dimension.

Parameters
index Index of attribute to retrieve.
defValue Value to return if the attribute is not defined or not a resource.
Returns
float Attribute dimension value multiplied by the appropriate metric, or defValue if not defined.
Throws
RuntimeException if the TypedArray has already been recycled.
UnsupportedOperationException if the attribute is defined but is not an integer.

public int getDimensionPixelOffset (int index, int defValue)

Added in API level 1

Retrieve a dimensional unit attribute at index for use as an offset in raw pixels. This is the same as getDimension(int, float), except the returned value is converted to integer pixels for you. An offset conversion involves simply truncating the base value to an integer.

This method will throw an exception if the attribute is defined but is not a dimension.

Parameters
index Index of attribute to retrieve.
defValue Value to return if the attribute is not defined or not a resource.
Returns
int Attribute dimension value multiplied by the appropriate metric and truncated to integer pixels, or defValue if not defined.
Throws
RuntimeException if the TypedArray has already been recycled.
UnsupportedOperationException if the attribute is defined but is not an integer.

public int getDimensionPixelSize (int index, int defValue)

Added in API level 1

Retrieve a dimensional unit attribute at index for use as a size in raw pixels. This is the same as getDimension(int, float), except the returned value is converted to integer pixels for use as a size. A size conversion involves rounding the base value, and ensuring that a non-zero base value is at least one pixel in size.

This method will throw an exception if the attribute is defined but is not a dimension.

Parameters
index Index of attribute to retrieve.
defValue Value to return if the attribute is not defined or not a resource.
Returns
int Attribute dimension value multiplied by the appropriate metric and truncated to integer pixels, or defValue if not defined.
Throws
RuntimeException if the TypedArray has already been recycled.
UnsupportedOperationException if the attribute is defined but is not a dimension.

public Drawable getDrawable (int index)

Added in API level 1

Retrieve the Drawable for the attribute at index.

This method will throw an exception if the attribute is defined but is not a color or drawable resource.

Parameters
index Index of attribute to retrieve.
Returns
Drawable Drawable for the attribute, or null if not defined.
Throws
RuntimeException if the TypedArray has already been recycled.
UnsupportedOperationException if the attribute is defined but is not a color or drawable resource.

public float getFloat (int index, float defValue)

Added in API level 1

Retrieve the float value for the attribute at index.

If the attribute is not a float or an integer, this method will attempt to coerce it to a float using parseFloat(String).

Parameters
index Index of attribute to retrieve.
Returns
float Attribute float value, or defValue if the attribute was not defined or could not be coerced to a float.
Throws
RuntimeException if the TypedArray has already been recycled.

public float getFraction (int index, int base, int pbase, float defValue)

Added in API level 1

Retrieves a fractional unit attribute at index.

Parameters
index Index of attribute to retrieve.
base The base value of this fraction. In other words, a standard fraction is multiplied by this value.
pbase The parent base value of this fraction. In other words, a parent fraction (nn%p) is multiplied by this value.
defValue Value to return if the attribute is not defined or not a resource.
Returns
float Attribute fractional value multiplied by the appropriate base value, or defValue if not defined.
Throws
RuntimeException if the TypedArray has already been recycled.
UnsupportedOperationException if the attribute is defined but is not a fraction.

public int getIndex (int at)

Added in API level 1

Returns an index in the array that has data.

Parameters
at The index you would like to returned, ranging from 0 to getIndexCount().
Returns
int The index at the given offset, which can be used with getValue(int, TypedValue) and related APIs.
Throws
RuntimeException if the TypedArray has already been recycled.

public int getIndexCount ()

Added in API level 1

Return the number of indices in the array that actually have data.

Returns
int
Throws
RuntimeException if the TypedArray has already been recycled.

public int getInt (int index, int defValue)

Added in API level 1

Retrieve the integer value for the attribute at index.

If the attribute is not an integer, this method will attempt to coerce it to an integer using decode(String).

Parameters
index Index of attribute to retrieve.
defValue Value to return if the attribute is not defined or cannot be coerced to an integer.
Returns
int Integer value of the attribute, or defValue if the attribute was not defined or could not be coerced to an integer.
Throws
RuntimeException if the TypedArray has already been recycled.

public int getInteger (int index, int defValue)

Added in API level 1

Retrieve the integer value for the attribute at index.

Unlike getInt(int, int), this method will throw an exception if the attribute is defined but is not an integer.

Parameters
index Index of attribute to retrieve.
defValue Value to return if the attribute is not defined or not a resource.
Returns
int Attribute integer value, or defValue if not defined.
Throws
RuntimeException if the TypedArray has already been recycled.
UnsupportedOperationException if the attribute is defined but is not an integer.

public int getLayoutDimension (int index, String name)

Added in API level 1

Special version of getDimensionPixelSize(int, int) for retrieving ViewGroup's layout_width and layout_height attributes. This is only here for performance reasons; applications should use getDimensionPixelSize(int, int).

This method will throw an exception if the attribute is defined but is not a dimension or integer (enum).

Parameters
index Index of the attribute to retrieve.
name Textual name of attribute for error reporting.
Returns
int Attribute dimension value multiplied by the appropriate metric and truncated to integer pixels.
Throws
RuntimeException if the TypedArray has already been recycled.
UnsupportedOperationException if the attribute is defined but is not a dimension or integer (enum).

public int getLayoutDimension (int index, int defValue)

Added in API level 3

Special version of getDimensionPixelSize(int, int) for retrieving ViewGroup's layout_width and layout_height attributes. This is only here for performance reasons; applications should use getDimensionPixelSize(int, int).

Parameters
index Index of the attribute to retrieve.
defValue The default value to return if this attribute is not default or contains the wrong type of data.
Returns
int Attribute dimension value multiplied by the appropriate metric and truncated to integer pixels.
Throws
RuntimeException if the TypedArray has already been recycled.

public String getNonResourceString (int index)

Added in API level 1

Retrieves the string value for the attribute at index, but only if that string comes from an immediate value in an XML file. That is, this does not allow references to string resources, string attributes, or conversions from other types. As such, this method will only return strings for TypedArray objects that come from attributes in an XML file.

Parameters
index Index of attribute to retrieve.
Returns
String String holding string data. Any styling information is removed. Returns null if the attribute is not defined or is not an immediate string value.
Throws
RuntimeException if the TypedArray has already been recycled.

public String getPositionDescription ()

Added in API level 1

Returns a message about the parser state suitable for printing error messages.

Returns
String Human-readable description of current parser state.
Throws
RuntimeException if the TypedArray has already been recycled.

public int getResourceId (int index, int defValue)

Added in API level 1

Retrieves the resource identifier for the attribute at index. Note that attribute resource as resolved when the overall TypedArray object is retrieved. As a result, this function will return the resource identifier of the final resource value that was found, not necessarily the original resource that was specified by the attribute.

Parameters
index Index of attribute to retrieve.
defValue Value to return if the attribute is not defined or not a resource.
Returns
int Attribute resource identifier, or defValue if not defined.
Throws
RuntimeException if the TypedArray has already been recycled.

public Resources getResources ()

Added in API level 1

Returns the Resources object this array was loaded from.

Returns
Resources
Throws
RuntimeException if the TypedArray has already been recycled.

public String getString (int index)

Added in API level 1

Retrieves the string value for the attribute at index.

If the attribute is not a string, this method will attempt to coerce it to a string.

Parameters
index Index of attribute to retrieve.
Returns
String String holding string data. Any styling information is removed. Returns null if the attribute is not defined or could not be coerced to a string.
Throws
RuntimeException if the TypedArray has already been recycled.

public CharSequence getText (int index)

Added in API level 1

Retrieves the styled string value for the attribute at index.

If the attribute is not a string, this method will attempt to coerce it to a string.

Parameters
index Index of attribute to retrieve.
Returns
CharSequence CharSequence holding string data. May be styled. Returns null if the attribute is not defined or could not be coerced to a string.
Throws
RuntimeException if the TypedArray has already been recycled.

public CharSequence[] getTextArray (int index)

Added in API level 1

Retrieve the CharSequence[] for the attribute at index. This gets the resource ID of the selected attribute, and uses Resources.getTextArray of the owning Resources object to retrieve its String[].

This method will throw an exception if the attribute is defined but is not a text array resource.

Parameters
index Index of attribute to retrieve.
Returns
CharSequence[] CharSequence[] for the attribute, or null if not defined.
Throws
RuntimeException if the TypedArray has already been recycled.

public int getType (int index)

Added in API level 21

Returns the type of attribute at the specified index.

Parameters
index Index of attribute whose type to retrieve.
Returns
int Attribute type.
Throws
RuntimeException if the TypedArray has already been recycled.

public boolean getValue (int index, TypedValue outValue)

Added in API level 1

Retrieve the raw TypedValue for the attribute at index.

Parameters
index Index of attribute to retrieve.
outValue TypedValue object in which to place the attribute's data.
Returns
boolean true if the value was retrieved, false otherwise.
Throws
RuntimeException if the TypedArray has already been recycled.

public boolean hasValue (int index)

Added in API level 1

Determines whether there is an attribute at index.

Note: If the attribute was set to @empty or @undefined, this method returns false.

Parameters
index Index of attribute to retrieve.
Returns
boolean True if the attribute has a value, false otherwise.
Throws
RuntimeException if the TypedArray has already been recycled.

public boolean hasValueOrEmpty (int index)

Added in API level 22

Determines whether there is an attribute at index, returning true if the attribute was explicitly set to @empty and false only if the attribute was undefined.

Parameters
index Index of attribute to retrieve.
Returns
boolean True if the attribute has a value or is empty, false otherwise.
Throws
RuntimeException if the TypedArray has already been recycled.

public int length ()

Added in API level 1

Returns the number of values in this array.

Returns
int
Throws
RuntimeException if the TypedArray has already been recycled.

public TypedValue peekValue (int index)

Added in API level 1

Retrieve the raw TypedValue for the attribute at index and return a temporary object holding its data. This object is only valid until the next call on to TypedArray.

Parameters
index Index of attribute to retrieve.
Returns
TypedValue Returns a TypedValue object if the attribute is defined, containing its data; otherwise returns null. (You will not receive a TypedValue whose type is TYPE_NULL.)
Throws
RuntimeException if the TypedArray has already been recycled.

public void recycle ()

Added in API level 1

Recycles the TypedArray, to be re-used by a later caller. After calling this function you must not ever touch the typed array again.

Throws
RuntimeException if the TypedArray has already been recycled.

public String toString ()

Added in API level 1

Returns a string containing a concise, human-readable description of this object. Subclasses are encouraged to override this method and provide an implementation that takes into account the object's type and data. The default implementation is equivalent to the following expression:

   getClass().getName() + '@' + Integer.toHexString(hashCode())

See Writing a useful toString method if you intend implementing your own toString method.

Returns
String a printable representation of this object.