diff options
| author | The Android Open Source Project <initial-contribution@android.com> | 2008-10-21 07:00:00 -0700 |
|---|---|---|
| committer | The Android Open Source Project <initial-contribution@android.com> | 2008-10-21 07:00:00 -0700 |
| commit | 54b6cfa9a9e5b861a9930af873580d6dc20f773c (patch) | |
| tree | 35051494d2af230dce54d6b31c6af8fc24091316 /core/java/android/content/package.html | |
| download | frameworks_base-54b6cfa9a9e5b861a9930af873580d6dc20f773c.zip frameworks_base-54b6cfa9a9e5b861a9930af873580d6dc20f773c.tar.gz frameworks_base-54b6cfa9a9e5b861a9930af873580d6dc20f773c.tar.bz2 | |
Initial Contribution
Diffstat (limited to 'core/java/android/content/package.html')
| -rw-r--r-- | core/java/android/content/package.html | 649 |
1 files changed, 649 insertions, 0 deletions
diff --git a/core/java/android/content/package.html b/core/java/android/content/package.html new file mode 100644 index 0000000..7b3e8cf --- /dev/null +++ b/core/java/android/content/package.html @@ -0,0 +1,649 @@ +<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}devel/resources-i18n.html">Resources + and Internationalization</a>. For a reference on the supported Android resource types, + see <a href="{@docRoot}reference/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}devel/resources-i18n.html">Resources</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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <string id="mainLabel">Hello <u>th<ignore>e</ignore>re</u>, <i>you</i> <b>Activity</b>!</string> + <string id="back">Back</string> + <string id="clear">Clear</string> +</resources> +</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 <color> 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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <color id="opaque_red">#ffff0000</color> + <color id="transparent_red">#80ff0000</color> + <color id="opaque_blue">#0000ff</color> + <color id="opaque_green">#0f0</color> +</resources> +</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/<myimage>.<ext></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 <drawable> tag to create a +drawable resource.</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <drawable id="opaque_red">#ffff0000</drawable> + <drawable id="transparent_red">#80ff0000</drawable> + <drawable id="opaque_blue">#0000ff</drawable> + <drawable id="opaque_green">#0f0</drawable> +</resources> +</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> +<?xml version="1.0" encoding="utf-8"?> +<root> + <EditText id="text" + android:layout_width="fill-parent" android:layout_height="fill-parent" + android:text="Hello, World!" /> +</root> +</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> +<?xml version="1.0" encoding="utf-8"?> +<root> + <EditText id="text" + android:layout_width="fill_parent" android:layout_height="fill_parent" + <b>android:textSize="18" android:textColor="#008"</b> + android:text="Hello, World!" /> +</root> +</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> +<?xml version="1.0" encoding="utf-8"?> +<root> + <EditText id="text" + android:layout_width="fill_parent" android:layout_height="fill_parent" + <b>android:textColor="@color/opaque_red"</b> + android:text="Hello, World!" /> +</root> +</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> +<?xml version="1.0" encoding="utf-8"?> +<root> + <EditText id="text" + android:layout_width="fill_parent" android:layout_height="fill_parent" + android:textColor="@<b>android:</b>color/opaque_red" + android:text="Hello, World!" /> +</root> +</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> +<?xml version="1.0" encoding="utf-8"?> +<root> + <EditText id="text" + android:layout_width="fill_parent" android:layout_height="fill_parent" + android:textColor="@android:color/opaque_red" + android:text="@string/hello_world" /> +</root> +</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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <drawable id="my_background">@android:drawable/theme2_background</drawable> +</resources> +</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> +<?xml version="1.0" encoding="utf-8"?> +<root> + <EditText id="text" + android:layout_width="fill_parent" android:layout_height="fill_parent" + <b>android:textColor="?android:textDisabledColor"</b> + android:text="@string/hello_world" /> +</root> +</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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <style id="Theme" parent="android:Theme.White"> + <item id="android:foregroundColor">#FFF8D96F</item> + <item id="android:textColor">@color/opaque_blue</item> + <item id="android:textSelectedColor">?android:textColor</item> + </style> +</resources> +</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> + <style id="Home" parent="android:Theme.White"> + ... + </style> +</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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <style id="Theme.WhiteText"> + <item id="android:foregroundColor">#FFFFFFFF</item> + <item id="android:textColor">?android:foregroundColor</item> + </style> +</resources> +</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> +<?xml version="1.0" encoding="utf-8"?> +<resources> + <style id="SpecialText"> + <item id="android:textSize">18</item> + <item id="android:textColor">#008</item> + </style> +</resources> +</pre> + +<p>You can now apply this style to your TextView in the XML file:</p> + +<pre> +<?xml version="1.0" encoding="utf-8"?> +<root> + <EditText id="text1" <b>style="@style/SpecialText"</b> + android:layout_width="fill_parent" android:layout_height="wrap_content" + android:text="Hello, World!" /> + <EditText id="text2" <b>style="@style/SpecialText"</b> + android:layout_width="fill_parent" android:layout_height="wrap_content" + android:text="I love you all." /> +</root></pre> +<h4> </h4> + +</body> +</html> + |