Android/frameworks_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

am 0f2e2b8b: Merge "Update package descriptions with editorial revisions. Notably, this removes exessive info about resources from the content package, because it\'s not a good location and the info is avilable in the dev guide, but also added some of the info to the R

Browse Source 
* commit '0f2e2b8b82c7b589bcc603ce57f8ff3d1c947784':
  Update package descriptions with editorial revisions. Notably, this removes exessive info about resources from the content package, because it's not a good location and the info is avilable in the dev guide, but also added some of the info to the Resources class description.
This commit is contained in:
Scott Main
2011-01-26 17:09:21 -08:00
committed by Android Git Automerger
parent c296b57389 0f2e2b8b82
commit d2b87091cc
15 changed files with 164 additions and 757 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
core/java/android/app/admin/package.html Normal file
View File

@@ -0,0 +1,12 @@
<HTML>
<BODY>
<p>Provides device administration features at the system level, allowing you to create
security-aware applications that are useful in enterprise settings, in which IT professionals
require rich control over employee devices.</p>
<p>For more information, see the <a
href="{@docRoot}guide/topics/admin/device-admin.html">Device Administration</a> developer guide.</p>
{@more}
</BODY>
</HTML>

5
core/java/android/app/backup/package.html
View File

@@ -2,9 +2,10 @@
<BODY>
<p>Contains the backup and restore functionality available to
applications. If a user wipes the data on their device or upgrades to a new Android-powered
device, all applications that have enabled backup will restore the user's previous data.</p>
device, all applications that have enabled backup can restore the user's previous data when the
application is reinstalled.</p>
<p>For a detailed guide to using the backup APIs, see the <a
<p>For more information, see the <a
href="{@docRoot}guide/topics/data/backup.html">Data Backup</a> developer guide.</p>
{@more}

89
core/java/android/app/package.html
View File

@@ -1,72 +1,43 @@
<html>
<head>
<script type="text/javascript" src="http://www.corp.google.com/style/prettify.js"></script>
<script src="http://www.corp.google.com/eng/techpubs/include/navbar.js" type="text/javascript"></script>
</head>
<body>
<p>High-level classes encapsulating the overall Android application model.
The central class is {@link android.app.Activity}, with other top-level
application components being defined by {@link android.app.Service} and,
from the {@link android.content} package, {@link android.content.BroadcastReceiver}
and {@link android.content.ContentProvider}. It also includes application
tools, such as dialogs and notifications.</p>
<p>Contains high-level classes encapsulating the overall Android application model.</p>
<p>This package builds on top of the lower-level Android packages
{@link android.widget}, {@link android.view}, {@link android.content},
{@link android.text}, {@link android.graphics}, {@link android.os}, and
{@link android.util}.</p>
<p>An Android application is defined using one or more of Android's four core application
components. Two such application components are defined in this package: {@link
android.app.Activity} and {@link android.app.Service}. The other two components are from the {@link
android.content} package: {@link android.content.BroadcastReceiver} and {@link
android.content.ContentProvider}.</p>
<p>An {@link android.app.Activity Activity} is a specific operation the
user can perform, generally corresponding
to one screen in the user interface.
It is the basic building block of an Android application.
Examples of activities are "view the
list of people," "view the details of a person," "edit information about
a person," "view an image," etc. Switching from one activity to another
generally implies adding a new entry on the navigation history; that is,
going "back" means moving to the previous activity you were doing.</p>
<p>An {@link android.app.Activity} is an application component that provides a screen with which
users can interact in order to do something, such as dial the phone, take a photo, send an email, or
view a map. An activity can start other activities, including activities that live in separate
applications.</p>
<p>A set of related activities can be grouped together as a "task". Until
a new task is explicitly specified, all activites you start are considered
to be part of the current task. While the only way to navigate between
individual activities is by going "back" in the history stack, the group
of activities in a task can be moved in relation to other tasks: for example
to the front or the back of the history stack. This mechanism can be used
to present to the user a list of things they have been doing, moving
between them without disrupting previous work.
</p>
<p>A {@link android.app.Service} is an application component that can perform
long-running operations in the background without a user interface. For example, a service
can handle network transactions, play music, or work with a content provider without the user being
aware of the work going on.</p>
<p>A complete "application" is a set of activities that allow the user to do a
cohesive group of operations -- such as working with contacts, working with a
calendar, messaging, etc. Though there can be a custom application object
associated with a set of activities, in many cases this is not needed --
each activity provides a particular path into one of the various kinds of
functionality inside of the application, serving as its on self-contained
"mini application".
</p>
<p>The {@link android.app.Fragment} class is also an important part of an application's
design&mdash;especially when designing for large screen devices, such as tablets. A fragment defines
a distinct part of an activity's behavior, including the associated UI. It has its own lifecycle
that is similar to that of the activity and can exist alongside other fragments that are embedded in
the activity. While an activity is running, you can add and remove fragments and include each
fragment in a back stack that's managed by the activity&mdash;allowing the user to navigate
backwards through the fragment states, without leaving the activity.</p>
<p>This approach allows an application to be broken into pieces, which
can be reused and replaced in a variety of ways. Consider, for example,
a "camera application." There are a number of things this application
must do, each of which is provided by a separate activity: take a picture
(creating a new image), browse through the existing images, display a
specific image, etc. If the "contacts application" then wants to let the
user associate an image with a person, it can simply launch the existing
"take a picture" or "select an image" activity that is part of the camera
application and attach the picture it gets back.
</p>
<p>This package also defines application utilities, such as dialogs, notifications, and the
action bar.</p>
<p>For information about using some the classes in this package, see the following
documents: <a href="{@docRoot}guide/topics/fundamentals/index.html">Application
Fundamentals</a> (for activities, services, and fragments), <a
href="{@docRoot}guide/topics/ui/actionbar.html">Using the Action Bar</a>, <a
href="{@docRoot}guide/topics/ui/dialogs.html">Creating Dialogs</a>, and <a
href="{@docRoot}guide/topics/ui/notifiers/index.html">Notifying the User</a>.</p>
<p>Note that there is no hard relationship between tasks the user sees and
applications the developer writes. A task can be composed of activities from
multiple applications (such as the contact application using an activity in
the camera application to get a picture for a person), and multiple active
tasks may be running for the same application (such as editing e-mail messages
to two different people). The way tasks are organized is purely a UI policy
decided by the system; for example, typically a new task is started when the
user goes to the application launcher and selects an application.
</p>
</body>
</html>

42
core/java/android/appwidget/package.html
View File

@@ -1,32 +1,32 @@
<body>
<p>Android allows applications to publish views to be embedded in other applications. These
views are called widgets, and are published by "AppWidget providers." The component that can
contain widgets is called a "AppWidget host."
</p>
<p>For more information, see the
<a href="{@docRoot}guide/topics/appwidgets/index.html">AppWidgets</a>
documentation in the Dev Guide.</p>
<p>Contains the components necessary to create "app widgets", which users can embed in other
applications (such as the home screen) to quickly access application data and services without
launching a new activity.</p>
<p>For more information, see the
<a href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a>
developer guide.</p>
{@more}
<p>The behavior of an app widget is published by an "app widget provider." An "app widget host" is
a component that can contain app widgets (such as the Home screen).</p>
<p>Any application can publish app widgets (as an app widget provider). All an application needs to
do to publish an app widget is
provide a {@link android.content.BroadcastReceiver} that receives the {@link
android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE} intent
and provide some metadata about the app widget. Android provides the
{@link android.appwidget.AppWidgetProvider} class, which extends {@link
android.content.BroadcastReceiver}, as a convenience class to define the app widget behavrio and aid
in handling the broadcasts.</p>
<h2><a name="providers"></a>AppWidget Providers</h2>
<p>Any application can publish widgets. All an application needs to do to publish a widget is
to have a {@link android.content.BroadcastReceiver} that receives the {@link
android.appwidget.AppWidgetManager#ACTION_APPWIDGET_UPDATE AppWidgetManager.ACTION_APPWIDGET_UPDATE} intent,
and provide some meta-data about the widget. Android provides the
{@link android.appwidget.AppWidgetProvider} class, which extends BroadcastReceiver, as a convenience
class to aid in handling the broadcasts.
<h2>AppWidget Hosts</h3>
<p>Widget hosts are the containers in which widgets can be placed. Most of the look and feel
<p>App widget hosts are the containers in which widgets can be placed. Most of the look and feel
details are left up to the widget hosts. For example, the home screen has one way of viewing
widgets, but the lock screen could also contain widgets, and it would have a different way of
adding, removing and otherwise managing widgets.</p>
<p>For more information on implementing your own widget host, see the
{@link android.appwidget.AppWidgetHost AppWidgetHost} class.</p>
<p>The <a href="{@docRoot}guide/topics/appwidgets/index.html">App Widgets</a>
developer guide shows you how to create an app widget provider. For information about implementing
an app widget host, see the {@link android.appwidget.AppWidgetHost} class.</p>
</body>

4
core/java/android/bluetooth/package.html
View File

@@ -3,7 +3,7 @@
<p>Provides classes that manage Bluetooth functionality, such as scanning for
devices, connecting with devices, and managing data transfer between devices.</p>
<p>For a complete guide to using the Bluetooth APIs, see the <a
<p>For more information, see the <a
href="{@docRoot}guide/topics/wireless/bluetooth.html">Bluetooth</a> developer guide.</p>
{@more}
@@ -25,6 +25,6 @@ permission.
</p>
<p class="note"><strong>Note:</strong>
Not all Android devices are guaranteed to have Bluetooth functionality.</p>
Not all Android-powered devices provide Bluetooth functionality.</p>
</BODY>
</HTML>

668
core/java/android/content/package.html
View File

@@ -1,649 +1,31 @@
<html>
<head>
<script type="text/javascript" src="http://www.corp.google.com/style/prettify.js"></script>
<script src="http://www.corp.google.com/eng/techpubs/include/navbar.js" type="text/javascript"></script>
</head>
<body>
<p>Contains classes for accessing and publishing data
on the device. It includes three main categories of APIs:
the {@link android.content.res.Resources Resources} for
retrieving resource data associated with an application;
{@link android.content.ContentProvider Content Providers} and
{@link android.content.ContentResolver ContentResolver} for managing and
publishing persistent data associated with an application; and
the {@link android.content.pm.PackageManager Package Manager}
for finding out information about the application packages installed
on the device.</p>
<p>In addition, the {@link android.content.Context Context} abstract class
is a base API for pulling these pieces together, allowing you to access
an application's resources and transfer data between applications.</p>
<p>This package builds on top of the lower-level Android packages
{@link android.database}, {@link android.text},
{@link android.graphics.drawable}, {@link android.graphics},
{@link android.os}, and {@link android.util}.</p>
<ol>
<li> <a href="#Resources">Resources</a>
<ol>
<li> <a href="#ResourcesTerminology">Terminology</a>
<li> <a href="#ResourcesQuickStart">Examples</a>
<ol>
<li> <a href="#UsingSystemResources">Using System Resources</a>
<li> <a href="#StringResources">String Resources</a>
<li> <a href="#ColorResources">Color Resources</a>
<li> <a href="#DrawableResources">Drawable Resources</a>
<li> <a href="#LayoutResources">Layout Resources</a>
<li> <a href="#ReferencesToResources">References to Resources</a>
<li> <a href="#ReferencesToThemeAttributes">References to Theme Attributes</a>
<li> <a href="#StyleResources">Style Resources</a>
<li> <a href="#StylesInLayoutResources">Styles in Layout Resources</a>
</ol>
</ol>
</ol>
<a name="Resources"></a>
<h2>Resources</h2>
<p>This topic includes a terminology list associated with resources, and a series
of examples of using resources in code. For a complete guide on creating and
using resources, see the document on <a href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources
and Internationalization</a>. For a reference on the supported Android resource types,
see <a href="{@docRoot}guide/topics/resources/available-resources.html">Available Resource Types</a>.</p>
<p>The Android resource system keeps track of all non-code
assets associated with an application. You use the
{@link android.content.res.Resources Resources} class to access your
application's resources; the Resources instance associated with your
application can generally be found through
{@link android.content.Context#getResources Context.getResources()}.</p>
<p>An application's resources are compiled into the application
binary at build time for you by the build system. To use a resource,
you must install it correctly in the source tree and build your
application. As part of the build process, Java symbols for each
of the resources are generated that you can use in your source
code -- this allows the compiler to verify that your application code matches
up with the resources you defined.</p>
<p>The rest of this section is organized as a tutorial on how to
use resources in an application.</p>
<a name="ResourcesTerminology"></a>
<h3>Terminology</h3>
<p>The resource system brings a number of different pieces together to
form the final complete resource functionality. To help understand the
overall system, here are some brief definitions of the core concepts and
components you will encounter in using it:</p>
<p><b>Asset</b>: A single blob of data associated with an application. This
includes Java object files, graphics (such as PNG images), XML files, etc.
These files are organized in a directory hierarchy that, during final packaging
of the application, is bundled together into a single ZIP file.</p>
<p><b>aapt</b>: The tool that generates the final ZIP file of application
assets. In addition to collecting raw assets together, it also parses
resource definitions into binary asset data.</p>
<p><b>Resource Table</b>: A special asset that aapt generates for you,
describing all of the resources contained in an application/package.
This file is accessed for you by the Resources class; it is not touched
directly by applications.</p>
<p><b>Resource</b>: An entry in the Resource Table describing a single
named value. Broadly, there are two types of resources: primitives and
bags.</p>
<p><b>Resource Identifier</b>: In the Resource Table all resources are
identified by a unique integer number. In source code (resource descriptions,
XML files, Java code) you can use symbolic names that stand as constants for
the actual resource identifier integer.</p>
<p><b>Primitive Resource</b>: All primitive resources can be written as a
simple string, using formatting to describe a variety of primitive types
included in the resource system: integers, colors, strings, references to
other resources, etc. Complex resources, such as bitmaps and XML
describes, are stored as a primitive string resource whose value is the path
of the underlying Asset holding its actual data.</p>
<p><b>Bag Resource</b>: A special kind of resource entry that, instead of a
simple string, holds an arbitrary list of name/value pairs. Each name is
itself a resource identifier, and each value can hold
the same kinds of string formatted data as a normal resource. Bags also
support inheritance: a bag can inherit the values from another bag, selectively
replacing or extending them to generate its own contents.</p>
<p><b>Kind</b>: The resource kind is a way to organize resource identifiers
for various purposes. For example, drawable resources are used to
instantiate Drawable objects, so their data is a primitive resource containing
either a color constant or string path to a bitmap or XML asset. Other
common resource kinds are string (localized string primitives), color
(color primitives), layout (a string path to an XML asset describing a view
layout), and style (a bag resource describing user interface attributes).
There is also a standard "attr" resource kind, which defines the resource
identifiers to be used for naming bag items and XML attributes</p>
<p><b>Style</b>: The name of the resource kind containing bags that are used
to supply a set of user interface attributes. For example, a TextView class may
be given a style resource that defines its text size, color, and alignment.
In a layout XML file, you associate a style with a bag using the "style"
attribute, whose value is the name of the style resource.</p>
<p><b>Style Class</b>: Specifies a related set of attribute resources.
This data is not placed in the resource table itself, but used to generate
Java constants that make it easier for you to retrieve values out of
a style resource and/or XML tag's attributes. For example, the
Android platform defines a "View" style class that
contains all of the standard view attributes: padding, visibility,
background, etc.; when View is inflated it uses this style class to
retrieve those values from the XML file (at which point style and theme
information is applied as approriate) and load them into its instance.</p>
<p><b>Configuration</b>: For any particular resource identifier, there may be
multiple different available values depending on the current configuration.
The configuration includes the locale (language and country), screen
orientation, screen density, etc. The current configuration is used to
select which resource values are in effect when the resource table is
loaded.</p>
<p><b>Theme</b>: A standard style resource that supplies global
attribute values for a particular context. For example, when writing a
Activity the application developer can select a standard theme to use, such
as the Theme.White or Theme.Black styles; this style supplies information
such as the screen background image/color, default text color, button style,
text editor style, text size, etc. When inflating a layout resource, most
values for widgets (the text color, selector, background) if not explicitly
set will come from the current theme; style and attribute
values supplied in the layout can also assign their value from explicitly
named values in the theme attributes if desired.</p>
<p><b>Overlay</b>: A resource table that does not define a new set of resources,
but instead replaces the values of resources that are in another resource table.
Like a configuration, this is applied at load time
to the resource data; it can add new configuration values (for example
strings in a new locale), replace existing values (for example change
the standard white background image to a "Hello Kitty" background image),
and modify resource bags (for example change the font size of the Theme.White
style to have an 18 pt font size). This is the facility that allows the
user to select between different global appearances of their device, or
download files with new appearances.</p>
<a name="ResourcesQuickStart"></a>
<h3>Examples</h3>
<p>This section gives a few quick examples you can use to make your own resources.
For more details on how to define and use resources, see <a
href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources and
Internationalization</a>. </p>
<a name="UsingSystemResources"></a>
<h4>Using System Resources</h4>
<p>Many resources included with the system are available to applications.
All such resources are defined under the class "android.R". For example,
you can display the standard application icon in a screen with the following
code:</p>
<pre class="prettyprint">
public class MyActivity extends Activity
{
public void onStart()
{
requestScreenFeatures(FEATURE_BADGE_IMAGE);
super.onStart();
setBadgeResource(android.R.drawable.sym_def_app_icon);
}
}
</pre>
<p>In a similar way, this code will apply to your screen the standard
"green background" visual treatment defined by the system:</p>
<pre class="prettyprint">
public class MyActivity extends Activity
{
public void onStart()
{
super.onStart();
setTheme(android.R.style.Theme_Black);
}
}
</pre>
<a name="StringResources"></a>
<h4>String Resources</h4>
<p>String resources are defined using an XML resource description syntax.
The file or multiple files containing these resources can be given any name
(as long as it has a .xml suffix) and placed at an appropriate location in
the source tree for the desired configuration (locale/orientation/density).
<p>Here is a simple resource file describing a few strings:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;resources&gt;
&lt;string id="mainLabel"&gt;Hello &lt;u&gt;th&lt;ignore&gt;e&lt;/ignore&gt;re&lt;/u&gt;, &lt;i&gt;you&lt;/i&gt; &lt;b&gt;Activity&lt;/b&gt;!&lt;/string&gt;
&lt;string id="back"&gt;Back&lt;/string&gt;
&lt;string id="clear"&gt;Clear&lt;/string&gt;
&lt;/resources&gt;
</pre>
<p>Typically this file will be called "strings.xml", and must be placed
in the <code>values</code> directory:</p>
<pre>
MyApp/res/values/strings.xml
</pre>
<p>The strings can now be retrieved by your application through the
symbol specified in the "id" attribute:</p>
<pre class="prettyprint">
public class MyActivity extends Activity
{
public void onStart()
{
super.onStart();
String back = getResources().getString(R.string.back).toString();
back = getString(R.string.back).toString(); // synonym
}
}
</pre>
<p>Unlike system resources, the resource symbol (the R class) we are using
here comes from our own application's package, not android.R.</p>
<p>Note that the "mainLabel" string is complex, including style information.
To support this, the <code>getString()</code> method returns a
<code>CharSequence</code> object that you can pass to a
<code>TextView</code> to retain those style. This is why code
must call <code>toString()</code> on the returned resource if it wants
a raw string.</p>
<a name="ColorResources"></a>
<h4>Color Resources</h4>
<p>Color resources are created in a way very similar to string resources,
but with the &lt;color&gt; resource tag. The data for these resources
must be a hex color constant of the form "#rgb", "#argb", "#rrggbb", or
"#aarrggbb". The alpha channel is 0xff (or 0xf) for opaque and 0
for transparent.</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;resources&gt;
&lt;color id="opaque_red"&gt;#ffff0000&lt;/color&gt;
&lt;color id="transparent_red"&gt;#80ff0000&lt;/color&gt;
&lt;color id="opaque_blue"&gt;#0000ff&lt;/color&gt;
&lt;color id="opaque_green"&gt;#0f0&lt;/color&gt;
&lt;/resources&gt;
</pre>
<p>While color definitions could be placed in the same resource file
as the previously shown string data, usually you will place the colors in
their own file:</p>
<pre>
MyApp/res/values/colors.xml
</pre>
<p>The colors can now be retrieved by your application through the
symbol specified in the "id" attribute:</p>
<pre class="prettyprint">
public class MyActivity extends Activity
{
public void onStart()
{
super.onStart();
int red = getResources().getColor(R.color.opaque_red);
}
}
</pre>
<a name="DrawableResources"></a>
<h4>Drawable Resources</h4>
<p>For simple drawable resources, all you need to do is place your
image in a special resource sub-directory called "drawable". Files here
are things that can be handled by an implementation of the
{@link android.graphics.drawable.Drawable Drawable} class, often bitmaps
(such as PNG images) but also various kinds of XML descriptions
for selectors, gradients, etc.</p>
<p>The drawable files will be scanned by the
resource tool, automatically generating a resource entry for each found.
For example the file <code>res/drawable/&lt;myimage&gt;.&lt;ext&gt;</code>
will result in a resource symbol named "myimage" (without the extension). Note
that these file names <em>must</em> be valid Java identifiers, and should
have only lower-case letters.</p>
<p>For example, to use your own custom image as a badge in a screen,
you can place the image here:</p>
<pre>
MyApp/res/drawable/my_badge.png
</pre>
<p>The image can then be used in your code like this:</p>
<pre class="prettyprint">
public class MyActivity extends Activity
{
public void onStart()
{
requestScreenFeatures(FEATURE_BADGE_IMAGE);
super.onStart();
setBadgeResource(R.drawable.my_badge);
}
}
</pre>
<p>For drawables that are a single solid color, you can also define them
in a resource file very much like colors shown previously. The only
difference is that here we use the &lt;drawable&gt; tag to create a
drawable resource.</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;resources&gt;
&lt;drawable id="opaque_red"&gt;#ffff0000&lt;/drawable&gt;
&lt;drawable id="transparent_red"&gt;#80ff0000&lt;/drawable&gt;
&lt;drawable id="opaque_blue"&gt;#0000ff&lt;/drawable&gt;
&lt;drawable id="opaque_green"&gt;#0f0&lt;/drawable&gt;
&lt;/resources&gt;
</pre>
<p>These resource entries are often placed in the same resource file
as color definitions:</p>
<pre>
MyApp/res/values/colors.xml
</pre>
<a name="LayoutResources"></a>
<h4>Layout Resources</h4>
<p>Layout resources describe a view hierarchy configuration that is
generated at runtime. These resources are XML files placed in the
resource directory "layout", and are how you should create the content
views inside of your screen (instead of creating them by hand) so that
they can be themed, styled, configured, and overlayed.</p>
<p>Here is a simple layout resource consisting of a single view, a text
editor:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;root&gt;
&lt;EditText id="text"
android:layout_width="fill-parent" android:layout_height="fill-parent"
android:text="Hello, World!" /&gt;
&lt;/root&gt;
</pre>
<p>To use this layout, it can be placed in a file like this:</p>
<pre>
MyApp/res/layout/my_layout.xml
</pre>
<p>The layout can then be instantiated in your screen like this:</p>
<pre class="prettyprint">
public class MyActivity extends Activity
{
public void onStart()
{
super.onStart();
setContentView(R.layout.my_layout);
}
}
</pre>
<p>Note that there are a number of visual attributes that can be supplied
to TextView (including textSize, textColor, and textStyle) that we did
not define in the previous example; in such a sitation, the default values for
those attributes come from the theme. If we want to customize them, we
can supply them explicitly in the XML file:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;root&gt;
&lt;EditText id="text"
android:layout_width="match_parent" android:layout_height="match_parent"
<b>android:textSize="18" android:textColor="#008"</b>
android:text="Hello, World!" /&gt;
&lt;/root&gt;
</pre>
<p>However, usually these kinds of attributes (those being attributes that
usually make sense to vary with theme or overlay) should be defined through
the theme or separate style resource. Later we will see how this is done.</p>
<a name="ReferencesToResources"></a>
<h4>References to Resources</h4>
<p>A value supplied in an attribute (or resource) can also be a reference to
a resource. This is often used in layout files to supply strings (so they
can be localized) and images (which exist in another file), though a reference
can be do any resource type including colors and integers.</p>
<p>For example, if we have the previously defined color resources, we can
write a layout file that sets the text color size to be the value contained in
one of those resources:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;root&gt;
&lt;EditText id="text"
android:layout_width="match_parent" android:layout_height="match_parent"
<b>android:textColor="@color/opaque_red"</b>
android:text="Hello, World!" /&gt;
&lt;/root&gt;
</pre>
<p>Note here the use of the '@' prefix to introduce a resource reference -- the
text following that is the name of a resource in the form
of <code>@[package:]type/name</code>. In this case we didn't need to specify
the package because we are referencing a resource in our own package. To
reference a system resource, you would need to write:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;root&gt;
&lt;EditText id="text"
android:layout_width="match_parent" android:layout_height="match_parent"
android:textColor="@<b>android:</b>color/opaque_red"
android:text="Hello, World!" /&gt;
&lt;/root&gt;
</pre>
<p>As another example, you should always use resource references when supplying
strings in a layout file so that they can be localized:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;root&gt;
&lt;EditText id="text"
android:layout_width="match_parent" android:layout_height="match_parent"
android:textColor="@android:color/opaque_red"
android:text="@string/hello_world" /&gt;
&lt;/root&gt;
</pre>
<p>This facility can also be used to create references between resources.
For example, we can create new drawable resources that are aliases for
existing images:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;resources&gt;
&lt;drawable id="my_background"&gt;@android:drawable/theme2_background&lt;/drawable&gt;
&lt;/resources&gt;
</pre>
<a name="ReferencesToThemeAttributes"></a>
<h4>References to Theme Attributes</h4>
<p>Another kind of resource value allows you to reference the value of an
attribute in the current theme. This attribute reference can <em>only</em>
be used in style resources and XML attributes; it allows you to customize the
look of UI elements by changing them to standard variations supplied by the
current theme, instead of supplying more concrete values.</p>
<p>As an example, we can use this in our layout to set the text color to
one of the standard colors defined in the base system theme:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;root&gt;
&lt;EditText id="text"
android:layout_width="match_parent" android:layout_height="match_parent"
<b>android:textColor="?android:textDisabledColor"</b>
android:text="@string/hello_world" /&gt;
&lt;/root&gt;
</pre>
<p>Note that this is very similar to a resource reference, except we are using
an '?' prefix instead of '@'. When you use this markup, you are supplying
the name of an attribute resource that will be looked up in the theme --
because the resource tool knows that an attribute resource is expected,
you do not need to explicitly state the type (which would be
<code>?android:attr/android:textDisabledColor</code>).</p>
<p>Other than using this resource identifier to find the value in the
theme instead of raw resources, the name syntax is identical to the '@' format:
<code>?[package:]type/name</code> with the type here being optional.</p>
<a name="StyleResources"></a>
<h4>Style Resources</h4>
<p>A style resource is a set of name/value pairs describing a group
of related attributes. There are two main uses for these resources:
defining overall visual themes, and describing a set of visual attributes
to apply to a class in a layout resource. In this section we will look
at their use to describe themes; later we will look at using them in
conjunction with layouts.</p>
<p>Like strings, styles are defined through a resource XML file. In the
situation where we want to define a new theme, we can create a custom theme
style that inherits from one of the standard system themes:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;resources&gt;
&lt;style id="Theme" parent="android:Theme.White"&gt;
&lt;item id="android:foregroundColor"&gt;#FFF8D96F&lt;/item&gt;
&lt;item id="android:textColor"&gt;@color/opaque_blue&lt;/item&gt;
&lt;item id="android:textSelectedColor"&gt;?android:textColor&lt;/item&gt;
&lt;/style&gt;
&lt;/resources&gt;
</pre>
<p>Typically these resource definitions will be placed in a file
called "styles.xml" , and must be placed in the <code>values</code>
directory:</p>
<pre>
MyApp/res/values/styles.xml
</pre>
<p>Similar to how we previously used a system style for an Activity theme,
you can apply this style to your Activity:</p>
<pre class="prettyprint">
public class MyActivity extends Activity
{
public void onStart()
{
super.onStart();
setTheme(R.style.Theme);
}
}
</pre>
<p>In the style resource shown here, we used the <code>parent</code>
attribute to specify another style resource from which it inherits
its values -- in this case the <code>Theme.White</code> system resource:</p>
<pre>
&lt;style id="Home" parent="android:Theme.White"&gt;
...
&lt;/style&gt;
</pre>
<p>Note, when doing this, that you must use the "android" prefix in front
to tell the compiler the namespace to look in for the resource --
the resources you are specifying here are in your application's namespace,
not the system. This explicit namespace specification ensures that names
the application uses will not accidentally conflict with those defined by
the system.</p>
<p>If you don't specify an explicit parent style, it will be inferred
from the style name -- everything before the final '.' in the name of the
style being defined is taken as the parent style name. Thus, to make
another style in your application that inherits from this base Theme style,
you can write:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;resources&gt;
&lt;style id="Theme.WhiteText"&gt;
&lt;item id="android:foregroundColor"&gt;#FFFFFFFF&lt;/item&gt;
&lt;item id="android:textColor"&gt;?android:foregroundColor&lt;/item&gt;
&lt;/style&gt;
&lt;/resources&gt;
</pre>
<p>This results in the symbol <code>R.style.Theme_WhiteText</code> that
can be used in Java just like we did with <code>R.style.Theme</code>
above.</p>
<a name="StylesInLayoutResources"></a>
<h4>Styles in Layout Resources</h4>
<p>Often you will have a number fo views in a layout that all use the same
set of attributes, or want to allow resource overlays to modify the values of
attributes. Style resources can be used for both of these purposes, to put
attribute definitions in a single place that can be references by multiple
XML tags and modified by overlays. To do this, you simply define a
new style resource with the desired values:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;resources&gt;
&lt;style id="SpecialText"&gt;
&lt;item id="android:textSize"&gt;18&lt;/item&gt;
&lt;item id="android:textColor"&gt;#008&lt;/item&gt;
&lt;/style&gt;
&lt;/resources&gt;
</pre>
<p>You can now apply this style to your TextView in the XML file:</p>
<pre>
&lt;?xml version="1.0" encoding="utf-8"?&gt;
&lt;root&gt;
&lt;EditText id="text1" <b>style="@style/SpecialText"</b>
android:layout_width="match_parent" android:layout_height="wrap_content"
android:text="Hello, World!" /&gt;
&lt;EditText id="text2" <b>style="@style/SpecialText"</b>
android:layout_width="match_parent" android:layout_height="wrap_content"
android:text="I love you all." /&gt;
&lt;/root&gt;</pre>
<h4>&nbsp;</h4>
<p>Contains classes for accessing and publishing data on a device. It includes three main
categories of APIs:</p>
<ul>
<dt>Content sharing ({@link android.content})</dt>
<dd>For sharing content between application components. The most important classes are:
<ul>
<li>{@link android.content.ContentProvider} and {@link android.content.ContentResolver}
for managing and publishing persistent data associated with an application.</li>
<li>{@link android.content.Intent} and {@link android.content.IntentFilter}, for delivering
structured messages between different application components&mdash;allowing components to initiate
other components and return results.</li>
</ul>
</dd>
<dt>Package management ({@link android.content.pm})</dt>
<dd>For accessing information about an Android package (an {@code .apk}), including information
about its activities, permissions, services, signatures, and providers. The most important class for
accessing this information is {@link android.content.pm.PackageManager}.</dd>
<dt>Resource management ({@link android.content.res})</dt>
<dd>For retrieving resource data associated with an application, such as strings, drawables,
media, and device configuration details. The most important class for accessing this data is {@link
android.content.res.Resources}.</dd>
</ul>
</body>
</html>

10
core/java/android/content/pm/package.html
View File

@@ -1,7 +1,11 @@
<HTML>
<BODY>
Contains classes for accessing information about an
application package, including information about its activities,
permissions, services, signatures, and providers.
<p>Contains classes for accessing information about an
application package, including information about its activities,
permissions, services, signatures, and providers.</p>
<p>Most of the information about an application package is defined by its manifest file. For
more information, see the <a
href="{@docRoot}guide/topics/manifest/guide/topics/manifest/manifest-intro.html">AndroidManifest.xml
File</a> documentation.</p>
</BODY>
</HTML>

24
core/java/android/content/res/Resources.java
View File

@@ -45,8 +45,28 @@ import libcore.icu.NativePluralRules;
/**
* Class for accessing an application's resources. This sits on top of the
* asset manager of the application (accessible through getAssets()) and
* provides a higher-level API for getting typed data from the assets.
* asset manager of the application (accessible through {@link #getAssets}) and
* provides a high-level API for getting typed data from the assets.
*
* <p>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 {@link android.content.res.Resources} instance associated with your application
* with {@link android.content.Context#getResources getResources()}.</p>
*
* <p>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 {@code 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.</p>
*
* <p>Using application resources makes it easy to update various characteristics of your
* application without modifying code, and&mdash;by providing sets of alternative
* resources&mdash;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.</p>
*
* <p>For more information about using resources, see the documentation about <a
* href="{@docRoot}guide/topics/resources/index.html">Application Resources</a>.</p>
*/
public class Resources {
static final String TAG = "Resources";

12
core/java/android/content/res/package.html
View File

@@ -1,8 +1,12 @@
<HTML>
<BODY>
Contains classes for accessing application resources,
such as raw asset files, colors, drawables, media or other other files
in the package, plus important device configuration details
(orientation, input types, etc.) that affect how the application may behave.
<p>Contains classes for accessing application resources,
such as raw asset files, colors, drawables, media or other other files
in the package, plus important device configuration details
(orientation, input types, etc.) that affect how the application may behave.</p>
<p>For more information, see the <a
href="{@docRoot}guide/topics/resources/index.html">Application Resources</a> developer guide.</p>
{@more}
</BODY>
</HTML>

6
core/java/android/hardware/package.html
View File

@@ -1,5 +1,9 @@
<HTML>
<BODY>
Provides support for hardware devices that may not be present on every Android device.
<p>Provides support for hardware features, such as the camera and other sensors. Be aware that
not all Android-powered devices support all hardware features, so you should declare hardware
that your application requires using the <a
href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code
&lt;uses-feature&gt;}</a> manifest element.</p>
</BODY>
</HTML>

2
core/java/android/inputmethodservice/package.html
View File

@@ -1,6 +1,6 @@
<html>
<body>
Base classes for writing input methods. These APIs are not for use by
Base classes for writing input methods (such as software keyboards). These APIs are not for use by
normal applications, they are a framework specifically for writing input
method components. Implementations will typically derive from
{@link android.inputmethodservice.InputMethodService}.

21
core/java/android/package.html
View File

@@ -1,10 +1,17 @@
<HTML>
<BODY>
Contains the resource classes used by standard Android applications.
<p>
This package contains the resource classes that Android defines to be used in
Android applications. Third party developers can use many of them also for their applications.
To learn more about how to use these classes, and what a
resource is, see <a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.
<p>Contains resource classes used by applications included in the platform and defines application
permissions for system features.</p>
<p>You can use some resources directly from these {@link android.R} classes in your own
applications, but you should generally use only resources that you've provided directly in your
application, in order to provide a cohesive application package that has no external dependencies.
In particular, you should not use drawable resources from the {@code android} package, because they
may change between platform versions, causing unforeseen conflicts with your design. Typically,
{@link android.R.style styles} are the only resources you should use directly from these
resources.</p>
<p>For information about using resources, see the <a
href="{@docRoot}guide/topics/resources/index.html">Application Resources</a> developer guide.</p>
</BODY>
</HTML>
</HTML>

10
core/java/android/provider/package.html
View File

@@ -1,11 +1,13 @@
<HTML>
<BODY>
Provides convenience classes to access the content providers supplied by
Android.
<p>Provides convenience classes to access the content providers supplied by
Android.</p>
<p>Android ships with a number of content providers that store common data such
as contact informations, calendar information, and media files. These classes
provide simplified methods of adding or retrieving data from these content
providers. For information about how to use a content provider, see <a
href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.
providers.</p>
<p>For information about how to use a content provider, see the <a
href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> developer
guide.</p>
</BODY>
</HTML>

7
graphics/java/android/graphics/drawable/package.html
View File

@@ -1,9 +1,10 @@
<HTML>
<BODY>
Provides classes to manage a variety of visual elements that are intended for
<p>Provides classes to manage a variety of visual elements that are intended for
display only, such as bitmaps and gradients. These elements are often used
by widgets as background images or simply as indicators (for example, a volume
level indicator). You can create most of these in XML as described in <a
href="{@docRoot}guide/topics/resources/available-resources.html">Availeble Resource Types</a>.
level indicator).</p>
<p>You can create most of these drawables using XML, as described in <a
href="{@docRoot}guide/topics/resources/drawable-resource.html">Drawable Resources</a>.</p>
</BODY>
</HTML>

9
location/java/android/location/package.html
View File

@@ -1,12 +1,11 @@
<html>
<head>
<script type="text/javascript" src="http://www.corp.google.com/style/prettify.js"></script>
<script src="http://www.corp.google.com/eng/techpubs/include/navbar.js" type="text/javascript"></script>
</head>
<body>
<p>Classes defining Android location-based and related services.</p>
<p>Contains classes that define Android location-based and related services.</p>
<p>For more information about location services, see the documentation for <a
href="{@docRoot}guide/topics/location/obtaining-user-location.html">Obtaining User Location</a>.</p>
{@more}
</body>
</html>