android.content.res

Class Resources

java.lang.Object

android.content.res.Resources

public class Resources
extends Object

Class for accessing an application's resources. This sits on top of the asset manager of the application (accessible through getAssets()) and provides a high-level API for getting typed data from the assets.

The Android resource system keeps track of all non-code assets associated with an application. You can use this class to access your application's resources. You can generally acquire the Resources instance associated with your application with getResources().

The Android SDK tools compile your application's resources into the application binary at build time. To use a resource, you must install it correctly in the source tree (inside your project's res/ directory) and build your application. As part of the build process, the SDK tools generate symbols for each resource, which you can use in your application code to access the resources.

Using application resources makes it easy to update various characteristics of your application without modifying code, and—by providing sets of alternative resources—enables you to optimize your application for a variety of device configurations (such as for different languages and screen sizes). This is an important aspect of developing Android applications that are compatible on different types of devices.

For more information about using resources, see the documentation about Application Resources.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	Resources.NotFoundException This exception is thrown by the resource APIs when a requested resource can not be found.

Constructor Summary

Constructors

Constructor and Description
Resources(AssetManager assets, DisplayMetrics metrics, Configuration config) Create a new Resources object on top of an existing set of assets in an AssetManager.

Method Summary

Modifier and Type	Method and Description
protected void	finalize() Invoked when the garbage collector has detected that this instance is no longer reachable.
AssetManager	getAssets() Retrieve underlying AssetManager storage for these resources.
Configuration	getConfiguration() Return the current configuration that is in effect for this resource object.
int	getIdentifier(String name, String defType, String defPackage) Return a resource identifier for the given resource name.
String	getResourceEntryName(int resid) Return the entry name for a given resource identifier.
void	getValue(int id, TypedValue outValue, boolean resolveRefs) Return the raw data associated with a particular resource ID.
InputStream	openRawResource(int id) Open a data stream for reading a raw resource.
InputStream	openRawResource(int id, TypedValue value) Open a data stream for reading a raw resource.
void	updateConfiguration(Configuration config, DisplayMetrics metrics) Store the newly updated configuration.
static void	updateSystemConfiguration(Configuration config, DisplayMetrics metrics) Update the system resources configuration if they have previously been initialized.

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Resources

public Resources(AssetManager assets,
                 DisplayMetrics metrics,
                 Configuration config)

Create a new Resources object on top of an existing set of assets in an AssetManager.

Parameters:

assets - Previously created AssetManager.

metrics - Current display metrics to consider when selecting/computing resource values.

config - Desired device configuration to consider when selecting/computing resource values (optional).

Method Detail

openRawResource

public InputStream openRawResource(@RawRes
                                   int id)
                            throws Resources.NotFoundException

Open a data stream for reading a raw resource. This can only be used with resources whose value is the name of an asset files -- that is, it can be used to open drawable, sound, and raw resources; it will fail on string and color resources.

Parameters:

id - The resource identifier to open, as generated by the appt tool.

Returns:

InputStream Access to the resource data.

Throws:

Resources.NotFoundException - Throws NotFoundException if the given ID does not exist.

getIdentifier

public int getIdentifier(String name,
                         String defType,
                         String defPackage)

Return a resource identifier for the given resource name. A fully qualified resource name is of the form "package:type/entry". The first two components (package and type) are optional if defType and defPackage, respectively, are specified here.

Note: use of this function is discouraged. It is much more efficient to retrieve resources by identifier than by name.

Parameters:

name - The name of the desired resource.

defType - Optional default resource type to find, if "type/" is not included in the name. Can be null to require an explicit type.

defPackage - Optional default package to find, if "package:" is not included in the name. Can be null to require an explicit package.

Returns:

int The associated resource identifier. Returns 0 if no such resource was found. (0 is not a valid resource ID.)

getValue

public void getValue(@AnyRes
                     int id,
                     TypedValue outValue,
                     boolean resolveRefs)
              throws Resources.NotFoundException

Return the raw data associated with a particular resource ID.

Parameters:

id - The desired resource identifier, as generated by the aapt tool. This integer encodes the package, type, and resource entry. The value 0 is an invalid identifier.

outValue - Object in which to place the resource data.

resolveRefs - If true, a resource that is a reference to another resource will be followed so that you receive the actual final resource data. If false, the TypedValue will be filled in with the reference itself.

Throws:

Resources.NotFoundException - Throws NotFoundException if the given ID does not exist.

openRawResource

public InputStream openRawResource(@RawRes
                                   int id,
                                   TypedValue value)
                            throws Resources.NotFoundException

Open a data stream for reading a raw resource. This can only be used with resources whose value is the name of an asset file -- that is, it can be used to open drawable, sound, and raw resources; it will fail on string and color resources.

Parameters:

id - The resource identifier to open, as generated by the appt tool.

value - The TypedValue object to hold the resource information.

Returns:

InputStream Access to the resource data.

Throws:

Resources.NotFoundException - Throws NotFoundException if the given ID does not exist.

finalize

protected void finalize()
                 throws Throwable

Description copied from class: Object

Invoked when the garbage collector has detected that this instance is no longer reachable. The default implementation does nothing, but this method can be overridden to free resources.

Note that objects that override finalize are significantly more expensive than objects that don't. Finalizers may be run a long time after the object is no longer reachable, depending on memory pressure, so it's a bad idea to rely on them for cleanup. Note also that finalizers are run on a single VM-wide finalizer thread, so doing blocking work in a finalizer is a bad idea. A finalizer is usually only necessary for a class that has a native peer and needs to call a native method to destroy that peer. Even then, it's better to provide an explicit close method (and implement Closeable), and insist that callers manually dispose of instances. This works well for something like files, but less well for something like a BigInteger where typical calling code would have to deal with lots of temporaries. Unfortunately, code that creates lots of temporaries is the worst kind of code from the point of view of the single finalizer thread.

If you must use finalizers, consider at least providing your own ReferenceQueue and having your own thread process that queue.

Unlike constructors, finalizers are not automatically chained. You are responsible for calling super.finalize() yourself.

Uncaught exceptions thrown by finalizers are ignored and do not terminate the finalizer thread. See Effective Java Item 7, "Avoid finalizers" for more.

Overrides:

finalize in class Object

Throws:

Throwable

updateConfiguration

public void updateConfiguration(Configuration config,
                                DisplayMetrics metrics)

Store the newly updated configuration.

updateSystemConfiguration

public static void updateSystemConfiguration(Configuration config,
                                             DisplayMetrics metrics)

Update the system resources configuration if they have previously been initialized.

getConfiguration

public Configuration getConfiguration()

Return the current configuration that is in effect for this resource object. The returned object should be treated as read-only.

Returns:

The resource's current configuration.

getResourceEntryName

public String getResourceEntryName(@AnyRes
                                   int resid)
                            throws Resources.NotFoundException

Return the entry name for a given resource identifier.

Parameters:

resid - The resource identifier whose entry name is to be retrieved.

Returns:

A string holding the entry name of the resource.

Throws:

Resources.NotFoundException - Throws NotFoundException if the given ID does not exist.

See Also:

#getResourceName

getAssets

public final AssetManager getAssets()

Retrieve underlying AssetManager storage for these resources.