diff options
Diffstat (limited to 'docs/html/guide/topics')
63 files changed, 0 insertions, 14064 deletions
diff --git a/docs/html/guide/topics/data/data-storage.jd b/docs/html/guide/topics/data/data-storage.jd deleted file mode 100644 index 0a1ee02..0000000 --- a/docs/html/guide/topics/data/data-storage.jd +++ /dev/null @@ -1,199 +0,0 @@ -page.title=Data Storage -@jd:body - - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Storage quickview</h2> - <ul> - <li>Fast, lightweight storage through system preferences</li> - <li>File storage to device internal or removable flash</li> - <li>Arbitrary and structured storage in databases</li> - <li>Support for network-based storage</li> - </ul> - - <h2>In this document</h2> - <ol> - <li><a href="#pref">Preferences</a></li> - <li><a href="#files">Files</a></li> - <li><a href="#db">Databases</a></li> - <li><a href="#netw">Network</a></li> - </ol> - - <h2>See also</h2> - <ol> - <li><a href="#pref">Content Providers and Content Resolvers</a></li> - </ol> - -</div> -</div> - -<p> -A typical desktop operating system provides a common file system that any -application can use to store files that can be read by other -applications (perhaps with some access control settings). Android uses a -different system: On Android, all application data (including files) are -private to that application. -</p> - -<p> -However, Android also provides a standard way for an application to expose -its private data to other applications — through content providers. -A content provider is an -optional component of an application that exposes read/write access to the -application's data, subject to whatever restrictions it might impose. -Content providers implement a standard syntax for requesting and modifying -data, and a standard mechanism for reading the returned data. Android supplies -a number of content providers for standard data types, such as image, audio, -and video files and personal contact information. For more information on -using content providers, see a separate document, -<a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>. -</p> - -<p> -Whether or not you want to export your application's data to others, -you need a way to store it. Android provides the following four mechanisms -for storing and retrieving data: <a href="#pref">Preferences</a>, -<a href="#files">Files</a>, <a href="#db">Databases</a>, and <a href="#netw">Network</a>. -</p> - - -<h2 id="pref">Preferences</h2> -<p>Preferences is a lightweight mechanism to store and retrieve key-value pairs of primitive -data types. It is typically used to store application preferences, such as a -default greeting or a text font to be loaded whenever the application is started. Call -<code>{@link android.content.Context#getSharedPreferences(java.lang.String,int) -Context.getSharedPreferences()}</code> to read and write values. Assign a name to -your set of preferences if you want to share them with other components in the same -application, or use <code>{@link android.app.Activity#getPreferences(int) -Activity.getPreferences()}</code> with no name to keep them private to the calling -activity. You cannot share preferences across applications (except by using a -content provider). -</p> - -<p> -Here is an example of setting user preferences for silent keypress mode for a -calculator: -</p> - -<pre> -import android.app.Activity; -import android.content.SharedPreferences; - -public class Calc extends Activity { -public static final String PREFS_NAME = "MyPrefsFile"; - . . . - - @Override - protected void onCreate(Bundle state){ - super.onCreate(state); - - . . . - - // Restore preferences - SharedPreferences settings = getSharedPreferences(PREFS_NAME, 0); - boolean silent = settings.getBoolean("silentMode", false); - setSilent(silent); - } - - @Override - protected void onStop(){ - super.onStop(); - - // Save user preferences. We need an Editor object to - // make changes. All objects are from android.context.Context - SharedPreferences settings = getSharedPreferences(PREFS_NAME, 0); - SharedPreferences.Editor editor = settings.edit(); - editor.putBoolean("silentMode", mSilentMode); - - // Don't forget to commit your edits!!! - editor.commit(); - } -} -</pre> - - -<h2 id="files">Files</h2> -<p>You can store files directly on the mobile device or on a removable -storage medium. By default, other applications cannot access these files. -</p> - -<p> -To read data from a file, call {@link android.content.Context#openFileInput -Context.openFileInput()} and pass it the local name and path of the file. -It returns a standard Java {@link java.io.FileInputStream} object. To write -to a file, call {@link android.content.Context#openFileOutput -Context.openFileOutput()} with the name and path. It returns a {@link -java.io.FileOutputStream} object. Calling these methods with name and path -strings from another application will not work; you can only access local -files. -</p> - -<p> -If you have a static file to package with your application at compile time, -you can save the file in your project in <code>res/raw/<em>myDataFile</em></code>, -and then open it with {@link -android.content.res.Resources#openRawResource(int) Resources.openRawResource -(R.raw.<em>myDataFile</em>)}. It returns an {@link java.io.InputStream} -object that you can use to read from the file. -</p> - -<h2 id="db">Databases</h2> -<p>The Android API contains support for creating and using SQLite databases. -Each database is private to the application that creates it. -</p> - -<p> -The {@link android.database.sqlite.SQLiteDatabase} object represents a database -and has methods for interacting with it — making queries and managing the -data. To create the database, call <code>{@link -android.database.sqlite.SQLiteDatabase#create SQLiteDatabase.create()}</code> -and also subclass {@link android.database.sqlite.SQLiteOpenHelper}. -</p> - -<p> -As part of its support for the SQLite database system, Android exposes -database management functions that let you store complex collections of data -wrapped into useful objects. For example, Android defines a data type -for contact information; it consists of many fields including a first and last -name (strings), an address and phone numbers (also strings), a photo (bitmap -image), and much other information describing a person. -</p> - -<p> -Android ships with the sqlite3 database tool, which enables you to browse -table contents, run SQL commands, and perform other useful functions on SQLite -databases. See <a href="{@docRoot}guide/developing/tools/adb.html#sqlite">Examine databases -(sqlite3)</a> to learn how to run this program. -</p> - -<p> -All databases, SQLite and others, are stored on the device in -<code>/data/data/<em>package_name</em>/databases</code>. -</p> - -<p> -Discussion of how many tables to create, what fields they contain, and how -they are linked, is beyond the scope of this note, but Android does not -impose any limitations beyond the standard SQLite concepts. We do recommend -including an autoincrement value key field that can be used as a unique ID to -quickly find a record. This is not required for private data, but if you -implement a content provider, you must include such a unique ID field. See the -<a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> -document for more information on this field and the NotePadProvider class -in the NotePad sample code for an example of creating and populating a -new database. Any databases you create will be accessible by name to any other -class in the application, but not outside the application. -</p> - - -<h2 id="netw">Network</h2> -<p>You can also use the network to store and retrieve data (when it's available). -To do network operations, use the classes in the following packages:</p> - -<ul class="no-style"> - <li><code>{@link java.net java.net.*}</code></li> - <li><code>{@link android.net android.net.*}</code></li> -</ul> - diff --git a/docs/html/guide/topics/data/index.html b/docs/html/guide/topics/data/index.html deleted file mode 100644 index a94f8c0..0000000 --- a/docs/html/guide/topics/data/index.html +++ /dev/null @@ -1,9 +0,0 @@ -<html> -<head> -<meta http-equiv="refresh" content="0;url=data-storage.html"> -<title>Redirecting...</title> -</head> -<body> -<a href="data-storage.html">click here</a> if you are not redirected. -</body> -</html>
\ No newline at end of file diff --git a/docs/html/guide/topics/drawing/index.html b/docs/html/guide/topics/drawing/index.html deleted file mode 100644 index 43c1499..0000000 --- a/docs/html/guide/topics/drawing/index.html +++ /dev/null @@ -1,9 +0,0 @@ -<html> -<head> -<meta http-equiv="refresh" content="0;url=opengl.html"> -<title>Redirecting...</title> -</head> -<body> -<a href="opengl.html">click here</a> if you are not redirected. -</body> -</html>
\ No newline at end of file diff --git a/docs/html/guide/topics/drawing/opengl.jd b/docs/html/guide/topics/drawing/opengl.jd deleted file mode 100644 index e22a251..0000000 --- a/docs/html/guide/topics/drawing/opengl.jd +++ /dev/null @@ -1,53 +0,0 @@ -page.title=OpenGL -@jd:body - -<p>Android includes support for 3D hardware acceleration. This functionality is -accessed via the OpenGL API — specifically, the OpenGL ES API.</p> - -<p>OpenGL ES is a flavor of the OpenGL specification intended for embedded -devices. Versions of OpenGL ES are loosely peered to versions of the primary -OpenGL standard. Android currently supports OpenGL ES 1.0, which corresponds -to OpenGL 1.3. So, if the application you have in mind is possible with OpenGL -1.3 on a desktop system, it should be possible on Android.</p> - -<p>The specific API provided by Android is similar to the J2ME JSR239 OpenGL -ES API. However, it may not be identical, so watch out for deviations.</p> - -<h2>Using the API</h2> - -<p>Here's how to use the API at an extremely high level:</p> - -<ol> -<li>Write a custom View subclass.</li> -<li>Obtain a handle to an OpenGLContext, which provides access to the OpenGL functionality.</li> -<li>In your View's onDraw() method, get a handle to a GL object, and use its methods to perform GL operations.</li> -</ol> - -<p>For an example of this usage model (based on the classic GL ColorCube), -see -<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/graphics/GLView1.html">com.android.samples.graphics.GLView1.java</a> -in the ApiDemos sample code project. A slightly more sophisticated version showing how to use -it with threads can be found in -<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/graphics/GLSurfaceViewActivity.html">com.android.samples.graphics.GLSurfaceViewActivity.java</a>. -</p> - -<p>Writing a summary of how to actually write 3D applications using OpenGL is -beyond the scope of this text and is left as an exercise for the reader.</p> - -<h2>Links to Additional Information</h2> - -<p>Information about OpenGL ES can be -found at <a title="http://www.khronos.org/opengles/" -href="http://www.khronos.org/opengles/">http://www.khronos.org/opengles/</a>.</p> - -<p>Information specifically -about OpenGL ES 1.0 (including a detailed specification) can be found -at <a title="http://www.khronos.org/opengles/1_X/" -href="http://www.khronos.org/opengles/1_X/">http://www.khronos.org/opengles/1_X/</a>.</p> - -<p>The documentation for the Android {@link javax.microedition.khronos.opengles.GL -OpenGL ES implementations} are also available.</p> - -<p>Finally, note that though Android does include some basic support for -OpenGL ES 1.1, the support is <strong>not complete</strong>, and should not be relied -upon at this time.</p> diff --git a/docs/html/guide/topics/fundamentals.jd b/docs/html/guide/topics/fundamentals.jd deleted file mode 100644 index 3c7f419..0000000 --- a/docs/html/guide/topics/fundamentals.jd +++ /dev/null @@ -1,1726 +0,0 @@ -page.title=Application Fundamentals -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> -<h2>Key classes</h2> -<ol> -<li>{@link android.app.Activity}</li> -<li>{@link android.app.Service}</li> -<li>{@link android.content.BroadcastReceiver}</li> -<li>{@link android.content.ContentProvider}</li> -<li>{@link android.content.Intent}</li> -</ol> - -<h2>In this document</h2> -<ol> -<li><a href="#appcomp">Application Components</a> - <ol> - <li><a href="#actcomp">Activating components: intents</a></li> - <li><a href="#endcomp">Shutting down components</a></li> - <li><a href="#manfile">The manifest file</a></li> - <li><a href="#ifilters">Intent filters</a></li> - </ol></li> -<li><a href="#acttask">Activities and Tasks</a> - <ol> - <li><a href="#afftask">Affinities and new tasks</a></li> - <li><a href="#lmodes">Launch modes</a></li> - <li><a href="#clearstack">Clearing the stack</a></li> - <li><a href="#starttask">Starting tasks</a></li> - </ol></li> -<li><a href="#procthread">Processes and Threads</a> - <ol> - <li><a href="#procs">Processes</a></li> - <li><a href="#threads">Threads</a></li> - <li><a href="#rpc">Remote procedure calls</a></li> - <li><a href="#tsafe">Thread-safe methods</a></li> - </ol></li> -<li><a href="#lcycles">Component Lifecycles</a> - <ol> - <li><a href="#actlife">Activity lifecycle</a></li> - <li><a href="#servlife">Service lifecycle</a></li> - <li><a href="#broadlife">Broadcast receiver lifecycle</a></li> - <li><a href="#proclife">Processes and lifecycles</a></li> - </ol></li> -</ol> -</div> -</div> - -<p> -Android applications are written in the Java programming language. -The compiled Java code — along with any data and resource -files required by the application — is bundled by the -<a href="{@docRoot}guide/developing/tools/aapt.html"><code>aapt</code> -tool</a> into an <i>Android package</i>, an archive file -marked by an {@code .apk} suffix. This file is the vehicle -for distributing the application and installing it on mobile devices; -it's the file users download to their devices. All the code in a -single {@code .apk} file is considered to be one <i>application</i>. -</p> - -<p> -In many ways, each Android application lives in its own world: -</p> - -<ul> -<li>By default, every application runs in its own Linux process. -Android starts the process when any of the application's code needs to be -executed, and shuts down the process when it's no longer needed and system -resources are required by other applications.</li> - -<li>Each process has its own Java virtual machine (VM), so application code -runs in isolation from the code of all other applications.</li> - -<li>By default, each application is assigned a unique Linux user ID. -Permissions are set so that the application's files are visible only -that user, only to the application itself — although there are ways -to export them to other applications as well.</li> -</ul> - -<p> -It's possible to arrange for two applications to share the same user ID, -in which case they will be able to see each other's files. To conserve -system resources, applications with the same ID can also arrange to run -in the same Linux process, sharing the same VM. -</p> - - -<h2 id="appcomp">Application Components</h2> - -<p> -A central feature of Android is that one application can make use of elements -of other applications (provided those applications permit it). For example, -if your application needs to display a scrolling list of images and another -application has developed a suitable scroller and made it available to others, -you can call upon that scroller to do the work, rather than develop your own. -Your application doesn't incorporate the code of the other application or -link to it. Rather, it simply starts up that piece of the other application -when the need arises. -</p> - -<p> -For this to work, the system must be able to start an application process -when any part of it is needed, and instantiate the Java objects for that part. -Therefore, unlike applications on most other systems, Android applications don't -have a single entry point for everything in the application (no {@code main()} -function, for example). Rather, they have essential <i>components</i> that -the system can instantiate and run as needed. There are four types of components: -</p> - -<dl> - -<dt><b>Activities</b></dt> -<dd>An <i>activity</i> presents a visual user interface for one focused endeavor -the user can undertake. For example, an activity might present a list of -menu items users can choose from or it might display photographs along -with their captions. A text messaging application might have one activity -that shows a list of contacts to send messages to, a second activity to write -the message to the chosen contact, and other activities to review old messages -or change settings. Though they work together to form a cohesive user interface, -each activity is independent of the others. -Each one is implemented as a subclass of the {@link android.app.Activity} base class. - -<p> -An application might consist of just one activity or, like the text messaging -application just mentioned, it may contain several. -What the activities are, and how many there are depends, of course, on the -application and its design. Typically, one of the activities is marked -as the first one that should be presented to the user when the application is -launched. Moving from one activity to another is accomplished by having the -current activity start the next one. -</p> - -<p> -Each activity is given a default window to draw in. Typically, the window -fills the screen, but it might be smaller than the screen and float on top -of other windows. An activity can also make use of additional windows — -for example, a pop-up dialog that calls for a user response in the midst of -the activity, or a window that presents users with vital information when they -select a particular item on-screen. -</p> - -<p> -The visual content of the window is provided by a hierarchy of views — -objects derived from the base {@link android.view.View} class. Each view -controls a particular rectangular space within the window. Parent views -contain and organize the layout of their children. Leaf views (those at the -bottom of the hierarchy) draw in the rectangles they control and respond to -user actions directed at that space. Thus, views are where the activity's -interaction with the user takes place. For example, a view might display -a small image and initiate an action when the user taps that image. Android -has a number of ready-made views that you can use — including buttons, -text fields, scroll bars, menu items, check boxes, and more. -</p> - -<p> -A view hierarchy is placed within an activity's window by the -<code>{@link android.app.Activity#setContentView Activity.setContentView()}</code> -method. The <i>content view</i> is the View object at the root of the hierarchy. -(See the separate <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> -document for more information on views and the hierarchy.) -</p> - -<p><dt><b>Services</b></dt> -<dd>A <i>service</i> doesn't have a visual user interface, but rather runs in -the background for an indefinite period of time. For example, a service might -play background music as the user attends to other matters, or it might fetch -data over the network or calculate something and provide the result to activities -that need it. Each service extends the {@link android.app.Service} base class. - -<p> -A prime example is a media player playing songs from a play list. The player -application would probably have one or more activities that allow the user to -choose songs and start playing them. However, the music playback itself would -not be handled by an activity because users will expect the music to keep -playing even after they leave the player and begin something different. -To keep the music going, the media player activity could start a service to run -in the background. The system would then keep the music playback service running -even after the activity that started it leaves the screen. -</p> - -<p> -It's possible to connect to (bind to) an ongoing service (and start the service -if it's not already running). While connected, you can communicate with the -service through an interface that the service exposes. For the music service, -this interface might allow users to pause, rewind, stop, and restart the playback. -</p> - -<p> -Like activities and the other components, services run in the main thread of -the application process. So that they won't block other components or the -user interface, they often spawn another thread for time-consuming tasks -(like music playback). See <a href="#procthread">Processes and Threads</a>, later. -</p></dd> - -<dt><b>Broadcast receivers</b></dt> -<dd>A <i>broadcast receiver</i> is a component that does nothing but -receive and react to broadcast announcements. Many broadcasts originate in -system code — for example, announcements that the timezone has changed, -that the battery is low, that a picture has been taken, or that the user -changed a language preference. Applications can also initiate broadcasts -— for example, to let other applications know that some data has been -downloaded to the device and is available for them to use. - -<p> -An application can have any number of broadcast receivers to respond to any -announcements it considers important. All receivers extend the {@link -android.content.BroadcastReceiver} base class. -</p> - -<p> -Broadcast receivers do not display a user interface. However, they may start -an activity in response to the information they receive, or they may use -the {@link android.app.NotificationManager} to alert the user. Notifications -can get the user's attention in various ways — flashing -the backlight, vibrating the device, playing a sound, and so on. They -typically place a persistent icon in the status bar, which users can open to -get the message. -</p></dd> - -<dt><b>Content providers</b></dt> -<dd>A <i>content provider</i> makes a specific set of the application's data -available to other applications. The data can be stored in the file system, -in an SQLite database, or in any other manner that makes sense. -The content provider extends the {@link android.content.ContentProvider} base -class to implement a standard set of methods that enable other applications -to retrieve and store data of the type it controls. However, applications -do not call these methods directly. Rather they use a {@link -android.content.ContentResolver} object and call its methods instead. -A ContentResolver can talk to any content provider; it cooperates with the -provider to manage any interprocess communication that's involved. - -<p> -See the separate -<a href="{@docRoot}guide/topics/providers/content-providers.html">Content -Providers</a> document for more information on using content providers. -</p></dd> - -</dl> - -<p> -Whenever there's a request that should be handled by a particular component, -Android makes sure that the application process of the component is running, -starting it if necessary, and that an appropriate instance of the component -is available, creating the instance if necessary. -</p> - - -<h3 id="actcomp">Activating components: intents</h3> - -<p> -Content providers are activated when they're targeted by a request from a -ContentResolver. The other three components — activities, services, -and broadcast receivers — are activated by asynchronous messages -called <i>intents</i>. An intent is an {@link android.content.Intent} -object that holds the content of the message. For activities and services, -it names the action being requested and specifies the URI of the data to -act on, among other things. For example, it might convey a request for -an activity to present an image to the user or let the user edit some -text. For broadcast receivers, the Intent object names the action being -announced. For example, it might announce to interested parties that the -camera button has been pressed. -</p> - -<p> -There are separate methods for activiating each type of component: -</p> - -<ul> - -<li>An activity is launched (or given something new to do) by passing an -Intent object to <code>{@link android.content.Context#startActivity -Context.startActivity()}</code> or <code>{@link -android.app.Activity#startActivityForResult -Activity.startActivityForResult()}</code>. The responding activity can -look at the initial intent that caused it to be launched by calling its -<code>{@link android.app.Activity#getIntent getIntent()}</code> method. -Android calls the activity's <code>{@link -android.app.Activity#onNewIntent onNewIntent()}</code> method to pass -it any subsequent intents. - -<p> -One activity often starts the next one. If it expects a result back from -the activity it's starting, it calls {@code startActivityForResult()} -instead of {@code startActivity()}. For example, if it starts an activity -that lets the user pick a photo, it might expect to be returned the chosen -photo. The result is returned in an Intent object that's passed to the -calling activity's <code>{@link android.app.Activity#onActivityResult -onActivityResult()}</code> method. -</p> -</li> - -<li><p>A service is started (or new instructions are given to an ongoing -service) by passing an Intent object to <code>{@link -android.content.Context#startService Context.startService()}</code>. -Android calls the service's <code>{@link android.app.Service#onStart -onStart()}</code> method and passes it the Intent object.</p> - -<p> -Similarly, an intent can be passed to <code>{@link -android.content.Context#bindService Context.bindService()}</code> to -establish an ongoing connection between the calling component and a -target service. The service receives the Intent object in -an <code>{@link android.app.Service#onBind onBind()}</code> call. -(If the service is not already running, {@code bindService()} can -optionally start it.) For example, an activity might establish a connection -with the music playback service mentioned earlier so that it can provide -the user with the means (a user interface) for controlling the playback. -The activity would call {@code bindService()} to set up that connection, -and then call methods defined by the service to affect the playback. -</p> - -<p> -A later section, <a href="#rpc">Remote procedure calls</a>, has more details -about binding to a service. -</p> -</li> - -<li><p>An application can initiate a broadcast by passing an Intent object to -methods like <code>{@link -android.content.Context#sendBroadcast(Intent) Context.sendBroadcast()}</code>, -<code>{@link android.content.Context#sendOrderedBroadcast(Intent, String) -Context.sendOrderedBroadcast()}</code>, and <code>{@link -android.content.Context#sendStickyBroadcast Context.sendStickyBroadcast()}</code> -in any of their variations. Android delivers the intent to all interested -broadcast receivers by calling their <code>{@link -android.content.BroadcastReceiver#onReceive onReceive()}</code> methods.</p></li> - -</ul> - -<p> -For more on intent messages, see the separate article, -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents -and Intent Filters</a>. -</p> - - -<h3 id="endcomp">Shutting down components</h3> - -<p> -A content provider is active only while it's responding to a request from -a ContentResolver. And a broadcast receiver is active only while it's -responding to a broadcast message. So there's no need to explicitly shut -down these components. -</p> - -<p> -Activities, on the other hand, provide the user interface. They're -in a long-running conversation with the user and may remain active, -even when idle, as long as the conversation continues. Similarly, services -may also remain running for a long time. So Android has methods to shut -down activities and services in an orderly way: -</p> - -<ul> -<li>An activity can be shut down by calling its -<code>{@link android.app.Activity#finish finish()}</code> method. One activity can -shut down another activity (one it started with {@code startActivityForResult()}) by -calling <code>{@link android.app.Activity#finishActivity finishActivity()}</code>.</li> - -<li>A service can be stopped by calling its -<code>{@link android.app.Service#stopSelf stopSelf()}</code> method, or by calling -<code>{@link android.content.Context#stopService Context.stopService()}</code>.</li> -</ul> - -<p> -Components might also be shut down by the system when they are no longer being -used or when Android must reclaim memory for more active components. A later -section, <a href="#lcycles">Component Lifecycles</a>, discusses this -possibility and its ramifications in more detail. -</p> - - -<h3 id="manfile">The manifest file</h3> - -<p> -Before Android can start an application component, it must learn that -the component exists. Therefore, applications declare their components -in a manifest file that's bundled into the Android package, the {@code .apk} -file that also holds the application's code, files, and resources. -</p> - -<p> -The manifest is a structured XML file and is always named AndroidManifest.xml -for all applications. It does a number of things in addition to declaring the -application's components, such as naming any libraries the application needs -to be linked against (besides the default Android library) and identifying -any permissions the application expects to be granted. -</p> - -<p> -But the principal task of the manifest is to inform Android about the application's -components. For example, an activity might be declared as follows: -</p> - -<pre><?xml version="1.0" encoding="utf-8"?> -<manifest . . . > - <application . . . > - <activity android:name="com.example.project.FreneticActivity" - android:icon="@drawable/small_pic.png" - android:label="@string/freneticLabel" - . . . > - </activity> - . . . - </application> -</manifest></pre> - -<p> -The {@code name} attribute of the -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -element names the {@link android.app.Activity} subclass that implements the -activity. The {@code icon} and {@code label} attributes point to -resource files containing an icon and label that can be displayed -to users to represent the activity. -</p> - -<p> -The other components are declared in a similar way — -<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> -elements for services, -<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> -elements for broadcast receivers, and -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> -elements for content providers. Activities, services, and content providers -that are not declared in the manifest are not visible to the system and are -consequently never run. However, broadcast receivers can either be -declared in the manifest, or they can be created dynamically in code -(as {@link android.content.BroadcastReceiver} objects) -and registered with the system by calling -<code>{@link android.content.Context#registerReceiver Context.registerReceiver()}</code>. -</p> - -<p> -For more on how to structure a manifest file for your application, see -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html">The -AndroidManifest.xml File</a>. -</p> - - -<h3 id="ifilters">Intent filters</h3> - -<p> -An Intent object can explicitly name a target component. If it does, -Android finds that component (based on the declarations in the manifest -file) and activates it. But if a target is not explicitly named, -Android must locate the best component to respond to the intent. -It does so by comparing the Intent object to the <i>intent filters</i> -of potential targets. A component's intent filters inform Android of -the kinds of intents the component is able to handle. Like other -essential information about the component, they're declared in the -manifest file. Here's an extension of the previous example that adds -two intent filters to the activity: -</p> - -<pre><?xml version="1.0" encoding="utf-8"?> -<manifest . . . > - <application . . . > - <activity android:name="com.example.project.FreneticActivity" - android:icon="@drawable/small_pic.png" - android:label="@string/freneticLabel" - . . . > - <intent-filter . . . > - <action android:name="android.intent.action.MAIN" /> - <category android:name="android.intent.category.LAUNCHER" /> - </intent-filter> - <intent-filter . . . > - <action android:name="com.example.project.BOUNCE" /> - <data android:type="image/jpeg" /> - <category android:name="android.intent.category.DEFAULT" /> - </intent-filter> - </activity> - . . . - </application> -</manifest></pre> - -<p> -The first filter in the example — the combination of the action -"{@code android.intent.action.MAIN}" and the category -"{@code android.intent.category.LAUNCHER}" — is a common one. -It marks the activity as one that should be represented in the -application launcher, the screen listing applications users can launch -on the device. In other words, the activity is the entry point for -the application, the initial one users would see when they choose -the application in the launcher. -</p> - -<p> -The second filter declares an action that the activity can perform on -a particular type of data. -</p> - -<p> -A component can have any number of intent filters, each one declaring a -different set of capabilities. If it doesn't have any filters, it can -be activated only by intents that explicitly name the component as the -target. -</p> - -<p> -For a broadcast receiver that's created and registered in code, the -intent filter is instantiated directly as an {@link android.content.IntentFilter} -object. All other filters are set up in the manifest. -</p> - -<p> -For more on intent filters, see a separate document, -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents -and Intent Filters</a>. -</p> - - -<h2 id="acttask">Activities and Tasks</h2> - -<p> -As noted earlier, one activity can start another, including one defined -in a different application. Suppose, for example, that you'd like -to let users display a street map of some location. There's already an -activity that can do that, so all your activity needs to do is put together -an Intent object with the required information and pass it to -{@code startActivity()}. The map viewer will display the map. When the user -hits the BACK key, your activity will reappear on screen. -</p> - -<p> -To the user, it will seem as if the map viewer is part of the same application -as your activity, even though it's defined in another application and runs in -that application's process. Android maintains this user experience by keeping -both activities in the same <i>task</i>. Simply put, a task is what the user -experiences as an "application." It's a group of related activities, arranged -in a stack. The root activity in the stack is the one that began the task -— typically, it's an activity the user selected in the application launcher. -The activity at the top of the stack is one that's currently running — -the one that is the focus for user actions. When one activity starts another, -the new activity is pushed on the stack; it becomes the running activity. -The previous activity remains in the stack. When the user presses the BACK key, -the current activity is popped from the stack, and the previous one resumes as -the running activity. -</p> - -<p> -The stack contains objects, so if a task has more than one instance of the same -Activity subclass open — multiple map viewers, for example — the -stack has a separate entry for each instance. Activities in the stack are never -rearranged, only pushed and popped. -</p> - -<p> -A task is a stack of activities, not a class or an element in the manifest file. -So there's no way to set values for a task independently of its activities. -Values for the task as a whole are set in the root activity. For example, the -next section will talk about the "affinity of a task"; that value is read from -the affinity set for the task's root activity. -</p> - -<p> -All the activities in a task move together as a unit. The entire task (the entire -activity stack) can be brought to the foreground or sent to the background. -Suppose, for instance, that the current task has four activities in its stack -— three under the current activity. The user presses the HOME key, goes -to the application launcher, and selects a new application (actually, a new <i>task</i>). -The current task goes into the background and the root activity for the new task is displayed. -Then, after a short period, the user goes back to the home screen and again selects -the previous application (the previous task). That task, with all four -activities in the stack, comes forward. When the user presses the BACK -key, the screen does not display the activity the user just left (the root -activity of the previous task). Rather, the activity on the top of the stack -is removed and the previous activity in the same task is displayed. -</p> - -<p> -The behavior just described is the default behavior for activities and tasks. -But there are ways to modify almost all aspects of it. The association of -activities with tasks, and the behavior of an activity within a task, is -controlled by the interaction between flags set in the Intent object that -started the activity and attributes set in the activity's -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -element in the manifest. Both requester and respondent have a say in what happens. -</p> - -<p> -In this regard, the principal Intent flags are: - -<p style="margin-left: 2em">{@code FLAG_ACTIVITY_NEW_TASK} -<br/>{@code FLAG_ACTIVITY_CLEAR_TOP} -<br/>{@code FLAG_ACTIVITY_RESET_TASK_IF_NEEDED} -<br/>{@code FLAG_ACTIVITY_SINGLE_TOP}</p> - -<p> -The principal {@code <activity>} attributes are: - -<p style="margin-left: 2em">{@code taskAffinity} -<br/>{@code launchMode} -<br/>{@code allowTaskReparenting} -<br/>{@code clearTaskOnLaunch} -<br/>{@code alwaysRetainTaskState} -<br/>{@code finishOnTaskLaunch}</p> - -<p> -The following sections describe what some of these flags and attributes do, -how they interact, and what considerations should govern their use. -</p> - - -<h3 id="afftask">Affinities and new tasks</h3> - -<p> -By default, all the activities in an application have an <i>affinity</i> for each -other — that is, there's a preference for them all to belong to the -same task. However, an individual affinity can be set for each activity -with the {@code taskAffinity} attribute of the {@code <activity>} element. -Activities defined in different applications can share an affinity, or activities -defined in the same application can be assigned different affinities. -The affinity comes into play in two circumstances: When the Intent object -that launches an activity contains the {@code FLAG_ACTIVITY_NEW_TASK} flag, -and when an activity has its {@code allowTaskReparenting} attribute set -to "{@code true}". -</p> - -<dl> -<dt>The <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> flag</dt> -<dd>As described earlier, a new activity is, by default, launched into -the task of the activity that called {@code startActivity()}. It's pushed - onto the same stack as the caller. However, if the Intent object passed -to {@code startActivity()} contains the {@code FLAG_ACTIVITY_NEW_TASK} -flag, the system looks for a different task to house the new activity. -Often, as the name of the flag implies, it's a new task. However, it -doesn't have to be. If there's already an existing task with the same -affinity as the new activity, the activity is launched into that task. If -not, it begins a new task.</dd> - -<dt>The <code><a -href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> -attribute</dt> -<dd>If an activity has its {@code allowTaskReparenting} attribute set -to "{@code true}", it can move from the task it starts in to the task -it has an affinity for when that task comes to the fore. For example, -suppose that an activity that reports weather conditions in selected -cities is defined as part of a travel application. It has the same -affinity as other activities in the same application (the default -affinity) and it allows reparenting. One of your activities -starts the weather reporter, so it initially belongs to the same task as -your activity. However, when the travel application next comes forward, -the weather reporter will be reassigned to and displayed with that task.</dd> -</dl> - -<p> -If an {@code .apk} file contains more than one "application" -from the user's point of view, you will probably want to assign different -affinities to the activities associated with each of them. -</p> - - -<h3 id="lmodes">Launch modes</h3> - -<p> -There are four different launch modes that can be assigned to an {@code -<activity>} element's -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#lmode">launchMode</a></code> -attribute: -</p> - -<p style="margin-left: 2em">"{@code standard}" (the default mode) -<br>"{@code singleTop}" -<br>"{@code singleTask}" -<br>"{@code singleInstance}"</p> - -<p> -The modes differ from each other on these four points: -</p> - -<ul> - -<li><b>Which task will hold the activity that responds to the intent</b>. -For the "{@code standard}" and "{@code singleTop}" modes, it's the task that -originated the intent (and called -<code>{@link android.content.Context#startActivity startActivity()}</code>) -— unless the Intent object contains the -<code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> flag. -In that case, a different task is chosen as described in the previous -section, <a href="#afftask">Affinities and new tasks</a>. - -<p> -In contrast, the "{@code singleTask}" and "{@code singleInstance}" modes mark -activities that are always at the root of a task. They define a task; they're -never launched into another task. -</p> - -<li><p><b>Whether there can be multiple instances of the activity</b>. -A "{@code standard}" or "{@code singleTop}" activity can be instantiated -many times. They can belong to multiple tasks, and a given task can have -multiple instances of the same activity. -</p> - -<p> -In contrast, "{@code singleTask}" and "{@code singleInstance}" activities -are limited to just one instance. Since these activities are at the root -of a task, this limitation means that there is never more than a single -instance of the task on the device at one time. -</p> - -<li><p><b>Whether the instance can have other activities in its task</b>. -A "{@code singleInstance}" activity stands alone as the only activity in its -task. If it starts another activity, that activity will be launched into a -different task regardless of its launch mode — as if {@code -FLAG_ACTIVITY_NEW_TASK} was in the intent. In all other respects, the -"{@code singleInstance}" mode is identical to "{@code singleTask}".</p> - -<p> -The other three modes permit multiple activities to belong to the task. -A "{@code singleTask}" activity will always be the root activity of the task, -but it can start other activities that will be assigned to its -task. Instances of "{@code standard}" and "{@code singleTop}" -activities can appear anywhere in a stack. -</p></li> - -<li><b>Whether a new instance of the class will be launched -to handle a new intent</b>. For the default "{@code standard}" mode, a -new instance is created to respond to every new intent. Each instance -handles just one intent. For the "{@code singleTop}" mode, an existing -instance of the class is re-used to handle a new intent if it resides -at the top of the activity stack of the target task. If it does not -reside at the top, it is not re-used. Instead, a new instance -is created for the new intent and pushed on the stack. - -<p> -For example, suppose a task's activity stack consists of root activity A with -activities B, C, and D on top in that order, so the stack is A-B-C-D. An intent -arrives for an activity of type D. If D has the default "{@code standard}" launch -mode, a new instance of the class is launched and the stack becomes A-B-C-D-D. -However, if D's launch mode is "{@code singleTop}", the existing instance is -expected to handle the new intent (since it's at the top of the stack) and the -stack remains A-B-C-D. -</p> - -<p> -If, on the other hand, the arriving intent is for an activity of type B, a new -instance of B would be launched no matter whether B's mode is "{@code standard}" -or "{@code singleTop}" (since B is not at the top of the stack), so the resulting -stack would be A-B-C-D-B. -</p> - -<p> -As noted above, there's never more than one instance of a "{@code singleTask}" -or "{@code singleInstance}" activity, so that instance is expected to handle -all new intents. A "{@code singleInstance}" activity is always at the top of -the stack (since it is the only activity in the task), so it is always in -position to handle the intent. However, a "{@code singleTask}" activity may -or may not have other activities above it in the stack. If it does, it is not -in position to handle the intent, and the intent is dropped. (Even though the -intent is dropped, its arrival would have caused the task to come to the -foreground, where it would remain.) -</p> -</li> - -</ul> - -<p> -When an existing activity is asked to handle a new intent, the Intent -object is passed to the activity in an -<code>{@link android.app.Activity#onNewIntent onNewIntent()}</code> call. -(The intent object that originally started the activity can be retrieved by -calling <code>{@link android.app.Activity#getIntent getIntent()}</code>.) -</p> - -<p> -Note that when a new instance of an Activity is created to handle a new -intent, the user can always press the BACK key to return to the previous state -(to the previous activity). But when an existing instance of an -Activity handles a new intent, the user cannot press the BACK key to -return to what that instance was doing before the new intent arrived. -</p> - -<p> -For more on launch modes, see the description of the -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -element. -</p> - - -<h3 id="clearstack">Clearing the stack</h3> - -<p> -If the user leaves a task for a long time, the system clears the task of all -activities except the root activity. When the user returns to the task again, -it's as the user left it, except that only the initial activity is present. -The idea is that, after -a time, users will likely have abandoned what they were doing before and are -returning to the task to begin something new. -</p> - -<p> -That's the default. There are some activity attributes that can be used to -control this behavior and modify it: -</p> - -<dl> -<dt>The <code><a -href="{@docRoot}guide/topics/manifest/activity-element.html#always">alwaysRetainTaskState</a></code> -attribute</dt> -<dd>If this attribute is set to "{@code true}" in the root activity of a task, -the default behavior just described does not happen. -The task retains all activities in its stack even after a long period.</dd> - -<dt>The <code><a -href="{@docRoot}guide/topics/manifest/activity-element.html#clear">clearTaskOnLaunch</a></code> -attribute</dt> -<dd>If this attribute is set to "{@code true}" in the root activity of a task, -the stack is cleared down to the root activity whenever the user leaves the task -and returns to it. In other words, it's the polar opposite of -{@code alwaysRetainTaskState}. The user always returns to the task in its -initial state, even after a momentary absence.</dd> - -<dt>The <code><a -href="{@docRoot}guide/topics/manifest/activity-element.html#finish">finishOnTaskLaunch</a></code> -attribute</dt> -<dd>This attribute is like {@code clearTaskOnLaunch}, but it operates on a -single activity, not an entire task. And it can cause any activity to go -away, including the root activity. When it's set to "{@code true}", the -activity remains part of the task only for the current session. If the user -leaves and then returns to the task, it no longer is present.</dd> -</dl> - -<p> -There's another way to force activities to be removed from the stack. -If an Intent object includes the <code>{@link -android.content.Intent#FLAG_ACTIVITY_CLEAR_TOP FLAG_ACTIVITY_CLEAR_TOP}</code> -flag, and the target task already has an instance of the type of activity that -should handle the intent in its stack, all activities above that instance -are cleared away so that it stands at the top of the stack and can respond -to the intent. -If the launch mode of the designated activity is "{@code standard}", it too -will be removed from the stack, and a new instance will be launched to handle -the incoming intent. That's because a new instance is always created for -a new intent when the launch mode is "{@code standard}". -</p> - -<p> -{@code FLAG_ACTIVITY_CLEAR_TOP} is most often used in conjunction -with {@code FLAG_ACTIVITY_NEW_TASK}. When used together, these flags are -a way of locating an existing activity in another task and putting it in -a position where it can respond to the intent. -</p> - - -<h3 id="starttask">Starting tasks</h3> - -<p> -An activity is set up as the entry point for a task by giving it -an intent filter with "{@code android.intent.action.MAIN}" as the -specified action and "{@code android.intent.category.LAUNCHER}" as -the specified category. (There's an example of this type of filter -in the earlier <a href="#ifilters">Intent Filters</a> section.) -A filter of this kind causes an icon and label for the activity to be -displayed in the application launcher, giving users a way both to -launch the task and to return to it at any time after it has been -launched. -</p> - -<p> -This second ability is important: Users must be able to leave a task -and then come back to it later. For this reason, the two launch modes -that mark activities as always initiating a task, "{@code singleTask}" -and "{@code singleInstance}", should be used only when the activity has -a {@code MAIN} and {@code LAUNCHER} filter. -Imagine, for example, what could happen if the filter is missing: -An intent launches a "{@code singleTask}" activity, initiating a new task, -and the user spends some time working in that task. The user then presses -the HOME key. The task is now ordered behind and obscured by the home -screen. And, because it is not represented in the application launcher, -the user has no way to return to it. -</p> - -<p> -A similar difficulty attends the {@code FLAG_ACTIVITY_NEW_TASK} flag. -If this flag causes an activity to -begin a new task and the user presses the HOME key to leave it, there -must be some way for the user to navigate back to it again. Some -entities (such as the notification manager) always start activities -in an external task, never as part of their own, so they always put -{@code FLAG_ACTIVITY_NEW_TASK} in the intents they pass to -{@code startActivity()}. If you have an activity that can be invoked -by an external entity that might use this flag, take care that the user -has a independent way to get back to the task that's started. -</p> - -<p> -For those cases where you don't want the user to be able to return -to an activity, set the {@code <activity>} element's {@code -finishOnTaskLaunch} to "{@code true}". -See <a href="#clearstack">Clearing the stack</a>, earlier. -</p> - - -<h2 id="procthread">Processes and Threads</h2> - -<p> -When the first of an application's components needs to be run, Android -starts a Linux process for it with a single thread of execution. By default, -all components of the application run in that process and thread. -</p> - -<p> -However, you can arrange for components to run in other processes, and you -can spawn additional threads for any process. -</p> - - -<h3 id="procs">Processes</h3> - -<p> -The process where a component runs is controlled by the manifest file. -The component elements — {@code <activity>}, -{@code <service>}, {@code <receiver>}, and {@code <provider>} -— each have a {@code process} attribute that can specify a process -where that component should run. These attributes can be set so that each -component runs in its own process, or so that some components share a process -while others do not. They can also be set so that components of -different applications run in the same process — provided that the -applications share the same Linux user ID and are signed by the same authorities. -The {@code <application>} element also has a {@code process} attribute, -for setting a default value that applies to all components. -</p> - -<p> -All components are instantiated in the main thread of the specified -process, and system calls to the component are dispatched from that -thread. Separate threads are not created for each instance. Consequently, -methods that respond to those calls — methods like -<code>{@link android.view.View#onKeyDown View.onKeyDown()}</code> that report -user actions and the lifecycle notifications discussed later in the -<a href="#lcycles">Component Lifecycles</a> section — always run in the -main thread of the process. This means -that no component should perform long or blocking operations (such as networking -operations or computation loops) when called by the system, since this will block -any other components also in the process. You can spawn separate threads for -long operations, as discussed under <a href="#threads">Threads</a>, next. -</p> - -<p> -Android may decide to shut down a process at some point, when memory is -low and required by other processes that are more immediately serving -the user. Application components running in the process are consequently -destroyed. A process is restarted for those components when there's again -work for them to do. -</p> - -<p> -When deciding which processes to terminate, Android weighs their relative -importance to the user. For example, it more readily shuts down a process -with activities that are no longer visible on screen than a process with -visible activities. -The decision whether to terminate a process, therefore, depends on the state -of the components running in that process. Those states are the subject of -a later section, <a href="#lcycles">Component Lifecycles</a>. -</p> - - -<h3 id="threads">Threads</h3> - -<p> -Even though you may confine your application to a single process, there will -likely be times when you will need to spawn a thread to do some background -work. Since the user interface must always be quick to respond to user actions, -the thread that hosts an activity should not also host time-consuming operations -like network downloads. Anything that may not be completed quickly should be -assigned to a different thread. -</p> - -<p> -Threads are created in code using standard Java {@link java.lang.Thread} -objects. Android provides a number of convenience classes for managing -threads — {@link android.os.Looper} for running a message loop within -a thread, {@link android.os.Handler} for processing messages, and -{@link android.os.HandlerThread} for setting up a thread with a message loop. -</p> - - -<h3 id="rpc">Remote procedure calls</h3> - -<p> -Android has a lightweight mechanism for remote procedure calls (RPCs) -— where a method is called locally, but executed remotely (in another -process), with any result returned back to the caller. -This entails decomposing the method call and all its attendant data to a -level the operating system can understand, transmitting it from the local -process and address space to the remote process and address space, and -reassembling and reenacting the call there. Return values have to be -transmitted in the opposite direction. Android provides all the code -to do that work, so that you can concentrate on defining and implementing -the RPC interface itself. -</p> - -<p> -An RPC interface can include only methods. -All methods are executed synchronously (the local method blocks until the -remote method finishes), even if there is no return value. -</p> - -<p> -In brief, the mechanism works as follows: You'd begin by declaring the -RPC interface you want to implement using a simple IDL (interface definition -language). From that declaration, the -<code><a href="{@docRoot}guide/developing/tools/aidl.html">aidl</a></code> -tool generates a Java interface definition that must be made available to -both the local and the remote process. It contains two inner class, as shown -in the following diagram: -</p> - -<p style="margin-left: 2em"> -<img src="{@docRoot}images/binder_rpc.png" alt="RPC mechanism." /> -</p> - -<p> -The inner classes have all the code needed to administer remote procedure -calls for the interface you declared with the IDL. -Both inner classes implement the {@link android.os.IBinder} -interface. One of them is used locally and internally by the system; -the code you write can ignore it. -The other, called Stub, extends the {@link android.os.Binder} -class. In addition to internal code for effectuating the IPC calls, it -contains declarations for the methods in the RPC interface you declared. -You would subclass Stub to implement those methods, as indicated in the -diagram. -</p> - -<p> -Typically, the remote process would be managed by a service (because a -service can inform the system about the process and its connections to -other processes). It would have both the interface file generated by -the {@code aidl} tool and the Stub subclass implementing the -RPC methods. Clients of the service would have only the interface file -generated by the {@code aidl} tool. -</p> - -<p> -Here's how a connection between a service and its clients is set up: -</p> - -<ul> -<li>Clients of the service (on the local side) would implement -<code>{@link android.content.ServiceConnection#onServiceConnected -onServiceConnected()}</code> and -<code>{@link android.content.ServiceConnection#onServiceDisconnected -onServiceDisconnected()}</code> methods so they can be notified -when a successful connection to the remote service is established, and -when it goes away. They would then call -<code>{@link android.content.Context#bindService bindService()}</code> -to set up the connection. -</li> - -<li> -The service's <code>{@link android.app.Service#onBind onBind()}</code> -method would be implemented to either accept or reject the connection, -depending on the intent it receives (the intent passed to -{@code bindService()}). If the connection is accepted, it returns -an instance of the Stub subclass. -</li> - -<li>If the service accepts the connection, Android calls the -client's {@code onServiceConnected()} method and passes it an IBinder -object, a proxy for the Stub subclass managed by the service. Through -the proxy, the client can make calls on the remote service. -</li> -</ul> - -<p> -This brief description omits some details of the RPC mechanism. For more -information, see -<a href="{@docRoot}guide/developing/tools/aidl.html">Designing a Remote -Interface Using AIDL</a> and the {@link android.os.IBinder IBinder} class -description. -</p> - - -<h3 id="tsafe">Thread-safe methods</h3> - -<p> -In a few contexts, the methods you implement may be called from more -than one thread, and therefore must be written to be thread-safe. -</p> - -<p> -This is primarily true for methods that can be called remotely — -as in the RPC mechanism discussed in the previous section. -When a call on a method implemented in an IBinder object originates -in the same process as the IBinder, the method is executed in the -caller's thread. However, when the call originates in another process, -the method is executed in a thread chosen from a pool of threads that -Android maintains in the same process as the IBinder; it's not executed -in the main thread of the process. For example, whereas a service's -{@code onBind()} method would be called from the main thread of the -service's process, methods implemented in the object that {@code onBind()} -returns (for example, a Stub subclass that implements RPC methods) would -be called from threads in the pool. -Since services can have more than one client, more than one pool thread -can engage the same IBinder method at the same time. IBinder methods -must, therefore, be implemented to be thread-safe. -</p> - -<p> -Similarly, a content provider can receive data requests that originate in -other processes. Although the ContentResolver and ContentProvider classes -hide the details of how the interprocess communication is managed, -ContentProvider methods that respond to those requests — the methods -<code>{@link android.content.ContentProvider#query query()}</code>, -<code>{@link android.content.ContentProvider#insert insert()}</code>, -<code>{@link android.content.ContentProvider#delete delete()}</code>, -<code>{@link android.content.ContentProvider#update update()}</code>, and -<code>{@link android.content.ContentProvider#getType getType()}</code> -— are called from a pool of threads in the content provider's -process, not the main thread of the process. Since these methods -may be called from any number of threads at the same time, they too must -be implemented to be thread-safe. -</p> - - -<h2 id="lcycles">Component Lifecycles</h2> - -<p> -Application components have a lifecycle — a beginning when -Android instantiates them to respond to intents through to an end when -the instances are destroyed. In between, they may sometimes be active -or inactive,or, in the case of activities, visible to the user or -invisible. This section discusses the lifecycles of activities, -services, and broadcast receivers — including the states that they -can be in during their lifetimes, the methods that notify you of transitions -between states, and the effect of those states on the possibility that -the process hosting them might be terminated and the instances destroyed. -</p> - - -<h3 id="actlife">Activity lifecycle</h3> - -<p>An activity has essentially three states:</p> - -<ul> -<li> It is <em>active</em> or <em>running</em> when it is in the foreground of the -screen (at the top of the activity stack for the current task). This is the -activity that is the focus for the user's actions.</li> - -<li><p>It is <em>paused</em> if it has lost focus but is still visible to the user. -That is, another activity lies on top of it and that activity either is transparent -or doesn't cover the full screen, so some of the paused activity can show through. -A paused activity is completely alive (it maintains all state and member information -and remains attached to the window manager), but can be killed by the system in -extreme low memory situations.</p></li> - -<li><p>It is <em>stopped</em> if it is completely obscured by another activity. -It still retains all state and member information. However, it is no longer -visible to the user so its window is hidden and it will often be killed by the -system when memory is needed elsewhere.</p></li> -</ul> - -<p> -If an activity is paused or stopped, the system can drop it from memory either -by asking it to finish (calling its {@link android.app.Activity#finish finish()} -method), or simply killing its process. When it is displayed again -to the user, it must be completely restarted and restored to its previous state. -</p> - -<p> -As an activity transitions from state to state, it is notified of the change -by calls to the following protected methods: -</p> - -<p style="margin-left: 2em">{@code void onCreate(Bundle <i>savedInstanceState</i>)} -<br/>{@code void onStart()} -<br/>{@code void onRestart()} -<br/>{@code void onResume()} -<br/>{@code void onPause()} -<br/>{@code void onStop()} -<br/>{@code void onDestroy()}</p> - -<p> -All of these methods are hooks that you can override to do appropriate work -when the state changes. All activities must implement -<code>{@link android.app.Activity#onCreate onCreate()}</code> to do the -initial setup when the object is first instantiated. -Many will also implement <code>{@link android.app.Activity#onPause onPause()}</code> -to commit data changes and otherwise prepare to stop interacting with the user. -</p> - -<div class="sidebox-wrapper"> -<div class="sidebox-inner"> -<h2>Calling into the superclass</h2> -<p> -An implementation of any activity lifecycle method should always first -call the superclass version. For example: -</p> - -<pre>protected void onPause() { - super.onPause(); - . . . -}</pre> -</div> -</div> - - -<p> -Taken together, these seven methods define the entire lifecycle of an -activity. There are three nested loops that you can monitor by -implementing them: -</p> - -<ul> -<li>The <b>entire lifetime</b> of an activity happens between the first call -to <code>{@link android.app.Activity#onCreate onCreate()}</code> through to a -single final call to <code>{@link android.app.Activity#onDestroy}</code>. -An activity does all its initial setup of "global" state in {@code onCreate()}, -and releases all remaining resources in {@code onDestroy()}. For example, -if it has a thread running in the background to download data from the network, -it may create that thread in {@code onCreate()} and then stop the thread in -{@code onDestroy()}.</li> - -<li><p>The <b>visible lifetime</b> of an activity happens between a call to -<code>{@link android.app.Activity#onStart onStart()}</code> until a -corresponding call to <code>{@link android.app.Activity#onStop onStop()}</code>. -During this time, the user can see the activity on-screen, though it may not -be in the foreground and interacting with the user. Between these two methods, -you can maintain resources that are needed to show the activity to the user. -For example, you can register a {@link android.content.BroadcastReceiver} in -{@code onStart()} to monitor for changes that impact your UI, and unregister -it in {@code onStop()} when the user can no longer see what you are displaying. -The {@code onStart()} and {@code onStop()} methods can be called multiple times, -as the activity alternates between being visible and hidden to the user.</p></li> - -<li><p>The <b>foreground lifetime</b> of an activity happens between a call -to <code>{@link android.app.Activity#onResume onResume()}</code> until a -corresponding call to <code>{@link android.app.Activity#onPause onPause()}</code>. -During this time, the activity is in front of all other activities on screen and -is interacting with the user. An activity can frequently transition between the -resumed and paused states — for example, {@code onPause()} is called when -the device goes to sleep or when a new activity is started, {@code onResume()} -is called when an activity result or a new intent is delivered. Therefore, the -code in these two methods should be fairly lightweight.</p></li> -</ul> - -<p> -The following diagram illustrates these loops and the paths an activity -may take between states. The colored ovals are major states the activity -can be in. The square rectangles represent the callback methods you can implement -to perform operations when the activity transitions between states. -<p> - -<p style="margin-left: 2em"><img src="{@docRoot}images/activity_lifecycle.png" -alt="State diagram for an Android activity lifecycle." /></p> - -<p> -The following table describes each of these methods in more detail and -locates it within the activity's overall lifecycle: -</p> - -<table border="2" width="85%" frame="hsides" rules="rows"> -<colgroup align="left" span="3"></colgroup> -<colgroup align="left"></colgroup> -<colgroup align="center"></colgroup> -<colgroup align="center"></colgroup> - -<thead> -<tr><th colspan="3">Method</th> <th>Description</th> <th>Killable?</th> <th>Next</th></tr> -</thead> - -<tbody> -<tr> - <td colspan="3" align="left"><code>{@link android.app.Activity#onCreate onCreate()}</code></td> - <td>Called when the activity is first created. - This is where you should do all of your normal static set up — - create views, bind data to lists, and so on. This method is passed - a Bundle object containing the activity's previous state, if that - state was captured (see <a href="#actstate">Saving Activity State</a>, - later). - <p>Always followed by {@code onStart()}.</p></td> - <td align="center">No</td> - <td align="center">{@code onStart()}</td> -</tr> - -<tr> - <td rowspan="5" style="border-left: none; border-right: none;"> </td> - <td colspan="2" align="left"><code>{@link android.app.Activity#onRestart -onRestart()}</code></td> - <td>Called after the activity has been stopped, just prior to it being - started again. - <p>Always followed by {@code onStart()}</p></td> - <td align="center">No</td> - <td align="center">{@code onStart()}</td> -</tr> - -<tr> - <td colspan="2" align="left"><code>{@link android.app.Activity#onStart onStart()}</code></td> - <td>Called just before the activity becomes visible to the user. - <p>Followed by {@code onResume()} if the activity comes - to the foreground, or {@code onStop()} if it becomes hidden.</p></td> - <td align="center">No</td> - <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td> -</tr> - -<tr> - <td rowspan="2" style="border-left: none;"> </td> - <td align="left"><code>{@link android.app.Activity#onResume onResume()}</code></td> - <td>Called just before the activity starts - interacting with the user. At this point the activity is at - the top of the activity stack, with user input going to it. - <p>Always followed by {@code onPause()}.</p></td> - <td align="center">No</td> - <td align="center">{@code onPause()}</td> -</tr> - -<tr> - <td align="left"><code>{@link android.app.Activity#onPause onPause()}</code></td> - <td>Called when the system is about to start resuming another - activity. This method is typically used to commit unsaved changes to - persistent data, stop animations and other things that may be consuming - CPU, and so on. It should do whatever it does very quickly, because - the next activity will not be resumed until it returns. - <p>Followed either by {@code onResume()} if the activity - returns back to the front, or by {@code onStop()} if it becomes - invisible to the user.</td> - <td align="center"><strong style="color:#800000">Yes</strong></td> - <td align="center">{@code onResume()} <br/>or<br/> {@code onStop()}</td> -</tr> - -<tr> - <td colspan="2" align="left"><code>{@link android.app.Activity#onStop onStop()}</code></td> - <td>Called when the activity is no longer visible to the user. This - may happen because it is being destroyed, or because another activity - (either an existing one or a new one) has been resumed and is covering it. - <p>Followed either by {@code onRestart()} if - the activity is coming back to interact with the user, or by - {@code onDestroy()} if this activity is going away.</p></td> - <td align="center"><strong style="color:#800000">Yes</strong></td> - <td align="center">{@code onRestart()} <br/>or<br/> {@code onDestroy()}</td> -</tr> - -<tr> - <td colspan="3" align="left"><code>{@link android.app.Activity#onDestroy -onDestroy()}</code></td> - <td>Called before the activity is destroyed. This is the final call - that the activity will receive. It could be called either because the - activity is finishing (someone called <code>{@link android.app.Activity#finish - finish()}</code> on it), or because the system is temporarily destroying this - instance of the activity to save space. You can distinguish - between these two scenarios with the <code>{@link - android.app.Activity#isFinishing isFinishing()}</code> method.</td> - <td align="center"><strong style="color:#800000">Yes</strong></td> - <td align="center"><em>nothing</em></td> -</tr> -</tbody> -</table> - -<p> -Note the <b>Killable</b> column in the table above. It indicates -whether or not the system can kill the process hosting the activity -<em>at any time after the method returns, without executing another -line of the activity's code</em>. Three methods ({@code onPause()}, -{@code onStop()}, and {@code onDestroy()}) are marked "Yes." Because -{@code onPause()} is the first of the three, it's the only one that's -guaranteed to be called before the process is killed — -{@code onStop()} and {@code onDestroy()} may not be. Therefore, you -should use {@code onPause()} to write any persistent data (such as user -edits) to storage. -</p> - -<p> -Methods that are marked "No" in the <b>Killable</b> column protect the -process hosting the activity from being killed from the moment they are -called. Thus an activity is in a killable state, for example, from the -time {@code onPause()} returns to the time {@code onResume()} is called. -It will not again be killable until {@code onPause()} again returns. -</p> - -<p> -As noted in a later section, <a href="#proclife">Processes and lifecycle</a>, -an activity that's not technically "killable" by this definition might -still be killed by the system — but that would happen only in -extreme and dire circumstances when there is no other recourse. -</p> - - -<h4 id="actstate">Saving activity state</h4> - -<p> -When the system, rather than the user, shuts down an activity to conserve -memory, the user may expect to return to the activity and find it in its -previous state. -</p> - -<p> -To capture that state before the activity is killed, you can implement -an <code>{@link android.app.Activity#onSaveInstanceState -onSaveInstanceState()}</code> method for the activity. Android calls this -method before making the activity vulnerable to being destroyed — -that is, before {@code onPause()} is called. It -passes the method a {@link android.os.Bundle} object where you can record -the dynamic state of the activity as name-value pairs. When the activity is -again started, the Bundle is passed both to {@code onCreate()} and to a -method that's called after {@code onStart()}, <code>{@link -android.app.Activity#onRestoreInstanceState onRestoreInstanceState()}</code>, -so that either or both of them can recreate the captured state. -</p> - -<p> -Unlike {@code onPause()} and the other methods discussed earlier, -{@code onSaveInstanceState()} and {@code onRestoreInstanceState()} are -not lifecycle methods. They are not always called. For example, Android -calls {@code onSaveInstanceState()} before the activity becomes -vulnerable to being destroyed by the system, but does not bother -calling it when the instance is actually being destroyed by a user action -(such as pressing the BACK key). In that case, the user won't expect to -return to the activity, so there's no reason to save its state. -</p> - -<p> -Because {@code onSaveInstanceState()} is not always called, you should -use it only to record the transient state of the activity, not to store -persistent data. Use {@code onPause()} for that purpose instead. -</p> - - -<h4 id="coordact">Coordinating activities</h4> - -<p> -When one activity starts another, they both experience lifecycle -transitions. One pauses and may stop, while the other starts up. -On occasion, you may need to coordinate these activities, one with -the other. -</p> - -<p> -The order of lifecycle callbacks is well defined, -particularly when the two activities are in the same process: -</p> - -<ol> -<li>The current activity's {@code onPause()} method is called.</li> - -<li>Next, the starting activity's {@code onCreate()}, {@code onStart()}, -and {@code onResume()} methods are called in sequence.</li> - -<li>Then, if the starting activity is no longer visible -on screen, its {@code onStop()} method is called.</li> -</ol> - - -<h3 id="servlife">Service lifecycle</h3> - -<p> -A service can be used in two ways: -</p> - -<ul> -<li>It can be started and allowed to run until someone stops it or -it stops itself. In this mode, it's started by calling -<code>{@link android.content.Context#startService Context.startService()}</code> -and stopped by calling -<code>{@link android.content.Context#stopService Context.stopService()}</code>. -It can stop itself by calling -<code>{@link android.app.Service#stopSelf() Service.stopSelf()}</code> or -<code>{@link android.app.Service#stopSelfResult Service.stopSelfResult()}</code>. -Only one {@code stopService()} call is needed to stop the service, no matter how -many times {@code startService()} was called.</li> - -<li><p>It can be operated programmatically using an interface that -it defines and exports. Clients establish a connection to the Service -object and use that connection to call into the service. The connection is -established by calling -<code>{@link android.content.Context#bindService Context.bindService()}</code>, -and is closed by calling -<code>{@link android.content.Context#unbindService Context.unbindService()}</code>. -Multiple clients can bind to the same service. -If the service has not already been launched, {@code bindService()} can optionally -launch it. -</p></li> -</ul> - -<p> -The two modes are not entirely separate. You can bind to a service that -was started with {@code startService()}. For example, a background music -service could be started by calling {@code startService()} with an Intent -object that identifies the music to play. Only later, possibly when the -user wants to exercise some control over the player or get information -about the current song, would an activity -establish a connection to the service by calling {@code bindService()}. -In cases like this, {@code stopService()} -will not actually stop the service until the last binding is closed. -</p> - -<p> -Like an activity, a service has lifecycle methods that you can implement -to monitor changes in its state. But they are fewer than the activity -methods — only three — and they are public, not protected: -</p> - -<p style="margin-left: 2em">{@code void onCreate()} -<br/>{@code void onStart(Intent <i>intent</i>)} -<br/>{@code void onDestroy()}</p> - -<p> -By implementing these methods, you can monitor two nested loops of the -service's lifecycle: -</p> - -<ul> -<li>The <b>entire lifetime</b> of a service happens between the time -<code>{@link android.app.Service#onCreate onCreate()}</code> is called and -the time <code>{@link android.app.Service#onDestroy}</code> returns. -Like an activity, a service does its initial setup in {@code onCreate()}, -and releases all remaining resources in {@code onDestroy()}. For example, -a music playback service could create the thread where the music will be played -in {@code onCreate()}, and then stop the thread in {@code onDestroy()}.</li> - -<li><p>The <b>active lifetime</b> of a service begins with a call to -<code>{@link android.app.Service#onStart onStart()}</code>. This method -is handed the Intent object that was passed to {@code startService()}. -The music service would open the Intent to discover which music to -play, and begin the playback.</p> - -<p> -There's no equivalent callback for when the service stops — no -{@code onStop()} method. -</p></li> -</ul> - -<p> -The {@code onCreate()} and {@code onDestroy()} methods are called for all -services, whether they're started by -<code>{@link android.content.Context#startService Context.startService()}</code> -or -<code>{@link android.content.Context#bindService Context.bindService()}</code>. -However, {@code onStart()} is called only for services started by {@code -startService()}. -</p> - -<p> -If a service permits others to -bind to it, there are additional callback methods for it to implement: -</p> - -<p style="margin-left: 2em">{@code IBinder onBind(Intent <i>intent</i>)} -<br/>{@code boolean onUnbind(Intent <i>intent</i>)} -<br/>{@code void onRebind(Intent <i>intent</i>)}</p> - -<p> -The <code>{@link android.app.Service#onBind onBind()}</code> callback is passed -the Intent object that was passed to {@code bindService} and -<code>{@link android.app.Service#onUnbind onUnbind()}</code> is handed -the intent that was passed to {@code unbindService()}. -If the service permits the binding, {@code onBind()} -returns the communications channel that clients use to interact with the service. -The {@code onUnbind()} method can ask for -<code>{@link android.app.Service#onRebind onRebind()}</code> -to be called if a new client connects to the service. -</p> - -<p> -The following diagram illustrates the callback methods for a service. -Although, it separates services that are created via {@code startService} -from those created by {@code bindService()}, keep in mind that any service, -no matter how it's started, can potentially allow clients to bind to it, -so any service may receive {@code onBind()} and {@code onUnbind()} calls. -</p> - -<p style="margin-left: 2em"><img src="{@docRoot}images/service_lifecycle.png" -alt="State diagram for Service callbacks." /></p> - - -<h3 id="broadlife">Broadcast receiver lifecycle</h3> - -<p> -A broadcast receiver has single callback method: -</p> - -<p style="margin-left: 2em">{@code void onReceive(Context <i>curContext</i>, Intent <i>broadcastMsg</i>)}</p> - -<p> -When a broadcast message arrives for the receiver, Android calls its -<code>{@link android.content.BroadcastReceiver#onReceive onReceive()}</code> -method and passes it the Intent object containing the message. The broadcast -receiver is considered to be active only while it is executing this method. -When {@code onReceive()} returns, it is inactive. -</p> - -<p> -A process with an active broadcast receiver is protected from being killed. -But a process with only inactive components can be killed by the system at -any time, when the memory it consumes is needed by other processes. -</p> - -<p> -This presents a problem when the response to a broadcast message is time -consuming and, therefore, something that should be done in a separate thread, -away from the main thread where other components of the user interface run. -If {@code onReceive()} spawns the thread and then returns, the entire process, -including the new thread, is judged to be inactive (unless other application -components are active in the process), putting it in jeopardy of being killed. -The solution to this problem is for {@code onReceive()} to start a service -and let the service do the job, so the -system knows that there is still active work being done in the process. -</p> - -<p> -The next section has more on the vulnerability of processes to being killed. -</p> - - -<h3 id="proclife">Processes and lifecycles</h3> - -<p>The Android system tries to maintain an application process for as -long as possible, but eventually it will need to remove old processes when -memory runs low. To determine which processes to keep and which to kill, -Android places each process into an "importance hierarchy" based on the -components running in it and the state of those components. Processes -with the lowest importance are eliminated first, then those with the next -lowest, and so on. There are five levels in the hierarchy. The following -list presents them in order of importance: -</p> - -<ol> - -<li>A <b>foreground process</b> is one that is required for -what the user is currently doing. A process is considered to be -in the foreground if any of the following conditions hold: - -<ul> -<li>It is running an activity that the user is interacting with -(the Activity object's <code>{@link android.app.Activity#onResume -onResume()}</code> method has been called).</li> - -<li><p>It hosts a service that's bound -to the activity that the user is interacting with.</p></li> - -<li><p>It has a {@link android.app.Service} object that's executing -one of its lifecycle callbacks (<code>{@link android.app.Service#onCreate -onCreate()}</code>, <code>{@link android.app.Service#onStart onStart()}</code>, -or <code>{@link android.app.Service#onDestroy onDestroy()}</code>).</p></li> - -<li><p>It has a {@link android.content.BroadcastReceiver} object that's -executing its <code>{@link android.content.BroadcastReceiver#onReceive -onReceive()}</code> method.</p></li> -</ul> - -<p> -Only a few foreground processes will exist at any given time. They -are killed only as a last resort — if memory is so low that -they cannot all continue to run. Generally, at that point, the device has -reached a memory paging state, so killing some foreground processes is -required to keep the user interface responsive. -</p></li> - -<li><p>A <b>visible process</b> is one that doesn't have any foreground -components, but still can affect what the user sees on screen. -A process is considered to be visible if either of the following conditions -holds:</p> - -<ul> -<li>It hosts an activity that is not in the foreground, but is still visible -to the user (its <code>{@link android.app.Activity#onPause onPause()}</code> -method has been called). This may occur, for example, if the foreground -activity is a dialog that allows the previous activity to be seen behind it.</li> - -<li><p>It hosts a service that's bound to a visible activity.</p></li> -</ul> - -<p> -A visible process is considered extremely important and will not be killed -unless doing so is required to keep all foreground processes running. -</p></li> - -<li><p>A <b>service process</b> is one that is running a service that -has been started with the -<code>{@link android.content.Context#startService startService()}</code> -method and that does not fall into either of the two higher categories. -Although service processes are not directly tied to anything the -user sees, they are generally doing things that the user cares about (such -as playing an mp3 in the background or downloading data on the network), -so the system keeps them running unless there's not enough -memory to retain them along with all foreground and visible processes. -</p></li> - -<li><p>A <b>background process</b> is one holding an activity -that's not currently visible to the user (the Activity object's -<code>{@link android.app.Activity#onStop onStop()}</code> method has been called). -These processes have no direct impact on the user experience, and can be killed -at any time to reclaim memory for a foreground, visible, or service process. -Usually there are many background processes running, so they are kept in an -LRU (least recently used) list to ensure that the process with the activity that -was most recently seen by the user is the last to be killed. -If an activity implements its lifecycle methods correctly, and captures its current -state, killing its process will not have a deleterious effect on the user experience. -</p></li> - -<li><p>An <b>empty process</b> is one that doesn't hold any active application -components. The only reason to keep such a process around is as a cache to -improve startup time the next time a component needs to run in it. The system -often kills these processes in order to balance overall system resources between -process caches and the underlying kernel caches.</p></li> - -</ol> - -<p> -Android ranks a process at the highest level it can, based upon the -importance of the components currently active in the process. For example, -if a process hosts a service and a visible activity, the process will be -ranked as a visible process, not a service process. -</p> - -<p> -In addition, a process's ranking may be increased because other processes are -dependent on it. A process that is serving another process can never be -ranked lower than the process it is serving. For example, if a content -provider in process A is serving a client in process B, or if a service in -process A is bound to a component in process B, process A will always be -considered at least as important as process B. -</p> - -<p> -Because a process running a service is ranked higher than one with background -activities, an activity that initiates a long-running operation might do -well to start a service for that operation, rather than simply spawn a thread -— particularly if the operation will likely outlast the activity. -Examples of this are playing music in the background -and uploading a picture taken by the camera to a web site. Using a service -guarantees that the operation will have at least "service process" priority, -regardless of what happens to the activity. As noted in the -<a href="#broadlife">Broadcast receiver lifecycle</a> section earlier, this -is the same reason that broadcast receivers should employ services rather -than simply put time-consuming operations in a thread. -</p> diff --git a/docs/html/guide/topics/geo/lbs.jd b/docs/html/guide/topics/geo/lbs.jd deleted file mode 100644 index 981f6fe..0000000 --- a/docs/html/guide/topics/geo/lbs.jd +++ /dev/null @@ -1,73 +0,0 @@ -page.title=Location-based Service APIs -@jd:body - -<p>The Android SDK includes two packages that provide Android's primary support -for building location-based services: -{@link android.location} and com.google.android.maps. -Please read on below for a brief introduction to each package.</p> - -<h2>android.location</h2> - -<p>This package contains several classes related to -location services in the Android platform. Most importantly, it introduces the -{@link android.location.LocationManager} -service, which provides an API to determine location and bearing if the -underlying device (if it supports the service). The LocationManager -should <strong>not</strong> be -instantiated directly; rather, a handle to it should be retrieved via -{@link android.content.Context#getSystemService(String) -getSystemService(Context.LOCATION_SERVICE)}.</p> - -<p>Once your application has a handle to the LocationManager, your application -will be able to do three things:</p> - -<ul> - <li>Query for the list of all LocationProviders known to the - LocationManager for its last known location.</li> - <li>Register/unregister for periodic updates of current location from a - LocationProvider (specified either by Criteria or name).</li> - <li>Register/unregister for a given Intent to be fired if the device comes - within a given proximity (specified by radius in meters) of a given - lat/long.</li> -</ul> - -<p>However, during initial development, you may not have access to real -data from a real location provider (Network or GPS). So it may be necessary to -spoof some data for your application, with some mock location data.</p> - -<p class="note"><strong>Note:</strong> If you've used mock LocationProviders in -previous versions of the SDK (m3/m5), you can no longer provide canned LocationProviders -in the /system/etc/location directory. These directories will be wiped during boot-up. -Please follow the new procedures below.</p> - - -<h3>Providing Mock Location Data</h3> - -<p>When testing your application on the Android emulator, there are a couple different -ways to send it some spoof location data: with the DDMS tool or the "geo" command.</p> - -<h4 id="ddms">Using DDMS</h4> -<p>With the DDMS tool, you can simulate location data a few different ways:</p> -<ul> - <li>Manually send individual longitude/latitude coordinates to the device.</li> - <li>Use a GPX file describing a route for playback to the device.</li> - <li>Use a KML file describing individual placemarks for sequenced playback to the device.</li> -</ul> -<p>For more information on using DDMS to spoof location data, see the -<a href="{@docRoot}reference/ddms.html#emulator-control">Using DDMS guide</a>. - -<h4 id="geo">Using the "geo" command</h4> -<p>Launch your application in the Android emulator and open a terminal/console in -your SDK's <code>/tools</code> directory. Now you can use:</p> -<ul><li><code>geo fix</code> to send a fixed geo-location. - <p>This command accepts a longitude and latitude in decimal degrees, and - an optional altitude in meters. For example:</p> - <pre>geo fix -121.45356 46.51119 4392</pre> - </li> - <li><code>geo nmea</code> to send an NMEA 0183 sentence. - <p>This command accepts a single NMEA sentence of type '$GPGGA' (fix data) or '$GPRMC' (transit data). - For example:</p> - <pre>geo nmea $GPRMC,081836,A,3751.65,S,14507.36,E,000.0,360.0,130998,011.3,E*62</pre> - </li> -</ul> - diff --git a/docs/html/guide/topics/geo/mapkey.jd b/docs/html/guide/topics/geo/mapkey.jd deleted file mode 100644 index 6442940..0000000 --- a/docs/html/guide/topics/geo/mapkey.jd +++ /dev/null @@ -1,28 +0,0 @@ -page.title=Obtaining a MapView API Key -@jd:body - -<p>MapView is a very useful class that lets you easily integrate Google Maps into your application. It provides built-in map downloading, rendering, and caching, as well as a variety of display options and controls. It provides a wrapper around the Google Maps API that lets your application request and manipulate Google Maps data through class methods, and it lets you work with Maps data as you would other types of Views. </p> - -<p>Because MapView gives you access to Google Maps data, you need to register your application with the Google Maps service and agree to the applicable Terms of Service, before your MapView will be able to obtain data from Google Maps. This will apply whether you are developing your application on the emulator or preparing your application for deployment to mobile devices. </p> - -<p>Registering your application is simple, and has two parts: </p> - -<ol> -<li>Registering a public key fingerprint from the certificate that you will use to sign the .apk. The registration service then provides you a Maps API Key that is associated with your application's signer certificate. </li> -<li>Adding the Maps API Key to a special attribute of the MapView element — <code>android:apiKey</code>. You can use the same Maps API Key for any MapView in any application, provided that the application's .apk is signed with the certificate whose fingerprint you registered with the service. </li> -</ol> - -<p>Once you have registered your application as described above, your MapView will be able to retrieve data from the Google Maps servers. </p> - -<div class="special"> -<p>The MapView registration service is not yet active and Google Maps is not yet enforcing the Maps API Key requirement. The registration service will be activated soon, so that MapViews in any application deployed to a mobile device will require registration and a valid Maps API Key.</p> - -<p>As soon as the registration service becomes available, this page (<a href="http://code.google.com/android/toolbox/apis/mapkey.html">http://code.google.com/android/toolbox/apis/mapkey.html</a>) will be updated with details about how and where to register and how to add your Maps API Key to your application. </p> - -<p>In the meantime, you can continue developing your MapView without registration, provided that you:</p> -<ol type="a"> -<li>Add the attribute "android:apiKey" to the MapView element in your layout XML, with any value. Or</li> -<li>Include an arbitrary string in the <code>apikey</code> parameter of the MapView constructor, if creating the MapView programmatically. </li> -</ol> - -<p>When the Maps API Key checking is activated in the service, any MapViews that do not have a properly registered apiKey will stop working. The map data (tile images) of the MapView will never load (even if the device is on the network). In this case, go to the page linked above and read about how to register your certificate fingerprint and obtain a Maps API Key. </p> diff --git a/docs/html/guide/topics/graphics/2d-graphics.jd b/docs/html/guide/topics/graphics/2d-graphics.jd deleted file mode 100644 index a72962e..0000000 --- a/docs/html/guide/topics/graphics/2d-graphics.jd +++ /dev/null @@ -1,480 +0,0 @@ -page.title=2D Graphics -parent.title=2D and 3D Graphics -parent.link=index.html -@jd:body - - -<div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#drawables">Drawables</a> - <ol> - <li><a href="#drawable-images">Creating from resource images</a></li> - <li><a href="#drawable-xml">Creating from resource XML</a></li> - </ol> - </li> - <li><a href="#shape-drawable">ShapeDrawable</a></li> - <!-- <li><a href="#state-list">StateListDrawable</a></li> --> - <li><a href="#nine-patch">NinePatchDrawable</a></li> - <li><a href="#tween-animation">Tween Animation</a></li> - <li><a href="#frame-animation">Frame Animation</a></li> - </ol> - </div> -</div> - -<p>Android offers a custom 2D graphics library for drawing and animating shapes and images. -The {@link android.graphics.drawable} and {@link android.view.animation} -packages are where you'll find the common classes used for drawing and animating in two-dimensions. -</p> - -<p>This document offers an introduction to drawing graphics in your Android application. -We'll discuss the basics of using Drawable objects to draw -graphics, how to use a couple subclasses of the Drawable class, and how to -create animations that either tween (move, stretch, rotate) a single graphic -or animate a series of graphics (like a roll of film).</p> - - -<h2 id="drawables">Drawables</h2> - -<p>A {@link android.graphics.drawable.Drawable} is a general abstraction for "something that can be drawn." -You'll discover that the Drawable class extends to define a variety of specific kinds of drawable graphics, -including {@link android.graphics.drawable.BitmapDrawable}, {@link android.graphics.drawable.ShapeDrawable}, -{@link android.graphics.drawable.PictureDrawable}, {@link android.graphics.drawable.LayerDrawable}, and several more. -Of course, you can also extend these to define your own custom Drawable objects that behave in unique ways.</p> - -<p>There are three ways to define and instantiate a Drawable: using an image saved in your project resouces; -using an XML file that defines the Drawable properties; or using the normal class constructors. Below, we'll discuss -each the first two techniques (using constructors is nothing new for an experienced developer).</p> - - -<h3 id="drawables-from-images">Creating from resource images</h3> - -<p>A simple way to add graphics to your application is by referencing an image file from your project resources. -Supported file types are PNG (preferred), JPG (acceptable) and GIF (discouraged). This technique would -obviously be preferred for application icons, logos, or other graphics such as those used in a game.</p> - -<p>To use an image resource, just add your file to the <code>res/drawable/</code> directory of your project. -From there, you can reference it from your code or your XML layout. -Either way, it is referred using a resource ID, which is the file name without the file type -extension (E.g., <code>my_image.png</code> is referenced as <var>my_image</var>).</p> - -<h4>Example code</h4> -<p>The following code snippet demonstrates how to build an {@link android.widget.ImageView} that uses an image -from drawable resources and add it to the layout.</p> -<pre> -LinearLayout mLinearLayout; - -protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - - // Create a LinearLayout in which to add the ImageView - mLinearLayout = new LinearLayout(this); - - // Instantiate an ImageView and define its properties - ImageView i = new ImageView(this); - i.setImageResource(R.drawable.my_image); - i.setAdjustViewBounds(true); // set the ImageView bounds to match the Drawable's dimensions - i.setLayoutParams(new Gallery.LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT)); - - // Add the ImageView to the layout and set the layout as the content view - mLinearLayout.addView(i); - setContentView(mLinearLayout); -} -</pre> -<p>In other cases, you may want to handle your image resource as a -{@link android.graphics.drawable.Drawable} object. -To do so, create a Drawable from the resource like so: -<pre>Drawable myImage = Resources.getDrawable(R.drawable.my_image);</pre> - -<p class="caution"><strong>Caution:</strong> Each unique resource in your project can maintain only one -state, no matter how many different objects you may instantiate for it. For example, if you instantiate two -Drawable objects from the same image resource, then change a property (such as the alpha) for one of the -Drawables, then it will also affect the other. So when dealing with multiple instances of an image resource, -instead of directly transforming the Drawable, you should perform a <a href="#tween-animation">tween animation</a>.</p> - - -<h4>Example XML</h4> -<p>The XML snippet below shows how to add a resource Drawable to an -{@link android.widget.ImageView} in the XML layout (with some red tint just for fun). -<pre> -<ImageView - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:tint="#55ff0000" - android:src="@drawable/my_image"/> -</pre> -<p>For more information on using project resources, read about - <a href="{@docRoot}guide/topics/resources/index.html">Resources and Assets</a>.</p> - - -<h3 id="drawables-from-xml">Creating from resource XML</h3> - -<p>By now, you should be familiar with Android's principles of developing a -<a href="{@docRoot}guide/topics/ui/index.html">User Interface</a>. Hence, you understand the power -and flexibility inherent in defining objects in XML. This philosophy caries over from Views to Drawables. -If there is a Drawable object that you'd like to create, which is not initially dependent on variables defined by -your applicaton code or user interaction, then defining the Drawable in XML is a good option. -Even if you expect your Drawable to change its properties during the user's experience with your application, -you should consider defining the object in XML, as you can always modify properties once it is instantiated.</p> - -<p>Once you've defined your Drawable in XML, save the file in the <code>res/drawable/</code> directory of -your project. Then, retrieve and instantiate the object by calling -{@link android.content.res.Resources#getDrawable(int) Resources.getDrawable()}, passing it the resource ID -of your XML file. (See the <a href="#drawable-xml-example">example below</a>.)</p> - -<p>Any Drawable subclass that supports the <code>inflate()</code> method can be defined in -XML and instantiated by your application. -Each Drawable that supports XML inflation utilizes specific XML attributes that help define the object -properties (see the class reference to see what these are). See the class documentation for each -Drawable subclass for information on how to define it in XML. - -<h4 id="drawable-xml-example">Example</h4> -<p>Here's some XML that defines a TransitionDrawable:</p> -<pre> -<transition xmlns:android="http://schemas.android.com/apk/res/android"> - <item android:drawable="@drawable/image_expand"> - <item android:drawable="@drawable/image_collapse"> -</transition> -</pre> - -<p>With this XML saved in the file <code>res/drawable/expand_collapse.xml</code>, -the following code will instantiate the TransitionDrawable and set it as the content of an ImageView:</p> -<pre> -Resources res = mContext.getResources(); -TransitionDrawable transition = (TransitionDrawable) res.getDrawable(R.drawable.expand_collapse); -ImageView image = (ImageView) findViewById(R.id.toggle_image); -image.setImageDrawable(transition); -</pre> -<p>Then this transition can be run forward (for 1 second) with:</p> -<pre>transition.startTransition(1000);</pre> - -<p>Refer to the Drawable classes listed above for more information on the XML attributes supported by each.</p> - - - -<h2 id="shape-drawable">ShapeDrawable</h2> - -<p>When you want to dynamically draw some two-dimensional graphics, a {@link android.graphics.drawable.ShapeDrawable} -object will probably suit your needs. With a ShapeDrawable, you can programmatically draw -primitive shapes and style them in any way imaginable.</p> - -<p>A ShapeDrawable is an extension of {@link android.graphics.drawable.Drawable}, so you can use one where ever -a Drawable is expected — perhaps for the background of a View, set with -{@link android.view.View#setBackgroundDrawable(android.graphics.drawable.Drawable) setBackgroundDrawable()}. -Of course, you can also draw your shape as its own custom {@link android.view.View}, -to be added to your layout however you please. -Because the ShapeDrawable has its own <code>draw()</code> method, you can create a subclass of View that -draws the ShapeDrawable during the <code>View.onDraw()</code> method. -Here's a basic extension of the View class that does just this, to draw a ShapeDrawable as a View:</p> -<pre> -public class CustomDrawableView extends View { - private ShapeDrawable mDrawable; - - public CustomDrawableView(Context context) { - super(context); - - int x = 10; - int y = 10; - int width = 300; - int height = 50; - - mDrawable = new ShapeDrawable(new OvalShape()); - mDrawable.getPaint().setColor(0xff74AC23); - mDrawable.setBounds(x, y, x + width, y + height); - } - - protected void onDraw(Canvas canvas) { - mDrawable.draw(canvas); - } -} -</pre> - -<p>In the constructor, a ShapeDrawable is defines as an {@link android.graphics.drawable.shapes.OvalShape}. -It's then given a color and the bounds of the shape are set. If you do not set the bounds, then the -shape will not be drawn, whereas if you don't set the color, it will default to black.</p> -<p>With the custom View defined, it can be drawn any way you like. With the sample above, we can -draw the shape progammatically in an Activity:</p> -<pre> -CustomDrawableView mCustomDrawableView; - -protected void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - mCustomDrawableView = new CustomDrawableView(this); - - setContentView(mCustomDrawableView); -} -</pre> - -<p>If you'd like to draw this custom drawable from the XML layout instead of from the Activity, -then the CustomDrawable class must override the {@link android.view.View#View(android.content.Context, android.util.AttributeSet) View(Context, AttributeSet)} constructor, which is called when -instantiating a View via inflation from XML. Then add a CustomDrawable element to the XML, -like so:</p> -<pre> -<com.example.shapedrawable.CustomDrawableView - android:layout_width="fill_parent" - android:layout_height="wrap_content" - /> -</pre> - -<p>The ShapeDrawable class (like many other Drawable types in the {@link android.graphics.drawable} package) -allows you to define various properties of the drawable with public methods. -Some properties you might want to adjust include -alpha transparency, color filter, dither, opacity and color.</p> - -<!-- TODO -<h2 id="state-list">StateListDrawable</h2> - -<p>A StateListDrawable is an extension of the DrawableContainer class, making it little different. -The primary distinction is that the -StateListDrawable manages a collection of images for the Drawable, instead of just one. -This means that it can switch the image when you want, without switching objects. However, the -intention of the StateListDrawable is to automatically change the image used based on the state -of the object it's attached to. ---> - -<h2 id="nine-patch">NinePatchDrawable</h2> - -<p>A {@link android.graphics.drawable.NinePatchDrawable} graphic is a stretchable bitmap image, which Android -will automatically resize to accomodate the contents of the View in which you have placed it as the background. -An example use of a NinePatch is the backgrounds used by standard Android buttons — -buttons must stretch to accommodate strings of various lengths. A NinePatch drawable is a standard PNG -image that includes an extra 1-pixel-wide border. It must be saved with the extension <code>.9.png</code>, -and saved into the <code>res/drawable/</code> directory of your project. -</p> -<p> - The border is used to define the stretchable and static areas of - the image. You indicate a stretchable section by drawing one (or more) 1-pixel-wide - black line(s) in the left and top part of the border. (You can have as - many stretchable sections as you want.) The relative size of the stretchable - sections stays the same, so the largest sections always remain the largest. -</p> -<p> - You can also define an optional drawable section of the image (effectively, - the padding lines) by drawing a line on the right and bottom lines. - If a View object sets the NinePatch as its background and then specifies the - View's text, it will stretch itself so that all the text fits inside only - the area designated by the right and bottom lines (if included). If the - padding lines are not included, Android uses the left and top lines to - define this drawable area. -</p> -<p>To clarify the difference between the different lines, the left and top lines define -which pixels of the image are allowed to be replicated in order to strech the image. -The bottom and right lines define the relative area within the image that the contents -of the View are allowed to lie within.</p> -<p> - Here is a sample NinePatch file used to define a button: -</p> - <img src="{@docRoot}images/ninepatch_raw.png" alt="" /> - -<p>This NinePatch defines one stretchable area with the left and top lines -and the drawable area with the bottom and right lines. In the top image, the dotted grey -lines identify the regions of the image that will be replicated in order to strech the image. The pink -rectangle in the bottom image identifies the region in which the contents of the View are allowed. -If the contents don't fit in this region, then the image will be stretched so that they do. -</p> - -<p>The <a href="{@docRoot}guide/developing/tools/draw9patch.html">Draw 9-patch</a> tool offers - an extremely handy way to create your NinePatch images, using a WYSIWYG graphics editor. It -even raises warnings if the region you've defined for the stretchable area is at risk of -producing drawing artifacts as a result of the pixel replication. -</p> - -<h3>Example XML</h3> - -<p>Here's some sample layout XML that demonstrates how to add a NinePatch image to a -couple of buttons. (The NinePatch image is saved as <code>res/drawable/my_button_background.9.png</code> -<pre> -<Button id="@+id/tiny" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:layout_alignParentTop="true" - android:layout_centerInParent="true" - android:text="Tiny" - android:textSize="8sp" - android:background="@drawable/my_button_background"/> - -<Button id="@+id/big" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:layout_alignParentBottom="true" - android:layout_centerInParent="true" - android:text="Biiiiiiig text!" - android:textSize="30sp" - android:background="@drawable/my_button_background"/> -</pre> -<p>Note that the width and height are set to "wrap_content" to make the button fit neatly around the text. -</p> - -<p>Below are the two buttons rendered from the XML and NinePatch image shown above. -Notice how the width and height of the button varies with the text, and the background image -stretches to accommodate it. -</p> - -<img src="{@docRoot}images/ninepatch_examples.png" alt=""/> - - -<h2 id="tween-animation">Tween Animation</h2> - -<p>A tween animation can perform a series of simple transformations (position, size, rotation, and transparency) on -the contents of a View object. So, if you have a TextView object, you can move, rotate, grow, or shrink the text. -If it has a background image, the background image will be transformed along with the text. -The {@link android.view.animation animation package} provides all the classes used in a tween animation.</p> - -<p>A sequence of animation instructions defines the twen animation, defined by either XML or Android code. -Like defining a layout, an XML file is recommended because it's more readable, reusable, and swappable -than hard-coding the animation. In the example below, we use XML. (To learn more about defining an animation -in your application code, instead of XML, refer to the -{@link android.view.animation.AnimationSet} class and other {@link android.view.animation.Animation} subclasses.)</p> - -<p>The animation instructions define the transformations that you want to occur, when they will occur, -and how long they should take to apply. Transformations can be sequential or simultaneous — -for example, you can have the contents of a TextView move from left to right, and then -rotate 180 degrees, or you can have the text move and rotate simultaneously. Each transformation -takes a set of parameters specific for that transformation (starting size and ending size -for size change, starting angle and ending angle for rotation, and so on), and -also a set of common parameters (for instance, start time and duration). To make -several transformations happen simultaneously, give them the same start time; -to make them sequential, calculate the start time plus the duration of the preceding transformation. -</p> - -<p>The animation XML file belongs in the <code>res/anim/</code> directory of your Android project. -The file must have a single root element: this will be either a single <code><alpha></code>, -<code><scale></code>, <code><translate></code>, <code><rotate></code>, interpolator element, -or <code><set></code> element that holds groups of these elements (which may include another -<code><set></code>). By default, all animation instructions are applied simultaneously. -To make them occur sequentially, you must specify the <code>startOffset</code> attribute, as shown in the example below. -</p> - -<p>The following XML from one of the ApiDemos is used to stretch, -then simultaneously spin and rotate a View object. -</p> -<pre> -<set android:shareInterpolator="false"> - <scale - android:interpolator="@android:anim/accelerate_decelerate_interpolator" - android:fromXScale="1.0" - android:toXScale="1.4" - android:fromYScale="1.0" - android:toYScale="0.6" - android:pivotX="50%" - android:pivotY="50%" - android:fillAfter="false" - android:duration="700" /> - <set android:interpolator="@android:anim/decelerate_interpolator"> - <scale - android:fromXScale="1.4" - android:toXScale="0.0" - android:fromYScale="0.6" - android:toYScale="0.0" - android:pivotX="50%" - android:pivotY="50%" - android:startOffset="700" - android:duration="400" - android:fillBefore="false" /> - <rotate - android:fromDegrees="0" - android:toDegrees="-45" - android:toYScale="0.0" - android:pivotX="50%" - android:pivotY="50%" - android:startOffset="700" - android:duration="400" /> - </set> -</set> -</pre> -<p>Screen coordinates (not used in this example) are (0,0) at the upper left hand corner, -and increase as you go down and to the right.</p> - -<p>Some values, such as pivotX, can be specified relative to the object itself or relative to the parent. -Be sure to use the proper format for what you want ("50" for 50% relative to the parent, or "50%" for 50% -relative to itself).</p> - -<p>You can determine how a transformation is applied over time by assigning an -{@link android.view.animation.Interpolator}. Android includes -several Interpolator subclasses that specify various speed curves: for instance, -{@link android.view.animation.AccelerateInterpolator} tells -a transformation to start slow and speed up. Each one has an attribute value that can be applied in the XML.</p> - -<p>With this XML saved as <code>hyperspace_jump.xml</code> in the <code>res/anim/</code> directory of the -project, the following Java code will reference it and apply it to an {@link android.widget.ImageView} object -from the layout. -</p> -<pre> -ImageView spaceshipImage = (ImageView) findViewById(R.id.spaceshipImage); -Animation hyperspaceJumpAnimation = AnimationUtils.loadAnimation(this, R.anim.hyperspace_jump); -spaceshipImage.startAnimation(hyperspaceJumpAnimation); -</pre> - -<p>As an alternative to <code>startAnimation()</code>, you can define a starting time for the animation with -<code>{@link android.view.animation.Animation#setStartTime(long) Animation.setStartTime()}</code>, -then assign the animation to the View with -<code>{@link android.view.View#setAnimation(android.view.animation.Animation) View.setAnimation()}</code>. -</p> - -<p>For more information on the XML syntax, available tags and attributes, see the discussion on animation -in the <a href="{@docRoot}guide/topics/resources/available-resources.html#animation">Available Resources</a>.</p> - -<p class="note"><strong>Note:</strong> Regardless of how your animation may move or resize, the bounds of the -View that holds your animation will not automatically adjust to accomodate it. Even so, the animation will still -be drawn beyond the bounds of its View and will not be clipped. However, clipping <em>will occur</em> -if the animation exceeds the bounds of the parent View.</p> - - -<h2 id="frame-animation">Frame Animation</h2> - -<p>This is a traditional animation in the sense that it is created with a sequence of different -images, played in order, like a roll of film. The {@link android.graphics.drawable.AnimationDrawable} -class is the basis for frame animations.</p> - -<p>While you can define the frames of an animation in your code, using the -{@link android.graphics.drawable.AnimationDrawable} class API, it's more simply accomplished with a single XML -file that lists the frames that compose the animation. Like the tween animation above, the XML file for this kind -of animation belongs in the <code>res/anim/</code> directory of your Android project. In this case, -the instructions are the order and duration for each frame of the animation.</p> - -<p>The XML file consists of an <code><animation-list></code> element as the root node and a series -of child <code><item></code> nodes that each define a frame: a drawable resource for the frame and the frame duration. -Here's an example XML file for a frame-by-frame animation:</p> -<pre> -<animation-list xmlns:android="http://schemas.android.com/apk/res/android" - android:oneshot="true"> - <item android:drawable="@drawable/rocket_thrust1" android:duration="200" /> - <item android:drawable="@drawable/rocket_thrust2" android:duration="200" /> - <item android:drawable="@drawable/rocket_thrust3" android:duration="200" /> -</animation-list> -</pre> - -<p>This animation runs for just three frames. By setting the <code>android:oneshot</code> attribute of the -list to <var>true</var>, it will cycle just once then stop and hold on the last frame. If it is set <var>false</var> then -the animation will loop. With this XML saved as <code>rocket_thrust.xml</p> in the <code>res/anim/</code> directory -of the project, it can be added as the background image to a View and then called to play. Here's an example Activity, -in which the animation is added to an {@link android.widget.ImageView} and then animated when the screen is touched:</p> -<pre> -AnimationDrawable rocketAnimation; - -public void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - setContentView(R.layout.main); - - ImageView rocketImage = (ImageView) findViewById(R.id.rocket_image); - rocketImage.setBackgroundResource(R.anim.rocket_thrust); - rocketAnimation = (AnimationDrawable) rocketImage.getBackground(); -} - -public boolean onTouchEvent(MotionEvent event) { - if (event.getAction() == MotionEvent.ACTION_DOWN) { - rocketAnimation.start(); - return true; - } - return super.onTouchEvent(event); -} -</pre> -<p>It's important to note that the <code>start()</code> method called on the AnimationDrawable cannot be -called during the <code>onCreate()</code> method of your Activity, because the AnimationDrawable is not yet fully attached -to the window. If you want to play the animation immediately, without -requiring interaction, then you might want to call it from the -<code>{@link android.app.Activity#onWindowFocusChanged(boolean) onWindowFocusChanged()}</code> method in -your Activity, which will get called when Android brings your window into focus.</p> - - diff --git a/docs/html/guide/topics/graphics/index.jd b/docs/html/guide/topics/graphics/index.jd deleted file mode 100644 index bc2a8bf..0000000 --- a/docs/html/guide/topics/graphics/index.jd +++ /dev/null @@ -1,203 +0,0 @@ -page.title=Graphics -@jd:body - -<div id="qv-wrapper"> - <div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#options">Consider your Options</a></li> - <li><a href="#draw-to-view">Simple Graphics Inside a View</a></li> - <li><a href="#draw-with-canvas">Draw with a Canvas</a> - <ol> - <li><a href="#on-view">On a View</a></li> - <li><a href="#on-surfaceview">On a SurfaceView</a></li> - </ol> - </li> - </ol> - </div> -</div> -<p>Android graphics are powered by a custom 2D graphics library and OpenGL ES 1.0 -for high performance 3D graphics. The most common 2D graphics APIs can be found in the -{@link android.graphics.drawable drawable package}. OpenGL APIs are available -from the Khronos {@link javax.microedition.khronos.opengles OpenGL ES package}, -plus some Android {@link android.opengl OpenGL utilities}.</p> - -<p>When starting a project, it's important to consider exactly what your graphical demands will be. -Varying graphical tasks are best accomplished with varying techniques. For example, graphics and animations -for a rather static application should be implemented much differently than graphics and animations -for an interactive game or 3D rendering.</p> - -<p>Here, we'll discuss a few of the options you have for drawing graphics on Android, -and which tasks they're best suited for.</p> - -<p>If you're specifically looking for information on drawing 3D graphics, this page won't -help a lot. However, the information below, on <a href="#drawing-with-canvas">Drawing with a Canvas</a> -(and the section on SurfaceView), -will give you a quick idea of how you should draw to the View hierarchy. For more information -on Android's 3D graphic utilities (provided by the OpenGL ES API), -read <a href="opengl.html">3D with OpenGL</a> and refer to other OpenGL documentation.</p> - - -<h2 id="options">Consider your Options</h2> - -<p>When drawing 2D graphics, you'll typically do so in one of two ways:</p> -<ol type="a"> - <li>Draw your graphics or animations into a View object from your layout. In this manner, - the drawing (and any animation) of your graphics is handled by the system's - normal View hierarchy drawing process — you simply define the graphics to go inside the View.</li> - <li>Draw your graphics directly to a Canvas. This way, you personally call the appropriate class's - <code>draw()</code> method (passing it your Canvas), or one of the Canvas <code>draw...()</code> methods (like - <code>{@link android.graphics.Canvas#drawPicture(Picture,Rect) drawPicture()}</code>). In doing so, you are also in - control of any animation.</li> -</ol> - -<p>Option "a," drawing to a View, is your best choice when you want to draw simple graphics that do not -need to change dynamically and are not part of a performance-intensive game. For example, you should -draw your graphics into a View when you want to display a static graphic or predefined animation, within -an otherwise static application. Read <a href="#draw-to-view">Simple Graphics Inside a View</a>.</li> - -<p>Option "b," drawing to a Canvas, is better when you're application needs to regularly re-draw itself. -Basically, any video game should be drawing to the Canvas on its own. However, there's more than -one way to do this: </p> -<ul> - <li>In the same thread as your UI Activity, wherein you create a custom View component in - your layout, call <code>{@link android.view.View#invalidate()}</code> and then handle the - <code>{@link android.view.View#onDraw(Canvas) onDraw()}</code> callback..</li> - <li>Or, in a separate thread, wherein you manage a {@link android.view.SurfaceView} and - perform draws to the Canvas as fast as your thread is capable - (you do not need to request <code>invalidate()</code>).</li> -</ul> -<p>...Begin by reading <a href="#draw-with-canvas">Draw with a Canvas</a>.</p> - -<h2 id="draw-to-view">Simple Graphics Inside a View</h2> - -<p>If you'll be drawing some simple graphics (images, shapes, colors, pre-defined animations, etc.), -then you should probably just draw to the background of a View or -to the content of an {@link android.widget.ImageView} in your layout. -In this case, you can skip the rest of this document and learn how to -draw graphics and animations in the <a href="2d-graphics.html">2D Graphics</a> document. -</p> - - -<h2 id="draw-with-canvas">Draw with a Canvas</h2> - -<p>When you're writing an application in which you would like to perform specialized drawing -and/or control the animation of graphics, -you should do so by drawing through a {@link android.graphics.Canvas}. A Canvas works for you as -a pretense, or interface, to the actual surface upon which your graphics will be drawn — it -holds all of your "draw" calls. Via the Canvas, your drawing is actually performed upon an -underlying {@link android.graphics.Bitmap}, which is placed into the window.</p> - -<p>In the event that you're drawing within the <code>{@link android.view.View#onDraw(Canvas) onDraw()}</code> -callback method, the Canvas is provided for you and you need only place your drawing calls upon it. -You can also acquire a Canvas from <code>{@link android.view.SurfaceHolder#lockCanvas() SurfaceHolder.lockCanvas()}</code>, -when dealing with a SurfaceView object. (Both of these scenarios are discussed in the following sections.) -However, if you need to create a new Canvas, then you must define the {@link android.graphics.Bitmap} -upon which drawing will actually be performed. The Bitmap is always required for a Canvas. You can set up -a new Canvas like this:</p> -<pre> -Bitmap b = Bitmap.createBitmap(100, 100, Bitmap.Config.ARGB_8888); -Canvas c = new Canvas(b); -</pre> - -<p>Now your Canvas will draw onto the defined Bitmap. After drawing upon it with the Canvas, you can then carry your -Bitmap to another Canvas with one of the <code>{@link android.graphics.Canvas#drawBitmap(Bitmap,Matrix,Paint) -Canvas.drawBitmap(Bitmap,...)}</code> methods. It's recommended that you ultimately draw your final -graphics through a Canvas offered to you -by <code>{@link android.view.View#onDraw(Canvas) View.onDraw()}</code> or -<code>{@link android.view.SurfaceHolder#lockCanvas() SurfaceHolder.lockCanvas()}</code> (see the following sections).</p> - -<p>The {@link android.graphics.Canvas} class has its own set of drawing methods that you can use, -like <code>drawBitmap(...)</code>, <code>drawRect(...)</code>, <code>drawText(...)</code>, and many more. -Other classes that you might use also have <code>draw()</code> methods. For example, you'll probably -have some {@link android.graphics.drawable.Drawable} objects that you want to put on the Canvas. Drawable -has its own <code>{@link android.graphics.drawable.Drawable#draw(Canvas) draw()}</code> method -that takes your Canvas as an arguement.</p> - - -<h3 id="on-view">On a View</h3> - -<p>If you're application does not require a significant amount of processing or -frame-rate speed (perhaps for a chess game, a snake game, -or another slowly-animated application), then you should consider creating a custom View component -and drawing with a Canvas in <code>{@link android.view.View#onDraw(Canvas) View.onDraw()}</code>. -The most convenient aspect of doing so is that the Android framework will -provide you with a pre-defined Canvas to which you will place your drawing calls.</p> - -<p>To start, extend the {@link android.view.View} class (or descendent thereof) and define -the <code>{@link android.view.View#onDraw(Canvas) onDraw()}</code> callback method. This method will be called by the Android -framework to request that your View draw itself. This is where you will perform all your calls -to draw through the {@link android.graphics.Canvas}, which is passed to you through the <code>onDraw()</code> callback.</p> - -<p>The Android framework will only call <code>onDraw()</code> as necessary. Each time that -your application is prepared to be drawn, you must request your View be invalidated by calling -<code>{@link android.view.View#invalidate()}</code>. This indicates that you'd like your View to be drawn and -Android will then call your <code>onDraw()</code> method (though is not guaranteed that the callback will -be instantaneous). </p> - -<p>Inside your View component's <code>onDraw()</code>, use the Canvas given to you for all your drawing, -using various <code>Canvas.draw...()</code> methods, or other class <code>draw()</code> methods that -take your Canvas as an argument. Once your <code>onDraw()</code> is complete, the Android framework will -use your Canvas to draw a Bitmap handled by the system.</p> - -<p class="note"><strong>Note: </strong> In order to request an invalidate from a thread other than your main -Activity's thread, you must call <code>{@link android.view.View#postInvalidate()}</code>.</p> - -<p>Also read <a href="{@docRoot}guide/topics/ui/custom-components.html">Building Custom Components</a> -for a guide to extending a View class, and <a href="2d-graphics.html">2D Graphics: Drawables</a> for -information on using Drawable objects like images from your resources and other primitive shapes.</p> - -<p>For a sample application, see the Snake game, in the SDK samples folder: -<code><your-sdk-directory>/samples/Snake/</code>.</p> - -<h3 id="on-surfaceview">On a SurfaceView</h3> - -<p>The {@link android.view.SurfaceView} is a special subclass of View that offers a dedicated -drawing surface within the View hierarchy. The aim is to offer this drawing surface to -an application's secondary thread, so that the application isn't required -to wait until the system's View hierarchy is ready to draw. Instead, a secondary thread -that has reference to a SurfaceView can draw to its own Canvas at its own pace.</p> - -<p>To begin, you need to create a new class that extends {@link android.view.SurfaceView}. The class should also -implement {@link android.view.SurfaceHolder.Callback}. This subclass is an interface that will notify you -with information about the underlying {@link android.view.Surface}, such as when it is created, changed, or destroyed. -These events are important so that you know when you can start drawing, whether you need -to make adjustments based on new surface properties, and when to stop drawing and potentially -kill some tasks. Inside your SurfaceView class is also a good place to define your secondary Thread class, which will -perform all the drawing procedures to your Canvas.</p> - -<p>Instead of handling the Surface object directly, you should handle it via -a {@link android.view.SurfaceHolder}. So, when your SurfaceView is initialized, get the SurfaceHolder by calling -<code>{@link android.view.SurfaceView#getHolder()}</code>. You should then notify the SurfaceHolder that you'd -like to receive SurfaceHolder callbacks (from {@link android.view.SurfaceHolder.Callback}) by calling -{@link android.view.SurfaceHolder#addCallback(SurfaceHolder.Callback) addCallback()} -(pass it <var>this</var>). Then override each of the -{@link android.view.SurfaceHolder.Callback} methods inside your SurfaceView class.</p> - -<p>In order to draw to the Surface Canvas from within your second thread, you must pass the thread your SurfaceHandler -and retrieve the Canvas with <code>{@link android.view.SurfaceHolder#lockCanvas() lockCanvas()}</code>. -You can now take the Canvas given to you by the SurfaceHolder and do your necessary drawing upon it. -Once you're done drawing with the Canvas, call -<code>{@link android.view.SurfaceHolder#unlockCanvasAndPost(Canvas) unlockCanvasAndPost()}</code>, passing it -your Canvas object. The Surface will now draw the Canvas as you left it. Perform this sequence of locking and -unlocking the canvas each time you want to redraw.</p> - -<p class="note"><strong>Note:</strong> On each pass you retrieve the Canvas from the SurfaceHolder, -the previous state of the Canvas will be retained. In order to properly animate your graphics, you must re-paint the -entire surface. For example, you can clear the previous state of the Canvas by filling in a color -with <code>{@link android.graphics.Canvas#drawColor(int) drawColor()}</code> or setting a background image -with <code>{@link android.graphics.Canvas#drawBitmap(Bitmap,Rect,RectF,Paint) drawBitmap()}</code>. Otherwise, -you will see traces of the drawings you previously performed.</p> - - -<p>For a sample application, see the Lunar Landar game, in the SDK samples folder: -<code><your-sdk-directory>/samples/LunarLander/</code>. Or, -browse the source in the <a href="{@docRoot}guide/samples/index.html">Sample Code</a> section.</p> - - - - - - - - diff --git a/docs/html/guide/topics/graphics/opengl.jd b/docs/html/guide/topics/graphics/opengl.jd deleted file mode 100644 index eb2932d..0000000 --- a/docs/html/guide/topics/graphics/opengl.jd +++ /dev/null @@ -1,56 +0,0 @@ -page.title=3D with OpenGL -parent.title=2D and 3D Graphics -parent.link=index.html -@jd:body - - -<p>Android includes support for high performance 3D graphics -via the OpenGL API — specifically, the OpenGL ES API.</p> - -<p>OpenGL ES is a flavor of the OpenGL specification intended for embedded -devices. Versions of <a href="http://www.khronos.org/opengles/">OpenGL ES</a> are loosely peered to versions of the primary -OpenGL standard. Android currently supports OpenGL ES 1.0, which corresponds -to OpenGL 1.3. So, if the application you have in mind is possible with OpenGL -1.3 on a desktop system, it should be possible on Android.</p> - -<p>The specific API provided by Android is similar to the J2ME JSR239 OpenGL -ES API. However, it may not be identical, so watch out for deviations.</p> - -<h2>Using the API</h2> - -<p>Here's how to use the API at an extremely high level:</p> - -<ol> -<li>Write a custom View subclass.</li> -<li>Obtain a handle to an OpenGLContext, which provides access to the OpenGL functionality.</li> -<li>In your View's onDraw() method, get a handle to a GL object, and use its methods to perform GL operations.</li> -</ol> - -<p>For an example of this usage model (based on the classic GL ColorCube), -see -<a href="{@docRoot}guide/samples/ApiDemos/src/com/example/android/apis/graphics/GLSurfaceView.html">com.android.samples.graphics.GLSurfaceView.java</a> -in the ApiDemos sample code project. A slightly more sophisticated version showing how to use -it with threads can be found in -<a href="{@docRoot}guide/samples/ApiDemos/src/com/example/android/apis/graphics/GLSurfaceViewActivity.html">com.android.samples.graphics.GLSurfaceViewActivity.java</a>. -</p> - -<p>Writing a summary of how to actually write 3D applications using OpenGL is -beyond the scope of this text and is left as an exercise for the reader.</p> - -<h2>Links to Additional Information</h2> - -<p>Information about OpenGL ES can be -found at <a title="http://www.khronos.org/opengles/" -href="http://www.khronos.org/opengles/">http://www.khronos.org/opengles/</a>.</p> - -<p>Information specifically -about OpenGL ES 1.0 (including a detailed specification) can be found -at <a title="http://www.khronos.org/opengles/1_X/" -href="http://www.khronos.org/opengles/1_X/">http://www.khronos.org/opengles/1_X/</a>.</p> - -<p>The documentation for the Android {@link javax.microedition.khronos.opengles -OpenGL ES implementations} are also available.</p> - -<p>Finally, note that though Android does include some basic support for -OpenGL ES 1.1, the support is <strong>not complete</strong>, and should not be relied -upon at this time.</p> diff --git a/docs/html/guide/topics/index.html b/docs/html/guide/topics/index.html deleted file mode 100644 index 4881acf..0000000 --- a/docs/html/guide/topics/index.html +++ /dev/null @@ -1,8 +0,0 @@ -<html> -<head> -<meta http-equiv="refresh" content="0;url=../index.html"> -</head> -<body> -<a href="../index.html">click here</a> if you are not redirected. -</body> -</html>
\ No newline at end of file diff --git a/docs/html/guide/topics/intents/index.html b/docs/html/guide/topics/intents/index.html deleted file mode 100644 index b831246..0000000 --- a/docs/html/guide/topics/intents/index.html +++ /dev/null @@ -1,9 +0,0 @@ -<html> -<head> -<meta http-equiv="refresh" content="0;url=intents-filters.html"> -<title>Redirecting...</title> -</head> -<body> -<a href="intents-filters.html">click here</a> if you are not redirected. -</body> -</html>
\ No newline at end of file diff --git a/docs/html/guide/topics/intents/intents-filters.jd b/docs/html/guide/topics/intents/intents-filters.jd deleted file mode 100644 index fd20ca1..0000000 --- a/docs/html/guide/topics/intents/intents-filters.jd +++ /dev/null @@ -1,693 +0,0 @@ -page.title=Intents and Intent Filters -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> -<h2>Key classes</h2> -<ol> -<li>{@link android.content.Intent}</li> -<li>{@link android.content.IntentFilter}</li> -<li>{@link android.app.Activity}</li> -<li>{@link android.app.Service}</li> -<li>{@link android.content.BroadcastReceiver}</li> -<li>{@link android.content.pm.PackageManager}</li> -</ol> - -<h2>In this document</h2> -<ol> -<li><a href="#iobjs">Intent Objects</a></li> -<li><a href="#ires">Intent Resolution</a>, including:</li> -<li style="margin-left: 2em"><a href="#ifs">Intent filters</a></li> -<li style="margin-left: 2em"><a href="#ccases">Common cases</a></li> -<li style="margin-left: 2em"><a href="#imatch">Using intent matching</a></li> -</ol> -</div> -</div> - - -<p> -Three of the core components of an application — activities, services, and -broadcast receivers — are activated through messages, called <i>intents</i>. -Intent messaging is a facility for late run-time binding between components in the same -or different applications. The intent itself, an {@link android.content.Intent} -object, is a passive data structure holding an abstract description of an operation -to be performed — or, in the case of broadcasts, a description of something -that has happened and is being announced. There are separate mechanisms for -delivering intents to each type of component: -</p> - -<ul> -<li>An Intent object is passed to <code>{@link android.content.Context#startActivity -Context.startActivity()}</code> or <code>{@link android.app.Activity#startActivityForResult -Activity.startActivityForResult()}</code> to launch an activity or get an existing -activity to do something new.</li> - -<li><p>An Intent object is passed to <code>{@link android.content.Context#startService -Context.startService()}</code> to initiate a service or deliver new instructions to an -ongoing service. Similarly, an intent can be passed to <code>{@link -android.content.Context#bindService Context.bindService()}</code> to establish a -connection between the calling component and a target service. It can optionally -initiate the service if it's not already running.</p></li> - -<li><p>Intent objects passed to any of the broadcast methods (such as <code>{@link -android.content.Context#sendBroadcast(Intent) Context.sendBroadcast()}</code>, -<code>{@link android.content.Context#sendOrderedBroadcast(Intent, String) -Context.sendOrderedBroadcast()}</code>, or <code>{@link -android.content.Context#sendStickyBroadcast Context.sendStickyBroadcast()}</code>) -are delivered to all interested broadcast receivers. Many kinds of broadcasts -originate in system code.</p></li> -</ul> - -<p> -In each case, the Android system finds the appropriate activity, service, or set -of broadcast receivers to respond to the intent, instantiating them if necessary. -There is no overlap within these messaging systems: Broadcast intents are delivered -only to broadcast receivers, never to activities or services. An intent passed to -{@code startActivity()} is delivered only to an activity, never to a service or -broadcast receiver, and so on. -</p> - -<p> -This document begins with a description of Intent objects. It then describes the -rules Android uses to map intents to components — how it resolves which -component should receive an intent message. For intents that don't explicitly -name a target component, this process involves testing the Intent object against -<i>intent filters</i> associated with potential targets. -</p> - - -<h2><a name="iobjs"></a>Intent Objects</h2> - -<p> -An {@link android.content.Intent} object is a bundle of information. It -contains information of interest to the component that receives the intent -(such as the action to be taken and the data to act on) plus information -of interest to the Android system (such as the category of component that -should handle the intent and instructions on how to launch a target activity). -Principally, it can contain the following: -</p> - -<dl> - -<dt><b>Component name</b><a name="cname"></a></dt> -<dd>The name of the component that should handle the intent. This field is -a {@link android.content.ComponentName} object — a combination of the -fully qualified class name of the target component (for example "{@code -com.example.project.app.FreneticActivity}") and the package name set -in the manifest file of the application where the component resides (for -example, "{@code com.example.project}"). The package part of the component -name and the package name set in the manifest do not necessarily have to match. - -<p> -The component name is optional. If it is set, the Intent object is -delivered to an instance of the designated class. If it is not set, -Android uses other information in the Intent object to locate a suitable -target — see <a href="#ires">Intent Resolution</a>, later in this -document. -</p> - -<p> -The component name is set by <code>{@link android.content.Intent#setComponent -setComponent()}</code>, <code>{@link android.content.Intent#setClass -setClass()}</code>, or <code>{@link android.content.Intent#setClassName(String, String) -setClassName()}</code> and read by <code>{@link android.content.Intent#getComponent -getComponent()}</code>. -</p> -</dd> - -<p><dt><b>Action</b></dt> -<dd>A string naming the action to be performed — or, in the case of broadcast -intents, the action that took place and is being reported. The Intent class defines -a number of action constants, including these: -</p> - -<table> -<tr> - <th>Constant</th> - <th>Target component</th> - <th>Action</th> -</tr><tr> - <td>{@code ACTION_CALL} - <td>activity - <td>Initiate a phone call. -</tr><tr> - <td>{@code ACTION_EDIT} - <td>activity - <td>Display data for the user to edit. -</tr><tr> - <td>{@code ACTION_MAIN} - <td>activity - <td>Start up as the initial activity of a task, with no data input and no returned output. -</tr><tr> - <td>{@code ACTION_SYNC} - <td>activity - <td>Synchronize data on a server with data on the mobile device. -</tr><tr> - <td>{@code ACTION_BATTERY_LOW} - <td>broadcast receiver - <td>A warning that the battery is low. -</tr><tr> - <td>{@code ACTION_HEADSET_PLUG} - <td>broadcast receiver - <td>A headset has been plugged into the device, or unplugged from it. -</tr><tr> - <td>{@code ACTION_SCREEN_ON} - <td>broadcast receiver - <td>The screen has been turned on. -</tr><tr> - <td>{@code ACTION_TIMEZONE_CHANGED} - <td>broadcast receiver - <td>The setting for the time zone has changed. -</tr> -</table> - -<p> -See the {@link android.content.Intent} class description for a list of -pre-defined constants for generic actions. Other actions are defined -elsewhere in the Android API. -You can also define your own action strings for activating the components -in your application. Those you invent should include the application -package as a prefix — for example: -"<code>com.example.project.SHOW_COLOR</code>". -</p> - -<p> -The action largely determines how the rest of the intent is structured -— particularly the <a href="#data">data</a> and -<a href="#extras">extras</a> fields — -much as a method name determines a set of arguments and a return value. -For this reason, it's a good idea to use action names that are -as specific as possible, and to couple them tightly to the other fields of -the intent. In other words, instead of defining an action in isolation, -define an entire protocol for the Intent objects your components can handle. -</p> - -<p> -The action in an Intent object is set by the -<code>{@link android.content.Intent#setAction setAction()}</code> -method and read by -<code>{@link android.content.Intent#getAction getAction()}</code>. -</p> -</dd> - -<p><dt><b>Data</b><a name="data"></a></dt> -<dd>The URI of the data to be acted on and the MIME type of that data. Different -actions are paired with different kinds of data specifications. For example, if -the action field is {@code ACTION_EDIT}, -the data field would contain the URI of the document to be displayed for editing. -If the action is {@code ACTION_CALL}, the data field would be a {@code tel:} URI -with the number to call. Similarly, if the action is {@code ACTION_VIEW} and the -data field is an {@code http:} URI, the receiving activity would be called upon -to download and display whatever data the URI refers to. - -<p> -When matching an intent to a component that is capable of handling the data, -it's often important to know the type of data (its MIME type) in addition to its URI. -For example, a component able to display image data should not be called -upon to play an audio file. -</p> - -<p> -In many cases, the data type can be inferred from the URI — particularly -{@code content:} URIs, which indicate that the data is located on the device and -controlled by a content provider (see the -<a href="{@docRoot}guide/topics/providers/content-providers.html">separate -discussion on content providers</a>). But the type can also be explicitly set -in the Intent object. -The <code>{@link android.content.Intent#setData setData()}</code> method specifies -data only as a URI, <code>{@link android.content.Intent#setType setType()}</code> -specifies it only as a MIME type, and <code>{@link -android.content.Intent#setDataAndType setDataAndType()}</code> specifies it as both -a URI and a MIME type. The URI is read by <code>{@link -android.content.Intent#getData getData()}</code> and the type by <code>{@link -android.content.Intent#getType getType()}</code>. -</p> -</dd> - -<p><dt><b>Category</b></dt> -<dd>A string containing additional information about the kind of component -that should handle the intent. Any number of category descriptions can be -placed in an Intent object. As it does for actions, the Intent class defines -several category constants, including these: - -<table> -<tr> - <th>Constant</th> - <th>Meaning</th> -</tr><tr> - <td>{@code CATEGORY_BROWSABLE} - <td>The target activity can be safely invoked by the browser to display data - referenced by a link — for example, an image or an e-mail message. -</tr><tr> - <td>{@code CATEGORY_GADGET} - <td>The activity can be embedded inside of another activity that hosts gadgets. -</tr><tr> - <td>{@code CATEGORY_HOME} - <td>The activity displays the home screen, the first screen the user sees when - the device is turned on or when the HOME key is pressed. -</tr><tr> - <td>{@code CATEGORY_LAUNCHER} - <td>The activity can be the initial activity of a task and is listed in - the top-level application launcher. -</tr><tr> - <td>{@code CATEGORY_PREFERENCE} - <td>The target activity is a preference panel. -</tr> -</table> - -<p> -See the {@link android.content.Intent} class description for the full list of -categories. -</p> - -<p> -The <code>{@link android.content.Intent#addCategory addCategory()}</code> method -places a category in an Intent object, <code>{@link android.content.Intent#removeCategory -removeCategory()}</code> deletes a category previously added, and <code>{@link android.content.Intent#getCategories getCategories()}</code> gets the set of all -categories currently in the object. -</p> -</dd> - -<p><dt><b>Extras</b><a name="extras"></a></dt> -<dd>Key-value pairs for additional information that should be delivered to the -component handling the intent. Just as some actions are paired with particular -kinds of data URIs, some are paired with particular extras. For example, an -{@code ACTION_TIMEZONE_CHANGED} intent has a "{@code time-zone}" extra that -identifies the new time zone, and {@code ACTION_HEADSET_PLUG} has a -"{@code state}" extra indicating whether the headset is now plugged in or -unplugged, as well as a "{@code name}" extra for the type of headset. -If you were to invent a {@code SHOW_COLOR} action, the color value would -be set in an extra key-value pair. - -<p> -The Intent object has a series of {@code put...()} methods for inserting various -types of extra data and a similar set of {@code get...()} methods for reading -the data. These methods parallel those for {@link android.os.Bundle} objects. -In fact, the extras can be installed and read as a Bundle using the <code>{@link -android.content.Intent#putExtras putExtras()}</code> and <code>{@link -android.content.Intent#getExtras getExtras()}</code> methods. -</p> -</dd> - -<p><dt><b>Flags</b></dt> -<dd>Flags of various sorts. Many instruct the Android system how to launch an -activity (for example, which task the activity should belong to) and how to treat -it after it's launched (for example, whether it belongs in the list of recent -activities). All these flags are defined in the Intent class. -</dd> - -</dl> - -<p> -The Android system and the applications that come with the platform employ -Intent objects both to send out system-originated broadcasts and to activate -system-defined components. To see how to structure an intent to activate a -system component, consult the -<a href="{@docRoot}guide/appendix/g-app-intents.html">list of intents</a> -in the reference. -</p> - - -<h2><a name="ires"></a>Intent Resolution</h2> - -<p> -Intents can be divided into two groups: -</p> - -<ul> -<li><i>Explicit intents</i> designate the target component by its -name (the <a href="#cname">component name field</a>, mentioned earlier, -has a value set). Since component names would generally not be known to -developers of other applications, explicit intents are typically used -for application-internal messages — such as an activity starting -a subordinate service or launching a sister activity.</li> - -<li><p><i>Implicit intents</i> do not name a target (the field for -the component name is blank). Implicit intents are often used to -activate components in other applications.</p></li> -</ul> - -<p> -Android delivers an explicit intent to an instance of the designated -target class. Nothing in the Intent object other than the component -name matters for determining which component should get the intent. -</p> - -<p> -A different strategy is needed for implicit intents. In the absence of a -designated target, the Android system must find the best component (or -components) to handle the intent — a single activity or service to -perform the requested action or the set of broadcast receivers to respond -to the broadcast announcement. It does so by comparing the contents of -the Intent object to <i>intent filters</i>, structures associated with -components that can potentially receive intents. Filters advertise the -capabilities of a component and delimit the intents it can handle. They -open the component to the possibility of receiving implicit intents of -the advertised type. If a component does not have any intent filters, -it can receive only explicit intents. A component with filters can -receive both explicit and implicit intents. -</p> - -<p> -Only three aspects of an Intent object are consulted when the object -is tested against an intent filter: -</p> - -<p style="margin-left: 2em">action -<br/>data (both URI and data type) -<br/>category</p> - -<p> -The extras and flags play no part in resolving which component receives -an intent. -</p> - - -<h3><a name="ifs"></a>Intent filters</h3> - -<p> -To inform the system which implicit intents they can handle, activities, -services, and broadcast receivers can have one or more intent filters. -Each filter describes a capability of the component, a set of intents that -the component is willing to receive. It, in effect, filters in -intents of a desired type, while filtering out unwanted -intents — but only unwanted implicit intents (those that don't name -a target class). An explicit intent is always delivered to its target, -no matter what it contains; the filter is not consulted. But an implicit -intent is delivered to a component only if it can pass through one of the -component's filters. -</p> - -<p> -A component has separate filters for each job it can do, each face it can -present to the user. For example, the principal activity of the sample -NotePad application has three filters — one for starting up with a -blank slate, another for starting with an assigned directory of notes -that the user can view, edit, or select from, and a third for finding a -particular note without an initial specification of its directory. -</p> - -<p> -An intent filter is an instance of the {@link android.content.IntentFilter} class. -However, since the Android system must know about the capabilities of a component -before it can launch that component, intent filters are generally not set up in -Java code, but in the application's manifest file (AndroidManifest.xml) as -{@code <intent-filter>} elements. (The one exception would be filters for -broadcast receivers that are registered dynamically by calling <code>{@link android.content.Context#registerReceiver(BroadcastReceiver, IntentFilter, String, -Handler) Context.registerReceiver()}</code>; they are directly created as -IntentFilter objects.) -</p> - -<div class="sidebox-wrapper"> -<div class="sidebox-inner"> -<h2>Filters and security</h2> -<p>An intent filter cannot be relied on for security. While it opens a -component to receiving only certain kinds of implicit intents, it does -nothing to prevent explicit intents from targeting the component. Even -though a filter restricts the intents a component will be asked to handle -to certain actions and data sources, someone could always put -together an explicit intent with a different action and data source, and -name the component as the target. -</p> -</div> -</div> - -<p> -A filter has fields that parallel the action, data, and category fields of an -Intent object. An implicit intent is tested against the filter in all three areas. -To be delivered to the component that owns the filter, it must pass all three tests. -If it fails even one of them, the Android system won't deliver it to the -component — at least not on the basis of that filter. However, since a -component can have multiple intent filters, an intent that does not pass -through one of a component's filters might make it through on another. -</p> - -<p> -Each of the three tests is described in detail below: -</p> - -<dl> - -<dt><b>Action test</b></dt> -<dd>An {@code <intent-filter>} element in the manifest file lists actions -as {@code <action>} subelements. For example: - -<pre><intent-filter . . . > - <action android:name="com.example.project.SHOW_CURRENT" /> - <action android:name="com.example.project.SHOW_RECENT" /> - <action android:name="com.example.project.SHOW_PENDING" /> - . . . -</intent-filter></pre> - -<p> -As the example shows, while an Intent object names just a single action, -a filter may list more than one. The list cannot be empty; a filter must -contain at least one {@code <action>} element, or it -will block all intents. -</p> - -<p> -To pass this test, the action specified in the Intent object must match -one of the actions listed in the filter. If the object or the filter -does not specify an action, the results are as follows: -</p> - -<ul> -<li>If the filter fails to list any actions, there is nothing for an -intent to match, so all intents fail the test. No intents can get -through the filter.</li> - -<li><p>On the other hand, an Intent object that doesn't specify an -action automatically passes the test — as long as the filter -contains at least one action.</p></li> -</ul -</dd> - -<dt><b>Category test</b></dt> -<dd>An {@code <intent-filter>} element also lists categories as subelements. -For example: - -<pre><intent-filter . . . > - <category android:name="android.intent.category.DEFAULT" /> - <category android:name="android.intent.category.BROWSABLE" /> - . . . -</intent-filter></pre> - -<p> -Note that the constants described earlier for actions and categories are not -used in the manifest file. The full string values are used instead. For -instance, the "{@code android.intent.category.BROWSABLE}" string in the example -above corresponds to the {@code CATEGORY_BROWSABLE} constant mentioned earlier -in this document. Similarly, the string "{@code android.intent.action.EDIT}" -corresponds to the {@code ACTION_EDIT} constant. -</p> - -<p> -For an intent to pass the category test, every category in the Intent object -must match a category in the filter. The filter can list additional categories, -but it cannot omit any that are in the intent. -</p> - -<p> -In principle, therefore, an Intent object with no categories should always pass -this test, regardless of what's in the filter. That's mostly true. However, -with one exception, Android treats all implicit intents passed to {@link -android.content.Context#startActivity startActivity()} as if they contained -at least one category: "{@code android.intent.category.DEFAULT}" (the -{@code CATEGORY_DEFAULT} constant). -Therefore, activities that are willing to receive implicit intents must -include "{@code android.intent.category.DEFAULT}" in their intent filters. -(Filters with "{@code android.intent.action.MAIN}" and -"{@code android.intent.category.LAUNCHER}" settings are the exception. -They mark activities that begin new tasks and that are represented on the -launcher screen. They can include "{@code android.intent.category.DEFAULT}" -in the list of categories, but don't need to.) See <a href="#imatch">Using -intent matching</a>, later, for more on these filters.) -</p> -<dd> - -<dt><b>Data test</b></dt> -<dd>Like the action and categories, the data specification for an intent filter -is contained in a subelement. And, as in those cases, the subelement can appear -multiple times, or not at all. For example: - -<pre><intent-filter . . . > - <data android:type="video/mpeg" android:scheme="http" . . . /> - <data android:type="audio/mpeg" android:scheme="http" . . . /> - . . . -</intent-filter></pre> - -<p> -Each {@code <data>} element can specify a URI and a data type (MIME media type). -There are separate attributes — {@code scheme}, {@code host}, {@code port}, -and {@code path} — for each part of the URI: -</p> - -<p style="margin-left: 2em">{@code scheme://host:port/path}</p> - -<p> -For example, in the following URI, -</p> - -<p style="margin-left: 2em">{@code content://com.example.project:200/folder/subfolder/etc}</p> - -<p> the scheme is "{@code content}", the host is "{@code com.example.project}", -the port is "{@code 200}", and the path is "{@code folder/subfolder/etc}". -The host and port together constitute the URI <i>authority</i>; if a host is -not specified, the port is ignored. -</p> - -<p> -Each of these attributes is optional, but they are not independent of each other: -For an authority to be meaningful, a scheme must also be specified. -For a path to be meaningful, both a scheme and an authority must be specified. -</p> - -<p> -When the URI in an Intent object is compared to a URI specification in a filter, -it's compared only to the parts of the URI actually mentioned in the filter. -For example, if a filter specifies only a scheme, all URIs with that scheme match -the filter. If a filter specifies a scheme and an authority but no path, all URIs -with the same scheme and authority match, regardless of their paths. If a filter -specifies a scheme, an authority, and a path, only URIs with the same scheme, -authority, and path match. However, a path specification in the filter can -contain wildcards to require only a partial match of the path. -</p> - -<p> -The {@code type} attribute of a {@code <data>} element specifies the MIME type -of the data. It's more common in filters than a URI. Both the Intent object and -the filter can use a "*" wildcard for the subtype field — for example, -"{@code text/*}" or "{@code audio/*}" — indicating any subtype matches. -</p> - -<p> -The data test compares both the URI and the data type in the Intent object to a URI -and data type specified in the filter. The rules are as follows: -</p> - -<ol type="a"> -<li>An Intent object that contains neither a URI nor a data type passes the -test only if the filter likewise does not specify any URIs or data types.</li> - -<li><p>An Intent object that contains a URI but no data type (and a type cannot -be inferred from the URI) passes the test only if its URI matches a URI in the -filter and the filter likewise does not specify a type. This will be the case -only for URIs like {@code mailto:} and {@code tel:} that do not refer to actual data.</p></li> - -<li><p>An Intent object that contains a data type but not a URI passes the test -only if the filter lists the same data type and similarly does not specify a URI.</p></li> - -<li><p>An Intent object that contains both a URI and a data type (or a data type -can be inferred from the URI) passes the data type part of the test only if its -type matches a type listed in the filter. It passes the URI part of the test -either if its URI matches a URI in the filter or if it has a {@code content:} -or {@code file:} URI and the filter does not specify a URI. In other words, -a component is presumed to support {@code content:} and {@code file:} data if -its filter lists only a data type.</p></li> -</ol> -</dl> - -<p> -If an intent can pass through the filters of more than one activity or service, -the user may be asked which component to activate. An exception is raised if -no target can be found. -</p> - - -<h3><a name="ccases"></a>Common cases</h3> - -<p> -The last rule shown above for the data test, rule (d), reflects the expectation -that components are able to get local data from a file or content provider. -Therefore, their filters can list just a data type and do not need to explicitly -name the {@code content:} and {@code file:} schemes. -This is a typical case. A {@code <data>} element like the following, -for example, tells Android that the component can get image data from a content -provider and display it: -</p> - -<pre><data android:type="image/*" /></pre> - -<p> -Since most available data is dispensed by content providers, filters that -specify a data type but not a URI are perhaps the most common. -</p> - -<p> -Another common configuration is filters with a scheme and a data type. For -example, a {@code <data>} element like the following tells Android that -the component can get video data from the network and display it: -</p> - -<pre><data android:scheme="http" android:type="video/*" /></pre> - -<p> -Consider, for example, what the browser application does when -the user follows a link on a web page. It first tries to display the data -(as it could if the link was to an HTML page). If it can't display the data, -it puts together an implicit intent with the scheme and data type and tries -to start an activity that can do the job. If there are no takers, it asks the -download manager to download the data. That puts it under the control -of a content provider, so a potentially larger pool of activities -(those with filters that just name a data type) can respond. -</p> - -<p> -Most applications also have a way to start fresh, without a reference -to any particular data. Activities that can initiate applications -have filters with "{@code android.intent.action.MAIN}" specified as -the action. If they are to be represented in the application launcher, -they also specify the "{@code android.intent.category.LAUNCHER}" -category: -</p> - -<pre><intent-filter . . . > - <action android:name="code android.intent.action.MAIN" /> - <category android:name="code android.intent.category.LAUNCHER" /> -</intent-filter></pre> - - -<h3><a name="imatch"></a>Using intent matching</h3> - -<p> -Intents are matched against intent filters not only to discover a target -component to activate, but also to discover something about the set of -components on the device. For example, the Android system populates the -application launcher, the top-level screen that shows the applications -that are available for the user to launch, by finding all the activities - with intent filters that specify the "{@code android.intent.action.MAIN}" -action and "{@code android.intent.category.LAUNCHER}" category -(as illustrated in the previous section). It then displays the icons and -labels of those activities in the launcher. Similarly, it discovers the -home screen by looking for the activity with -"{@code android.intent.category.HOME}" in its filter. -</p> - -<p> -Your application can use intent matching is a similar way. -The {@link android.content.pm.PackageManager} has a set of {@code query...()} -methods that return all components that can accept a particular intent, and -a similar series of {@code resolve...()} methods that determine the best -component to respond to an intent. For example, -{@link android.content.pm.PackageManager#queryIntentActivities -queryIntentActivities()} returns a list of all activities that can perform -the intent passed as an argument, and {@link -android.content.pm.PackageManager#queryIntentServices -queryIntentServices()} returns a similar list of services. -Neither method activates the components; they just list the ones that -can respond. There's a similar method, -{@link android.content.pm.PackageManager#queryBroadcastReceivers -queryBroadcastReceivers()}, for broadcast receivers. -</p> - - - - - - - - - - - diff --git a/docs/html/guide/topics/location/geo/mapkey.jd b/docs/html/guide/topics/location/geo/mapkey.jd deleted file mode 100644 index 9aa824c..0000000 --- a/docs/html/guide/topics/location/geo/mapkey.jd +++ /dev/null @@ -1,210 +0,0 @@ -page.title=Obtaining a Maps API Key -@jd:body - -<div class="sidebox"><p>To register for a Maps API Key, read this document and then go to the <a href="http://code.google.com/android/maps-api-signup.html">Android Maps API Key Signup</a> page.</p> - -</div> - -<p>com.google.android.maps.MapView is a very useful class that lets you easily integrate Google Maps into your application. It provides built-in map downloading, rendering, and caching of Maps tiles, as well as a variety of display options and controls. It provides a wrapper around the Google Maps API that lets your application request and manipulate Google Maps data through class methods, and it lets you work with Maps data as you would other types of Views. </p> - -<p>Because MapView gives you access to Google Maps data, you need to register with the Google Maps service and agree to the applicable Terms of Service before your MapView will be able to obtain data from Google Maps. This will apply whether you are developing your application on the emulator or preparing your application for deployment to mobile devices. </p> - -<p>Registering for a Maps API Key is simple, free, and has two parts: </p> - -<ol> -<li>Registering the MD5 fingerprint of the certificate that you will use to sign your application. The Maps registration service then provides you a Maps API Key that is associated with your application's signer certificate. </li> -<li>Adding a reference to the Maps API Key in each MapView, whether declared in XML or instantiated directly from code. You can use the same Maps API Key for any MapView in any Android application, provided that the application is signed with the certificate whose fingerprint you registered with the service. </li> -</ol> - -<p>During registration, you also need to agree to the Maps API Terms of Service, which describe how your application can use the Maps data. In general, the terms of service are permissive and place few restrictions on how you can use the data. For example, the terms allow you to build "friend finder" type applications. </p> - -<p>The sections below describe how to obtain your Maps API Key and how to reference it from your MapView elements. </p> - -<ul> -<li><a href="#overview">Overview</a></li> -<li><a href="#getfingerprint">Getting the MD5 Fingerprint of Your Signing Certificate</a></li> -<li><a href="#getdebugfingerprint">Getting the MD5 Fingerprint of the SDK Debug Certificate</a></li> -<li><a href="#registering">Registering the Certificate Fingerprint with the Google Maps Service</a></li> -<li><a href="#addingkey">Adding the Maps API Key to your Application</a></li> -<li><a href="#finalsteps">Final Steps to Enable MapView Elements</a></li> -</ul> - -<h2 id="overview">Overview</h2> - -<p>MapView objects are views that display Maps tiles downloaded from the Google Maps service. To ensure that applications use Maps data in an appropriate manner, the Google Maps service requires application developers to register with the service, agreeing to the Terms of Service and supplying an MD5 fingerprint of the certificate(s) that they will use to sign applications. For each registered certificate fingerprint, the service then provides the developer with a Maps API Key — an alphanumeric string that uniquely identifies the certificate and developer registered with the service. </p> - -<p>The Google Maps service also requires that each MapView identify itself to the service using a Maps API Key. Before providing Maps tiles to a MapView, the service checks the Maps API Key supplied by the MapView to ensure that it:</p> -<ul> -<li>References a certificate/developer registered with the service, and </li> -<li>References a certificate that matches the certificate with which the application (containing the MapView) was signed. </li> -</ul> - -<p>Unless both conditions are met, the service does not provide Maps tiles to the MapView. </p> - -<p>Each MapView object in your application must reference a Maps API Key. Since the Key is associated with a certificate, all Mapview elements in an application should reference the same Key. Going a step further, all MapView elements in all applications that you sign with the same certificate should reference the same Key. </p> - -<p>On the other hand, you can register for multiple Maps API Keys, each being associated with a specific certificate. You would want to do this if, for example, you were developing several independent applications that you will sign using different certificates. In this case, note that all MapView elements in a given application can reference the same Maps API Key, but <em>must</em> reference the Key that is associated with the certificate used to sign the application. </p> - -<p>Because MapView elements must refer to a Maps API Key, you need to register your certificate and receive a Key before you can make use of MapView elements in your application. To make it easier for you to get started using MapView elements, you are welcome to register the debug certificate generated by the SDK tools and receive a temporary Maps API Key. The details of how to do that are given below. </p> - -<p>When you are preparing to release your application, however, note that you <em>must</em> sign your application with a suitable cryptographic key, rather than the SDK debug key. That means that you will also need to register your application's release certificate with the Google Maps service. After you've done so, you will receive a new Maps API Key that is uniquely associated with your release certificate. To enable the MapView elements in your application to work after release, you must remember to change the Maps API Key for all MapViews in your application so that they refer to the Key associated with your release certificate (rather than your debug certificate). </p> - -<p>To summarize, the important points to understand about MapViews and the Maps API Key are: </p> - -<ul> -<li>To display Maps data in a MapView, you need to register for a Maps API Key</li> -<li>Each Maps API Key is uniquely associated with a specific certificate, based on an MD5 fingerprint of the certificate </li> -<li>Each MapView must reference a Maps API Key, and the Key referenced must be registered to the certificate used to sign the application</li> -<li>All MapView elements in an application can reference the same Maps API Key</li> -<li>You can register multiple certificates under your developer identity</li> -<li>You can get a temporary Maps API Key based on your debug certificate, but before you publish your application, you must register for a new Key based on your release certificate and update references in your MapViews accordingly</li> -</ul> - -<h2 id="getfingerprint">Getting the MD5 Fingerprint of Your Signing Certificate</h2> - -<div class="sidebox"> -For more information about using Keytool and Jarsigner to sign your application, see <a href="{@docRoot}guide/publishing/app-signing.html">Signing Your Applications</a>. -</div> - -<p>To register for a Maps API Key, you need to provide an MD5 fingerprint of the certificate that you will use to sign your application. </p> - -<p>Before you visit the registration page, use Keytool to generate the fingerprint of the appropriate certificate. - -<p>First, determine which key you will use to sign your application at release and make sure of the path to the keystore that contains it.</p> - -<p>Next, run Keytool with the <code>-list</code> option, against the target keystore and key alias. The table below lists the options you should use.</p> - -<table> -<tr> -<th>Keytool Option</th> -<th>Description</th> -</tr> -<tr> -<td><code>-list</code></td><td>Print an MD5 fingerprint of a certificate.</td> -</tr> -<tr> -<td><code>-keystore <keystore-name>.keystore</code></td><td>The name of the keystore containing the target key.</td> -</tr> -<tr> -<td><code>-storepass <password></code></td><td><p>A password for the -keystore.</p><p>As a security precaution, do not include this option -in your command line unless you are working at a secure computer. -If not supplied, Keytool prompts you to enter the password. In this -way, your password is not stored in your shell history.</p></td> -</tr> -<tr> -<td><code>-alias <alias_name></code></td><td>The alias for the key for which to generate the MD5 certificate fingerprint.</td> -</tr> -<tr> -<td><code>-keypass <password></code></td><td><p>The password for the key.</p> -<p>As a security precaution, do not include this option -in your command line unless you are working at a secure computer. -If not supplied, Keytool prompts you to enter the password. In this -way, your password is not stored in your shell history.</p></td> -</tr> -</table> - -<p>Here's an example of a Keytool command that generates an MD5 certificate fingerprint for the key <code>alias_name</code> in the keystore <code>my-release-key.keystore</code>:</p> - -<pre>$ keytool -list -alias alias_name -keystore my-release-key.keystore</pre> - -<p>Keytool will prompt you to enter passwords for the keystore and key. As output of the command, Keytool prints the fingerprint to the shell. For example:</p> - -<pre>Certificate fingerprint (MD5): 94:1E:43:49:87:73:BB:E6:A6:88:D7:20:F1:8E:B5:98</pre> - -<p>Note that, if you happen to forget your Maps API Key, you can repeat the process described above and register the fingerprint again. The server will give you the same key for the specified certificate fingerprint.</p> - -<p>Once you have the fingerprint, you can go to the Maps API registration site, described next.</p> - -<h2 id="getdebugfingerprint">Getting the MD5 Fingerprint of the SDK Debug Certificate</h2> - -<p>While you are developing and debugging your application, you will likely be -sigining your application in debug mode — that is, the SDK build tools -will automatically sign your application using the debug certificate. To let -your MapView elements properly display Maps data during this period, you should -obtain a temporary Maps API Key registered to the debug certificate. To do so, -you first need to get the MD5 fingerprint of the debug certificate. When -you are ready to release your application, you must register your release -certificate with the Google Maps service and obtain a new Maps API Key. You must -then change the MapView elements in your application to reference the new API -key. </p> - -<p>To generate an MD5 fingerprint of the debug certificate, first locate the debug keystore. The location at which the SDK tools create the default debug keystore varies by platform: </p> - -<ul> -<li>Windows Vista: <code>C:\Users\<user>\AppData\Local\Android\debug.keystore</code></li> -<li>Windows XP: <code>C:\Documents and Settings\<user>\Local Settings\Application Data\Android\debug.keystore</code></li> -<li>OS X and Linux: <code>~/.android/debug.keystore</code></li> -</ul> - -<p>If you are using Eclipse/ADT and are unsure where the debug keystore is located, you can select <strong>Windows</strong> > <strong>Prefs</strong> > <strong>Android</strong> > <strong>Build</strong> to check the full path, which you can then paste into a file explorer to locate the directory containing the keystore.</p> - -<p>Once you have located the keystore, use this Keytool command to get the MD5 fingerprint of the debug certificate:</p> - -<pre>$ keytool -list -alias androiddebugkey \ --keystore <path_to_debug_keystore>.keystore \ --storepass android -keypass android</pre> - -<h2 id="registering">Registering the Certificate Fingerprint with the Google Maps Service</h2> - -<p>When you are ready to register for a Maps API Key, load this page in a browser: </p> - -<p><a href="http://code.google.com/android/maps-api-signup.html">http://code.google.com/android/maps-api-signup.html</a></p> - -<p>To register for a Maps API Key, follow these steps:</p> - -<ol> -<li>If you don't have a Google account, use the link on the page to set one up. </li> -<li>Read the Android Maps API Terms of Service carefully. If you agree to the terms, indicate so using the checkbox on the screen. </li> -<li>Paste the MD5 certificate fingerprint of the certificate that you are registering into the appropriate form field.</li> -<li>Click "Generate API Key"</li> -</ol> - -<p>The server will handle your request, associating the fingerprint with your developer identity and generating a unique Maps API Key, then returning a results page that gives you your Key string. </p> - -<p>To use the Maps API Key string, copy and paste it into your code as described in the next section.</p> - -<h2 id="addingkey">Adding the Maps API Key to your Application</h2> - -<p>Once you've registered with the Google Maps service and have obtained a Maps API Key, you must add it to your application's MapView objects, so that the Maps server will allow them to download Maps tiles. </p> - -<p>For <code><MapView></code> elements declared in XML layout files, add the Maps API Key as the value of a special attribute — <code>android:apiKey</code>. For example: </li> - -<pre><com.google.android.maps.MapView - android:layout_width="fill_parent" - android:layout_height="fill_parent" - android:enabled="true" - android:clickable="true" - android:apiKey="example_Maps_ApiKey_String" - /></pre> -</li> - -<p>For MapView objects instantiated directly from code, pass the Maps API Key string as a parameter in the constructor. For example: </p> - -<pre>mMapView = new MapView(this, "example_Maps_ApiKey_String");</pre> - -<p>For more information about MapView, see the MapView class Documentation. </p> - -<h2 id="finalsteps">Final Steps to Enable MapView Elements</h2> - -<p>If you've added the Maps API Key to the MapViews in your application, here are the final steps to enable the MapView elements to run properly:</p> - -<ul> -<li>Make sure that you added a <code><uses-library></code> element referencing the external <code>com.google.android.maps</code> library. The element must be a child of the <code><application></code> element in the application's manifest. For example: - -<p><pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.example.package.name"> - ... - <application android:name="MyApplication" > - <uses-library android:name="com.google.android.maps" /> - ... - </application></pre></p></li> - -<li>Sign your application with the certificate that corresponds to the Maps API Key referenced in your MapView elements. </li> - -</ul> - -<div class="special"><p>Note that, when you are ready to publish your application, you must get a Maps API Key that is based on the certificate that you will use to sign the application for release. You must then change the Maps API Key string referenced by all of your MapView elements, so that they reference the new Key. </p></div> - - - diff --git a/docs/html/guide/topics/location/index.jd b/docs/html/guide/topics/location/index.jd deleted file mode 100644 index 53f1d29..0000000 --- a/docs/html/guide/topics/location/index.jd +++ /dev/null @@ -1,109 +0,0 @@ -page.title=Location -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>In this document</h2> - <ol> - <li><a href="#location">android.location</a></li> - <li><a href="#maps">com.google.android.maps</a></li> - </ol> -</div> -</div> - -<p>The Android SDK includes two packages that provide Android's primary support -for building location-based services: -{@link android.location} and {@link-fixme com.google.android.maps}. -Please read on below for a brief introduction to each package.</p> - -<h2 id="location">android.location</h2> - -<p>This package contains several classes related to -location services in the Android platform. Most importantly, it introduces the -{@link android.location.LocationManager} -service, which provides an API to determine location and bearing if the -underlying device (if it supports the service). The LocationManager -should <strong>not</strong> be -instantiated directly; rather, a handle to it should be retrieved via -{@link android.content.Context#getSystemService(String) -getSystemService(Context.LOCATION_SERVICE)}.</p> - -<p>Once your application has a handle to the LocationManager, your application -will be able to do three things:</p> - -<ul> - <li>Query for the list of all LocationProviders known to the - LocationManager for its last known location.</li> - <li>Register/unregister for periodic updates of current location from a - LocationProvider (specified either by Criteria or name).</li> - <li>Register/unregister for a given Intent to be fired if the device comes - within a given proximity (specified by radius in meters) of a given - lat/long.</li> -</ul> - -<p>However, during initial development, you may not have access to real -data from a real location provider (Network or GPS). So it may be necessary to -spoof some data for your application, with some mock location data.</p> - -<p class="note"><strong>Note:</strong> If you've used mock LocationProviders in -previous versions of the SDK (m3/m5), you can no longer provide canned LocationProviders -in the /system/etc/location directory. These directories will be wiped during boot-up. -Please follow the new procedures below.</p> - - -<h3>Providing Mock Location Data</h3> - -<p>When testing your application on the Android emulator, there are a couple different -ways to send it some spoof location data: with the DDMS tool or the "geo" command.</p> - -<h4 id="ddms">Using DDMS</h4> -<p>With the DDMS tool, you can simulate location data a few different ways:</p> -<ul> - <li>Manually send individual longitude/latitude coordinates to the device.</li> - <li>Use a GPX file describing a route for playback to the device.</li> - <li>Use a KML file describing individual placemarks for sequenced playback to the device.</li> -</ul> -<p>For more information on using DDMS to spoof location data, see the -<a href="{@docRoot}guide/developing/tools/ddms.html#emulator-control">Using DDMS guide</a>. - -<h4 id="geo">Using the "geo" command</h4> -<p>Launch your application in the Android emulator and open a terminal/console in -your SDK's <code>/tools</code> directory. Now you can use:</p> -<ul><li><code>geo fix</code> to send a fixed geo-location. - <p>This command accepts a longitude and latitude in decimal degrees, and - an optional altitude in meters. For example:</p> - <pre>geo fix -121.45356 46.51119 4392</pre> - </li> - <li><code>geo nmea</code> to send an NMEA 0183 sentence. - <p>This command accepts a single NMEA sentence of type '$GPGGA' (fix data) or '$GPRMC' (transit data). - For example:</p> - <pre>geo nmea $GPRMC,081836,A,3751.65,S,14507.36,E,000.0,360.0,130998,011.3,E*62</pre> - </li> -</ul> - - -<h2 id="maps">com.google.android.maps</h2> - -<p>This package introduces a number of classes related to -rendering, controlling, and overlaying customized information on your own -Google Mapified Activity. The most important of which is the -{@link-fixme com.google.android.maps.MapView} class, which automagically draws you a -basic Google Map when you add a MapView to your layout. Note that, if you -want to do so, then your Activity that handles the -MapView must extend {@link-fixme com.google.android.maps.MapActivity}. </p> - -<p>Also note that you must obtain a MapView API Key from the Google Maps -service, before your MapView can load maps data. For more information, see -<a href="{@docRoot}guide/topics/location/geo/mapkey.html">Obtaining a MapView API Key</a>.</p> - -<p>Once you've created a MapView, you'll probably want to use -{@link-fixme com.google.android.maps.MapView#getController()} to -retrieve a {@link-fixme com.google.android.maps.MapController}, for controlling and -animating the map, and {@link-fixme com.google.android.maps.ItemizedOverlay} to -draw {@link-fixme com.google.android.maps.Overlay}s and other information on the Map.</p> - -<p>This is not a standard package in the Android library. In order to use it, you must add the following node to your Android Manifest file, as a child of the -<code><application></code> element:</p> -<pre><uses-library android:name="com.google.android.maps" /></pre> - diff --git a/docs/html/guide/topics/manifest/action-element.jd b/docs/html/guide/topics/manifest/action-element.jd deleted file mode 100644 index bc2e1d3..0000000 --- a/docs/html/guide/topics/manifest/action-element.jd +++ /dev/null @@ -1,46 +0,0 @@ -page.title=<action> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><action android:<a href="#nm">name</a>="<i>string</i>" /></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code></dd> - -<p> -<dt>description:</dt> -<dd>Adds an action to an intent filter. -An <code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element must contain -one or more {@code <action>} elements. If it doesn't contain any, no -Intent objects will get through the filter. See -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and -Intent Filters</a> for details on intent filters and the role of action -specifications within a filter. -</dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the action. Some standard actions are defined in the -{@link android.content.Intent#ACTION_CHOOSER Intent} class as -{@code ACTION_<i>string</i>} constants. To assign one of these actions to -this attribute, prepend "{@code android.intent.action.}" to the -{@code <i>string</i>} that follows {@code ACTION_}. -For example, for {@code ACTION_MAIN}, use "{@code android.intent.action.MAIN}" -and for {@code ACTION_WEB_SEARCH}, use "{@code android.intent.action.WEB_SEARCH}". - -<p> -For actions you define, it's best to use the package name as a prefix to -ensure uniqueness. For example, a {@code TRANSMOGRIFY} action might be specified -as follows: -</p> - -<pre><action android:name="com.example.project.TRANSMOGRIFY" /></pre> -</dd> -</dl></dd> - -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code></dd> - -</dl>
\ No newline at end of file diff --git a/docs/html/guide/topics/manifest/activity-alias-element.jd b/docs/html/guide/topics/manifest/activity-alias-element.jd deleted file mode 100644 index 9d81d50..0000000 --- a/docs/html/guide/topics/manifest/activity-alias-element.jd +++ /dev/null @@ -1,129 +0,0 @@ -page.title=<activity-alias> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><activity-alias android:<a href="#enabled">enabled</a>=["true" | "false"] - android:<a href="#exported">exported</a>=["true" | "false"] - android:<a href="#icon">icon</a>="<i>drawable resource</i>" - android:<a href="#label">label</a>="<i>string resource</i>" - android:<a href="#nm">name</a>="<i>string</i>" - android:<a href="#prmsn">permission</a>="<i>string</i>" - android:<a href="#trgt">targetActivity</a>="<i>string</i>" > - . . . -</activity-alias></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> - -<dt>can contain:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code></dd> - -<dt>description:</dt> -<dd>An alias for an activity, named by the {@code targetActivity} -attribute. The target must be in the same application as the -alias and it must be declared before the alias in the manifest. - -<p> -The alias presents the target activity as a independent entity. -It can have its own set of intent filters, and they, rather than the -intent filters on the target activity itself, determine which intents -can activate the target through the alias and how the system -treats the alias. For example, the intent filters on the alias may -specify the "<code>{@link android.content.Intent#ACTION_MAIN -android.intent.action.MAIN}</code>" -and "<code>{@link android.content.Intent#CATEGORY_LAUNCHER -android.intent.category.LAUNCHER}</code>" flags, causing it to be -represented in the application launcher, even though none of the -filters on the target activity itself set these flags. -</p> - -<p> -With the exception of {@code targetActivity}, {@code <activity-alias>} -attributes are a subset of <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> attributes. -For attributes in the subset, none of the values set for the target carry over -to the alias. However, for attributes not in the subset, the values set for -the target activity also apply to the alias. -</p></dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the target activity can be instantiated by the system through -this alias — "{@code true}" if it can be, and "{@code false}" if not. -The default value is "{@code true}". - -<p> -The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all -application components, including activity aliases. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and {@code <activity-alias>} -attributes must both be "{@code true}" for the system to be able to instantiate -the target activity through the alias. If either is "{@code false}", the alias -does not work. -</p></dd> - -<dt><a name="exported"></a>{@code android:exported}</dt> -<dd>Whether or not components of other applications can launch the target activity -through this alias — "{@code true}" if they can, and "{@code false}" if not. -If "{@code false}", the target activity can be launched through the alias only by -components of the same application as the alias or applications with the same user ID. - -<p> -The default value depends on whether the alias contains intent filters. The -absence of any filters means that the activity can be invoked through the alias -only by specifying the exact name of the alias. This implies that the alias -is intended only for application-internal use (since others would not know its name) -— so the default value is "{@code false}". -On the other hand, the presence of at least one filter implies that the alias -is intended for external use — so the default value is "{@code true}". -</p></dd> - -<dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon for the target activity when presented to users through the alias. -See the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#icon">icon</a></code> attribute for more information. - -<dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the alias when presented to users through the alias. -See the the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#label">label</a></code> attribute for more information. -</p></dd> - -<dt><a name="nm">{@code android:name}</dt> -<dd>A unique name for the alias. The name should resemble a fully -qualified class name. But, unlike the name of the target activity, -the alias name is arbitrary; it does not refer to an actual class. -</p></dd> - -<dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that clients must have to launch the target activity -or get it to do something via the alias. If a caller of -<code>{@link android.content.Context#startActivity startActivity()}</code> or -<code>{@link android.app.Activity#startActivityForResult startActivityForResult()}</code> -has not been granted the specified permission, the target activity will not be -activated. - -<p>This attribute supplants any permission set for the target activity itself. If -it is not set, a permission is not needed to activate the target through the alias. -</p> - -<p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a> -section in the introduction. -</p></dd> - -<dt><a name="trgt"></a>{@code android:targetActivity}</dt> -<dd>The name of the activity that can be activated through the alias. -This name must match the {@code name} attribute of an -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element that precedes -the alias in the manifest. -</p></dd> -</dl></dd> - -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code></dd> - -</dl>
\ No newline at end of file diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd deleted file mode 100644 index aba89d7..0000000 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ /dev/null @@ -1,565 +0,0 @@ -page.title=<activity> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><activity android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] - android:<a href="#always">alwaysRetainTaskState</a>=["true" | "false"] - android:<a href="#clear">clearTaskOnLaunch</a>=["true"" | "false"] - android:<a href="#config">configChanges</a>=[<i>one or more of</i>: "mcc" "mnc" "locale" - "touchscreen" "keyboard" "keyboardHidden" - "navigation" "orientation" "fontScale"] - android:<a href="#enabled">enabled</a>=["true" | "false"] - android:<a href="#exclude">excludeFromRecents</a>=["true" | "false"] - android:<a href="#exported">exported</a>=["true" | "false"] - android:<a href="#finish">finishOnTaskLaunch</a>=["true" | "false"] - android:<a href="#icon">icon</a>="<i>drawable resource</i>" - android:<a href="#label">label</a>="<i>string resource</i>" - android:<a href="#lmode">launchMode</a>=["multiple" | "singleTop" | - "singleTask" | "singleInstance"] - android:<a href="#multi">multiprocess</a>=["true" | "false"] - android:<a href="#nm">name</a>="<i>string</i>" - android:<a href="#prmsn">permission</a>="<i>string</i>" - android:<a href="#proc">process</a>="<i>string</i>" - android:<a href="#screen">screenOrientation</a>=["unspecified" | "user" | "behind" | - "landscape" | "portrait" | - "sensor" | "nonsensor"] - android:<a href="#state">stateNotNeeded</a>=["true" | "false"] - android:<a href="#aff">taskAffinity</a>="<i>string</i>" - android:<a href="#theme">theme</a>="<i>resource or theme</i>" > - . . . -</activity></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> - -<dt>can contain:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code></dd> - -<dt>description:</dt> -<dd>Declares an activity (an {@link android.app.Activity} subclass) that -implements part of the application's visual user interface. All activities -must be represented by {@code <activity>} -elements in the manifest file. Any that are not declared there will not be seen -by the system and will never be run. - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a href name="reparent"></a>{@code android:allowTaskReparenting}</dt> -<dd>Whether or not the activity can move from the task that started it to -the task it has an affinity for when that task is next brought to the -front — "{@code true}" if it can move, and "{@code false}" if it -must remain with the task where it started. - -<p> -If this attribute is not set, the value set by the corresponding -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#reparent">allowTaskReparenting</a></code> -attribute of the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element -applies to the activity. The default value is "{@code false}". -</p> - -<p> -Normally when an activity is started, it's associated with the task of -the activity that started it and it stays there for its entire lifetime. -You can use this attribute to force it to be re-parented to the task it -has an affinity for when its current task is no longer displayed. -Typically, it's used to cause the activities of an application to move -to the main task associated with that application. -</p> - -<p> -For example, if an e-mail message contains a link to a web page, clicking -the link brings up an activity that can display the page. That activity -is defined by the browser application, but is launched as part of the e-mail -task. If it's reparented to the browser task, it will be shown when the -browser next comes to the front, and will be absent when the e-mail task -again comes forward. -</p> - -<p> -The affinity of an activity is defined by the -<code><a href="#aff">taskAffinity</a></code> attribute. The affinity -of a task is determined by reading the affinity of its root activity. -Therefore, by definition, a root activity is always in a task with the -same affinity. Since activities with "{@code singleTask}" or -"{@code singleInstance}" launch modes can only be at the root of a task, -re-parenting is limited to the "{@code standard}" and "{@code singleTop}" -modes. (See also the <code><a href="#lmode">launchMode</a></code> -attribute.) -</p></dd> - -<dt><a name="always"></a>{@code android:alwaysRetainTaskState}</dt> -<dd>Whether or not the state of the task that the activity is in will always -be maintained by the system — "{@code true}" if it will be, and -"{@code false}" if the system is allowed to reset the task to its initial -state in certain situations. The default value is "{@code false}". This -attribute is meaningful only for the root activity of a task; it's ignored -for all other activities. - -<p> -Normally, the system clears a task (removes all activities from the stack -above the root activity) in certain situations when the user re-selects that -task from the home screen. Typically, this is done if the user hasn't visited -the task for a certain amount of time, such as 30 minutes. -</p> - -<p> -However, when this attribute is "{@code true}", users will always return -to the task in its last state, regardless of how they get there. This is -useful, for example, in an application like the web browser where there is -a lot of state (such as multiple open tabs) that users would not like to lose. -</p></dd> - -<dt><a name="clear"></a>{@code android:clearTaskOnLaunch}</dt> -<dd>Whether or not all activities will be removed from the task, except for -the root activity, whenever it is re-launched from the home screen — -"{@code true}" if the task is always stripped down to its root activity, and -"{@code false}" if not. The default value is "{@code false}". This attribute -is meaningful only for activities that start a new task (the root activity); -it's ignored for all other activities in the task. - -<p> -When the value is "{@code true}", every time users start the task again, they -are brought to its root activity, regardless of what they were last doing in -the task and regardless of whether they used BACK or HOME to last leave it. -When the value is "{@code false}", the task may be cleared of activities in -some situations (see the -<code><a href="#always">alwaysRetainTaskState</a></code> attribute), but not always. -</p> - -<p> -Suppose, for example, that someone launches activity P from the home screen, -and from there goes to activity Q. The user next presses HOME, and then returns -to activity P. Normally, the user would see activity Q, since that is what they -were last doing in P's task. However, if P set this flag to "{@code true}", all -of the activities on top of it (Q in this case) were removed when the user pressed -HOME and the task went to the background. So the user sees only P when returning -to the task. -</p> - -<p> -If this attribute and <code><a href="#reparent">allowTaskReparenting</a></code> -are both "{@code true}", any activities that can be re-parented are moved to -the task they share an affinity with; the remaining activities are then dropped, -as described above. -</p></dd> - -<dt><a name="config"></a>{@code android:configChanges}</dt> -<dd>Lists configuration changes that the activity will handle itself. When -changes that are not listed occur, the activity is shut down and restarted. -When a listed change occurs, the activity remains running and its <code>{@link android.app.Activity#onConfigurationChanged onConfigurationChanged()}</code> -method is called. - -<p> -Any or all of the following strings can be used to set this attribute. Values are -separated by '{@code |}' — for example, "{@code locale|navigation|orientation}". -</p> - -<table> -<tr> - <td><b>Value</b></td> - <td><b>Description</b></td> -</tr><tr> - <td>"{@code mcc}"</td> - <td>The IMSI mobile country code (MCC) has changed — - that is, a SIM has been detected and updated the MCC.</td> -</tr><tr> - <td>"{@code mnc}"</td> - <td>The IMSI mobile network code (MNC) has changed — - that is, a SIM has been detected and updated the MNC.</td> -</tr><tr> - <td>"{@code locale}"</td> - <td>The locale has changed — for example, the user has selected a new - language that text should be displayed in.</td> -</tr><tr> - <td>"{@code touchscreen}"</td> - <td>The touchscreen has changed. (This should never normally happen.)</td> -</tr><tr> - <td>"{@code keyboard}"</td> - <td>The keyboard type has changed — for example, the user has - plugged in an external keyboard.</td> -</tr><tr> - <td>"{@code keyboardHidden}"</td> - <td>The keyboard accessibility has changed — for example, the - user has slid the keyboard out to expose it.</td> -</tr><tr> - <td>"{@code navigation}"</td> - <td>The navigation type has changed. (This should never normally happen.)</td> -</tr><tr> - <td>"{@code orientation}"</td> - <td>The screen orientation has changed — that is, the user has rotated - the device.</td> - </tr><tr> - <td>"{@code fontScale}"</td> - <td>The font scaling factor has changed — that is, the user has selected - a new global font size.</td> -</tr> -</table> - -<p> -All of these configuration changes can impact the resource values seen by the -application. Therefore, when <code>{@link android.app.Activity#onConfigurationChanged -onConfigurationChanged()}</code> is called, it will generally be necessary to again -retrieve all resources (including view layouts, drawables, and so on) to correctly -handle the change. -</p></dd> - -<dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the activity can be instantiated by the system — -"{@code true}" if it can be, and "{@code false}" if not. The default value -is "{@code true}". - -<p> -The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all -application components, including activities. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and {@code <activity>} -attributes must both be "{@code true}" (as they both are by default) for -the system to be able to instantiate the activity. If either is -"{@code false}", it cannot be instantiated. -</p></dd> - -<dt><a name="exclude"></a>{@code android:excludeFromRecents}</dt> -<dd>Whether or not the activity should be excluded from the list of recently -launched activities that can be displayed to users — "{@code true}" if -it should be excluded, and "{@code false}" if it should be included. -The default value is "{@code false}". -</p></dd> - -<dt><a name="exported"></a>{@code android:exported}</dt> -<dd>Whether or not the activity can be launched by components of other -applications — "{@code true}" if it can be, and "{@code false}" if not. -If "{@code false}", the activity can be launched only by components of the -same application or applications with the same user ID. - -<p> -The default value depends on whether the activity contains intent filters. The -absence of any filters means that the activity can be invoked only by specifying -its exact class name. This implies that the activity is intended only for -application-internal use (since others would not know the class name). So in -this case, the default value is "{@code false}". -On the other hand, the presence of at least one filter implies that the activity -is intended for external use, so the default value is "{@code true}". -</p> - -<p> -This attribute is not the only way to limit an activity's exposure to other -applications. You can also use a permission to limit the external entities that -can invoke the activity (see the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#prmsn">permission</a></code> -attribute). -</p></dd> - -<dt><a name="finish"></a>{@code android:finishOnTaskLaunch}</dt> -<dd>Whether or not an existing instance of the activity should be shut down -(finished) whenever the user again launches its task (chooses the task on the -home screen) — "{@code true}" if it should be shut down, and "{@code false}" -if not. The default value is "{@code false}". - -<p> -If this attribute and <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> -are both "{@code true}", this attribute trumps the other. The affinity of the -activity is ignored. The activity is not re-parented, but destroyed. -</p> - -<dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon representing the activity. The icon is displayed to users when -a representation of the activity is required on-screen. For example, icons -for activities that initiate tasks are displayed in the launcher window. -The icon is often accompanied by a label (see the {@code label} attribute). -</p> - -<p> -This attribute must be set as a reference to a drawable resource containing -the image definition. If it is not set, the icon specified for the application -as a whole is used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute). -</p> - -<p> -The activity's icon — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the -default icon for all the activity's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute). -</p></dd> - -<dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the activity. The label is displayed on-screen -when the activity must be represented to the user. It's often displayed along -with the activity icon. - -<p> -If this attribute is not set, the label set for the application as a whole is -used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). -</p> - -<p> -The activity's label — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the -default label for all the activity's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). -</p> - -<p> -The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, -it can also be set as a raw string. -</p></dd> - -<dt><a name="lmode"></a>{@code android:launchMode}</dt> -<dd>An instruction on how the activity should be launched. There are four modes -that work in conjunction with activity flags ({@code FLAG_ACTIVITY_*} constants) -in {@link android.content.Intent} objects to determine what should happen when -the activity is called upon to handle an intent. They are: - -<p style="margin-left: 2em">"{@code standard}" -<br>"{@code singleTop}" -<br>"{@code singleTask}" -<br>"{@code singleInstance}"</p> - -<p> -The default mode is "{@code standard}". -</p> - -<p> -The modes fall into two main groups, with "{@code standard}" and -"{@code singleTop}" activities on one side, and "{@code singleTask}" and -"{@code singleInstance}" activities on the other. An activity with the -"{@code standard}" or "{@code singleTop}" launch mode can be instantiated -multiple times. The instances can belong to any task and can be located -anywhere in the activity stack. Typically, they're launched into the task -that called -<code>{@link android.content.Context#startActivity startActivity()}</code> -(unless the Intent object contains a -<code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> -instruction, in which case a different task is chosen — see the -<a href="#aff">taskAffinity</a> attribute). -</p> - -<p> -In contrast, "{@code singleTask}" and "{@code singleInstance}" activities -can only begin a task. They are always at the root of the activity stack. -Moreover, the device can hold only one instance of the activity at a time -— only one such task. -</p> - -<p> -The "{@code standard}" and "{@code singleTop}" modes differ from each other -in just one respect: Every time there's new intent for a "{@code standard}" -activity, a new instance of the class is created to respond to that intent. -Each instance handles a single intent. -Similarly, a new instance of a "{@code singleTop}" activity may also be -created to handle a new intent. However, if the target task already has an -existing instance of the activity at the top of its stack, that instance -will receive the new intent (in an -<code>{@link android.app.Activity#onNewIntent onNewIntent()}</code> call); -a new instance is not created. -In other circumstances — for example, if an existing instance of the -"{@code singleTop}" activity is in the target task, but not at the top of -the stack, or if it's at the top of a stack, but not in the target task -— a new instance would be created and pushed on the stack. -</p> - -<p> -The "{@code singleTask}" and "{@code singleInstance}" modes also differ from -each other in only one respect: A "{@code singleTask}" activity allows other -activities to be part of its task. It's at the root of the activity stack, -but other activities (necessarily "{@code standard}" and "{@code singleTop}" -activities) can be launched into the same task. A "{@code singleInstance}" -activity, on the other hand, permits no other activities to be part of its -task. It's the only activity in the task. If it starts another activity, -that activity is assigned to a different task — as if {@code -FLAG_ACTIVITY_NEW_TASK} was in the intent. -</p> - -<p>For more information on launch modes and their interaction with Intent -flags, see the -<a href="{@docRoot}guide/topics/fundamentals.html#acttask">Activities and -Tasks</a> section of the -<a href="{@docRoot}guide/topics/fundamentals.html">Application Fundamentals</a> -document. -</p> -</dd> - -<dt><a name="multi"></a>{@code android:multiprocess}</dt> -<dd>Whether an instance of the activity can be launched into the process of the component -that started it — "{@code true}" if it can be, and "{@code false}" if not. -The default value is "{@code false}". - -<p> -Normally, a new instance of an activity is launched into the process of the -application that defined it, so all instances of the activity run in the same -process. However, if this flag is set to "{@code true}", instances of the -activity can run in multiple processes, allowing the system to create instances -wherever they are used (provided permissions allow it), something that is almost -never necessary or desirable. -</p></dd> - -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the class that implements the activity, a subclass of -{@link android.app.Activity}. The attribute value should be a fully qualified -class name (such as, "{@code com.example.project.ExtracurricularActivity}"). -However, as a shorthand, if the first character of the name is a period -(for example, "{@code .ExtracurricularActivity}"), it is appended to the -package name specified in the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> -element. - -<p> -There is no default. The name must be specified. -</p></dd> - -<dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that clients must have to launch the activity -or otherwise get it to respond to an intent. If a caller of -<code>{@link android.content.Context#startActivity startActivity()}</code> or -<code>{@link android.app.Activity#startActivityForResult startActivityForResult()}</code> -has not been granted the specified permission, its intent will not be -delivered to the activity. - -<p> -If this attribute is not set, the permission set by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> attribute applies -to the activity. If neither attribute is set, the activity is -not protected by a permission. -</p> - -<p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> -section in the introduction and another document, -<a href="{@docRoot}guide/topics/security/security.html">Security and -Permissions</a>. -</p></dd> - -<dt><a name="proc"></a>{@code android:process}</dt> -<dd>The name of the process in which the activity should run. Normally, -all components of an application run in the default process created for the -application. It has the same name as the application package. The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> attribute can set a different -default for all components. But each component can override the default, -allowing you to spread your application across multiple processes. - -<p> -If the name assigned to this attribute begins with a colon (':'), a new -process, private to the application, is created when it's needed and -the activity runs in that process. -If the process name begins with a lowercase character, the activity will run -in a global process of that name, provided that it has permission to do so. -This allows components in different applications to share a process, reducing -resource usage. -</p></dd> - -<dt><a name="screen"></a>{@code android:screenOrientation}</dt> -<dd>The orientation of the activity's display on the device. -The value can be any one of the following strings: - -<table> -<tr> - <td>"{@code unspecified}"</td> - <td>The default value. The system chooses the orientation. The policy it - uses, and therefore the choices made in specific contexts, may differ - from device to device.</td> -</tr><tr> - <td>"{@code landscape}"</td> - <td>Landscape orientation (the display is wider than it is tall).</td> -</tr><tr> - <td>"{@code portrait}"</td> - <td>Portrait orientation (the display is taller than it is wide).</td> -</tr><tr> - <td>"{@code user}"</td> - <td>The user's current preferred orientation.</td> -</tr><tr> - <td>"{@code behind}"</td> - <td>The same orientation as the activity that's immediately beneath it in - the activity stack.</td> -</tr><tr> - <td>"{@code sensor}"</td> - <td>The orientation determined by a physical orientation sensor. The - orientation of the display depends on how the user is holding the device; - it changes when the user rotates the device.</td> -</tr><tr> - <td>"{@code nosensor}"</td> - <td>An orientation determined without reference to a physical orientation sensor. - The sensor is ignored, so the display will not rotate based on how the user - moves the device. Except for this distinction, the system chooses the - orientation using the same policy as for the "{@code unspecified}" setting.</td> -</tr> -</table></dd> - -<dt><a name="state"></a>{@code android:stateNotNeeded}</dt> -<dd>Whether or not the activity can be killed and successfully restarted -without having saved its state — "{@code true}" if it can be restarted -without reference to its previous state, and "{@code false}" if its previous -state is required. The default value is "{@code false}". - -<p> -Normally, before an activity is temporarily shut down to save resources, its -<code>{@link android.app.Activity#onSaveInstanceState onSaveInstanceState()}</code> -method is called. This method stores the current state of the activity in a -{@link android.os.Bundle} object, which is then passed to -<code>{@link android.app.Activity#onCreate onCreate()}</code> when the activity -is restarted. If this attribute is set to "{@code true}", -{@code onSaveInstanceState()} may not be called and {@code onCreate()} will -be passed {@code null} instead of the Bundle — just as it was when the -activity started for the first time. -</p> - -<p> -A "{@code true}" setting ensures that the activity can be restarted in the -absence of retained state. For example, the activity that displays the -home screen uses this setting to make sure that it does not get removed if it -crashes for some reason. -</p></dd> - -<dt><a name="aff"></a>{@code android:taskAffinity}</dt> -<dd>The task that the activity has an affinity for. Activities with -the same affinity conceptually belong to the same task (to the same -"application" from the user's perspective). The affinity of a task -is determined by the affinity of its root activity. - -<p> -The affinity determines two things — the task that the activity is re-parented -to (see the <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> -attribute) and the task that will house the activity when it is launched -with the <code>{@link android.content.Intent#FLAG_ACTIVITY_NEW_TASK}</code> -flag. -</p> - -<p> -By default, all activities in an application have the same affinity. You -can set this attribute to group them differently, and even place -activities defined in different applications within the same task. To -specify that the activity does not have an affinity for any task, set -it to an empty string. - -<p> -If this attribute is not set, the activity inherits the affinity set -for the application (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#aff">taskAffinity</a></code> attribute). -The name of the default affinity for an application is the package name set -by the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. -</p> - -<dt><a name="theme"></a>{@code android:theme}</dt> -<dd>A reference to a style resource defining an overall theme for the activity. -This automatically sets the activity's context to use this theme (see -<code>{@link android.content.Context#setTheme setTheme()}</code>, and may also -cause "starting" animations prior to the activity being launched (to better -match what the activity actually looks like). - -<p> -If this attribute is not set, the activity inherits the theme set for the -application as a whole — see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#theme">theme</a></code> attribute. If that attribute is -also not set, the default system theme is used. -</p> -<dd> -</dl></dd> - -</dl>
\ No newline at end of file diff --git a/docs/html/guide/topics/manifest/application-element.jd b/docs/html/guide/topics/manifest/application-element.jd deleted file mode 100644 index 362c205..0000000 --- a/docs/html/guide/topics/manifest/application-element.jd +++ /dev/null @@ -1,226 +0,0 @@ -page.title=<application> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><application android:<a href="#clear">allowClearUserData</a>=["true" | "false"] - android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] - android:<a href="#debug">debuggable</a>=["true" | "false"] - android:<a href="#desc">description</a>="<i>string resource</i>" - android:<a href="#enabled">enabled</a>=["true" | "false"] - android:<a href="#code">hasCode</a>=["true" | "false"] - android:<a href="#icon">icon</a>="<i>drawable resource</i>" - android:<a href="#label">label</a>="<i>string resource</i>" - android:<a href="#space">manageSpaceActivity</a>="<i>string</i>" - android:<a href="#nm">name</a>="<i>string</i>" - android:<a href="#prmsn">permission</a>="<i>string</i>" - android:<a href="#persistent">persistent</a>=["true" | "false"] - android:<a href="#proc">process</a>="<i>string</i>" - android:<a href="#aff">taskAffinity</a>="<i>string</i>" - android:<a href="#theme">theme</a>="<i>resource or theme</i>" > - . . . -</application></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> - -<dt>can contain:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code></dd> - -<dt>description:</dt> -<dd>The declaration of the application. This element contains subelements -that declare each of the application's components and has attributes -that can affect all the components. Many of these attributes (such as -{@code icon}, {@code label}, {@code permission}, {@code process}, -{@code taskAffinity}, and {@code allowTaskReparenting}) set default values -for corresponding attributes of the component elements. Others (such as -{@code debuggable}, {@code enabled}, {@code description}, and -{@code allowClearUserData}) set values for the application as a whole and -cannot be overridden by the components.</dd> - -<dt>attributes</dt> -<dd><dl class="attr"> -<dt><a name="clear"></a>{@code android:allowClearUserData}</dt> -<dd>Whether or not users are given the option to remove user data — -"{@code true}" if they are, and "{@code false}" if not. If the value is -"{@code true}", as it is by default, the application manager includes an -option that allows users to clear the data.</dd> - -<dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt> -<dd>Whether or not activities that the application defines can move from -the task that started them to the task they have an affinity for when that task -is next brought to the front — "{@code true}" if they can move, and -"{@code false}" if they must remain with the task where they started. -The default value is "{@code false}". - -<p> -The -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -element has its own -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> -attribute that can override the value set here. See that attribute for more -information. -</p></dd> - -<dt><a name="debug"></a>{@code android:debuggable}</dt> -<dd>Whether or not the application can be debugged, even when running -on a device in user mode — "{@code true}" if it can be, and "{@code false}" -if not. The default value is "{@code false}".</dd> - -<dt><a name="desc"></a>{@code android:description}</dt> -<dd>User-readable text about the application, longer and more descriptive than the application label. The value must be set as a reference to a string resource. Unlike the label, it cannot be a raw string. There is no default value.</dd> - -<dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the Android system can instantiate components of -the application — "{@code true}" if it can, and "{@code false}" -if not. If the value is "{@code true}", each component's -{@code enabled} attribute determines whether that component is enabled -or not. If the value is "{@code false}", it overrides the -component-specific values; all components are disabled. - -<p> -The default value is "{@code true}". -</p></dd> - -<dt><a name="code"></a>{@code android:hasCode}</dt> -<dd>Whether or not the application contains any code — "{@code true}" -if it does, and "{@code false}" if not. When the value is "{@code false}", -the system does not try to load any application code when launching components. -The default value is "{@code true}". - -<p> -An application would not have any code of its own only if it's using nothing -but built-in component classes, such as an activity that uses the {@link -android.app.AliasActivity} class, a rare occurrence. - -<dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon for the application as whole, and the default icon for -each of the application's components. See the individual -{@code icon} attributes for -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. - -<p> -This attribute must be set as a reference to a drawable resource containing -the image definition. There is no default icon. -</p></dd> - -<dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the application as a whole, and a default -label for each of the application's components. See the individual -{@code label} attributes for -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. - -<p> -The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, -it can also be set as a raw string. -</p></dd> - -<dt><a name="space"></a>{@code android:manageSpaceActivity}</dt> -<dd>The fully qualified name of an Activity subclass that the system -can launch to let users manage the memory occupied by the application -on the device. The activity should also be declared with an -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element. -</dd> - -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The fully qualified name of an {@link android.app.Application} -subclass implemented for the application. When the application process -is started, this class is instantiated before any of the application's -components. - -<p> -The subclass is optional; most applications won't need one. -In the absence of a subclass, Android uses an instance of the base -Application class. -</p></dd> - -<dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that clients must have in order to interact -with the application. This attribute is a convenient way to set a -permission that applies to all of the application's components. It can -be overwritten by setting the {@code permission} attributes of individual -components. - -<p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> -section in the introduction and another document, -<a href="{@docRoot}guide/topics/security/security.html">Security and -Permissions</a>. -</p></dd> - -<dt><a name="persistent"></a>{@code android:persistent}</dt> -<dd>Whether or not the application should remain running at all times — -"{@code true}" if it should, and "{@code false}" if not. The default value -is "{@code false}". Applications should not normally set this flag; -persistence mode is intended only for certain system applications.</dd> - -<dt><a name="proc"></a>{@code android:process}</dt> -<dd>The name of a process where all components of the application should run. -Each component can override this default by setting its own {@code process} -attribute. - -<p> -By default, Android creates a process for an application when the first -of its components needs to run. All components then run in that process. -The name of the default process matches the package name set by the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. -</p> - -<p>By setting this attribute to a process name that's shared with another -application, you can arrange for components of both applications to run in -the same process — but only if the two applications also share a -user ID and be signed with the same certificate. -</p> - -<p> -If the name assigned to this attribute begins with a colon (':'), a new -process, private to the application, is created when it's needed. -If the process name begins with a lowercase character, a global process -of that name is created. A global process can be shared with other -applications, reducing resource usage. -</p></dd> - -<dt><a href name="aff"></a>{@code android:taskAffinity}</dt> -<dd>An affinity name that applies to all activities within the application, -except for those that set a different affinity with their own -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> -attributes. See that attribute for more information. - -<p> -By default, all activities within an application share the same -affinity. The name of that affinity is the same as the package name -set by the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. -</p></dd> - -<dt><a name="theme"></a>{@code android:theme}</dt> -<dd>A reference to a style resource defining a default theme for all -activities in the application. Individual activities can override -the default by setting their own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#theme">theme</a></code> -attributes; see that attribute for more information.</dd> - -</dl></dd> - -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/category-element.jd b/docs/html/guide/topics/manifest/category-element.jd deleted file mode 100644 index 50ea576..0000000 --- a/docs/html/guide/topics/manifest/category-element.jd +++ /dev/null @@ -1,38 +0,0 @@ -page.title=<category> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><category android:<a href="#nm">name</a>="<i>string</i>" /></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code></dd> - -<dt>description:</dt> -<dd>Adds a category name to an intent filter. See -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and -Intent Filters</a> for details on intent filters and the role of category -specifications within a filter.</dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the category. Standard categories are defined in the -{@link android.content.Intent} class as {@code CATEGORY_<i>name</i>} -constants. The name assigned here can be derived from those constants -by prefixing "{@code android.intent.category.}" to the -{@code <i>name</i>} that follows {@code CATEGORY_}. For example, -the string value for {@code CATEGORY_LAUNCHER} is -"{@code android.intent.category.LAUNCHER}". - -<p> -Custom categories should use the package name as a prefix, to ensure -that they are unique. -</p></dd> -</dl></dd> - -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/data-element.jd b/docs/html/guide/topics/manifest/data-element.jd deleted file mode 100644 index 5d8fde2..0000000 --- a/docs/html/guide/topics/manifest/data-element.jd +++ /dev/null @@ -1,148 +0,0 @@ -page.title=<data> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><data android:<a href="#host">host</a>="<i>string</i>" - android:<a href="#mime">mimeType</a>="<i>string</i>" - android:<a href="#path">path</a>="<i>string</i>" - android:<a href="#path">pathPattern</a>="<i>string</i>" - android:<a href="#path">pathPrefix</a>="<i>string</i>" - android:<a href="#port">port</a>="<i>string</i>" - android:<a href="#scheme">scheme</a>="<i>string</i>" /></pre></dd> - - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code></dd> - -<dt>description:</dt> -<dd>Adds a data specification to an intent filter. The specification can -be just a data type (the <code><a href="{@docRoot}guide/topics/manifest/data-element.html#mime">mimeType</a></code> attribute), -just a URI, or both a data type and a URI. A URI is specified by separate -attributes for each of its parts: - -<p style="margin-left: 2em">{@code scheme://host:port/path} <i>or</i> -{@code pathPrefix} <i>or</i> {@code pathPattern}</p> - -<p> -These attributes are optional, but also mutually dependent: -If a <code><a href="{@docRoot}guide/topics/manifest/data-element.html#scheme">scheme</a></code> is not specified for the -intent filter, all the other URI attributes are ignored. If a -<code><a href="{@docRoot}guide/topics/manifest/data-element.html#host">host</a></code> is not specified for the filer, -the {@code port} attribute and all the path attributes are ignored. -</p> - -<p> -All the {@code <data>} elements contained within the same -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element contribute to -the same filter. So, for example, the following filter specification, -</p> - -<pre><intent-filter . . . > - <data android:scheme="something" android:host="project.example.com" /> - . . . -</intent-filter></pre> - -<p>is equivalent to this one:</p> - -<pre><intent-filter . . . > - <data android:scheme="something" /> - <data android:host="project.example.com" /> - . . . -</intent-filter></pre> - -<p> -You can place any number of <data> elements inside an -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> to give it multiple data -options. None of its attributes have default values. -</p> - -<p> -Information on how intent filters work, including the rules for how Intent objects -are matched against filters, can be found in another document, -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and -Intent Filters</a>. See also the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#ifs">Intent Filters</a> -section in the introduction. -</p></dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="host"></a>{@code android:host}</dt> -<dd>The host part of a URI authority. This attribute is meaningless -unless a <code><a href="{@docRoot}guide/topics/manifest/data-element.html#scheme">scheme</a></code> attribute is also -specified for the filter. -</dd> - -<dt><a name="mime"></a>{@code android:mimeType}</dt> -<dd>A MIME media type, such as {@code image/jpeg} or {@code audio/mpeg4-generic}. -The subtype can be the asterisk wildcard ({@code *}) to indicate that any -subtype matches.</dd> - -<dt><a name="path"></a>{@code android:path} -<br/>{@code android:pathPrefix} -<br/>{@code android:pathPattern}</dt> -<dd>The path part of a URI. The {@code path} attribute specifies a complete -path that is matched against the complete path in an Intent object. The -{@code pathPrefix} attribute specifies a partial path that is matched against -only the initial part of the path in the Intent object. The {@code pathPattern} -attribute specifies a complete path that is matched against the complete path -in the Intent object, but it can contain the following wildcards: - -<ul> -<li>An asterisk ('{@code *}') matches a sequence of 0 to many occurrences of -the immediately preceding character.</li> - -<li>A period followed by an asterisk ("{@code .*}") matches any sequence of -0 to many characters.</li> -</ul> - -<p> -Because '{@code \}' is used as an escape character when the string is read -from XML (before it is parsed as a pattern), you will need to double-escape: -For example, a literal '{@code *}' would be written as "{@code \\*}" and a -literal '{@code \}' would be written as "{@code \\\\}". This is basically -the same as what you would need to write if constructing the string in Java code. -</p> - -<p> -For more information on these three types of patterns, see the descriptions of -{@link android.os.PatternMatcher#PATTERN_LITERAL}, -{@link android.os.PatternMatcher#PATTERN_PREFIX}, and -{@link android.os.PatternMatcher#PATTERN_SIMPLE_GLOB} in the -{@link android.os.PatternMatcher} class. -</p> - -<p>These attributes are meaningful only if the -<code><a href="#scheme">scheme</a></code> and <code><a href="#host">host</a></code> -attributes are also specified for the filter. -</p></dd> - -<dt><a name="port"></a>{@code android:port}</dt> -<dd>The port part of a URI authority. This attribute is meaningful only -if the <code><a href="#scheme">scheme</a></code> and -<code><a href="#host">host</a></code> attributes are also specified for -the filter.</dd> - -<dt><a name="scheme"></a>{@code android:scheme}</dt> -<dd>The scheme part of a URI. This is the minimal essential attribute for -specifying a URI; at least one {@code scheme} attribute must be set -for the filter, or none of the other URI attributes are meaningful. - -<p> -A scheme is specified without the trailing colon (for example, -{@code http}, rather than {@code http:}). -</p> - -<p> -If the filter has a data type set (the <code><a href="{@docRoot}guide/topics/manifest/data-element.html#mime">mimeType</a></code> -attribute) but no scheme, the {@code content:} and {@code file:} schemes are -assumed. -</p></dd> -</dl></dd> - -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/category-element.html"><category></a></code></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/grant-uri-permission-element.jd b/docs/html/guide/topics/manifest/grant-uri-permission-element.jd deleted file mode 100644 index f5b37b5..0000000 --- a/docs/html/guide/topics/manifest/grant-uri-permission-element.jd +++ /dev/null @@ -1,85 +0,0 @@ -page.title=<grant-uri-permission> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><grant-uri-permission android:<a href="#path">path</a>="<i>string</i>" - android:<a href="#path">pathPattern</a>="<i>string</i>" - android:<a href="#path">pathPrefix</a>="<i>string</i>" /></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code></dd> - -<dt>description:</dt> -<dd>Specifies which data subsets of the parent content provider permission -can be granted for. Data subsets are indicated by the path part of a -{@code content:} URI. (The authority part of the URI identifies the -content provider.) -Granting permission is a way of enabling clients of the provider that don't -normally have permission to access its data to overcome that restriction on -a one-time basis. - -<p> -If a content provider's <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmns">grantUriPermissions</a></code> -attribute is "{@code true}", permission can be granted for any the data under -the provider's purview. However, if that attribute is "{@code false}", permission -can be granted only to data subsets that are specified by this element. -A provider can contain any number of {@code <grant-uri-permission>} elements. -Each one can specify only one path (only one of the three possible attributes). -</p> - -<p> -For information on how permission is granted, see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmsn">grantUriPermissions</a></code> attribute. -</p></dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="path"></a>{@code android:path} -<br/>{@code android:pathPrefix} -<br/>{@code android:pathPattern}</dt> -<dd>A path identifying the data subset or subsets that permission can be -granted for. The {@code path} attribute specifies a complete path; -permission can be granted only to the particular data subset identified -by that path. -The {@code pathPrefix} attribute specifies the initial part of a path; -permission can be granted to all data subsets with paths that share that -initial part. -The {@code pathPattern} attribute specifies a complete path, but one -that can contain the following wildcards: - -<ul> -<li>An asterisk ('{@code *}') matches a sequence of 0 to many occurrences of -the immediately preceding character.</li> - -<li><p>A period followed by an asterisk ("{@code .*}") matches any sequence of -0 to many characters.</p></li> -</ul> - -<p> -Because '{@code \}' is used as an escape character when the string is read -from XML (before it is parsed as a pattern), you will need to double-escape: -For example, a literal '{@code *}' would be written as "{@code \\*}" and a -literal '{@code \}' would be written as "{@code \\\\}". This is basically -the same as what you would need to write if constructing the string in Java code. -</p> - -<p> -For more information on these types of patterns, see the descriptions of -{@link android.os.PatternMatcher#PATTERN_LITERAL}, -{@link android.os.PatternMatcher#PATTERN_PREFIX}, and -{@link android.os.PatternMatcher#PATTERN_SIMPLE_GLOB} in the -{@link android.os.PatternMatcher} class. -</p></dd> -</dl></dd> - -<dt>see also:</dt> -<dd>the -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#gprmns">grantUriPermissions</a></code> -attribute of the -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> -element</dd> - - -</dl> diff --git a/docs/html/guide/topics/manifest/instrumentation-element.jd b/docs/html/guide/topics/manifest/instrumentation-element.jd deleted file mode 100644 index fdec949..0000000 --- a/docs/html/guide/topics/manifest/instrumentation-element.jd +++ /dev/null @@ -1,61 +0,0 @@ -page.title=<instrumentation> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><instrumentation android:<a href="#ftest">functionalTest</a>=["true" | "false"] - android:<a href="#hprof">handleProfiling</a>=["true" | "false"] - android:<a href="#icon">icon</a>="<i>drawable resource</i>" - android:<a href="#label">label</a>="<i>string resource</i>" - android:<a href="#nm">name</a>="<i>string</i>" - android:<a href="#trgt">targetPackage</a>="<i>string</i>" /></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> - -<dt>description:</dt> -<dd>Declares an {@link android.app.Instrumentation} class that enables you -to monitor an application's interaction with the system. The Instrumentation -object is instantiated before any of the application's components.</dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="ftest"></a>{@code android:functionalTest}</dt> -<dd>Whether or not the Instrumentation class should run as a functional test -— "{@code true}" if it should, and "{@code false}" if not. The -default value is "{@code false}".</dd> - -<dt><a name="hprof"></a>{@code android:handleProfiling}</dt> -<dd>Whether or not the Instrumentation object will turn profiling on and -off — "{@code true}" if it determines when profiling starts and -stops, and "{@code false}" if profiling continues the entire time it is -running. A value of "{@code true}" enables the object to target profiling -at a specific set of operations. The default value is "{@code false}".</dd> - -<dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon that represents the Instrumentation class. This attribute must -be set as a reference to a drawable resource.</dd> - -<dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the Instrumentation class. The label can -be set as a raw string or a reference to a string resource.</dd> - -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the {@link android.app.Instrumentation} subclass. -This should be a fully qualified class name (such as, -"{@code com.example.project.StringInstrumentation}"). However, as a shorthand, -if the first character of the name is a period, it is appended to the package -name specified in the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. - -<p> -There is no default. The name must be specified. -</p></dd> - -<dt><a name="trgt"></a>{@code android:targetPackage}</dt> -<dd>The application that the Instrumentation object will run against. -An application is identified by the package name assigned in its manifest -file by the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element.</dd> - -</dl></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/intent-filter-element.jd b/docs/html/guide/topics/manifest/intent-filter-element.jd deleted file mode 100644 index 58d1f91..0000000 --- a/docs/html/guide/topics/manifest/intent-filter-element.jd +++ /dev/null @@ -1,130 +0,0 @@ -page.title=<intent-filter> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><intent-filter android:<a href="#icon">icon</a>="<i>drawable resource</i>" - android:<a href="#label">label</a>="<i>string resource</i>" - android:<a href="#priority">priority</a>="<i>integer</i>" > - . . . -</intent-filter></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code></dd> - -<dt>must contain:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code></dd> - -<dt>can contain:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/category-element.html"><category></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code></dd> - -<dt>description:</dt> -<dd>Specifies the types of intents that an activity, service, or broadcast -receiver can respond to. An intent filter declares the capabilities of its -parent component — what an activity or service can do and what types -of broadcasts a receiver can handle. It opens the component to receiving -intents of the advertised type, while filtering out those that are not -meaningful for the component. - -<p> -Most of the contents of the filter are described by its -<code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/category-element.html"><category></a></code>, and -<code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> subelements. -</p> - -<p> -For a more detailed discussion of filters, see the separate -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents -and Intent Filters</a> document, as well as the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#ifs">Intents Filters</a> -section in the introduction. -</p></dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon that represents the parent activity, service, or broadcast -receiver when that component is presented to the user as having the -capability described by the filter. - -<p> -This attribute must be set as a reference to a drawable resource -containing the image definition. The default value is the icon set -by the parent component's {@code icon} attribute. If the parent -does not specify an icon, the default is the icon set by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element. -</p> - -<p> -For more on intent filter icons, see -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#iconlabel">Icons and Labels</a> -in the introduction. -</p></dd> - -<dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the parent component. This label, rather than -the one set by the parent component, is used when the component is presented -to the user as having the capability described by the filter. - -<p> -The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, -it can also be set as a raw string. -</p> - -<p> -The default value is the label set by the parent component. If the -parent does not specify a label, the default is the label set by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label"> label</a></code> attribute. -</p> - -<p> -For more on intent filter labels, see -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#iconlabel">Icons and Labels</a> -in the introduction. -</p></dd> - -<dt><a name="priority"></a>{@code android:priority}</dt> -<dd>The priority that should be given to the parent component with regard -to handling intents of the type described by the filter. This attribute has -meaning for both activities and broadcast receivers: - -<ul> -<li>It provides information about how able an activity is to respond to -an intent that matches the filter, relative to other activities that could -also respond to the intent. When an intent could be handled by multiple -activities with different priorities, Android will consider only those with -higher priority values as potential targets for the intent.</li> - -<li><p>It controls the order in which broadcast receivers are executed to -receive broadcast messages. Those with higher priority -values are called before those with lower values. (The order applies only -to synchronous messages; it's ignored for asynchronous messages.)</p></li> -</ul> - -<p> -Use this attribute only if you really need to impose a specific order in -which the broadcasts are received, or want to force Android to prefer -one activity over others. -</p> - -<p> -The value must be an integer, such as "{@code 100}". Higher numbers have a -higher priority. -</p></dd> - -</dl></dd> - -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/category-element.html"><category></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/manifest-element.jd b/docs/html/guide/topics/manifest/manifest-element.jd deleted file mode 100644 index 2669487..0000000 --- a/docs/html/guide/topics/manifest/manifest-element.jd +++ /dev/null @@ -1,94 +0,0 @@ -page.title=<manifest> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><manifest xmlns:<a href="#nspace">android</a>="http://schemas.android.com/apk/res/android" - <a href="#package">package</a>="<i>string</i>" - android:<a href="#uid">sharedUserId</a>="<i>string</i>" - android:<a href="#vcode">versionCode</a>="<i>integer</i>" - android:<a href="#vname">versionName</a>="<i>string</i>" > - . . . -</manifest></pre></dd> - -<p> -<dt>contained in:</dt> -<dd><i>none</i></dd> - -<p> -<p> -<dt>must contain:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> - -<dt>can contain:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></dd> - -<p> -<dt>description:</dt> -<dd>The root element of the AndroidManifest.xml file. It must -contain an <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element -and specify {@code xlmns:android} and {@code package} attributes.</dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="nspace"></a>{@code xmlns:android}</dt> -<dd>Defines the Android namespace. This attribute should always be set -to "{@code http://schemas.android.com/apk/res/android}".</dd> - -<dt><a name="package"></a>{@code package}</dt> -<dd>A full Java package name for the application. The name should -be unique. For example, applications published by Google could have -names in the form <code>com.google.app.<i>application_name</i></code>. - -<p> -The package name serves as a unique identifier for the application. -It's also the default name for the application process (see the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#aff">process</a></code> -process</a></code> attribute) and the default task affinity of an activity -(see the -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -element's -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> attribute). -</p></dd> - -<dt><a name="uid"></a>{@code android:sharedUserId}</dt> -<dd>The name of a Linux user ID that will be shared with other applications. -By default, Android assigns each application its own unique user ID. -However, if this attribute is set to the same value for two or more applications, -they will all share the same ID — provided that they are also signed -by the same certificate. Application with the same user ID can access each -other's data and, if desired, run in the same process.</dd> - -<dt><a name="vcode"></a>{@code android:versionCode}</dt> -<dd>An internal version number. This number is used only to determine whether -one version is more recent than another, with higher numbers indicating more -recent versions. This is not the version number shown to users; that number -is set by the {@code versionName} attribute. - -<p> -The value must be set as an integer, such as "100". You can define it however -you want, as long as each successive version has a higher number. For example, -it could be a build number. Or you could translate a version number in "x.y" -format to an integer by encoding the "x" and "y" separately in the lower and -upper 16 bits. Or you could simply increase the number by one each time a new -version is released. -</p></dd> - -<dt><a name="vname"></a>{@code android:versionName}</dt> -<dd>The version number shown to users. This attribute can be set as a raw -string or as a reference to a string resource. The string has no other purpose -than to be displayed to users. The {@code versionCode} attribute holds -the significant version number used internally. -</dl></dd> - -<p> -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/manifest-intro.jd b/docs/html/guide/topics/manifest/manifest-intro.jd deleted file mode 100644 index 3c8a34a..0000000 --- a/docs/html/guide/topics/manifest/manifest-intro.jd +++ /dev/null @@ -1,511 +0,0 @@ -page.title=The AndroidManifest.xml File -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>In this document</h2> -<ol> -<li><a href="#filestruct">Structure of the Manifest File</a></li> -<li><a href="#filec">File Conventions</a> -<li><a href="#filef">File Features</a> - <ol> - <li><a href="#ifs">Intent Filters</a></li> - <li><a href="#iconlabel">Icons and Labels</a></li> - <li><a href="#perms">Permissions</a></li> - <li><a href="#libs">Libraries</a></li> - </ol></li> -</ol> -</div> -</div> - -<p> -Every application must have an AndroidManifest.xml file (with precisely that -name) in its root directory. The manifest presents essential information about -the application to the Android system, information the system must have before -it can run any of the application's code. Among other things, the manifest -does the following: -</p> - -<ul> -<li>It names the Java package for the application. -The package name serves as a unique identifier for the application.</li> - -<li>It describes the components of the application — the activities, -services, broadcast receivers, and content providers that the application is -composed of. It names the classes that implement each of the components and -publishes their capabilities (for example, which {@link android.content.Intent -Intent} messages they can handle). These declarations let the Android system -know what the components are and under what conditions they can be launched.</li> - -<li>It determines which processes will host application components.</li> - -<li>It declares which permissions the application must have in order to -access protected parts of the API and interact with other applications.</li> - -<li>It also declares the permissions that others are required to have in -order to interact with the application's components.</li> - -<li>It lists the {@link android.app.Instrumentation} classes that provide -profiling and other information as the application is running. These declarations -are present in the manifest only while the application is being developed and -tested; they're removed before the application is published.</li> - -<li>It declares the minimum version of the Android API that the application -requires.</li> - -<li>It lists the libraries that the application must be linked against.</li> -</ul> - - -<h2 id="filestruct">Structure of the Manifest File</h2> - -<p> -The diagram below shows the general structure of the manifest file and -every element that it can contain. Each element, along with all of its -attributes, is documented in full in a separate file. To view detailed -information about any element, click on the element name in the diagram, -in the alphabetical list of elements that follows the diagram, or on any -other mention of the element name. -</p> - -<pre> -<?xml version="1.0" encoding="utf-8"?> - -<a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a> - - <a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission /></a> - <a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission /></a> - <a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree /></a> - <a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group /></a> - - <a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation /></a> - - <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk /></a> - - <a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a> - - <a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a> - <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> - <a href="{@docRoot}guide/topics/manifest/action-element.html"><action /></a> - <a href="{@docRoot}guide/topics/manifest/category-element.html"><category /></a> - <a href="{@docRoot}guide/topics/manifest/data-element.html"><data /></a> - <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> - <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> - <a href="{@docRoot}guide/topics/manifest/activity-element.html"></activity></a> - - <a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a> - <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> - <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> - <a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"></activity-alias></a> - - <a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a> - <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> - <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data/></a> - <a href="{@docRoot}guide/topics/manifest/service-element.html"></service></a> - - <a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a> - <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a> . . . <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"></intent-filter></a> - <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> - <a href="{@docRoot}guide/topics/manifest/receiver-element.html"></receiver></a> - - <a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a> - <a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission /></a> - <a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data /></a> - <a href="{@docRoot}guide/topics/manifest/provider-element.html"></provider></a> - - <a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library /></a> - - <a href="{@docRoot}guide/topics/manifest/application-element.html"></application></a> - -<a href="{@docRoot}guide/topics/manifest/manifest-element.html"></manifest></a> -</pre> - -<p> -All the elements that can appear in the manifest file are listed below -in alphabetical order. These are the only legal elements; you cannot -add your own elements or attributes. -</p> - -<p style="margin-left: 2em"> -<code><a href="{@docRoot}guide/topics/manifest/action-element.html"><action></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/category-element.html"><category></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/data-element.html"><data></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/instrumentation-element.html"><instrumentation></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html"><uses-sdk></a></code> -</p> - - - -<h2 id="filec">File Conventions</h2> - -<p> -Some conventions and rules apply generally to all elements and attributes -in the manifest: -</p> - -<dl> -<dt><b>Elements</b></dt> -<dd>Only the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> and -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -elements are required, they each must be present and can occur only once. -Most of the others can occur many times or not at all — although at -least some of them must be present for the manifest to accomplish anything -meaningful. - -<p> -If an element contains anything at all, it contains other elements. -All values are set through attributes, not as character data within an element. -</p> - -<p> -Elements at the same level are generally not ordered. For example, -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>, and -<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> -elements can be intermixed in any sequence. (An -<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> -element is the exception to this rule: It must follow the -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -it is an alias for.) -</p></dd> - -<dt><b>Attributes</b></dt> -<dd>In a formal sense, all attributes are optional. However, there are some -that must be specified for an element to accomplish its purpose. Use the -documentation as a guide. For truly optional attributes, it mentions a default -value or states what happens in the absence of a specification. - -<p>Except for some attributes of the root -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> -element, all attribute names begin with an {@code android:} prefix — -for example, {@code android:alwaysRetainTaskState}. Because the prefix is -universal, the documentation generally omits it when referring to attributes -by name.</p></dd> - -<dt><b>Declaring class names</b></dt> -<dd>Many elements correspond to Java objects, including elements for the -application itself (the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element) and its principal components — activities -(<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>), -services -(<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>), -broadcast receivers -(<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>), -and content providers -(<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code>). - -<p> -If you define a subclass, as you almost always would for the component classes -({@link android.app.Activity}, {@link android.app.Service}, -{@link android.content.BroadcastReceiver}, and {@link android.content.ContentProvider}), -the subclass is declared through a {@code name} attribute. The name must include -the full package designation. -For example, an {@link android.app.Service} subclass might be declared as follows: -</p> - -<pre><manifest . . . > - <application . . . > - <service android:name="com.example.project.SecretService" . . . > - . . . - </service> - . . . - </application> -</manifest></pre> - -<p> -However, as a shorthand, if the first character of the string is a period, the -string is appended to the application's package name (as specified by the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> -element's -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html#package">package</a></code> -attribute). The following assignment is the same as the one above: -</p> - -<pre><manifest package="com.example.project" . . . > - <application . . . > - <service android:name=".SecretService" . . . > - . . . - </service> - . . . - </application> -</manifest></pre> - -<p> -When starting a component, Android creates an instance of the named subclass. -If a subclass isn't specified, it creates an instance of the base class. -</p></dd> - -<dt><b>Multiple values</b></dt> -<dd>If more than one value can be specified, the element is almost always -repeated, rather than listing multiple values within a single element. -For example, an intent filter can list several actions: - -<pre><intent-filter . . . > - <action android:name="android.intent.action.EDIT" /> - <action android:name="android.intent.action.INSERT" /> - <action android:name="android.intent.action.DELETE" /> - . . . -</intent-filter></pre></dd> - -<dt><b>Resource values</b></dt> -<dd>Some attributes have values that can be displayed to users — for -example, a label and an icon for an activity. The values of these attributes -should be localized and therefore set from a resource or theme. Resource -values are expressed in the following format,</p> - -<p style="margin-left: 2em">{@code @[<i>package</i>:]<i>type</i>:<i>name</i>}</p> - -<p> -where the <i>package</i> name can be omitted if the resource is in the same package -as the application, <i>type</i> is a type of resource — such as "string" or -"drawable" — and <i>name</i> is the name that identifies the specific resource. -For example: -</p> - -<pre><activity android:icon="@drawable/smallPic" . . . ></pre> - -<p> -Values from a theme are expressed in a similar manner, but with an initial '{@code ?}' -rather than '{@code @}': -</p> - -<p style="margin-left: 2em">{@code ?[<i>package</i>:]<i>type</i>:<i>name</i>} -</p></dd> - -<dt><b>String values</b></dt> -<dd>Where an attribute value is a string, double backslashes ('{@code \\}') -must be used to escape characters — for example, '{@code \\n}' for -a newline or '{@code \\uxxxx}' for a Unicode character.</dd> -</dl> - - -<h2 id="filef">File Features</h2> - -<p> -The following sections describe how some Android features are reflected -in the manifest file. -</p> - - -<h3 id="ifs">Intent Filters</h3> - -<p> -The core components of an application (its activities, services, and broadcast -receivers) are activated by <i>intents</i>. An intent is a -bundle of information (an {@link android.content.Intent} object) describing a -desired action — including the data to be acted upon, the category of -component that should perform the action, and other pertinent instructions. -Android locates an appropriate component to respond to the intent, launches -a new instance of the component if one is needed, and passes it the -Intent object. -</p> - -<p> -Components advertise their capabilities — the kinds of intents they can -respond to — through <i>intent filters</i>. Since the Android system -must learn which intents a component can handle before it launches the component, -intent filters are specified in the manifest as -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> -elements. A component may have any number of filters, each one describing -a different capability. -</p> - -<p> -An intent that explicitly names a target component will activate that component; -the filter doesn't play a role. But an intent that doesn't specify a target by -name can activate a component only if it can pass through one of the component's -filters. -</p> - -<p> -For information on how Intent objects are tested against intent filters, -see a separate document, -<a href="{@docRoot}guide/topics/intents/intents-filters.html">Intents -and Intent Filters</a>. -</p> - - -<h3 id="iconlabel">Icons and Labels</h3> - -<p> -A number of elements have {@code icon} and {@code label} attributes for a -small icon and a text label that can be displayed to users. Some also have a -{@code description} attribute for longer explanatory text that can also be -shown on-screen. For example, the -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -element has all three of these attributes, so that when the user is asked whether -to grant the permission to an application that has requested it, an icon representing -the permission, the name of the permission, and a description of what it -entails can all be presented to the user. -</p> - -<p> -In every case, the icon and label set in a containing element become the default -{@code icon} and {@code label} settings for all of the container's subelements. -Thus, the icon and label set in the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element are the default icon and label for each of the application's components. -Similarly, the icon and label set for a component — for example, an -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -element — are the default settings for each of the component's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> -elements. If an -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element sets a label, but an activity and its intent filter do not, -the application label is treated as the label for both the activity and -the intent filter. -</p> - -<p> -The icon and label set for an intent filter are used to represent a component -whenever the component is presented to the user as fulfilling the function -advertised by the filter. For example, a filter with -"{@code android.intent.action.MAIN}" and -"{@code android.intent.category.LAUNCHER}" settings advertises an activity -as one that initiates an application — that is, as -one that should be displayed in the application launcher. The icon and label -set in the filter are therefore the ones displayed in the launcher. -</p> - - -<h3 id="perms">Permissions</h3> - -<p> -A <i>permission</i> is a restriction limiting access to a part of the code -or to data on the device. The limitation is imposed to protect critical -data and code that could be misused to distort or damage the user experience. -</p> - -<p> -Each permission is identified by a unique label. Often the label indicates -the action that's restricted. For example, here are some permissions defined -by Android: -</p> - -<p style="margin-left: 2em">{@code android.permission.CALL_EMERGENCY_NUMBERS} -<br/>{@code android.permission.READ_OWNER_DATA} -<br/>{@code android.permission.SET_WALLPAPER} -<br/>{@code android.permission.DEVICE_POWER}</p> - -<p> -A feature can be protected by at most one permission. -</p> - -<p> -If an application needs access to a feature protected by a permission, -it must declare that it requires that permission with a -<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> -element in the manifest. Then, when the application is installed on -the device, the installer determines whether or not to grant the requested -permission by checking the authorities that signed the application's -certificates and, in some cases, asking the user. -If the permission is granted, the application is able to use the protected -features. If not, its attempts to access those features will simply fail -without any notification to the user. -</p> - -<p> -An application can also protect its own components (activities, services, -broadcast receivers, and content providers) with permissions. It can employ -any of the permissions defined by Android (listed in -{@link android.Manifest.permission android.Manifest.permission}) or declared -by other applications. Or it can define its own. A new permission is declared -with the -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -element. For example, an activity could be protected as follows: -</p> - -<pre> -<manifest . . . > - <permission android:name="com.example.project.DEBIT_ACCT" . . . /> - . . . - <application . . .> - <activity android:name="com.example.project.FreneticActivity" . . . > - android:permission="com.example.project.DEBIT_ACCT" - . . . > - . . . - </activity> - </application> - . . . - <uses-permission android:name="com.example.project.DEBIT_ACCT" /> - . . . -</manifest> -</pre> - -<p> -Note that, in this example, the {@code DEBIT_ACCT} permission is not only -declared with the -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -element, its use is also requested with the -<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> -element. Its use must be requested in order for other components of the -application to launch the protected activity, even though the protection -is imposed by the application itself. -</p> - -<p> -If, in the same example, the {@code permission} attribute was set to a -permission declared elsewhere -(such as {@code android.permission.CALL_EMERGENCY_NUMBERS}, it would not -have been necessary to declare it again with a -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -element. However, it would still have been necessary to request its use with -<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code>. -</p> - -<p> -The -<code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> -element declares a namespace for a group of permissions that will be defined in -code. And -<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> -defines a label for a set of permissions (both those declared in the manifest with -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -elements and those declared elsewhere). It affects only how the permissions are -grouped when presented to the user. The -<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> -element does not specify which permissions belong to the group; -it just gives the group a name. A permission is placed in the group -by assigning the group name to the -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -element's -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html#pgroup">permissionGroup</a></code> -attribute. -</p> - - -<h3 id="libs">Libraries</h3> - -<p> -Every application is linked against the default Android library, which -includes the basic packages for building applications (with common classes -such as Activity, Service, Intent, View, Button, Application, ContentProvider, -and so on). -</p> - -<p> -However, some packages reside in their own libraries. If your application -uses code from any of these packages, it must explicitly asked to be linked -against them. The manifest must contain a separate -<code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code> -element to name each of the libraries. (The library name can be found in the -documentation for the package.) -</p> diff --git a/docs/html/guide/topics/manifest/meta-data-element.jd b/docs/html/guide/topics/manifest/meta-data-element.jd deleted file mode 100644 index 1c91407..0000000 --- a/docs/html/guide/topics/manifest/meta-data-element.jd +++ /dev/null @@ -1,90 +0,0 @@ -page.title=<meta-data> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><meta-data android:<a href="#nm">name</a>="<i>string</i>" - android:<a href="#rsrc">resource</a>="<i>resource specification</i>" - android:<a href="#val">value</a>="<i>string</i>" /></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code></dd> - -<dt>description:</dt> -<dd>A name-value pair for an item of additional, arbitrary data that can -be supplied to the parent component. A component element can contain any -number of {@code <meta-data>} subelements. The values from all of -them are collected in a single {@link android.os.Bundle} object and made -available to the component as the -{@link android.content.pm.PackageItemInfo#metaData -PackageItemInfo.metaData} field. - -<p> -Ordinary values are specified through the <code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#value">value</a></code> -attribute. However, to assign a resource ID as the value, use the -<code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html#resource">resource</a></code> attribute instead. For example, -the following code assigns whatever value is stored in the {@code @string/kangaroo} -resource to the "{@code zoo}" name: -</p> - -<pre><meta-data android:name="zoo" android:value="@string/kangaroo" /></pre> - -<p> -On the other hand, using the {@code resource} attribute would assign "{@code zoo}" -the numeric ID of the resource, not the value stored in the resource: -</p> - -<pre><meta-data android:name="zoo" android:resource="@string/kangaroo" /></pre> - -<p> -It is highly recommended that you avoid supplying related data as -multiple separate {@code <meta-data>} entries. Instead, if you -have complex data to associate with a component, store it as a resource and -use the {@code resource} attribute to inform the component of its ID. -</p></dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>A unique name for the item. To ensure that the name is unique, use a -Java-style naming convention — for example, -"{@code com.example.project.activity.fred}".</dd> - -<dt><a name="rsrc"></a>{@code android:resource}</dt> -<dd>A reference to a resource. The ID of the resource is the value assigned -to the item. The ID can be retrieved from the meta-data Bundle by the -{@link android.os.Bundle#getInt Bundle.getInt()} method.</dd> - -<dt><a name="val"></a>{@code android:value}</dt> -<dd>The value assigned to the item. The data types that can be assigned as values and the Bundle methods that components use to retrieve those values are listed in the following table: - -<table> -<tr> - <th>Type</th> - <th>Bundle method</th> -</tr><tr> - <td>String value, using double backslashes ({@code \\}) to escape characters - — such as "{@code \\n}" and "{@code \\uxxxxx}" for a Unicode character.</td> - <td>{@link android.os.Bundle#getString(String) getString()}</td> -</tr><tr> - <td>Integer value, such as "{@code 100}"</td> - <td>{@link android.os.Bundle#getInt(String) getInt()}</td> -</tr><tr> - <td>Boolean value, either "{@code true}" or "{@code false}"</td> - <td>{@link android.os.Bundle#getBoolean(String) getBoolean()}</td> -</tr><tr> - <td>Color value, in the form "{@code #rgb}", "{@code #argb}", - "{@code #rrggbb}", or "{@code #aarrggbb}"</td> - <td>{@link android.os.Bundle#getString(String) getString()}</td> -</tr><tr> - <td>Float value, such as "{@code 1.23}"</td> - <td>{@link android.os.Bundle#getFloat(String) getFloat()}</td> -</tr> -</table> -</dd> -</dl></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/permission-element.jd b/docs/html/guide/topics/manifest/permission-element.jd deleted file mode 100644 index 6eef081..0000000 --- a/docs/html/guide/topics/manifest/permission-element.jd +++ /dev/null @@ -1,131 +0,0 @@ -page.title=<permission> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt></dt> -<dd><pre class="stx"><permission android:<a href="#desc">description</a>="<i>string resource</i>" - android:<a href="#icon">icon</a>="<i>drawable resource</i>" - android:<a href="#label">label</a>="<i>string resource</i>" - android:<a href="#nm">name</a>="<i>string</i>" - android:<a href="#pgroup">permissionGroup</a>="<i>string</i>" - android:<a href="#plevel">protectionLevel</a>=["normal" | "dangerous" | - "signature" | "signatureOrSystem"] /></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> - -<dt>description:</dt> -<dd>Declares a security permission that can be used to limit access -to specific components or features of this or other applications. -See the <a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a> -section in the introduction, -and the <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> -document for more information on how permissions work.</dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="desc"></a>{@code android:description}</dt> -<dd>A user-readable description of the permission, longer and more -informative than the label. It may be displayed to explain the -permission to the user — for example, when the user is asked -whether to grant the permission to another application. - -<p> -This attribute must be set as a reference to a string resource; -unlike the {@code label} attribute, it cannot be a raw string. -</p></dd> - -<dt><a name="icon"></a>{@code android:icon}</dt> -<dd>A reference to a drawable resource for an icon that represents the -permission.</dd> - -<dt><a name="label"></a>{@code android:label}</dt> -<dd>A name for the permission, one that can be displayed to users. - -<p> -As a convenience, the label can be directly set -as a raw string while you're developing the application. However, -when the application is ready to be published, it should be set as a -reference to a string resource, so that it can be localized like other -strings in the user interface. -</p></dd> - -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the permission. This is the name that will be used in -code to refer to the permission — for example, in a -<code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> element and the -{@code permission} attributes of application components. - -<p> -The name must be unique, so it should use Java-style scoping — -for example, "{@code com.example.project.PERMITTED_ACTION}". -</p></dd> - -<dt><a name="pgroup"></a>{@code android:permissionGroup}</dt> -<dd>Assigns this permission to a group. The value of this attribute is -the name of the group, which must be declared with the -<code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> element in this -or another application. If this attribute is not set, the permission -does not belong to a group.</dd> - -<dt><a name="plevel"></a>{@code android:protectionLevel}</dt> -<dd>Characterizes the potential risk implied in the permission and -indicates the procedure the system should follow when determining -whether or not to grant the permission to an application requesting it. -The value can be set to one of the following strings: - -<table> -<tr> - <th>Value</th> - <th>Meaning</th> -</tr><tr> - <td>"{@code normal}"</td> - <td>The default value. A lower-risk permission that gives requesting - applications access to isolated application-level features, with - minimal risk to other applications, the system, or the user. - The system automatically grants this type - of permission to a requesting application at installation, without - asking for the user's explicit approval (though the user always - has the option to review these permissions before installing). -</tr><tr> - <td>"{@code dangerous}"</td> - <td>A higher-risk permission that would give a requesting application - access to private user data or control over the device that can - negatively impact the user. Because this type of permission - introduces potential risk, the system may not automatically - grant it to the requesting application. For example, any dangerous - permissions requested by an application may be displayed to the - user and require confirmation before proceeding, or some other - approach may be taken to avoid the user automatically allowing - the use of such facilities. -</tr><tr> - <td>"{@code signature}"</td> - <td>A permission that the system grants only if the requesting - application is signed with the same certificate as the application - that declared the permission. If the certificates match, the system - automatically grants the permission without notifying the user or - asking for the user's explicit approval. -</tr><tr> - <td>"{@code signatureOrSystem}"</td> - <td>A permission that the system grants only to applications that are - in the Android system image <em>or</em> that are signed with the same - certificates as those in the system image. Please avoid using this - option, as the {@code signature} protection level should be sufficient - for most needs and works regardless of exactly where applications are - installed. The "{@code signatureOrSystem}" - permission is used for certain special situations where multiple - vendors have applications built into a system image and need - to share specific features explicitly because they are being built - together. -</tr> -</table> -</dd> -</dl></dd> - -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code></dd> -</dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/permission-group-element.jd b/docs/html/guide/topics/manifest/permission-group-element.jd deleted file mode 100644 index 9cfca6e..0000000 --- a/docs/html/guide/topics/manifest/permission-group-element.jd +++ /dev/null @@ -1,59 +0,0 @@ -page.title=<permission-group> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><permission-group android:<a href="#desc">description</a>="<i>string resource</i>" - android:<a href="#icon">icon</a>="<i>drawable resource</i>" - android:<a href="#label">label</a>="<i>string resource</i>" - android:<a href="#nm">name</a>="<i>string</i>" /></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> - -<dt>description:</dt> -<dd>Declares a name for a logical grouping of related permissions. Individual -permission join the group through the {@code permissionGroup} attribute of the -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> element. Members of a group are -presented together in the user interface. - -<p> -Note that this element does not declare a permission itself, only a category in -which permissions can be placed. See the -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> element for element for information -on declaring permissions and assigning them to groups. -</p></dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="desc"></a>{@code android:description}</dt> -<dd>User-readable text that describes the group. The text should be -longer and more explanatory than the label. This attribute must be -set as a reference to a string resource. Unlike the {@code label} -attribute, it cannot be a raw string.</dd> - -<dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon representing the permission. This attribute must be set -as a reference to a drawable resource containing the image definition.</dd> - -<dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable name for the group. As a convenience, the label can -be directly set as a raw string while you're developing the application. -However, when the application is ready to be published, it should be set -as a reference to a string resource, so that it can be localized like other -strings in the user interface.</dd> - -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the group. This is the name that can be assigned to a -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -element's -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html#pgroup"><permissionGroup></a></code> -attribute.</dd> -</dl></dd> - -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/permission-tree-element.html"><permission-tree></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/permission-tree-element.jd b/docs/html/guide/topics/manifest/permission-tree-element.jd deleted file mode 100644 index e2f7474..0000000 --- a/docs/html/guide/topics/manifest/permission-tree-element.jd +++ /dev/null @@ -1,61 +0,0 @@ -page.title=<permission-tree> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><permission-tree android:<a href="#icon">icon</a>="<i>drawable resource</i>" - android:<a href="#label">label</a>="<i>string resource</i>" ] - android:<a href="#nm">name</a>="<i>string</i>" /></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> - -<dt>description:</dt> -<dd>Declares the base name for a tree of permissions. The application takes -ownership of all names within the tree. It can dynamically add new permissions -to the tree by calling <code>{@link android.content.pm.PackageManager#addPermission PackageManager.addPermission()}</code>. Names within the tree are separated by -periods ('{@code .}'). For example, if the base name is -{@code com.example.project.taxes}, permissions like the following might be -added: - -<p style="margin-left: 2em">{@code com.example.project.taxes.CALCULATE} -<br/>{@code com.example.project.taxes.deductions.MAKE_SOME_UP} -<br/>{@code com.example.project.taxes.deductions.EXAGGERATE}</p> - -<p> -Note that this element does not declare a permission itself, only a -namespace in which further permissions can be placed. See the -<code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -element for information on declaring permissions. - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon representing all the permissions in the tree. This attribute -must be set as a reference to a drawable resource containing the image -definition.</dd> - -<dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable name for the group. As a convenience, the label can -be directly set as a raw string for quick and dirty programming. However, -when the application is ready to be published, it should be set as a -reference to a string resource, so that it can be localized like other -strings in the user interface.</dd> - -<dt><a name="nm"</a>{@code android:name}</dt> -<dd>The name that's at the base of the permission tree. It serves as -a prefix to all permission names in the tree. Java-style scoping should -be used to ensure that the name is unique. The name must have more than -two period-separated seqments in its path — for example, -{@code com.example.base} is OK, but {@code com.example} is not.</dd> - -</dl></dd> - -<p> -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/permission-group-element.html"><permission-group></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/uses-permission-element.html"><uses-permission></a></code> -</dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/provider-element.jd b/docs/html/guide/topics/manifest/provider-element.jd deleted file mode 100644 index 7359e50..0000000 --- a/docs/html/guide/topics/manifest/provider-element.jd +++ /dev/null @@ -1,267 +0,0 @@ -page.title=<provider> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><provider android:<a href="#auth">authorities</a>="<i>list</i>" - android:<a href="#enabled">enabled</a>=["true" | "false"] - android:<a href="#exported">exported</a>=["true" | "false"] - android:<a href="#gprmsn">grantUriPermissions</a>=["true" | "false"] - android:<a href="#icon">icon</a>="<i>drawable resource</i>" - android:<a href="#init">initOrder</a>="<i>integer</i>" - android:<a href="#label">label</a>="<i>string resource</i>" - android:<a href="#multi">multiprocess</a>=["true" | "false"] - android:<a href="#nm">name</a>="<i>string</i>" - android:<a href="#prmsn">permission</a>="<i>string</i>" - android:<a href="#proc">process</a>="<i>string</i>" - android:<a href="#rprmsn">readPermission</a>="<i>string</i>" - android:<a href="#sync">syncable</a>=["true" | "false"] - android:<a href="#wprmsn">writePermission</a>="<i>string</i>" > - . . . -</provider></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> - -<dt>can contain:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code></dd> - -<dt>description:</dt> -<dd>Declares a content provider — a subclass of -{@link android.content.ContentProvider} — that supplies structured -access to data managed by the application. All content providers that -are part of the application must be represented by {@code <provider>} -elements in the manifest file. The system cannot see, and therefore will -not run, any that are not declared. (You need to declare only -those content providers that you develop as part of your application, -not those developed by others that your application uses.) - -<p> -The Android system identifies content providers by the authority part - of a {@code content:} URI. For example, suppose that the following URI -is passed to <code>{@link android.content.ContentResolver#query -ContentResolver.query()}</code>: - -<p style="margin-left: 2em">{@code content://com.example.project.healthcareprovider/nurses/rn}</p> - -<p> -The {@code content:} scheme identifies the data as belonging to a content -provider and the authority ({@code com.example.project.healthcareprovider}) -identifies the particular provider. The authority therefore must be unique. -Typically, as in this example, it's the fully qualified name of a -ContentProvider subclass. The path part of a URI may be used by a content -provider to identify particular data subsets, but those paths are not -declared in the manifest. -</p> - -<p> -For information on using and developing content providers, see a separate document, -<a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>. -</p></dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="auth"></a>{@code android:authorities}</dt> -<dd>A list of one or more URI authorities that identify data under the purview -of the content provider. -Multiple authorities are listed by separating their names with a semicolon. -To avoid conflicts, authority names should use a Java-style naming convention -(such as {@code com.example.provider.cartoonprovider}). Typically, it's the name -of the ContentProvider subclass. - -<p> -There is no default. At least one authority must be specified. -</p></dd> - -<dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the content provider can be instantiated by the system — -"{@code true}" if it can be, and "{@code false}" if not. The default value -is "{@code true}". - -<p> -The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all -application components, including content providers. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and {@code <provider>} -attributes must both be "{@code true}" (as they both -are by default) for the content provider to be enabled. If either is -"{@code false}", the provider is disabled; it cannot be instantiated. -</p></dd> - -<dt><a name="exported"></a>{@code android:exported}</dt> -<dd>Whether or not the content provider can be used by components of other -applications — "{@code true}" if it can be, and "{@code false}" if not. -If "{@code false}", the provider is available only to components of the -same application or applications with the same user ID. The default value -is "{@code true}". - -<p> -You can export a content provider but still limit access to it with the -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission</a></code> attribute. -</p></dd> - -<dt><a name="gprmsn"></a>{@code android:grantUriPermissions}</dt> -<dd>Whether or not those who ordinarily would not have permission to -access the content provider's data can be granted permission to do so, -temporarily overcoming the restriction imposed by the -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">readPermission</a></code>, -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#wprmsn">writePermission</a></code>, and -<code><a href="{@docRoot}guide/topics/manifest/provider-element.html#prmsn">permission</a></code> attributes -— -"{@code true}" if permission can be granted, and "{@ code false}" if not. -If "{@code true}", permission can be granted to any of the content -provider's data. If "{@code false}", permission can be granted only -to the data subsets listed in -<code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> subelements, -if any. The default value is "{@code false}". - -<p> -Granting permission is a way of giving an application component one-time -access to data protected by a permission. For example, when an e-mail -message contains an attachment, the mail application may call upon the -appropriate viewer to open it, even though the viewer doesn't have general -permission to look at all the content provider's data. -</p> - -<p> -In such cases, permission is granted by -<code>{@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION}</code> -and <code>{@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION}</code> -flags in the Intent object that activates the component. For example, the -mail application might put {@code FLAG_GRANT_READ_URI_PERMISSION} in the -Intent passed to {@code Context.startActivity()}. The permission is specific -to the URI in the Intent. -</p> - -<p> -If you enable this feature, either by setting this attribute to "{@code true}" -or by defining <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> -subelements, you must call -<code>{@link android.content.Context#revokeUriPermission -Context.revokeUriPermission()}</code> when a covered URI is deleted from -the provider. -</p> - -<p> -See also the <code><a href="{@docRoot}guide/topics/manifest/grant-uri-permission-element.html"><grant-uri-permission></a></code> -element. -</p></dd> - -<dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon representing the content provider. -This attribute must be set as a reference to a drawable resource containing -the image definition. If it is not set, the icon specified for the application -as a whole is used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute).</dd> - -<dt><a name="init"></a>{@code android:initOrder}</dt> -<dd>The order in which the content provider should be instantiated, -relative to other content providers hosted by the same process. -When there are dependencies among content providers, setting this -attribute for each of them ensures that they are created in the order -required by those dependencies. The value is a simple integer, -with higher numbers being initialized first.</dd> - -<dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the content provided. -If this attribute is not set, the label set for the application as a whole is -used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). - -<p> -The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, -it can also be set as a raw string. -</p></dd> - -<dt><a name="multi"></a>{@code android:multiprocess}</dt> -<dd>Whether or not an instance of the content provider can be created in -every client process — "{@code true}" if instances can run in multiple -processes, and "{@code false}" if not. The default value is "{@code false}". - -<p> -Normally, a content provider is instantiated in the process of the -application that defined it. However, if this flag is set to "{@code true}", -the system can create an instance in every process where there's a client -that wants to interact withit, thus avoiding the overhead of interprocess -communication. -</p></dd> - -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the class that implements the content provider, a subclass of -{@link android.content.ContentProvider}. This should be a fully qualified -class name (such as, "{@code com.example.project.TransportationProvider}"). -However, as a shorthand, if the first character of the name is a period, -it is appended to the package name specified in the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. - -<p> -There is no default. The name must be specified. -</p></dd> - - -<dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that clients must have to read or write the -content provider's data. This attribute is a convenient way of setting a -single permission for both reading and writing. However, the -<code><a href="#rprmsn">readPermission</a></code> and -<code><a href="#wprmsn">writePermission</a></code> attributes take precedence -over this one. If the <code><a href="{@docRoot}guide/topics/manifest/provider-element.html#rprmsn">readPermission</a></code> -attribute is also set, it controls access for querying the content provider. -And if the <code><a href="#wprmsn">writePermission</a></code> attribute is set, -it controls access for modifying the provider's data. - -<p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> -section in the introduction and a separate document, -<a href="{@docRoot}guide/topics/security/security.html">Security and -Permissions</a>. -</p></dd> - -<dt><a name="proc"></a>{@code android:process}</dt> -<dd>The name of the process in which the content provider should run. Normally, -all components of an application run in the default process created for the -application. It has the same name as the application package. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> -attribute can set a different -default for all components. But each component can override the default -with its own {@code process} attribute, allowing you to spread your -application across multiple processes. - -<p> -If the name assigned to this attribute begins with a colon (':'), a new -process, private to the application, is created when it's needed and -the activity runs in that process. -If the process name begins with a lowercase character, the activity will run -in a global process of that name, provided that it has permission to do so. -This allows components in different applications to share a process, reducing -resource usage. -</p></dd> - -<dt><a name="rprmsn"></a>{@code android:readPermission}</dt> -<dd>A permission that clients must have to query the content provider. -See also the <code><a href="#prmsn">permission</a></code> and -<code><a href="#wprmsn">writePermission</a></code> attributes.</dd> - -<dt><a name="sync"></a>{@code android:syncable}</dt> -<dd>Whether or not the data under the content provider's control -is to be synchronized with data on a server — "{@code true}" -if it is to be synchronized, and "{@ code false}" if not.</dd> - -<dt><a name="wprmsn"></a>{@code android:writePermission}</dt> -<dd>A permission that clients must have to make changes to the data -controlled by the content provider. -See also the <code><a href="#prmsn">permission</a></code> and -<code><a href="#rprmsn">readPermission</a></code> attributes.</dd> - -</dl></dd> - -<p> -<dt>see also:</dt> -<dd><a href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/receiver-element.jd b/docs/html/guide/topics/manifest/receiver-element.jd deleted file mode 100644 index 777d016..0000000 --- a/docs/html/guide/topics/manifest/receiver-element.jd +++ /dev/null @@ -1,164 +0,0 @@ -page.title=<receiver> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><receiver android:<a href="#enabled">enabled</a>=["true" | "false"] - android:<a href="#exported">exported</a>=["true" | "false"] - android:<a href="#icon">icon</a>="<i>drawable resource</i>" - android:<a href="#label">label</a>="<i>string resource</i>" - android:<a href="#nm">name</a>="<i>string</i>" - android:<a href="#prmsn">permission</a>="<i>string</i>" - android:<a href="#proc">process</a>="<i>string</i>" > - . . . -</receiver></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> - -<dt>can contain:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filer></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code></dd> - -<dt>description:</dt> -<dd>Declares a broadcast receiver (a {@link android.content.BroadcastReceiver} -subclass) as one of the application's components. Broadcast receivers enable -applications to receive intents that are broadcast by the system or by other -applications, even when other components of the application are not running. - -<p> -There are two ways to make a broadcast receiver known to the system: One is -declare it in the manifest file with this element. The other is to create -the receiver dynamically in code and register it with the <code>{@link -android.content.Context#registerReceiver Context.registerReceiver()}</code> -method. See the {@link android.content.BroadcastReceiver} class description -for more on dynamically created receivers. -</p></dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the broadcast receiver can be instantiated by the system — -"{@code true}" if it can be, and "{@code false}" if not. The default value -is "{@code true}". - -<p> -The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all -application components, including broadcast receivers. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and -{@code <receiver>} attributes must both be "{@code true}" for -the broadcast receiver to be enabled. If either is "{@code false}", it is -disabled; it cannot be instantiated. -</p></dd> - -<dt><a name="exported"></a>{@code android:exported}</dt> -<dd>Whether or not the broadcast receiver can receive messages from sources -outside its application — "{@code true}" if it can, and "{@code false}" -if not. If "{@code false}", the only messages the broadcast receiver can -receive are those sent by components of the same application or applications -with the same user ID. - -<p> -The default value depends on whether the broadcast receiver contains intent filters. -The absence of any filters means that it can be invoked only by Intent objects that -specify its exact class name. This implies that the receiver is intended only for -application-internal use (since others would not normally know the class name). -So in this case, the default value is "{@code false}". -On the other hand, the presence of at least one filter implies that the broadcast -receiver is intended to receive intents broadcast by the system or other applications, -so the default value is "{@code true}". -</p> - -<p> -This attribute is not the only way to limit a broadcast receiver's external exposure. -You can also use a permission to limit the external entities that can send it messages -(see the <code><a href="{@docRoot}guide/topics/manifest/receiver-element.html#prmsn">permission</a></code> attribute). -</p></dd> - -<dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon representing the broadcast receiver. This attribute must be set -as a reference to a drawable resource containing the image definition. -If it is not set, the icon specified for the application as a whole is used -instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute). - -<p> -The broadcast receiver's icon — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the -default icon for all the receiver's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute). -</p></dd> - -<dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the broadcast receiver. If this attribute is not -set, the label set for the application as a whole is -used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). - -<p> -The broadcast receiver's label — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the -default label for all the receiver's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). -</p> - -<p> -The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, -it can also be set as a raw string. -</p></dd> - -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the class that implements the broadcast receiver, a subclass of -{@link android.content.BroadcastReceiver}. This should be a fully qualified -class name (such as, "{@code com.example.project.ReportReceiver}"). However, -as a shorthand, if the first character of the name is a period (for example, -"{@code . ReportReceiver}"), it is appended to the package name specified in -the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. - -<p> -There is no default. The name must be specified. -</p></dd> - -<dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that broadcasters must have to send a -message to the broadcast receiver. -If this attribute is not set, the permission set by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> attribute applies -to the broadcast receiver. If neither attribute is set, the receiver -is not protected by a permission. - -<p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> -section in the introduction and a separate document, -<a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. -</p></dd> - -<dt><a name="proc"></a>{@code android:process}</dt> -<dd>The name of the process in which the broadcast receiver should run. -Normally, all components of an application run in the default process created -for the application. It has the same name as the application package. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> attribute can set a different -default for all components. But each component can override the default -with its own {@code process} attribute, allowing you to spread your -application across multiple processes. - -<p> -If the name assigned to this attribute begins with a colon (':'), a new -process, private to the application, is created when it's needed and -the broadcast receiver runs in that process. -If the process name begins with a lowercase character, the receiver will run -in a global process of that name, provided that it has permission to do so. -This allows components in different applications to share a process, reducing -resource usage. -</p></dd> -</dl></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/service-element.jd b/docs/html/guide/topics/manifest/service-element.jd deleted file mode 100644 index ad65abe..0000000 --- a/docs/html/guide/topics/manifest/service-element.jd +++ /dev/null @@ -1,176 +0,0 @@ -page.title=<service> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><service android:<a href="#enabled">enabled</a>=["true" | "false"] - android:<a href="#exported">exported[</a>="true" | "false"] - android:<a href="#icon">icon</a>="<i>drawable resource</i>" - android:<a href="#label">label</a>="<i>string resource</i>" - android:<a href="#nm">name</a>="<i>string</i>" - android:<a href="#prmsn">permission</a>="<i>string</i>" - android:<a href="#proc">process</a>="<i>string</i>" > - . . . -</service></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> - -<dt>can contain:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filer></a></code> -<br/><code><a href="{@docRoot}guide/topics/manifest/meta-data-element.html"><meta-data></a></code></dd> - -<dt>description:</dt> -<dd>Declares a service (a {@link android.app.Service} subclass) as one -of the application's components. Unlike activities, services lack a -visual user interface. They're used to implement long-running background -operations or a rich communications API that can be called by other -applications. - -<p> -All services must be represented by {@code <service>} elements in -the manifest file. Any that are not declared there will not be seen -by the system and will never be run. -</p></dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the service can be instantiated by the system — -"{@code true}" if it can be, and "{@code false}" if not. The default value -is "{@code true}". - -<p> -The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element has its own -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#enabled">enabled</a></code> attribute that applies to all -application components, including services. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> and {@code <service>} -attributes must both be "{@code true}" (as they both -are by default) for the service to be enabled. If either is -"{@code false}", the service is disabled; it cannot be instantiated. -</p></dd> - -<dt><a name="exported"></a>{@code android:exported}</dt> -<dd>Whether or not components of other applications can invoke -the service or interact with it — "{@code true}" if they can, and -"{@code false}" if not. When the value is "{@code false}", only -components of the same application or applications -with the same user ID can start the service or bind to it. - -<p> -The default value depends on whether the service contains intent filters. The -absence of any filters means that it can be invoked only by specifying -its exact class name. This implies that the service is intended only for -application-internal use (since others would not know the class name). So in -this case, the default value is "{@code false}". -On the other hand, the presence of at least one filter implies that the service -is intended for external use, so the default value is "{@code true}". -</p> - -<p> -This attribute is not the only way to limit the exposure of a service to other -applications. You can also use a permission to limit the external entities that -can interact with the service (see the <code><a href="{@docRoot}guide/topics/manifest/service-element.html#prmsn">permission</a></code> -attribute). -</p></dd> - -<dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon representing the service. This attribute must be set as a -reference to a drawable resource containing the image definition. -If it is not set, the icon specified for the application -as a whole is used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element's <code><a href="{@docRoot}guide/topics/manifest/application-element.html#icon">icon</a></code> attribute). -</p> - -<p> -The service's icon — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the -default icon for all the service's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#icon">icon</a></code> attribute). -</p></dd> - -<dt><a name="label"></a>{@code android:label}</dt> -<dd>A name for the service that can be displayed to users. -If this attribute is not set, the label set for the application as a whole is -used instead (see the <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#label">label</a></code> attribute). - -<p> -The service's label — whether set here or by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element — is also the -default label for all the service's intent filters (see the -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html"><intent-filter></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/intent-filter-element.html#label">label</a></code> attribute). -</p> - -<p> -The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, -it can also be set as a raw string. -</p></dd> - -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the {@link android.app.Service} subclass that implements -the service. This should be a fully qualified class name (such as, -"{@code com.example.project.RoomService}"). However, as a shorthand, if -the first character of the name is a period (for example, "{@code .RoomService}"), -it is appended to the package name specified in the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. - -<p> -There is no default. The name must be specified. -</p></dd> - -<dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that that an entity must have in order to -launch the service or bind to it. If a caller of -<code>{@link android.content.Context#startService startService()}</code>, -<code>{@link android.content.Context#bindService bindService()}</code>, or -<code>{@link android.content.Context#stopService stopService()}</code>, -has not been granted this permission, the method will not work and the -Intent object will not be delivered to the service. - -<p> -If this attribute is not set, the permission set by the -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#prmsn">permission</a></code> -attribute applies to the service. If neither attribute is set, the service is -not protected by a permission. -</p> - -<p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> -section in the introduction and a separate document, -<a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. -</p></dd> - -<dt><a name="proc"></a>{@code android:process}</dt> -<dd>The name of the process where the service is to run. Normally, -all components of an application run in the default process created for the -application. It has the same name as the application package. The -<code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> element's -<code><a href="{@docRoot}guide/topics/manifest/application-element.html#proc">process</a></code> -attribute can set a different -default for all components. But component can override the default -with its own {@code process} attribute, allowing you to spread your -application across multiple processes. - -<p> -If the name assigned to this attribute begins with a colon (':'), a new -process, private to the application, is created when it's needed and -the service runs in that process. -If the process name begins with a lowercase character, the service will run -in a global process of that name, provided that it has permission to do so. -This allows components in different applications to share a process, reducing -resource usage. -</p></dd> -</dl></dd> - -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -<br><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/uses-library-element.jd b/docs/html/guide/topics/manifest/uses-library-element.jd deleted file mode 100644 index d66da2c..0000000 --- a/docs/html/guide/topics/manifest/uses-library-element.jd +++ /dev/null @@ -1,32 +0,0 @@ -page.title=<uses-library> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre><uses-library android:<a href="#nm">name</a>="<i>string</i>" /></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code></dd> - -<dt>description:</dt> -<dd>Specifies a shared library that the application must be linked against. -This element tells the system to include the library's code in the class -loader for the package. - -<p> -All of the {@code android} packages (such as {@link android.app}, -{@link android.content}, {@link android.view}, and {@link android.widget}) -are in the default library that all applications are automatically linked -against. However, some packages (such as {@code maps} and {@code awt} are -in separate libraries that are not automatically linked. Consult the -documentation for the packages you're using to determine which library -contains the package code. -</p></dd> - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the library.</dd> -</dl></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/uses-permission-element.jd b/docs/html/guide/topics/manifest/uses-permission-element.jd deleted file mode 100644 index 07741b1..0000000 --- a/docs/html/guide/topics/manifest/uses-permission-element.jd +++ /dev/null @@ -1,39 +0,0 @@ -page.title=<uses-permission> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><uses-permission android:<a href="#nm">name</a>="<i>string</i>" /></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> - -<dt>description:</dt> -<dd>Requests a permission that the application must be granted in -order for it to operate correctly. Permissions are granted when the -application is installed, not while it's running. - -<p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#perms">Permissions</a></code> -section in the introduction and the separate -<a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a> document. -A list of permissions defined by the base platform can be found at -{@link android.Manifest.permission android.Manifest.permission}. - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="nm"></a>{@code android:name}</dt> -<dd>The name of the permission. It can be a permission defined by the -application with the <code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code> -element, a permission defined by another application, or one of the -standard system permissions, such as "{@code android.permission.CAMERA}" -or "{@code android.permission.READ_CONTACTS}". As these examples show, -a permission name typically includes the package name as a prefix.</dd> - -</dl></dd> - -<dt>see also:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/permission-element.html"><permission></a></code></dd> - -</dl> diff --git a/docs/html/guide/topics/manifest/uses-sdk-element.jd b/docs/html/guide/topics/manifest/uses-sdk-element.jd deleted file mode 100644 index a88635a..0000000 --- a/docs/html/guide/topics/manifest/uses-sdk-element.jd +++ /dev/null @@ -1,49 +0,0 @@ -page.title=<uses-sdk> -@jd:body - -<dl class="xml"> -<dt>syntax:</dt> -<dd><pre class="stx"><uses-sdk android:<a href="#min">minSdkVersion</a>="<i>integer</i>" /></pre></dd> - -<dt>contained in:</dt> -<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> - -<dt>description:</dt> -<dd>Declares which levels of the Android API the application can run against. -The level is incremented when there are additions to the API and resource tree, -so an application developed using level 3 of the API may not run against level -1 or 2, but should run against level 3, 4, 5, and above. -</p> - -<p> -The default level is 1. -</p> - -<p> -For more information on the API level, see the -<a href="{@docRoot}guide/publishing/versioning.html#minsdkversion">Specifying -Minimum System API Version</a> section of -<a href="{@docRoot}guide/publishing/versioning.html">Versioning Your -Applications</a>. -</p></dd> - - -<dt>attributes:</dt> -<dd><dl class="attr"> -<dt><a name="min"></a>{@code android:minSdkVersion}</dt> -<dd>An integer designating the minimum level of the Android API that's required -for the application to run. - -<p> -Despite its name, this attribute is set to the API level, <em>not</em> to the -version number of the SDK (software development kit). The API level is always -a single integer; the SDK version may be split into major and minor components -(such as 1.2). You cannot derive the API level from the SDK version number -(for example, it is not the same as the major version or the sum of the major -and minor versions). To learn what the API level is, check the notes that -came with the SDK you're using. -</p></dd> - -</dl></dd> - -</dl> diff --git a/docs/html/guide/topics/media/index.jd b/docs/html/guide/topics/media/index.jd deleted file mode 100644 index ba6d89f..0000000 --- a/docs/html/guide/topics/media/index.jd +++ /dev/null @@ -1,188 +0,0 @@ -page.title=Audio and Video -@jd:body - - <div id="qv-wrapper"> - <div id="qv"> - -<h2>Audio/Video quickview</h2> -<ul> -<li>Audio playback and record</li> -<li>Video playback</li> -<li>Handles data from raw resources, files, streams</li> -<li>Built-in codecs for a variety of media. See <a href="{@docRoot}guide/appendix/media-formats.html">Android 1.0 Media Formats</a></li> -</ul> - -<h2>Key classes</h2> -<ol> -<li><a href="{@docRoot}reference/android/media/MediaPlayer.html">MediaPlayer</a> (all audio and video formats)</li> -<li><a href="{@docRoot}reference/android/media/MediaRecorder.html">MediaRecorder</a> (record, all audio formats)</li> -</ol> - -<h2>In this document</h2> -<ol> -<li><a href="#playback.html">Audio and Video Playback</a></li> -<li><a href="#capture">Audio Capture</a></li> -</ol> - -<h2>See also</h2> -<ol> -<li><a href="{@docRoot}guide/topics/data/data-storage.html">Data Storage</a></li> -</ol> - -</div> -</div> - -<p>The Android platform offers built-in encoding/decoding for a variety of -common media types, so that you can easily integrate audio, video, and images into your -applications. Accessing the platform's media capabilities is fairly straightforward -— you do so using the same intents and activities mechanism that the rest of -Android uses.</p> - -<p>Android lets you play audio and video from several types of data sources. You -can play audio or video from media files stored in the application's resources -(raw resources), from standalone files in the filesystem, or from a data stream -arriving over a network connection. To play audio or video from your -application, use the {@link android.media.MediaPlayer} class.</p> - -<p>The platform also lets you record audio, where supported by the mobile device -hardware. Recording of video is not currently supported, but is planned for a -future release. To record audio, use the -{@link android.media.MediaRecorder} class. Note that the emulator doesn't have -hardware to capture audio, but actual mobile devices are likely to provide these -capabilities that you can access through MediaRecorder. </p> - -<p>For a list of the media formats for which Android offers built-in support, -see the <a href="{@docRoot}guide/appendix/media-formats.html">Android Media -Formats</a> appendix. </p> - -<h2 id="play">Audio and Video Playback</h2> -<p>Media can be played from anywhere: from a raw resource, from a file from the system, -or from an available network (URL).</p> - -<p>You can play back the audio data only to the standard -output device; currently, that is the mobile device speaker or Bluetooth headset. You -cannot play sound files in the conversation audio. </p> - -<h3 id="playraw">Playing from a Raw Resource</h3> -<p>Perhaps the most common thing to want to do is play back media (notably sound) -within your own applications. Doing this is easy:</p> -<ol> - <li>Put the sound (or other media resource) file into the <code>res/raw</code> - folder of your project, where the Eclipse plugin (or aapt) will find it and - make it into a resource that can be referenced from your R class</li> - <li>Create an instance of <code>MediaPlayer</code>, referencing that resource using - {@link android.media.MediaPlayer#create MediaPlayer.create}, and then call - {@link android.media.MediaPlayer#start() start()} on the instance:</li> -</ol> -<pre> - MediaPlayer mp = MediaPlayer.create(context, R.raw.sound_file_1); - mp.start(); -</pre> -<p>To stop playback, call {@link android.media.MediaPlayer#stop() stop()}. If -you wish to later replay the media, then you must -{@link android.media.MediaPlayer#reset() reset()} and -{@link android.media.MediaPlayer#prepare() prepare()} the MediaPlayer object -before calling {@link android.media.MediaPlayer#start() start()} again. -(<code>create()</code> calls <code>prepare()</code> the first time.)</p> -<p>To pause playback, call {@link android.media.MediaPlayer#pause() pause()}. -Resume playback from where you paused with -{@link android.media.MediaPlayer#start() start()}.</p> - -<h3 id="playfile">Playing from a File or Stream</h3> -<p>You can play back media files from the filesystem or a web URL:</p> -<ol> - <li>Create an instance of the <code>MediaPlayer</code> using <code>new</code></li> - <li>Call {@link android.media.MediaPlayer#setDataSource setDataSource()} - with a String containing the path (local filesystem or URL) - to the file you want to play</li> - <li>First {@link android.media.MediaPlayer#prepare prepare()} then - {@link android.media.MediaPlayer#start() start()} on the instance:</li> -</ol> -<pre> - MediaPlayer mp = new MediaPlayer(); - mp.setDataSource(PATH_TO_FILE); - mp.prepare(); - mp.start(); -</pre> -<p>{@link android.media.MediaPlayer#stop() stop()} and -{@link android.media.MediaPlayer#pause() pause()} work the same as discussed -above.</p> - <p class="note"><strong>Note:</strong> It is possible that <code>mp</code> could be - null, so good code should <code>null</code> check after the <code>new</code>. - Also, <code>IllegalArgumentException</code> and <code>IOException</code> either - need to be caught or passed on when using <code>setDataSource()</code>, since - the file you are referencing may not exist.</p> -<p class="note"><strong>Note:</strong> -If you're passing a URL to an online media file, the file must be capable of -progressive download.</p> - -<h2 id="capture">Audio Capture</h2> -<p>Audio capture from the device is a bit more complicated than audio/video playback, but still fairly simple:</p> -<ol> - <li>Create a new instance of {@link android.media.MediaRecorder - android.media.MediaRecorder} using <code>new</code></li> - <li>Create a new instance of {@link android.content.ContentValues - android.content.ContentValues} and put in some standard properties like - <code>TITLE</code>, <code>TIMESTAMP</code>, and the all important - <code>MIME_TYPE</code></li> - <li>Create a file path for the data to go to (you can use {@link - android.content.ContentResolver android.content.ContentResolver} to - create an entry in the Content database and get it to assign a path - automatically which you can then use)</li> - <li>Set the audio source using {@link android.media.MediaRecorder#setAudioSource - MediaRecorder.setAudioSource()}. You will probably want to use - <code>MediaRecorder.AudioSource.MIC</code></li> - <li>Set output file format using {@link - android.media.MediaRecorder#setOutputFormat MediaRecorder.setOutputFormat()} - </li> - <li>Set the audio encoder using - {@link android.media.MediaRecorder#setAudioEncoder MediaRecorder.setAudioEncoder()} - </li> - <li>Call {@link android.media.MediaRecorder#prepare prepare()} - on the MediaRecorder instance.</li> - <li>To start audio capture, call - {@link android.media.MediaRecorder#start start()}. </li> - <li>To stop audio capture, call {@link android.media.MediaRecorder#stop stop()}. - <li>When you are done with the MediaRecorder instance, call -{@link android.media.MediaRecorder#release release()} on it. </li> -</ol> - -<h3>Example: Audio Capture Setup and Start</h3> -<p>The example below illustrates how to set up, then start audio capture.</p> -<pre> - recorder = new MediaRecorder(); - ContentValues values = new ContentValues(3); - - values.put(MediaStore.MediaColumns.TITLE, SOME_NAME_HERE); - values.put(MediaStore.MediaColumns.TIMESTAMP, System.currentTimeMillis()); - values.put(MediaStore.MediaColumns.MIME_TYPE, recorder.getMimeContentType()); - - ContentResolver contentResolver = new ContentResolver(); - - Uri base = MediaStore.Audio.INTERNAL_CONTENT_URI; - Uri newUri = contentResolver.insert(base, values); - - if (newUri == null) { - // need to handle exception here - we were not able to create a new - // content entry - } - - String path = contentResolver.getDataFilePath(newUri); - - // could use setPreviewDisplay() to display a preview to suitable View here - - recorder.setAudioSource(MediaRecorder.AudioSource.MIC); - recorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP); - recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB); - recorder.setOutputFile(path); - - recorder.prepare(); - recorder.start(); -</pre> -<h3>Stop Recording</h3> -<p>Based on the example above, here's how you would stop audio capture. </p> -<pre> - recorder.stop(); - recorder.release(); -</pre> - diff --git a/docs/html/guide/topics/media/media.jd b/docs/html/guide/topics/media/media.jd deleted file mode 100644 index 463686d..0000000 --- a/docs/html/guide/topics/media/media.jd +++ /dev/null @@ -1,172 +0,0 @@ -page.title=Media Capabilities -@jd:body - -<div class="sidebox"> - -<h3>Media Quickview</h3> - -<h4>Built-in capabilities</h4> -<ul> -<li>Audio playback and record</li> -<li>Video playback</li> -</ul> - -<h4>Data sources</h4> -<ul> -<li>Raw resources</li> -<li>Data files</li> -<li>Streams</li> -</ul> - -<h4>Media Formats</h4> -<ul> -<li>See appendix <a href="{@docRoot}devguide/appendix/media_formats.html">Android 1.0 Media Formats</a></li> -</ul> - -<h4>Key APIs</h4> -<ul> -<li>{@link android.media.MediaPlayer} (playback, all audio and video formats)</li> -<li>{@link android.media.MediaRecorder} (record, all audio formats)</li> -</ul> -</div> - -<p>The Android platform offers built-in encoding/decoding for a variety of common media types, -so that you can easily integrate audio, video, and images into your applications. Accessing the platform's media -capabilities is fairly straightforward &mdash you do so using the same intents and -activities mechanism that the rest of Android uses.</p> - -<p>Android lets you play audio and video from several types of data sources. You can play audio or video from media files stored in the application's resources (raw resources), from standalone files in the filesystem, or from a data stream arriving over a network connection. To play audio or video from your application, use the {@link android.media.MediaPlayer} class.</p> - -<p>The platform also lets you record audio, where supported by the mobile device hardware. Recording of video is not currently supported, but is planned for a future release. To record audio, use the -{@link android.media.MediaRecorder} class. Note that the emulator doesn't have hardware to capture audio, but actual mobile devices are likely to provide these capabilities that you can access through MediaRecorder. </p> - -<p>For a list of the media formats for which Android offers built-in support, see the <a href="{@docRoot}devguide/appendix/media_formats.html">Android Media Formats</a> appendix. </p> - -<h2>Playing Audio and Video</h2> -<p>Media can be played from anywhere: from a raw resource, from a file from the system, -or from an available network (URL).</p> - -<p>You can play back the audio data only to the standard -output device; currently, that is the mobile device speaker or Bluetooth headset. You -cannot play sound files in the conversation audio. </p> - -<h3>Playing from a Raw Resource</h3> -<p>Perhaps the most common thing to want to do is play back media (notably sound) -within your own applications. Doing this is easy:</p> -<ol> - <li>Put the sound (or other media resource) file into the <code>res/raw</code> - folder of your project, where the Eclipse plugin (or aapt) will find it and - make it into a resource that can be referenced from your R class</li> - <li>Create an instance of <code>MediaPlayer</code>, referencing that resource using - {@link android.media.MediaPlayer#create MediaPlayer.create}, and then call - {@link android.media.MediaPlayer#start() start()} on the instance:<br><br></li> -</ol> -<pre> - MediaPlayer mp = MediaPlayer.create(context, R.raw.sound_file_1); - mp.start(); -</pre> -<p>To stop playback, call {@link android.media.MediaPlayer#stop() stop()}. If -you wish to later replay the media, then you must -{@link android.media.MediaPlayer#reset() reset()} and -{@link android.media.MediaPlayer#prepare() prepare()} the MediaPlayer object -before calling {@link android.media.MediaPlayer#start() start()} again. -(<code>create()</code> calls <code>prepare()</code> the first time.)</p> -<p>To pause playback, call {@link android.media.MediaPlayer#pause() pause()}. -Resume playback from where you paused with -{@link android.media.MediaPlayer#start() start()}.</p> - -<h3>Playing from a File or Stream</h3> -<p>You can play back media files from the filesystem or a web URL:</p> -<ol> - <li>Create an instance of the <code>MediaPlayer</code> using <code>new</code></li> - <li>Call {@link android.media.MediaPlayer#setDataSource setDataSource()} - with a String containing the path (local filesystem or URL) - to the file you want to play</li> - <li>First {@link android.media.MediaPlayer#prepare prepare()} then - {@link android.media.MediaPlayer#start() start()} on the instance:<br><br></li> -</ol> -<pre> - MediaPlayer mp = new MediaPlayer(); - mp.setDataSource(PATH_TO_FILE); - mp.prepare(); - mp.start(); -</pre> -<p>{@link android.media.MediaPlayer#stop() stop()} and -{@link android.media.MediaPlayer#pause() pause()} work the same as discussed -above.</p> - <p class="note"><strong>Note:</strong> It is possible that <code>mp</code> could be - null, so good code should <code>null</code> check after the <code>new</code>. - Also, <code>IllegalArgumentException</code> and <code>IOException</code> either - need to be caught or passed on when using <code>setDataSource()</code>, since - the file you are referencing may not exist.</p> -<p class="note"><strong>Note:</strong> -If you're passing a URL to an online media file, the file must be capable of -progressive download.</p> - -<h2>Recording Media Resources</h2> -<p>Recording media is a little more involved than playing it back, as you would -probably expect, but it is still fairly simple. There is just a little more set -up to do</p> -<ol> - <li>Create a new instance of {@link android.media.MediaRecorder - android.media.MediaRecorder} using <code>new</code></li> - <li>Create a new instance of {@link android.content.ContentValues - android.content.ContentValues} and put in some standard properties like - <code>TITLE</code>, <code>TIMESTAMP</code>, and the all important - <code>MIME_TYPE</code></li> - <li>Create a file path for the data to go to (you can use {@link - android.content.ContentResolver android.content.ContentResolver} to - create an entry in the Content database and get it to assign a path - automatically which you can then use)</li> - <li>Set the audio source using {@link android.media.MediaRecorder#setAudioSource - MediaRecorder.setAudioSource()}. You will probably want to use - <code>MediaRecorder.AudioSource.MIC</code></li> - <li>Set output file format using {@link - android.media.MediaRecorder#setOutputFormat MediaRecorder.setOutputFormat()} - </li> - <li>Set the audio encoder using - {@link android.media.MediaRecorder#setAudioEncoder MediaRecorder.setAudioEncoder()} - </li> - <li>Finally, {@link android.media.MediaRecorder#prepare prepare()} and - {@link android.media.MediaRecorder#start start()} the recording. - {@link android.media.MediaRecorder#stop stop()} and - {@link android.media.MediaRecorder#release release()} when you are done</li> -</ol> -<p>Here is a code example that will hopefully help fill in the gaps:</p> -<p><strong>Start Recording</strong></p> -<pre> - recorder = new MediaRecorder(); - ContentValues values = new ContentValues(3); - - values.put(MediaStore.MediaColumns.TITLE, SOME_NAME_HERE); - values.put(MediaStore.MediaColumns.TIMESTAMP, System.currentTimeMillis()); - values.put(MediaStore.MediaColumns.MIME_TYPE, recorder.getMimeContentType()); - - ContentResolver contentResolver = new ContentResolver(); - - Uri base = MediaStore.Audio.INTERNAL_CONTENT_URI; - Uri newUri = contentResolver.insert(base, values); - - if (newUri == null) { - // need to handle exception here - we were not able to create a new - // content entry - } - - String path = contentResolver.getDataFilePath(newUri); - - // could use setPreviewDisplay() to display a preview to suitable View here - - recorder.setAudioSource(MediaRecorder.AudioSource.MIC); - recorder.setOutputFormat(MediaRecorder.OutputFormat.THREE_GPP); - recorder.setAudioEncoder(MediaRecorder.AudioEncoder.AMR_NB); - recorder.setOutputFile(path); - - recorder.prepare(); - recorder.start(); -</pre> -<p><strong>Stop Recording</strong></p> -<pre> - recorder.stop(); - recorder.release(); -</pre> - diff --git a/docs/html/guide/topics/processes/process-lifecycle.jd b/docs/html/guide/topics/processes/process-lifecycle.jd deleted file mode 100644 index 0380f94..0000000 --- a/docs/html/guide/topics/processes/process-lifecycle.jd +++ /dev/null @@ -1,120 +0,0 @@ -page.title=Processes and Application Life Cycle -@jd:body - -<p>In most cases, every Android application runs in its own Linux process. -This process is created for the application when some of its code needs to -be run, and will remain running until it is no longer needed <em>and</em> -the system needs to reclaim its memory for use by other applications.</p> - -<p>An unusual and fundamental feature of Android is that an application process's -lifetime is <em>not</em> directly controlled by the application itself. -Instead, it is determined by the system through a combination of the parts of the application -that the system knows are running, how important these things are to the user, -and how much overall memory is available in the system.</p> - -<p>It is important that -application developers understand how different application components -(in particular {@link android.app.Activity}, {@link android.app.Service}, -and {@link android.content.BroadcastReceiver}) impact the lifetime -of the application's process. <strong>Not using these components correctly can -result in the system killing the application's process while it is doing -important work.</strong></p> - -<p>A common example of a process life-cycle bug is a -{@link android.content.BroadcastReceiver} that starts a thread when it -receives an Intent in its {@link android.content.BroadcastReceiver#onReceive -BroadcastReceiver.onReceive()} -method, and then returns from the function. Once it returns, the system -considers the BroadcastReceiver to be no longer active, and thus, its hosting -process no longer needed (unless other application components are active in -it). So, the system may kill the process at any time to reclaim memory, and in doing so, -it terminates the spawned thread running in the process. The solution to this problem -is to start a {@link android.app.Service} from the BroadcastReceiver, so the -system knows that there is still active work being done in the process.</p> - -<p>To determine which processes should be killed when low on memory, Android -places each process into an "importance hierarchy" based on the components running in -them and the state of those components. These process types are (in order of importance):</p> - -<ol> - -<li>A <strong>foreground process</strong> is one that is required for -what the user is currently doing. Various application components can -cause its containing process to be considered foreground in different -ways. A process is considered to be in the foreground if any of the -following conditions hold: - <ul> - <li> It is running an {@link android.app.Activity} - at the top of the screen that the user is interacting with (its - {@link android.app.Activity#onResume} method has been called).</li> - <li> It has a {@link android.content.BroadcastReceiver} that is currently running - (its {@link android.content.BroadcastReceiver#onReceive - BroadcastReceiver.onReceive()} method is executing).</li> - <li>It has a {@link android.app.Service} that is currently executing code - in one of its callbacks ({@link android.app.Service#onCreate Service.onCreate()}, - {@link android.app.Service#onStart Service.onStart()}, or - {@link android.app.Service#onDestroy Service.onDestroy()}).</li> - </ul> -</li> -<p>There will only ever be a few such processes in the system, and these will only -be killed as a last resort if memory is so low that not even these processes -can continue to run. Generally, at this point, the device has -reached a memory paging state, so this action is required in order to keep the user -interface responsive.</p> -</li> - -<li>A <strong>visible process</strong> is one holding an {@link android.app.Activity} -that is visible to the user on-screen but not in the foreground (its -{@link android.app.Activity#onPause} method has been called). This may -occur, for example, if the foreground Activity is displayed as a dialog -that allows the previous Activity to be seen behind it. Such a -process is considered extremely important and will not be killed unless doing so is -required to keep all foreground processes running. -</li> - -<li>A <strong>service process</strong> is one holding a {@link android.app.Service} -that has been started with the -{@link android.content.Context#startService startService()} method. Though these -processes are not directly visible to the user, they are generally doing things -that the user cares about (such as background mp3 playback or background -network data upload or download), so the system will always keep such processes -running unless there is not enough memory to retain all foreground and visible process. -</li> - -<li>A <strong>background process</strong> is one holding an {@link android.app.Activity} -that is not currently visible to the user (its -{@link android.app.Activity#onStop} method has been called). These processes -have no direct impact on the user experience. Provided they implement -their Activity life-cycle correctly -(see {@link android.app.Activity} for more details), the system -can kill such processes at any time to reclaim memory for one of the three -previous processes types. Usually there are many of these processes running, -so they are kept in an LRU list to ensure the process that was most recently seen -by the user is the last to be killed when running low on memory. -</li> - -<li>An <strong>empty process</strong> is one that doesn't hold any active application -components. The only reason to keep such a process around is as a cache to -improve startup time the next time a component of its application needs to -run. As such, the system will often kill these processes in order to -balance overall system resources between these empty cached processes and the -underlying kernel caches. -</li> - -</ol> - -<p>When deciding how to classify a process, the system will base its decision on the most -important level found among all the components currently active in the process. -See the {@link android.app.Activity}, {@link android.app.Service}, and -{@link android.content.BroadcastReceiver} documentation for more detail on how -each of these components contribute to the overall life-cycle of a process. -The documentation for each of these classes describes in more detail how -they impact the overall life-cycle of their application.</p> - -<p>A process's priority may also be increased based on other dependencies -a process has to it. For example, if process A has bound to a -{@link android.app.Service} with -the {@link android.content.Context#BIND_AUTO_CREATE Context.BIND_AUTO_CREATE} -flag or is using a -{@link android.content.ContentProvider} in process B, then process B's -classification will always be at least as important as process A's.</p> diff --git a/docs/html/guide/topics/providers/content-providers.jd b/docs/html/guide/topics/providers/content-providers.jd deleted file mode 100644 index 86dcebf..0000000 --- a/docs/html/guide/topics/providers/content-providers.jd +++ /dev/null @@ -1,922 +0,0 @@ -page.title=Content Providers -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> -<h2>Key classes</h2> -<ol> -<li>{@link android.content.ContentProvider}</li> -<li>{@link android.content.ContentResolver}</li> -<li>{@link android.database.Cursor}</li> -</ol> - -<h2>In this document</h2> -<ol> -<li><a href="#basics">Content provider basics</a></li> -<li><a href="#querying">Querying a content provider</a></li> -<li><a href="#modifying">Modifying data in a provider</a></li> -<li><a href="#creating">Creating a content provider</a></li> -<li><a href="#urisum">Content URI summary</a></li> -</ol> -</div> -</div> - -<p> -Content providers store and retrieve data and make it accessible to all -applications. They're the only way to share data across applications; there's -no common storage area that all Android packages can access. -</p> - -<p> -Android ships with a number of content providers for common data types -(audio, video, images, personal contact information, and so on). You can -see some of them listed in the {@link android.provider android.provider} -package. You can query these providers for the data they contain (although, -for some, you must acquire the proper permission to read the data). -</p> - -<p> -If you want to make your own data public, you have two options: You can -create your own content provider (a {@link android.content.ContentProvider} -subclass) or you can add the data to an existing provider — if there's -one that controls the same type of data and you have permission to write to it. -</p> - -<p> -This document is an introduction to using content providers. After a -brief discussion of the fundamentals, it explores how to query a content -provider, how to modify data controlled by a provider, and how to create -a content provider of your own. -</p> - - -<h2><a name="basics"></a>Content Provider Basics</h2> - -<p> -How a content provider actually stores its data under the covers is -up to its designer. But all content providers implement a common interface -for querying the provider and returning results — as well as for -adding, altering, and deleting data. -</p> - -<p> -It's an interface that clients use indirectly, most generally through -{@link android.content.ContentResolver} objects. You get a ContentResolver -by calling <code>{@link android.content.Context#getContentResolver -getContentResolver()}</code> from within the implementation of an Activity -or other application component: -</p> - -<pre>ContentResolver cr = getContentResolver();</pre> - -<p> -You can then use the ContentResolver's methods to interact with whatever -content providers you're interested in. -</p> - -<p> -When a query is initiated, the Android system identifies the content provider -that's the target of the query and makes sure that it is up and running. -The system instantiates all ContentProvider objects; you never need to do it -on your own. In fact, you never deal directly with ContentProvider objects -at all. Typically, there's just a single instance of each type of -ContentProvider. But it can communicate with multiple ContentResolver objects -in different applications and processes. The interaction between processes is -handled by the ContentResolver and ContentProvider classes. -</p> - - -<h3>The data model</h3> - -<p> -Content providers expose their data as a simple table on a database model, -where each row is a record and each column is data of a particular type -and meaning. For example, information about people and their phone numbers -might be exposed as follows: -</p> - -<table> - <tr> - <th scope="col">_ID</th> - <th scope="col">NUMBER</th> - <th scope="col">NUMBER_KEY</th> - <th scope="col">LABEL</th> - <th scope="col">NAME</th> - <th scope="col">TYPE</th> - </tr> - <tr> - <td>13</td> - <td>(425) 555 6677</td> - <td>425 555 6677</td> - <td>Kirkland office</td> - <td>Bully Pulpit</td> - <td>{@code TYPE_WORK}</td> - </tr> - <tr> - <td>44</td> - <td>(212) 555-1234</td> - <td>212 555 1234</td> - <td>NY apartment</td> - <td>Alan Vain</td> - <td>{@code TYPE_HOME}</td> - </tr> - <tr> - <td>45</td> - <td>(212) 555-6657</td> - <td>212 555 6657</td> - <td>Downtown office</td> - <td>Alan Vain</td> - <td>{@code TYPE_MOBILE}</td> - </tr> - <tr> - <td>53</td> - <td>201.555.4433</td> - <td>201 555 4433</td> - <td>Love Nest</td> - <td>Rex Cars</td> - <td>{@code TYPE_HOME}</td> - </tr> -</table> - -<p> -Every record includes a numeric {@code _ID} field that uniquely identifies -the record within the table. IDs can be used to match records in related -tables — for example, to find a person's phone number in one table -and pictures of that person in another. -</p> - -<p> -A query returns a {@link android.database.Cursor} object that can move from -record to record and column to column to read the contents of each field. -It has specialized methods for reading each type of data. So, to read a field, -you must know what type of data the field contains. (There's more on query -results and Cursor objects later.) -</p> - - -<h3><a name="uri"></a>URIs</h3> - -<p> -Each content provider exposes a public URI (wrapped as a {@link android.net.Uri} -object) that uniquely identifies its data set. A content provider that controls -multiple data sets (multiple tables) exposes a separate URI for each one. All -URIs for providers begin with the string "{@code content://}". The {@code content:} -scheme identifies the data as being controlled by a content provider. -</p> - -<p> -If you're defining a content provider, it's a good idea to also define a -constant for its URI, to simplify client code and make future updates cleaner. -Android defines {@code CONTENT_URI} constants for all the providers that come -with the platform. For example, the URI for the table that matches -phone numbers to people and the URI for the table that holds pictures of -people (both controlled by the Contacts content provider) are: -</p> - -<p> -<p style="margin-left: 2em">{@code android.provider.Contacts.Phones.CONTENT_URI} -<br/>{@code android.provider.Contacts.Photos.CONTENT_URI} -</p> - -<p> -Similarly, the URIs for the table of recent phone calls and the table -of calendar entries are: -</p> - -<p> -<p style="margin-left: 2em">{@code android.provider.CallLog.Calls.CONTENT_URI} -<br/>{@code android.provider.Calendar.CONTENT_URI} -</p> - -<p> -The URI constant is used in all interactions with the content provider. -Every {@link android.content.ContentResolver} method takes the URI -as its first argument. It's what identifies which provider the ContentResolver -should talk to and which table of the provider is being targeted. -</p> - - -<h2><a name="querying"></a>Querying a Content Provider</h2> - -<p> -You need three pieces of information to query a content provider: -</p> - -<ul> -<li>The URI that identifies the provider</li> -<li>The names of the data fields you want to receive</li> -<li>The data types for those fields</li> -</ul> - -<p> -If you're querying a particular record, you also need the ID for that record. -</p> - - -<h3>Making the query</h3> - -<p> -To query a content provider, you can use either the -<code>{@link android.content.ContentResolver#query ContentResolver.query()}</code> -method or the <code>{@link android.app.Activity#managedQuery -Activity.managedQuery()}</code> method. -Both methods take the same set of arguments, and both return a -Cursor object. However, {@code managedQuery()} -causes the activity to manage the life cycle of the Cursor. A managed Cursor -handles all of the niceties, such as unloading itself when the activity pauses, -and requerying itself when the activity restarts. You can ask an Activity to -begin managing an unmanaged Cursor object for you by calling -<code>{@link android.app.Activity#startManagingCursor -Activity.startManagingCursor()}</code>. -</p> - -<p> -The first argument to either <code>{@link android.content.ContentResolver#query query()}</code> -or <code>{@link android.app.Activity#managedQuery managedQuery()}</code> is the provider URI -— the {@code CONTENT_URI} constant that identifies a particular -ContentProvider and data set (see <a href="#uri">URIs</a> earlier). -</p> - -<p> -To restrict a query to just one record, you can append the {@code _ID} value for -that record to the URI — that is, place a string matching the ID as the -last segment of the path part of the URI. For example, if the ID is 23, -the URI would be: -</p> - -<p style="margin-left: 2em">{@code content://. . . ./23}</p> - -<p> -There are some helper methods, particularly -<code>{@link android.content.ContentUris#withAppendedId -ContentUris.withAppendedId()}</code> and <code>{@link -android.net.Uri#withAppendedPath Uri.withAppendedPath()}</code>, -that make it easy to append an ID to a URI. Both are static methods that return -a Uri object with the ID added. So, for example, if you were looking for record -23 in the database of people contacts, you might construct a query as follows: -</p> - -<pre> -import android.provider.Contacts.People; -import android.content.ContentUris; -import android.net.Uri; -import android.database.Cursor; - -// Use the ContentUris method to produce the base URI for the contact with _ID == 23. -Uri myPerson = ContentUris.withAppendedId(People.CONTENT_URI, 23); - -// Alternatively, use the Uri method to produce the base URI. -// It takes a string rather than an integer. -Uri myPerson = Uri.withAppendedPath(People.CONTENT_URI, "23"); - -// Then query for this specific record: -Cursor cur = managedQuery(myPerson, null, null, null, null); -</pre> - -<p> -The other arguments to the <code>{@link android.content.ContentResolver#query query()}</code> -and <code>{@link android.app.Activity#managedQuery managedQuery()}</code> methods delimit -the query in more detail. They are: -</p> - -<ul> -<li>The names of the data columns that should be returned. A {@code null} -value returns all columns. Otherwise, only columns that are listed by name -are returned. All the content providers that come with the platform define -constants for their columns. For example, the -{@link android.provider.Contacts.Phones android.provider.Contacts.Phones} class -defines constants for the names of the columns in the phone table illustrated -earlier &mdash {@code _ID}, {@code NUMBER}, {@code NUMBER_KEY}, {@code NAME}, -and so on.</li> - -<li><p>A filter detailing which rows to return, formatted as an SQL {@code WHERE} -clause (excluding the {@code WHERE} itself). A {@code null} value returns -all rows (unless the URI limits the query to a single record).</p></li> - -<li><p>Selection arguments.</p></li> - -<li><p>A sorting order for the rows that are returned, formatted as an SQL -{@code ORDER BY} clause (excluding the {@code ORDER BY} itself). A {@code null} -value returns the records in the default order for the table, which may be -unordered.</p></li> -</ul> - -<p> -Let's look at an example query to retrieve a list of contact names and their -primary phone numbers: -</p> - -<pre> -import android.provider.Contacts.People; -import android.database.Cursor; - -// Form an array specifying which columns to return. -String[] projection = new String[] { - People._ID, - People._COUNT, - People.NAME, - People.NUMBER - }; - -// Get the base URI for the People table in the Contacts content provider. -Uri contacts = People.CONTENT_URI; - -// Make the query. -Cursor managedCursor = managedQuery(contacts, - projection, // Which columns to return - null, // Which rows to return (all rows) - null, // Selection arguments (none) - // Put the results in ascending order by name - People.NAME + " ASC"); -</pre> - -<p> -This query retrieves data from the People table of the Contacts content -provider. It gets the name, primary phone number, and unique record ID for -each contact. It also reports the number of records that are returned as -the {@code _COUNT} field of each record. -</p> - -<p> -The constants for the names of the columns are defined in various interfaces -— {@code _ID} and {@code _COUNT} in -{@link android.provider.BaseColumns BaseColumns}, {@code NAME} in {@link android.provider.Contacts.PeopleColumns PeopleColumns}, and {@code NUMBER} -in {@link android.provider.Contacts.PhonesColumns PhoneColumns}. The -{@link android.provider.Contacts.People Contacts.People} class implements -each of these interfaces, which is why the code example above could refer -to them using just the class name. -</p> - - -<h3>What a query returns</h3> - -<p> -A query returns a set of zero or more database records. The names of the -columns, their default order, and their data types are specific to each -content provider. -But every provider has an {@code _ID} column, which holds a unique numeric -ID for each record. Every provider can also report the number -of records returned as the {@code _COUNT} column; its value -is the same for all rows. -</p> - -<p> -Here is an example result set for the query in the previous section: -</p> - -<table border="1"> - <tbody> - <tr> - <th scope="col">_ID</th> - <th scope="col">_COUNT</th> - <th scope="col">NAME</th> - <th scope="col">NUMBER</th> - </tr> - <tr> - <td>44</td> - <td>3</td> - <td>Alan Vain</td> - <td>212 555 1234</td> - </tr> - <tr> - <td>13</td> - <td>3</td> - <td>Bully Pulpit</td> - <td>425 555 6677</td> - </tr> - <tr> - <td>53</td> - <td>3</td> - <td>Rex Cars</td> - <td>201 555 4433</td> - </tr> - </tbody> -</table> - -<p> -The retrieved data is exposed by a {@link android.database.Cursor Cursor} -object that can be used to iterate backward or forward through the result -set. You can use this object only to read the data. To add, modify, or -delete data, you must use a ContentResolver object. -</p> - - -<h3>Reading retrieved data</h3> - -<p> -The Cursor object returned by a query provides access to a recordset of -results. If you have queried for a specific record by ID, this set will -contain only one value. Otherwise, it can contain multiple values. -(If there are no matches, it can also be empty.) You -can read data from specific fields in the record, but you must know the -data type of the field, because the Cursor object has a separate method -for reading each type of data — such as <code>{@link -android.database.Cursor#getString getString()}</code>, <code>{@link -android.database.Cursor#getInt getInt()}</code>, and <code>{@link -android.database.Cursor#getFloat getFloat()}</code>. -(However, for most types, if you call the method for reading strings, -the Cursor object will give you the String representation of the data.) -The Cursor lets you request the column name from the index of the column, -or the index number from the column name. -</p> - -<p> -The following snippet demonstrates reading names and phone numbers from -the query illustrated earlier: -</p> - -<pre> -import android.provider.Contacts.People; - -private void getColumnData(Cursor cur){ - if (cur.moveToFirst()) { - - String name; - String phoneNumber; - int nameColumn = cur.getColumnIndex(People.NAME); - int phoneColumn = cur.getColumnIndex(People.NUMBER); - String imagePath; - - do { - // Get the field values - name = cur.getString(nameColumn); - phoneNumber = cur.getString(phoneColumn); - - // Do something with the values. - ... - - } while (cur.moveToNext()); - - } -} -</pre> - -<p> -If a query can return binary data, such as an image or sound, the data -may be directly entered in the table or the table entry for that data may be -a string specifying a {@code content:} URI that you can use to get the data. -In general, smaller amounts of data (say, from 20 to 50K or less) are most often -directly entered in the table and can be read by calling -<code>{@link android.database.Cursor#getBlob Cursor.getBlob()}</code>. -It returns a byte array. -</p> - -<p> -If the table entry is a {@code content:} URI, you should never try to open -and read the file directly (for one thing, permissions problems can make this -fail). Instead, you should call -<code>{@link android.content.ContentResolver#openInputStream -ContentResolver.openInputStream()}</code> to get an -{@link java.io.InputStream} object that you can use to read the data. -</p> - - -<h2><a name="modifying"></a>Modifying Data</h2> - -<p> -Data kept by a content provider can be modified by: -</p> - -<ul> -<p><li>Adding new records</li> -<li>Adding new values to existing records</li> -<li>Batch updating existing records</li> -<li>Deleting records</li> -</ul> - -<p> -All data modification is accomplished using {@link android.content.ContentResolver} -methods. Some content providers require a more restrictive permission for writing -data than they do for reading it. If you don't have permission to write to a -content provider, the ContentResolver methods will fail. -</p> - - -<h3>Adding records</h3> - -<p> -To add a new record to a content provider, first set up a map of key-value pairs -in a {@link android.content.ContentValues} object, where each key matches -the name of a column in the content provider and the value is the desired -value for the new record in that column. Then call <code>{@link -android.content.ContentResolver#insert ContentResolver.insert()}</code> and pass -it the URI of the provider and the ContentValues map. This method returns -the full URI of the new record — that is, the provider's URI with -the appended ID for the new record. You can then use this URI to query and -get a Cursor over the new record, and to further modify the record. -Here's an example: -</p> - -<pre> -import android.provider.Contacts.People; -import android.content.ContentResolver; -import android.content.ContentValues; - -ContentValues values = new ContentValues(); - -// Add Abraham Lincoln to contacts and make him a favorite. -values.put(People.NAME, "Abraham Lincoln"); -// 1 = the new contact is added to favorites -// 0 = the new contact is not added to favorites -values.put(People.STARRED, 1); - -Uri uri = getContentResolver().insert(People.CONTENT_URI, values); -</pre> - - -<h3>Adding new values</h3> - -<p> -Once a record exists, you can add new information to it or modify -existing information. For example, the next step in the example above would -be to add contact information — like a phone number or an IM or e-mail -address — to the new entry. -</p> - -<p> -The best way to add to a record in the Contacts database is to append -the name of the table where the new data goes to the URI for the -record, then use the amended URI to add the new data values. Each -Contacts table exposes a name for this purpose as a {@code -CONTENT_DIRECTORY} constant. The following code continues the previous -example by adding a phone number and e-mail address for the record -just created: -</p> - -<pre> -Uri phoneUri = null; -Uri emailUri = null; - -// Add a phone number for Abraham Lincoln. Begin with the URI for -// the new record just returned by insert(); it ends with the _ID -// of the new record, so we don't have to add the ID ourselves. -// Then append the designation for the phone table to this URI, -// and use the resulting URI to insert the phone number. -phoneUri = Uri.withAppendedPath(uri, People.Phones.CONTENT_DIRECTORY); - -values.clear(); -values.put(People.Phones.TYPE, People.Phones.TYPE_MOBILE); -values.put(People.Phones.NUMBER, "1233214567"); -getContentResolver().insert(phoneUri, values); - -// Now add an email address in the same way. -emailUri = Uri.withAppendedPath(uri, People.ContactMethods.CONTENT_DIRECTORY); - -values.clear(); -// ContactMethods.KIND is used to distinguish different kinds of -// contact methods, such as email, IM, etc. -values.put(People.ContactMethods.KIND, Contacts.KIND_EMAIL); -values.put(People.ContactMethods.DATA, "test@example.com"); -values.put(People.ContactMethods.TYPE, People.ContactMethods.TYPE_HOME); -getContentResolver().insert(emailUri, values); -</pre> - -<p> -You can place small amounts of binary data into a table by calling -the version of <code>{@link android.content.ContentValues#put -ContentValues.put()}</code> that takes a byte array. -That would work for a small icon-like image or a short audio clip, for example. -However, if you have a large amount of binary data to add, such as a photograph -or a complete song, put a {@code content:} URI for the data in the table and call -<code>{@link android.content.ContentResolver#openOutputStream -ContentResolver.openOutputStream()}</code> -with the file's URI. (That causes the content provider to store the data -in a file and record the file path in a hidden field of the record.) -</p> - -<p> -In this regard, the {@link android.provider.MediaStore} content -provider, the main provider that dispenses image, audio, and video -data, employs a special convention: The same URI that is used with -{@code query()} or {@code managedQuery()} to get meta-information -about the binary data (such as, the caption of a photograph or the -date it was taken) is used with {@code openInputStream()} -to get the data itself. Similarly, the same URI that is used with -{@code insert()} to put meta-information into a MediaStore record -is used with {@code openOutputStream()} to place the binary data there. -The following code snippet illustrates this convention: -</p> - -<pre> -import android.provider.MediaStore.Images.Media; -import android.content.ContentValues; -import java.io.OutputStream; - -// Save the name and description of an image in a ContentValues map. -ContentValues values = new ContentValues(3); -values.put(Media.DISPLAY_NAME, "road_trip_1"); -values.put(Media.DESCRIPTION, "Day 1, trip to Los Angeles"); -values.put(Media.MIME_TYPE, "image/jpeg"); - -// Add a new record without the bitmap, but with the values just set. -// insert() returns the URI of the new record. -Uri uri = getContentResolver().insert(Media.EXTERNAL_CONTENT_URI, values); - -// Now get a handle to the file for that record, and save the data into it. -// Here, sourceBitmap is a Bitmap object representing the file to save to the database. -try { - OutputStream outStream = getContentResolver().openOutputStream(uri); - sourceBitmap.compress(Bitmap.CompressFormat.JPEG, 50, outStream); - outStream.close(); -} catch (Exception e) { - Log.e(TAG, "exception while writing image", e); -} -</pre> - - -<h3>Batch updating records</h3> - -<p> -To batch update a group of records (for example, to change "NY" to "New York" -in all fields), call the <code>{@link -android.content.ContentResolver#update ContentResolver.update()}</code> -method with the columns and values to change. -</p> - - -<h3><a name="deletingrecord"></a>Deleting a record</h3> - -<p> -To delete a single record, call {<code>{@link -android.content.ContentResolver#delete ContentResolver.delete()}</code> -with the URI of a specific row. -</p> - -<p> -To delete multiple rows, call <code>{@link -android.content.ContentResolver#delete ContentResolver.delete()}</code> -with the URI of the type of record to delete (for example, {@code android.provider.Contacts.People.CONTENT_URI}) and an SQL {@code WHERE} -clause defining which rows to delete. (<i><b>Caution</b>: -Be sure to include a valid {@code WHERE} clause if you're deleting a general -type, or you risk deleting more records than you intended!</i>). -</p> - - -<h2><a name="creating"></a>Creating a Content Provider</h2> - -<p> -To create a content provider, you must: -</p> - -<ul> -<li>Set up a system for storing the data. Most content providers -store their data using Android's file storage methods or SQLite databases, -but you can store your data any way you want. Android provides the -{@link android.database.sqlite.SQLiteOpenHelper SQLiteOpenHelper} -class to help you create a database and {@link -android.database.sqlite.SQLiteDatabase SQLiteDatabase} to manage it.</li> - -<li><p>Extend the {@link android.content.ContentProvider} class to provide -access to the data.</p></li> - -<li><p>Declare the content provider in the manifest file for your -application (AndroidManifest.xml).</p></li> -</ul> - -<p> -The following sections have notes on the last two of these tasks. -</p> - - -<h3>Extending the ContentProvider class</h3> - -<p> -You define a {@link android.content.ContentProvider} subclass to -expose your data to others using the conventions expected by -ContentResolver and Cursor objects. Principally, this means -implementing six abstract methods declared in the ContentProvider class: -</p> - -<p style="margin-left: 2em">{@code query()} -<br/>{@code insert()} -<br/>{@code update()} -<br/>{@code delete()} -<br/>{@code getType()} -<br/>{@code onCreate()}</p> - -<p> -The {@code query()} method must return a {@link android.database.Cursor} object -that can iterate over the requested data. Cursor itself is an interface, but -Android provides some ready-made Cursor objects that you can use. For example, -{@link android.database.sqlite.SQLiteCursor} can iterate over data stored in -an SQLite database. You get the Cursor object by calling any of the {@link -android.database.sqlite.SQLiteDatabase SQLiteDatabase} class's {@code query()} -methods. There are other Cursor implementations — such as {@link -android.database.MatrixCursor} — for data not stored in a database. -</p> - -<p> -Because these ContentProvider methods can be called from -various ContentResolver objects in different processes and threads, -they must be implemented in a thread-safe manner. -</p> - -<p> -As a courtesy, you might also want to call <code>{@link android.content.ContentResolver#notifyChange(android.net.Uri,android.database.ContentObserver) -ContentResolver.notifyChange()}</code> to notify listeners when there are -modifications to the data. -</p> - -<p> -Beyond defining the subclass itself, there are other steps you should take -to simplify the work of clients and make the class more accessible: -</p> - -<ul> -<li>Define a {@code public static final} {@link android.net.Uri} -named {@code CONTENT_URI}. This is the string that represents the full -{@code content:} URI that your content provider handles. You must define a -unique string for this value. The best solution is to use the fully-qualified -class name of the content provider (made lowercase). So, for example, the -URI for a TransportationProvider class could be defined as follows: - -<pre>public static final Uri CONTENT_URI = - Uri.parse("content://com.example.codelab.transporationprovider");</pre> - -<p> -If the provider has subtables, also define {@code CONTENT_URI} constants for -each of the subtables. These URIs should all have the same authority (since -that identifies the content provider), and be distinguished only by their paths. -For example: -</p> - -<p style="margin-left: 2em">{@code content://com.example.codelab.transporationprovider/train} -<br/>{@code content://com.example.codelab.transporationprovider/air/domestic} -<br/>{@code content://com.example.codelab.transporationprovider/air/international}</p> - -<p> -For an overview of {@code content:} URIs, see the <a href="#urisum">Content URI -Summary</a> at the end of this document. -</p></li> - -<li><p>Define the column names that the content provider will return to clients. -If you are using an underlying database, these column names are typically -identical to the SQL database column names they represent. Also define -{@code public static} String constants that clients can use to specify -the columns in queries and other instructions. -</p> - -<p> -Be sure to include an integer column named "{@code _id}" -(with the constant {@code _ID}) for -the IDs of the records. You should have this field whether or not you have -another field (such as a URL) that is also unique among all records. If -you're using the SQLite database, the {@code _ID} field should be the -following type: -</p> - -<p style="margin-left: 2em">{@code INTEGER PRIMARY KEY AUTOINCREMENT}</p> - -<p> -The {@code AUTOINCREMENT} descriptor is optional. But without it, SQLite -increments an ID counter field to the next number above the largest -existing number in the column. If you delete the last row, the next row added -will have the same ID as the deleted row. {@code AUTOINCREMENT} avoids this -by having SQLite increment to the next largest value whether deleted or not. -</p> -</li> - -<li><p>Carefully document the data type of each column. Clients need this -information to read the data.</p></li> - -<li><p>If you are handling a new data type, you must define a new MIME type -to return in your implementation of <code>{@link -android.content.ContentProvider#getType ContentProvider.getType()}</code>. -The type depends in part on whether or not the {@code content:} URI submitted -to {@code getType()} limits the request to a specific record. There's one -form of the MIME type for a single record and another for multiple records. -Use the {@link android.net.Uri Uri} methods to help determine what is being -requested. Here is the general format for each type:</p></li> - -<ul> -<li><p>For a single record: {@code vnd.android.cursor.item/vnd.<em>yourcompanyname.contenttype</em}</p> - -<p>For example, a request for train record 122, like this URI,</p> -<p style="margin-left: 2em">{@code content://com.example.transportationprovider/trains/122}</p> - -<p>might return this MIME type:</p> -<p style="margin-left: 2em">{@code vnd.android.cursor.item/vnd.example.rail}</p> -</li> - -<li><p>For multiple records: {@code vnd.android.cursor.dir/vnd.<em>yourcompanyname.contenttype</em>}</p> - -<p>For example, a request for all train records, like the following URI,</p> -<p style="margin-left: 2em">{@code content://com.example.transportationprovider/trains}</p> - -<p>might return this MIME type:</p> -<p style="margin-left: 2em">{@code vnd.android.cursor.dir/vnd.example.rail}</p> -</li> -</ul> - -<li><p>If you are exposing byte data that's too big to put in the table itself -— such as a large bitmap file — the field that exposes the -data to clients should actually contain a {@code content:} URI string. -This is the field that gives clients access to the data file. The record -should also have another field, named "{@code _data}" that lists the exact file -path on the device for that file. This field is not intended to be read by -the client, but by the ContentResolver. The client will call <code>{@link -android.content.ContentResolver#openInputStream ContentResolver.openInputStream()}</code> -on the user-facing field holding the URI for the item. The ContentResolver -will request the "{@code _data}" field for that record, and because -it has higher permissions than a client, it should be able to access -that file directly and return a read wrapper for the file to the client.</p></li> - -</ul> - -<p> -For an example of a private content provider implementation, see the -NodePadProvider class in the Notepad sample application that ships with the SDK. -</p> - - -<h3>Declaring the content provider</h3> - -<p> -To let the Android system know about the content provider you've developed, -declare it with a {@code <provider>} element in the application's -AndroidManifest.xml file. Content providers that are not declared in the -manifest are not visible to the Android system -</p> - -<p> -The {@code name} attribute is the fully qualified name of the ContentProvider -subclass. The {@code authorities} attribute is the authority part of the -{@code content:} URI that identifies the provider. -For example if the ContentProvider subclass is AutoInfoProvider, the -{@code <provider>} element might look like this: -</p> - -<pre> -<provider name="com.example.autos.AutoInfoProvider" - authorities="com.example.autos.autoinfoprovider" - . . . /> -</provider> -</pre> - -<p> -Note that the {@code authorities} attribute omits the path part of a -{@code content:} URI. For example, if AutoInfoProvider controlled subtables -for different types of autos or different manufacturers, -</p> - -<p style="margin-left: 2em">{@code content://com.example.autos.autoinfoprovider/honda} -<br/>{@code content://com.example.autos.autoinfoprovider/gm/compact} -<br/>{@code content://com.example.autos.autoinfoprovider/gm/suv}</p> - -<p> -those paths would not be declared in the manifest. The authority is what -identifies the provider, not the path; your provider can interpret the path -part of the URI in any way you choose. -</p> - -<p> -Other {@code <provider>} attributes can set permissions to read and -write data, provide for an icon and text that can be displayed to users, -enable and disable the provider, and so on. Set the {@code multiprocess} -attribute to "{@code true}" if data does not need to be synchronized between -multiple running versions of the content provider. This permits an instance -of the provider to be created in each client process, eliminating the need -to perform IPC. -</p> - - -<h2><a name="urisum"></a>Content URI Summary</h2> - -<p> -Here is a recap of the important parts of a content URI: -</p> - -<p> -<img src="{@docRoot}images/content_uri.png" alt="Elements of a content URI" -height="80" width="528"> -</p> - -<ol type="A"> -<li>Standard prefix indicating that the data is controlled by a -content provider. It's never modified.</li> - -<li><p>The authority part of the URI; it identifies the content provider. -For third-party applications, this should be a fully-qualified class name -(reduced to lowercase) to ensure uniqueness. The authority is declared in -the {@code <provider>} element's {@code authorities} attribute:</p> - -<pre><provider name=".TransportationProvider" - authorities="com.example.transportationprovider" - . . . ></pre></li> - -<li><p>The path that the content provider uses to determine what kind of data is -being requested. This can be zero or more segments long. If the content provider -exposes only one type of data (only trains, for example), it can be absent. -If the provider exposes several types, including subtypes, it can be several -segments long — for example, "{@code land/bus}", "{@code land/train}", -"{@code sea/ship}", and "{@code sea/submarine}" to give four possibilities.</p></li> - -<li><p>The ID of the specific record being requested, if any. This is the -{@code _ID} value of the requested record. If the request is not limited to -a single record, this segment and the trailing slash are omitted:</p> - -<p style="margin-left: 2em">{@code content://com.example.transportationprovider/trains}</p> -</li> -</ol> - - diff --git a/docs/html/guide/topics/resources/available-resources.jd b/docs/html/guide/topics/resources/available-resources.jd deleted file mode 100644 index 2a6a6ac..0000000 --- a/docs/html/guide/topics/resources/available-resources.jd +++ /dev/null @@ -1,1135 +0,0 @@ -page.title=Available Resource Types -parent.title=Resources and Assets -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Key classes</h2> - <ol> - <li>{@link android.content.res.Resources}</li> - <li>{@link android.content.res.AssetManager}</li> - </ol> - - <h2>In this document</h2> - <ol> - <li><a href="#simplevalues">Simple Values</a> - <ol> - <li><a href="#colorvals">Color Values</a></li> - <li><a href="#stringresources">Strings and Styled Text</a></li> - <li><a href="#dimension">Dimension Values</a></li> - </ol> - </li> - <li><a href="#drawables">Drawables</a> - <ol> - <li><a href="#imagefileresources">Bitmap Files</a></li> - <li><a href="#colordrawableresources">Color Drawables</a></li> - <li><a href="#ninepatch">Nine-Patch (Stretchable) Images</a></li> - </ol> - </li> - <li><a href="#animation">Animation</a></li> - <li><a href="#menus">Menus</a></li> - <li><a href="#layoutresources">Layout</a> - <ol> - <li><a href="#customresources">Custom Layout Resources</a> - </ol> - </li> - <li><a href="#stylesandthemes">Styles and Themes</a></li> - </ol> - -</div> -</div> - -<p>This page describes the different types of resources that you can -externalize from your code and package with your application. </p> - - -<p>For more details on how to use resources in your application, please see the - <a href="resources-i18n.html">Resources and Internationalization</a> - documentation.</p> - - -<h2 id="simplevalues">Simple Values</h2> - -<p>All simple resource values can be expressed as a string, using various -formats to unambiguously indicate the type of resource being created. For -this reason, these values can be defined both as standard resources -(under res/values/), as well as direct values supplied for -mappings in <a href="#stylesandthemes">styles and themes</a>, and attributes in -XML files such as <a href="#layoutresources">layouts</a>.</p> - - - -<h3 id="colorvals">Color Values</h3> -<p> - A color value specifies an RGB value with an alpha channel, which can - be used in various places such as specifying a solid color for a {@link android.graphics.drawable.Drawable} - or the color to use for text. A color value always begins with - a pound (#) character and then followed by the Alpha-Red-Green-Blue information - in one of the following formats: -</p> -<ul> -<li> #RGB -<li> #ARGB -<li> #RRGGBB -<li> #AARRGGBB -</ul> -<p> - If you want to retrieve the color represented by a resource ID, you can call - the {@link android.content.res.Resources#getColor(int) Resources.getColor()} method. -</p> -<p> - <strong>Source file format:</strong> XML file requiring a - <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and - a root <code><resources></code> element containing one or more - <code><color></code> tags. -</p> -<p> - <strong>Resource source file location</strong>: res/values/<em>colors</em>.xml (file name is arbitrary) -</p> -<p> - <strong>Compiled resource datatype:</strong> Resource pointer to a Java int. -</p> -<p> - <strong>Resource reference name:</strong> -</p> -<ul> - <li> - <strong>Java:</strong> <code>R.color.<em>some_name</em></code> - </li> - <li> - <strong>XML:</strong> <code>@[<em>package</em>:]color/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific color) - </li> -</ul> -<p> - <strong>Syntax</strong> -</p> -<pre> -<color name=<em>color_name</em>><em>#color_value</em></color> -</pre> -<dl> - <dt> - <color> - </dt> - <dd> - Value is a color, using web-style syntax, as describe above. Has only one attribute: - <ul> - <li> - <em>name</em> - The name used in referring to this color. - </li> - </ul> - </dd> -</dl> -<p> - <strong>Example XML Declaration</strong> -</p> -<p> - The following code declares two colors, the first fully opaque, and the - second translucent. -</p> -<pre> -<resources> - <color name="opaque_red">#f00</color> - <color name="translucent_red">#80ff0000</color> -</resources> -</pre> -<p> - <strong>Example Code Use</strong> -</p> -<p> - Example Java code -</p> -<pre> -// Retrieve a color value. -int color = getResources.getColor(R.color.opaque_red); -</pre> -<p> - Example XML code -</p> -<pre> -<TextView android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:textAlign="center" - android:textColor="@color/translucent_red" - android:text="Some Text"/> -</pre> - - - -<h3 id="stringresources">Strings and Styled Text</h3> -<p> - Strings, with optional <a href="#styledtext">simple formatting</a>, can be -stored and retrieved as resources. You can add formatting to your string by -using three standard HTML tags: <b>, <i>, and <u>. To -guarantee getting an unstyled string only (the raw text) call the -<code>toString()</code> method of the retrieved CharSequence object. -Methods that accept string resources should be able to process these styling -tags. -</p> -<p> - If you want to retrieve the String represented by a resource ID, you can call the {@link android.content.Context#getString(int) Context.getString()} method. -</p> -<p> - <strong>Note:</strong> If you use an apostrophe or a quote in your string, you must either escape it or enclose the whole string in the other kind of enclosing quotes: -</p> -<pre> -<string name="good_example">"This'll work"</string> -<string name="good_example_2">This\'ll also work</string> -<string name="bad_example">This won't work!</string> -<string name="bad_example_2">XML encodings won&apos;t work either!</string> -</pre> -<p> - <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><string></code> tags. -</p> -<p> - <strong>Resource source file location</strong>: res/values/<em>strings</em>.xml (file name is arbitrary) -</p> -<p> - <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. -</p> -<p> - <strong>Resource reference name:</strong> -</p> -<ul> - <li> - <strong>Java:</strong> <code>R.string.<em>some_name</em></code> - </li> - <li> - <strong>XML:</strong> <code>@[<em>package</em>:]string/some_name</code> (where <em>some_name</em> is the <em>name</em> of a specific string) - </li> -</ul> -<p> - <strong>Syntax</strong> -</p> -<pre> -<string name=<em>string_name</em>><em>string_value</em></string> -</pre> -<dl> - <dt> - <string> - </dt> - <dd> - Value is a string, with optional styling tags. Has only one attribute: - <ul> - <li> - <em>name</em> - The name used in referring to this string. - </li> - </ul> - </dd> -</dl> -<p> - <strong>Example XML Declaration</strong> -</p> -<p> - The following declares two strings: the first — simple text with no - formatting (resulting in a CharSequence that is simply a String object) — the second includes formatting information in the string (resulting - in a CharSequence that is a complex data structure). If you are using the custom editor for string files in Eclipse, the HTML formatting tags will automatically be escaped and you will need to use {@link android.content.Context#getString(int) Context.getString()} and {@link android.text.Html#fromHtml} to retreive the resource and then convert it to formatted text. -</p> -<pre> -<resources> - <string name="simple_welcome_message">Welcome!</string> - <string name="styled_welcome_message">We are <b><i>so</i></b> glad to see you.</string> -</resources> -</pre> -<p> - <strong>Example Code Use</strong> -</p> -<p> - Example Java code -</p> -<pre> -// Assign a styled string resource to a TextView -// on the current screen. -CharSequence str = getString(R.string.styled_welcome_message); -TextView tv = (TextView)findViewByID(R.id.text); -tv.setText(str); -</pre> -<p> - Example XML code -</p> -<pre> -<TextView android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:textAlign="center" - android:text="@string/simple_welcome_message"/> -</pre> - - -<h4 id="styledtext">Using Styled Text as a Format String</h4> -<p> -Sometimes you may want to create a styled text resource that is also used as a -format string. This cannot be done directly because there is no way of passing -the styled text as the format string argument of String.format() -without stripping out the style information. The workaround is to store the -style tags as escaped HTML tags, and then convert the escaped HTML string into -a styled text after formatting has taken place. -</p> -<p> -To use styled text as a format string, do the following. -</p> -<ol> - <li>Store your styled text resource as an escaped string, so that the HTML tags in your text resource are not interpreted as if they were XML tags: -<pre> -<resources> - <string name="search_results_resultsTextFormat">%1$d results for &lt;b>&amp;quot;%2$s&amp;quot;&lt;/b></string> -</resources> -</pre> -<p> -In this example the format string has two arguments: <code>%1$d</code> is a decimal number, <code>%2$s</code> is a string. -</p> -</li> -<li> - Make sure any String arguments are properly escaped if they might contain '<' or '&' characters. -The {@link android.text.TextUtils#htmlEncode} method will do this: -<pre> -String escapedTitle = TextUtil.htmlEncode(title); -</pre> -</li> -<li> - Use String.format() to format the HTML text, then use {@link android.text.Html#fromHtml} to convert the HTML text into styled text: -<pre> -String resultsTextFormat = getContext().getResources().getString(R.string.search_results_resultsTextFormat); -String resultsText = String.format(resultsTextFormat, count, escapedTitle); -CharSequence styledResults = Html.fromHtml(resultsText); -</pre> -</li> -</ol> - - -<h3 id="dimension"Dimension Values</h3> -<p>You can create common dimensions to use for various screen elements by -defining dimension values in XML. A dimension resource is a number followed by -a unit of measurement. For example: 10px, 2in, 5sp. Here are the units of -measurement supported by Android:</p> -<dl> - <dt>px</dt> - <dd>Pixels - corresponds to actual pixels on the screen.</dd> - - <dt>in</dt> - <dd>Inches - based on the physical size of the screen.</dd> - - <dt>mm</dt> - <dd>Millimeters - based on the physical size of the screen.</dd> - - <dt>pt</dt> - <dd>Points - 1/72 of an inch based on the physical size of the screen.</dd> - - <dt>dp</dt> - <dd>Density-independent Pixels - an abstract unit that is based on the - physical density of the screen. These units are relative to a 160 dpi - screen, so one dp is one pixel on a 160 dpi screen. The ratio of - dp-to-pixel will change with the screen density, but not necessarily - in direct proportion. <strong>Note:</strong> The compiler accepts both "dip" and "dp", though "dp" is more consistent with "sp".</dd> - - <dt>sp</dt> - <dd>Scale-independent Pixels - this is like the dp unit, but it is also - scaled by the user's font size preference. It is recommend you use this - unit when specifying font sizes, so they will be adjusted for both the - screen density and user's preference.</dd> -</dl> - -<p>Dimension values are not normally used as raw resources, but rather as -attribute values in XML files. You can, however, create plain resources -containing this data type.</p> - -<p><strong>Source file format:</strong> XML file requiring a <code><?xml -version="1.0" encoding="utf-8"?></code> declaration, and a root -<code><resources></code> element containing one or more -<code><dimen></code> tags.</p> - -<p><strong>Resource source file location</strong>: res/values/dimens.xml (File -name is arbitrary; standard practice is to put all dimensions in one file -devoted to dimensions.)</p> -<p><strong>Compiled resource datatype:</strong> Resource pointer to a -dimension.</p> -<p> - <strong>Resource reference name:</strong> -</p> -<ul> - <li> - <strong>Java:</strong> <code>R.dimen.<em>some_name</em></code> - </li> - <li> - <strong>XML:</strong> <code>@[<em>package</em>:]dimen/<em>some_name</em></code> (where <em>some_name</em> is the <em>name</em> of a specific <code><dimen></code> element) - </li> -</ul> -<p> - <strong>Syntax</strong> -</p> -<pre> -<dimen name=<em>dimen_name</em>><em>dimen_value</em></dimen> -</pre> -<dl> - <dt> - <dimen> - </dt> - <dd> - A valid dimension value. - <ul> - <li> - <em>name</em> - The name used in referring to this dimension. - </li> - </ul> - </dd> -</dl> -<p> - <strong>Example XML Declaration</strong> -</p> -<p> - The following code declares several dimension values. -</p> -<pre> -<resources> - <dimen name="one_pixel">1px</dimen> - <dimen name="double_density">2dp</dimen> - <dimen name="sixteen_sp">16sp</dimen> -</resources> -</pre> -<p> - <strong>Example Code Use</strong> -</p> -<p> - Example Java code: -</p> -<pre> -float dimen = Resources.getDimen(R.dimen.one_pixel); -</pre> -<p> - Example XML code: -</p> -<pre> -<TextView android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:textSize="@dimen/sixteen_sp"/> -</pre> - - -<h2 id="drawables">Drawables</h2> - -<p>A {@link android.graphics.drawable.Drawable} is a type of resource that -you retrieve with {@link android.content.res.Resources#getDrawable -Resources.getDrawable()} and use to draw to the screen. There are a -number of drawable resources that can be created.</p> - - - -<h3 id="imagefileresources">Bitmap Files</h3> -<p>Android supports bitmap resource files in a few different formats: png -(preferred), jpg (acceptable), gif (discouraged). The bitmap file itself is -compiled and referenced by the file name without the extension (so -res/drawable/my_picture.png would be referenced as R.drawable.my_picture).</p> - -<p> - <strong>Source file formats:</strong> png (preferred), jpg (acceptable), gif (discouraged). One resource per file. -</p> -<p> - <strong>Resource file location</strong>: res/drawable/<em>some_file</em>.png or <em>some_file</em>.jpg or <em>some_file</em>.gif. -</p> -<p> - <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.BitmapDrawable BitmapDrawable}. -</p> -<p> - <strong>Resource reference name:</strong> -</p> -<ul> - <li> - <strong>Java:</strong> <code>R.drawable.<em>some_file</em></code> - </li> - <li> - <strong>XML:</strong> <code>@[<em>package</em>:]drawable/<em>some_file</em></code> - </li> -</ul> - -<p>For more discussion and examples using drawable resources, see the discussion in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#drawable-resource#drawables">2D Graphics</a>.</p> - - -<h3 id="colordrawableresources">Color Drawables</h3> -<p>You can create a {@link android.graphics.drawable.PaintDrawable} object that is a rectangle of color, -with optionally rounded corners. This element can be defined in any of the -files inside res/values/.</p> -<p><strong>Source file format:</strong> XML file requiring a <code><?xml -version="1.0" encoding="utf-8"?></code> declaration, and a root -<code><resources></code> element containing one or more -<code><drawable></code> tags.</p> -<p> - <strong>Resource source file location</strong>: res/values/colors.xml (File name is arbitrary; standard practice is to put the PaintDrawable items in the file along with the <a href="resources-i18n.html#numericcolorresources">numeric color values</a>.) -</p> -<p> - <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.PaintDrawable}. -</p> -<p> - <strong>Resource reference name:</strong> -</p> -<ul> - <li> - <strong>Java:</strong> <code>R.drawable.<em>some_name</em></code> - </li> - <li> - <strong>XML:</strong> <code>@[<em>package</em>:]drawable/<em>some_name</em></code> (where <em>some_name</em> is the name of a specific resource) - </li> -</ul> -<p> - <strong>Syntax</strong> -</p> -<pre> -<drawable name=<em>color_name</em>><em>color_value</em></drawable> -</pre> -<dl> - <dt> - <drawable> - </dt> - <dd> - A valid <a href="#colorvals">color value</a>. - <ul> - <li> - <em>name</em> - The name used in referring to this drawable. - </li> - </ul> - </dd> -</dl> -<p> - <strong>Example XML Declaration</strong> -</p> -<p> - The following code declares several color drawables. -</p> -<pre> -<resources> - <drawable name="solid_red">#f00</drawable> - <drawable name="solid_blue">#0000ff</drawable> - <drawable name="solid_green">#f0f0</drawable> -</resources> -</pre> -<p> - <strong>Example Code Use</strong> -</p> -<p> - Example Java code -</p> -<pre> -// Assign a PaintDrawable as the background to -// a TextView on the current screen. -Drawable redDrawable = Resources.getDrawable(R.drawable.solid_red); -TextView tv = (TextView)findViewByID(R.id.text); -tv.setBackground(redDrawable); -</pre> -<p> - Example XML code -</p> -<pre> -<TextView android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:textAlign="center" - android:background="@drawable/solid_red"/> -</pre> - - -<h3 id="ninepatch">Nine-Patch (stretchable) Images</h3> -<p> - Android supports a stretchable bitmap image, called a - {@link android.graphics.NinePatch} graphic. This is a PNG image in which - you define stretchable sections that Android will resize to fit the object - at display time to accommodate variable sized sections, such as text strings. - You typically assign this resource to the View's background. An example use - of a stretchable image is the button backgrounds that Android uses; buttons - must stretch to accommodate strings of various lengths. -</p> - -<p> - <strong>Source file format:</strong> PNG — one resource per file -</p> -<p> - <strong>Resource source file location</strong>: res/drawable/<em>some_name</em>.9.png (must end in .9.png) -</p> -<p> - <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.graphics.drawable.NinePatchDrawable NinePatchDrawable}. -</p> -<p> - <strong>Resource reference name:</strong> -</p> -<ul> - <li> - <strong>Java:</strong> <code>R.drawable.<em>some_file</em></code> - </li> - <li> - <strong>XML:</strong> <code>@[<em>package</em>:]drawable.<em>some_file</em></code> - </li> -</ul> - - -<p>For more information and examples using NinePatch drawables, see the discussion -in <a href="{@docRoot}guide/topics/graphics/2d-graphics.html#nine-patch">2D Graphics</a>.</p> - - - -<h2 id="animation">Animation</h2> - -<h3 id="tweenedanimation">Tweened Animation</h3> -<p> - Android can perform simple animation on a graphic, or a series of graphics. These include rotations, fading, moving, and stretching. -</p> -<p> - <strong>Source file format:</strong> XML file, one resource per file, one root tag with no <code><?xml></code> declaration -</p> -<p> - <strong>Resource file location</strong>: res/anim/<em>some_file</em>.xml -</p> -<p> - <strong>Compiled resource datatype:</strong> Resource pointer to an {@link android.view.animation.Animation}. -</p> -<p> - <strong>Resource reference name:</strong> -</p> -<ul> - <li> - <strong>Java:</strong> <code>R.anim.<em>some_file</em></code> - </li> - <li> - <strong>XML:</strong> <code>@[<em>package</em>:]anim/<em>some_file</em></code> - </li> -</ul> -<p> - <strong>Syntax</strong> -</p> -<p> - The file must have a single root element: this will be either a single <code><alpha></code>, <code><scale></code>, <code><translate></code>, <code><rotate></code>, interpolator element, or <code><set></code> element that holds groups of these elements (which may include another <code><set></code>). By default, all elements are applied simultaneously. To have them occur sequentially, you must specify the <code>startOffset</code> attribute. -</p> -<pre> -<set android:shareInterpolator=boolean> // Only required if multiple tags are used. - <alpha android:fromAlpha=float - android:toAlpha=float > | - <scale android:fromXScale=float - android:toXScale=float - android:fromYScale=float - android:toYScale=float - android:pivotX=string - android:pivotY=string > | - <translate android:fromX=string - android:toX=string - android:fromY=string - android:toY=string > | - <rotate android:fromDegrees=float - android:toDegrees=float - android:pivotX=string - android:pivotY=string > | - <<em>interpolator tag</em>> - <set> -</set> -</pre> -<p> - <strong>Elements and Attributes</strong> -</p> -<dl> - <dt> - <set> - </dt> - <dd> - A container that can recursively hold itself or other animations. - Represents an {@link android.view.animation.AnimationSet}. - You can include as many child elements of the same or different types as you like. - Supports the following attribute: - <ul> - <li> - <em>shareInterpolator</em> - Whether to share the same Interpolator among all immediate child elements. - </li> - </ul> - </dd> - <dt> - <alpha> - </dt> - <dd> - A fading animation. Represents an {@link android.view.animation.AlphaAnimation}. - Supports the following attributes: - <ul> - <li> - <em>fromAlpha</em> - 0.0 to 1.0, where 0.0 is transparent. - </li> - <li> - <em>toAlpha</em> - 0.0 to 1.0, where 0.0 is transparent. - </li> - </ul> - </dd> - <dt> - <scale> - </dt> - <dd> - A resizing animation. Represents a {@link android.view.animation.ScaleAnimation}. - You can specify what is the center point of the image (the pinned center), from which it grows outward (or inward), by specifying pivotX and pivotY. So, for example, if these were 0, 0 (top left corner), all growth would be down and to the right. <code>scale</code> supports the following attributes: - <ul> - <li> - <em>fromXScale</em> - Starting X size, where 1.0 is no change. - </li> - <li> - <em>toXScale</em> - Ending X size, where 1.0 is no change. - </li> - <li> - <em>fromYScale</em> - Starting Y size, where 1.0 is no change. - </li> - <li> - <em>toYScale</em> - Ending Y size, where 1.0 is no change. - </li> - <li> - <em>pivotX</em> - The X coordinate of the pinned center. - </li> - <li> - <em>pivotY</em> - The Y coordinate of the pinned center. - </li> - </ul> - </dd> - <dt> - <translate> - </dt> - <dd> - A vertical/horizontal motion animation. - Represents a {@link android.view.animation.TranslateAnimation}. -Supports the following attributes in any of the following three formats: values from -100 to 100, ending with "%", indicating a percentage relative to itself; values from -100 to 100, ending in "%p", indicating a percentage relative to its parent; a float with no suffix, indicating an absolute value. - <ul> - <li> - <em>fromXDelta</em> - Starting X location. - </li> - <li> - <em>toXDelta</em> - Ending X location. - </li> - <li> - <em>fromYDelta</em> - Starting Y location. - </li> - <li> - <em>toYDelta</em> - Ending Y location. - </li> - </ul> - </dd> - <dt> - <rotate> - </dt> - <dd> - A rotation animation. Represents a {@link android.view.animation.RotateAnimation}. - Supports the following attributes: - <ul> - <li> - <em>fromDegrees</em> - Starting rotation, in degrees. - </li> - <li> - <em>toDegrees</em> - Ending rotation, in degrees. - </li> - <li> - <em>pivotX</em> - The X coordinate of the center of rotation, in pixels, where (0,0) is the top left corner. - </li> - <li> - <em>pivotY</em> - The Y coordinate of the center of rotation, in pixels, where (0,0) is the top left corner. - </li> - </ul> - </dd> - <dt> - <em><interpolator tag></em> - </dt> - <dd> - You can also use any of the interpolator subclass elements defined in {@link android.R.styleable}. Examples include <CycleInterpolator>, <EaseInInterpolator>, and <EaseOutInterpolator>. These objects define a velocity curve that describes how quickly a visual action takes place on a timeline (fast at first and slow later, slow at first and gradually faster, and so on). - </dd> -</dl> -<p> -In addition to the attributes defined for each element above, the elements -<code><alpha></code>, <code><scale></code>, <code><translate></code>, -<code><rotate></code>, and <code><set></code> all support the following attributes (inherited -from the {@link android.view.animation.Animation} class): -</p> -<dl> - <dt><em>{@link android.R.attr#duration duration}</em></dt> - <dd> - Duration, in milliseconds, for this effect. - </dd> - <dt><em>{@link android.R.attr#startOffset startOffset}</em></dt> - <dd> - Offset start time for this effect, in milliseconds. - </dd> - <dt><em>{@link android.R.attr#fillBefore fillBefore}</em></dt> - <dd> - When set true, the animation transformation is applied before the animation begins. - </dd> - <dt><em>{@link android.R.attr#fillAfter fillAfter}</em></dt> - <dd> - When set true, the animation transformation is applied after the animation ends. - </dd> - <dt><em>{@link android.R.attr#repeatCount repeatCount}</em></dt> - <dd> - Defines the number of times the animation should repeat. - </dd> - <dt><em>{@link android.R.attr#repeatMode repeatMode}</em></dt> - <dd> - Defines the animation behavior when it reaches the end and the repeat count is greater than 0. - Options are to either restart or reverse the animation. - </dd> - <dt><em>{@link android.R.attr#zAdjustment zAdjustment}</em></dt> - <dd> - Defines the z-axis ordering mode to use when running the animation (normal, top, or bottom). - </dd> - <dt><em>{@link android.R.attr#interpolator interpolator}</em></dt> - <dd> - You can optionally set an interpolator for each element to determine how quickly or slowly it performs its effect over time. For example, slow at the beginning and faster at the end for EaseInInterpolator, and the reverse for EaseOutInterpolator. A list of interpolators is given in {@link android.R.anim}. To specify these, use the syntax @android:anim/<em>interpolatorName</em>. - </dd> -</dl> - -<p>For more discussion and animation code samples, see the discussion in the -<a href="{@docRoot}guide/topics/graphics/2d-graphics.html#tween-animation">2D Graphics</a> document.</p> - - - -<h2 id="menus">Menus</h2> -<p>Application menus (Options Menu, Context Menu, or Sub Menu) can be defined as -XML resources and inflated by your application using {@link android.view.MenuInflater}.</p> - -<p><strong>Source file format:</strong> XML file, one resource per file, one root tag, -<code><?xml></code> declaration not required.</p> -<p><strong>Resource file location:</strong> res/menu/<em>some_file</em>.xml</p> -<p><strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.Menu} (or subclass) resource.</p> -<p><strong>Resource reference name:</strong> </p> -<ul><li><strong>Java:</strong> <code>R.menu.<em>some_file</em></code></li></ul> - -<h3>Syntax</h3> -<p>The file must have a single root element: a <code><menu></code> element. In all, -there are three valid elements: <code><menu></code>, <code><group></code> and <code><item></code>. The -<code><item></code> and <code><group></code> elements must be the children of a <code><menu></code>, but <code><item></code> -elements can also be the children of a <code><group></code>, and another <code><menu></code> element may be the child -of an <code><item></code> (to create a Sub Menu).</p> -<pre> -<menu xmlns:android="http://schemas.android.com/apk/res/android"> - - <item android:id="@+id/<em>example_item</em> - android:title="<em>Example Item</em>" - android:icon="<em>@drawable/example_item_icon</em>" /> - - <group android:id="@+id/<em>example_group</em>"> - <item android:id="@+id/<em>example_item2</em> - android:title="<em>Example Item 2</em>" - android:icon="<em>@drawable/example_item2_icon</em>" /> - </group> - - <item android:id="@+id/<em>example_submenu</em> - android:title="<em>Example Sub Menu</em>" > - <menu> - <item android:id="@+id/<em>example_submenu_item</em> - android:title="<em>Example Sub Menu Item</em>" /> - </menu> - </item> - -</menu> -</pre> - -<h3>Elements and Attributes</h3> -<p>All attributes must be defined with the <em>android</em> namespace (e.g., <em>android:icon="@drawable/icon"</em>).</p> -<dl> - <dt><menu></dt> - <dd>The root of a menu. Contains <code><item></code> and <code><group></code> nodes. No attributes.</dd> - <dt><group></dt> - <dd>A menu group. Contains <code><item></code> elements. Valid attributes: - <ul> - <li><em>id</em> - A unique integer ID for the group.</li> - <li><em>menuCategory</em> - Value corresponding to Menu CATEGORY_* constants — defines the priority of the group. Valid values: - <em>container</em>, <em>system</em>, <em>secondary</em>, and <em>alternative</em>.</li> - <li><em>orderInCategory</em> - An integer that defines the default order of the items within the category.</li> - <li><em>checkableBehavior</em> - Whether the items are checkable. Valid values: - <em>none</em>, <em>all</em> (exclusive / radio buttons), <em>single</em> (non-exclusive / checkboxes)</li> - <li><em>visible</em> - Whether the group is visible. <em>true</em> or <em>false</em>.</li> - <li><em>enabled</em> - Whether the group is enabled. <em>true</em> or <em>false</em>.</li> - </ul> - </dd> - <dt><item></dt> - <dd>A menu item. May contain a <code><menu></code> element (for a Sub Menu). Valid attributes: - <ul> - <li><em>id</em> - A unique resource ID for the item.</li> - <li><em>menuCategory</em> - Used to define the menu category.</li> - <li><em>orderInCategory</em> - Used to define the order of the item, within a group.</li> - <li><em>title</em> - A string for the menu title.</li> - <li><em>titleCondensed</em> - A condensed string title, for situations in which the normal title is too long.</li> - <li><em>icon</em> - A resource identifier for a drawable icon.</li> - <li><em>alphabeticShortcut</em> - A character for the alphabetic shortcut key.</li> - <li><em>numericShortcut</em> - A number for the numeric shortcut key.</li> - <li><em>checkable</em> - Whether the item is checkable. <em>true</em> or <em>false</em>.</li> - <li><em>checked</em> - Whether the item is checked by default. <em>true</em> or <em>false</em>.</li> - <li><em>visible</em> - Whether the item is visible by default. <em>true</em> or <em>false</em>.</li> - <li><em>enabled</em> - Whether the item is enabled by default. <em>true</em> or <em>false</em>.</li> - </ul> - </dd> -</dl> - -<p>For more discussion on how to create menus in XML and inflate them in your application, -read <a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a>.</p> - - - -<h2 id="layoutresources">Layout</h2> -<p>Android lets you specify screen layouts using XML elements inside an XML -file, similar to designing screen layout for a webpage in an HTML file. Each -file contains a whole screen or a part of a screen, and is compiled into a -View resource that can be passed in to -{@link android.app.Activity#setContentView(int) Activity.setContentView} or used as a -reference by other layout resource elements. Files are saved in the -<code>res/layout/</code> folder of your project, and compiled by the Android resource -compiler, aapt. </p> - -<p> Every layout XML file must evaluate to a single root -element. First we'll describe how to use the standard XML tags understood by -Android as it is shipped, and then we'll give a little information on how you -can define your own custom XML elements for custom View objects. - -<p> The root element must have -the Android namespace "http://schemas.android.com/apk/res/android" defined in -the root element.</p> - -<p>For a complete discussion on creating layouts, see the -<a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> topic.</p> - -<p> <strong>Source file format:</strong> XML file -requiring a <code><?xml version="1.0" encoding="utf-8"?></code> -declaration, and a root element of one of the supported XML layout elements. -</p> - - -<p><strong>Resource file location</strong>: -res/layout/<em>some_file</em>.xml.</p> -<p> - <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource. -</p> -<p> - <strong>Resource reference name:</strong> -</p> -<ul> - <li> - <strong>Java:</strong> <code>R.layout.<em>some_file</em></code> - </li> - <li> - <strong>XML:</strong> <code>@[<em>package</em>:]layout/<em>some_file</em></code> - </li> -</ul> -<p> - <strong>Syntax</strong> -</p> -<pre> -<<em>ViewGroupClass</em> xmlns:android="http://schemas.android.com/apk/res/android" - id="@+id/<em>string_name</em>" (attributes)> - <<em>widget</em> or other nested <em>ViewGroupClass</em>>+ - <requestFocus/>(0 or 1 per layout file, assigned to any element) -</<em>ViewGroupClass</em>> -</pre> -<dl> - <dt> - <<em>ViewGroupClass</em>> - </dt> - <dd> - <p>The file must have a single root element. This can be a ViewGroup class that contains other elements, or a widget (or custom item) if it's only one object. By default, you can use any (case-sensitive) Android {@link android.widget widget} or {@link android.view.ViewGroup ViewGroup} class name as an element. These elements support attributes that apply to the underlying class, but the naming is not as clear. How to discover what attributes are supported for what tags is discussed below. You should not assume that any nesting is valid (for example you cannot enclose <code><TextView></code> elements inside a <code><ListLayout></code>).</p> - <p>If a class derives from another class, the XML element inherits all the attributes from the element that it "derives" from. So, for example, <code><EditText></code> is the corresponding XML element for the EditText class. It exposes its own unique attributes (<code>EditText_numeric</code>), as well as all attributes supported by <code><TextView></code> and <code><View></code>. For the <em>id</em> attribute of a tag in XML, you should use a special syntax: "@+id/<em>somestringvalue</em>". The "@+" syntax creates a resource number in the R.id class, if one doesn't exist, or uses it, if it does exist. When declaring an ID value for an XML tag, use this syntax. Example: <code><TextView id="@+id/nameTextbox"/></code>, and refer to it this way in Java: <code>findViewById(R.id.nameTextbox)</code>. All elements support the following values:</p> - <ul> - <li> - <em>id</em> - An ID value used to access this element in Java. Typically you will use the syntax @+id/<em>string_name</em> to generate an ID for you in the id.xml file if you haven't created one yourself. - </li> - <li> - <code>xmlns:android="http://schemas.android.com/apk/res/android"</code> - <em><strong>Required for the root element only.</strong></em> - </li> - </ul> - </dd> - <dt> - <requestFocus> - </dt> - <dd> - Any element representing a View object can include this empty element, which gives it's parent tag initial focus on the screen. You can have only one of these elements per file. - </dd> -</dl> -<p> - <strong>What Attributes Are Supported for What Elements?</strong> -</p> -<p> - Android uses the {@link android.view.LayoutInflater} class at run time to load an XML layout resource and translate it into visual elements. By default, all widget class names are supported directly as tags, but a full list of supported tags and attributes is listed in the {@link android.R.styleable} reference page. However, the attribute names are somewhat obscure. If an underscore appears in the name, this indicates that it is an attribute — typically of the element before the underscore. So, for example, <code>EditText_autoText</code> means that the <code><EditText></code> tag supports an attribute <em>autoText</em>. When you actually use the attribute in that element, use only the portion after the last underscore, and prefix the attribute with the prefix "<code>android:</code>". So, for example, if {@link android.R.styleable} lists the following values: -</p> -<ul> - <li> - <code>TextView</code> - </li> - <li> - <code>TextView_lines</code> - </li> - <li> - <code>TextView_maxlines</code> - </li> -</ul> -<p> - You could create an element like this: -</p> -<pre> -<TextView android:lines="10" android:maxlines="20"/> -</pre> -<p> - This would create a {@link android.widget.TextView} object and set its lines and maxlines properties. -</p> -<p> - Attributes come from three sources: -</p> -<ul> - <li> - <strong>Attributes exposed directly by the element.</strong> For example, <code>TextView</code> supports <code>TextView_text</code>, as discussed above. - </li> - <li> - <strong>Attributes exposed by all the superclasses of that element.</strong> For example, the TextView class extends the View class, so the <code><TextView></code> element supports all the attributes that the <code><View></code> element exposes — a long list, including <code>View_paddingBottom</code> and <code>View_scrollbars</code>. These too are used without the class name: <code><TextView android:paddingBottom="20" android:scrollbars="horizontal" /></code>. - </li> - <li> - <strong>Attributes of the object's {@link android.view.ViewGroup.LayoutParams} subclass.</strong> All View objects support a LayoutParams member (see <a href="{@docRoot}guide/topics/ui/declaring-layout.html#layout-params">Declaring Layout</a>). To set properties on an element's LayoutParams member, the attribute to use is "android:layout_<em>layoutParamsProperty</em>". For example: <code>android:layout_gravity</code> for an object wrapped by a <code><LinearLayout></code> element. Remember that each LayoutParams subclass also supports inherited attributes. Attributes exposed by each subclass are given in the format <em>someLayoutParamsSubclass</em>_Layout_layout_<em>someproperty</em>. This defines an attribute "android:layout_<em>someproperty</em>". Here is an example of how Android documentation lists the properties of the {@link android.widget.LinearLayout.LayoutParams LinearLayout.LayoutParams} class: - </li> -</ul> -<ul> - <li>LinearLayout_Layout // The actual object — not used. - </li> - <li>LinearLayout_Layout_layout_gravity // Exposes a <code>gravity</code> attribute - </li> - <li>LinearLayout_Layout_layout_height // Exposes a <code>height</code> attribute - </li> - <li>LinearLayout_Layout_layout_weight // Exposes a <code>weight</code> attribute - </li> - <li>LinearLayout_Layout_layout_width // Exposes a <code>width</code> attribute - </li> -</ul> -<p> - Here is an example that sets some of these values on a few objects, including direct attributes, inherited attributes, and LayoutParams attributes: -</p> -<pre> -<?xml version="1.0" encoding="utf-8"?> -<!-- res/main_screen.xml --> -<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:orientation="vertical" // The object's own orientation property - android:padding="4" // Inherited View property - android:gravity="center" // The object's own property - android:layout_width="fill_parent" // Parent object's LinearLayout.LayoutParams.width - android:layout_height="fill_parent"> // Parent object's LinearLayout.LayoutParams.height - - <TextView android:layout_width="fill_parent" // TextView.LayoutParams.width - android:layout_height="wrap_content" // TextView.LayoutParams.height - android:layout_weight="0" // TextView.LayoutParams.weight - android:paddingBottom="4" // TextView.paddingBottom - android:text="@string/redirect_getter"/> // TextView.text - - <EditText id="@+id/text" - android:layout_width="fill_parent" // EditText.LayoutParams.width - android:layout_height="wrap_content" // EditText.LayoutParams.height - android:layout_weight="0" // EditText.LinearLayoutParams.weight - android:paddingBottom="4"> // EditText.paddingBottom - <requestFocus /> - </EditText> - - <Button id="@+id/apply" - android:layout_width="wrap_content" // Button.LayoutParams.width - android:layout_height="wrap_content" // Button.LayoutParams.height - android:text="@string/apply" /> // TextView.text -</LinearLayout> -</pre> -<p> - <strong>Example Code Use</strong> -</p> -<p> - The most common use is to load the XML file (located at <em>res/main_screen.xml</em>) and use it as the current screen, as shown here with the preceding file: -</p> -<pre> -setContentView(R.layout.main_screen); -</pre> -<p> - However, layout elements can also represent repeating elements used as templates. -</p> - -<p>Also see <a href="{@docRoot}guide/topics/ui/index.html">User Interface</a> for more information on layouts.</p> - - - -<h3 id="customresources">Custom Layout Resources</h3> -<p> - You can define custom elements to use in layout resources. These custom elements can then be used the same as any Android layout elements: that is, you can use them and specify their attributes in other resources. The ApiDemos sample application has an example of creating a custom layout XML tag, LabelView. To create a custom element, you will need the following files: -</p> -<ul> - <li> - <strong>Java implementation file</strong> - The implementation file. The class must extend {@link android.view.View View} or a subclass. See LabelView.java in ApiDemos. - </li> - <li> - <strong>res/values/attrs.xml</strong> - Defines the XML element, and the attributes that it supports, for clients to use to instantiate your object in their layout XML file. Define your element in a <code><declare-styleable id=<em>your_java_class_name</em>></code>. See res/layout/attrs.xml in ApiDemos. - </li> - <li> - <strong>res/layout/<em>your_class</em>.xml</strong> [<em>optional</em>] - An optional XML file to describe the layout of your object. This could also be done in Java. See custom_view_1.xml in ApiDemos. - </li> -</ul> -<p> - <strong>Source file format:</strong> XML file without an <code><?xml></code> declaration, and a <code><resources></code> root element containing one or more custom element tags. -</p> -<p> - <strong>Resource file location</strong>: res/values/<em>attrs</em>.xml (file name is arbitrary). -</p> -<p> - <strong>Compiled resource datatype:</strong> Resource pointer to a {@link android.view.View} (or subclass) resource. -</p> -<p> - <strong>Resource reference name:</strong> R.styleable.<em>some_file</em> (Java). -</p> - - - -<h2 id="stylesandthemes">Styles and Themes</h2> -<p> - A <em>style</em> is one or more attributes applied to a single element (for example, 10 point red Arial font, applied to a TextView). A style is applied as an attribute to an element in a layout XML file. -</p> -<p> - A <em>theme</em> is one or more attributes applied to a whole screen — for example, you might apply the stock Android Theme.dialog theme to an activity designed to be a floating dialog box. A theme is assigned as an attribute to an Activity in the manifest file. -</p> -<p> - Both styles and themes are defined in a <code><style></code> block containing one or more string or numerical values (typically color values), or references to other resources (drawables and so on). These elements support inheritance, so you could have MyBaseTheme, MyBaseTheme.Fancy, MyBaseTheme.Small, and so on. -</p> - -<p>For a complete discussion on styles and themes, read -<a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p> - -<p> - <strong>Source file format:</strong> XML file requiring a <code><?xml version="1.0" encoding="utf-8"?></code> declaration, and a root <code><resources></code> element containing one or more <code><style></code> tags. -</p> -<p> - <strong>Resource source file location</strong>: res/values/styles.xml (file name is arbitrary). The file name is arbitrary, but standard practice is to put all styles into a file named styles.xml. -</p> -<p> - <strong>Compiled resource datatype:</strong> Resource pointer to a Java CharSequence. -</p> -<p> - <strong>Resource reference name:</strong> -</p> -<ul> - <li> - <strong>Java:</strong> <code>R.style.<em>styleID</em></code> for the whole style, <code>R.style.<em>styleID</em>.<em>itemID</em></code> for an individual setting - </li> - <li> - <strong>XML:</strong> <code>@[<em>package</em>:]style/<em>styleID</em></code> for a whole style, <code>@[<em>package</em>:]style/<em>styleID</em>/<em>itemID</em></code> for an individual item. <strong>Note</strong>: to refer to a value in the <em>currently</em> applied theme, use "?" instead of "@" as described below (XML). - </li> -</ul> -<p> - <strong>Syntax</strong> -</p> -<pre> -<style name=<em>string</em> [parent=<em>string</em>] > - <item name=<em>string</em>><em>Hex value | string value | reference</em></item>+<em> -</em></style> -</pre> -<dl> - <dt> - <style> - </dt> - <dd> - Holds one or more <item> elements, each describing one value. This style, which is a bundle of values, can be referred to as a <em>theme</em>. - <ul> - <li> - <em>name</em> - The name used in referring to this theme. - </li> - <li> - <em>parent</em> - An optional parent theme. All values from the specified theme will be inherited into this theme. Any values with identical names that you specify will override inherited values. The name must be qualified by the package, but you don't need the /style directive (for example, <code>android:Theme</code> for the base Android theme, or <code>MyTheme</code> for a theme defined in your package). - </li> - </ul> - </dd> - <dt> - <item> - </dt> - <dd> - A value to use in this theme. It can be a standard string, a hex color value, or a reference to any other resource type. - </dd> -</dl> - -<p>For examples of how to declare and apply styles and themes, read -<a href="{@docRoot}guide/topics/ui/themes.html">Applying Styles and Themes</a>.</p> diff --git a/docs/html/guide/topics/resources/index.jd b/docs/html/guide/topics/resources/index.jd deleted file mode 100644 index 7e3bce42..0000000 --- a/docs/html/guide/topics/resources/index.jd +++ /dev/null @@ -1,40 +0,0 @@ -page.title=Resources and Assets -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Key classes</h2> - <ol> - <li>{@link android.content.res.Resources}</li> - <li>{@link android.content.res.AssetManager}</li> - </ol> - -</div> -</div> - -<p>Resources are an integral part of an Android application. -In general, these are external elements that you want to include and reference within your application, -like images, audio, video, text strings, layouts, themes, etc. Every Android application contains -a directory for resources (<code>res/</code>) and a directory for assets (<code>assets/</code>). -Assets are used less often, because their applications are far fewer. You only need to save data -as an asset when you need to read the raw bites. -The directories for resources and assets both reside at the top of your project directory, alongside your source code directory -(<code>src/</code>).</p> - -<p>The difference between "resources" and "assets" isn't much on the surface, but in general, -you'll use resources to store your external content much more often than you'll use assets. -The real difference is that anything -placed in the resources directory will be easily accessible from your application from the -<code>R</code> class, which is compiled by Android. Whereas, anything placed in the assets -directory will maintain its raw file format and, in order to read it, you must use the -{@link android.content.res.AssetManager} to read the file as a stream of bytes. So keeping -files and data in resources (<code>res/</code>) makes them easily accessible.</p> - -<p>Within the documents of this topic, you'll find information on the kinds of standard resources -that are typically used in an Android application and how to reference them from you code. -<a href="{@docRoot}guide/topics/resources/resources-i18n.html">Resources and Internationalization</a> -is where you should start, to learn more about how Android utilizes project resources. Then, the -<a href="{@docRoot}guide/topics/resources/available-resources.html">Available Resource Types</a> -document offers a summary of various resource types and a reference to their specifications. -</p> diff --git a/docs/html/guide/topics/resources/resources-i18n.jd b/docs/html/guide/topics/resources/resources-i18n.jd deleted file mode 100644 index b1da4cd..0000000 --- a/docs/html/guide/topics/resources/resources-i18n.jd +++ /dev/null @@ -1,704 +0,0 @@ -page.title=Resources and Internationalization -parent.title=Resources and Assets -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Key classes</h2> - <ol> - <li>{@link android.content.res.Resources}</li> - </ol> - - <h2>In this document</h2> - <ol> - <li><a href="#intro">Introduction</a></li> - <li><a href="#CreatingResources">Creating Resources</a></li> - <li><a href="#UsingResources">Using Resources</a> - <ol> - <li><a href="#ResourcesInCode">Using Resources in Code</a></li> - <li><a href="#ReferencesToResources">References to Resources</a></li> - <li><a href="#ReferencesToThemeAttributes">References to Theme Attributes</a></li> - <li><a href="#UsingSystemResources">Using System Resources</a></li> - </ol> - </li> - <li><a href="#AlternateResources">Alternate Resources</a></li> - <li><a href="#ResourcesTerminology">Terminology</a></li> - <li><a href="#i18n">Internationalization (I18N)</a></li> - </ol> -</div> -</div> - -<p>Resources are external files (that is, non-code files) that are used by -your code and compiled into your application at build time. Android -supports a number of different kinds of resource files, including XML, -PNG, and JPEG files. The XML files have very different formats depending -on what they describe. This document describes what kinds of files are -supported, and the syntax or format of each.</p> -<p>Resources are externalized from source code, and XML files are compiled into -a binary, fast loading format for efficiency reasons. Strings, likewise are compressed -into a more efficient storage form. It is for these reasons that we have these -different resource types in the Android platform.</p> - -<p>This is a fairly technically dense document, and together with the -<a href="available-resources.html">Available Resources</a> -document, they cover a lot of information about resources. It is not necessary -to know this document by heart to use Android, but rather to know that the -information is here when you need it.</p> - -<a name="intro"></a> -<h2>Introduction</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 to the supported - Android resource types, see - <a href="available-resources.html">Available Resources</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, 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="CreatingResources" id="CreatingResources"></a> -<h2>Creating Resources</h2> - -<p>Android supports string, bitmap, and many other types of resource. The syntax and format -of each, and where they're stored, depends upon the type of object. In -general, though, you create resources from three types of files: XML files -(everything but bitmaps and raw), bitmap files(for images) and Raw files (anything -else, for example sound files, etc.). In fact, there are two different types of -XML file as well, those that get compiled as-is into the package, and those that -are used to generate resources by aapt. Here is a list of each -resource type, the format of the file, a description of the file, and details -of any XML files. </p> - -<p>You will create and store your resource files under the appropriate -subdirectory under the <code>res/</code> directory in your project. Android -has a resource compiler (aapt) that compiles resources according to which -subfolder they are in, and the format of the file. Here is a list of the file -types for each resource. See the -<a href="available-resources.html">Available Resources</a> for -descriptions of each type of object, the syntax, and the format or syntax of -the containing file.</p> - -<table width="100%" border="1"> - <tr> - <th scope="col">Directory</th> - <th scope="col">Resource Types </th> - </tr> - <tr> - <td><code>res/anim/</code></td> - <td>XML files that are compiled into - <a href="available-resources.html#animationdrawable">frame by - frame animation</a> or - <a href="available-resources.html#tweenedanimation">tweened - animation</a> objects </td> - </tr> - <tr> - <td><code>res/drawable/</code></td> - <td><p>.png, .9.png, .jpg files that are compiled into the following - Drawable resource subtypes:</p> - <p>To get a resource of this type, use <code>Resource.getDrawable(<em>id</em>)</code> - <ul> - <li><a href="available-resources.html#imagefileresources">bitmap files</a></li> - <li><a href="available-resources.html#ninepatch">9-patches (resizable bitmaps)</a></li> - </ul></td> - </tr> - <tr> - <td><code>res/layout/</code></td> - <td>XML files that are compiled into screen layouts (or part of a screen). - See <a href="{@docRoot}guide/topics/ui/declaring-layout.html">Declaring Layout</a></td> - </tr> - <tr> - <td><code>res/values/</code></td> - <td><p>XML files that can be compiled into many kinds of resource.</p> - <p class="note"><strong>Note:</strong> unlike the other res/ folders, this one - can hold any number of files that hold descriptions of resources to create - rather than the resources themselves. The XML element types control - where these resources are placed under the R class.</p> - <p>While the files can be named anything, these are - the typical files in this folder (the convention is to name - the file after the type of elements defined within):</p> - <ul> - <li><strong>arrays.xml</strong> to define arrays </li> - <!-- TODO: add section on arrays --> - <li><strong>colors.xml</strong> to define <a href="available-resources.html#colordrawableresources">color - drawables</a> and <a href="#colorvals">color string values</a>. - Use <code>Resources.getDrawable()</code> and - <code>Resources.getColor(), respectively,</code> - to get these resources.</li> - <li><strong>dimens.xml</strong> to define <a href="available-resources.html#dimension">dimension value</a>. Use <code>Resources.getDimension()</code> to get - these resources.</li> - <li><strong>strings.xml</strong> to define <a href="available-resources.html#stringresources">string</a> values (use either - <code>Resources.getString</code> or preferably <code>Resources.getText()</code> - to get - these resources. <code>getText()</code> will retain any rich text styling - which is usually desirable for UI strings.</li> - <li><strong>styles.xml</strong> to define <a href="available-resources.html#stylesandthemes">style</a> objects.</li> - </ul></td> - </tr> - <tr> - <td><code>res/xml/</code></td> - <td>Arbitrary XML files that are compiled and can be read at run time by - calling {@link android.content.res.Resources#getXml(int) Resources.getXML()}.</td> - </tr> - <tr> - <td><code>res/raw/</code></td> - <td>Arbitrary files to copy directly to the device. They are added uncompiled - to the compressed file that your application build produces. To use these - resources in your application, call {@link android.content.res.Resources#openRawResource(int) - Resources.openRawResource()} with the resource ID, which is R.raw.<em>somefilename</em>.</td> - </tr> -</table> -<p>Resources are compiled into the final APK file. Android creates a wrapper class, - called R, that you can use to refer to these resources in your code. R contains subclasses - named according to the path and file name of the source file</p> -<a name="colorvals" id="colorvals"></a> -<h3>Global Resource Notes</h3> -<ul> - <li>Several resources allow you to define colors. Android accepts color values - written in various web-style formats -- a hexadecimal constant in any of the - following forms: #RGB, #ARGB, #RRGGBB, #AARRGGBB. </li> - <li>All color values support setting an alpha channel value, where the first - two hexadecimal numbers specify the transparency. Zero in the alpha channel - means transparent. The default value is opaque. </li> -</ul> -<a name="UsingResources" id="UsingResources"></a> -<h2>Using Resources </h2> -<p>This section describes how to use the resources you've created. It includes the - following topics:</p> -<ul> - <li><a href="#ResourcesInCode">Using resources in code</a> - How to call - resources in your code to instantiate them. </li> - <li><a href="#ReferencesToResources">Referring to resources from other resources</a> - - You can reference resources from other resources. This lets you reuse common - resource values inside resources. </li> - <li><a href="#AlternateResources">Supporting Alternate Resources for Alternate - Configurations</a> - You can specify different resources - to load, depending on the language or display configuration of the host - hardware. </li> -</ul> -<p>At compile time, Android generates a class named R that contains resource identifiers - to all the resources in your program. This class contains several subclasses, - one for each type of resource supported by Android, and for which you provided - a resource file. Each class contains one or more identifiers for the compiled resources, - that you use in your code to load the resource. Here is a small resource file - that contains string, layout (screens or parts of screens), and image resources.</p> -<p class="note"><strong>Note:</strong> the R class is an auto-generated file and is not -designed to be edited by hand. It will be automatically re-created as needed when -the resources are updated.</p> -<pre class="prettyprint">package com.android.samples; -public final class R { - public static final class string { - public static final int greeting=0x0204000e; - public static final int start_button_text=0x02040001; - public static final int submit_button_text=0x02040008; - public static final int main_screen_title=0x0204000a; - }; - public static final class layout { - public static final int start_screen=0x02070000; - public static final int new_user_pane=0x02070001; - public static final int select_user_list=0x02070002; - - }; - public static final class drawable { - public static final int company_logo=0x02020005; - public static final int smiling_cat=0x02020006; - public static final int yellow_fade_background=0x02020007; - public static final int stretch_button_1=0x02020008; - - }; -}; -</pre> -<a name="ResourcesInCode" id="ResourcesInCode"></a> -<h3>Using Resources in Code </h3> - -<p>Using resources in code is just a matter of knowing the full resource ID -and what type of object your resource has been compiled into. Here is the -syntax for referring to a resource:</p> -<p><code>R.<em>resource_type</em>.<em>resource_name</em></code></p> -<p>or</p> -<p><code>android.R.<em>resource_type</em>.<em>resource_name</em></code></p> - -<p>Where <code>resource_type</code> is the R subclass that holds a specific type -of resource. <code>resource_name</code> is the <em>name</em> attribute for resources -defined in XML files, or the file name (without the extension) for resources -defined by other file types. Each type of resource will be added to a specific -R subclass, depending on the type of resource it is; to learn which R subclass -hosts your compiled resource type, consult the -<a href="available-resources.html">Available Resources</a> document. Resources compiled by your own application can -be referred to without a package name (simply as -<code>R.<em>resource_type</em>.<em>resource_name</em></code>). Android contains -a number of standard resources, such as screen styles and button backgrounds. To -refer to these in code, you must qualify them with <code>android</code>, as in -<code>android.R.drawable.button_background</code>.</p> - -<p>Here are some good and bad examples of using compiled resources in code:</p> - -<pre class="prettyprint">// Load a background for the current screen from a drawable resource. -this.getWindow().setBackgroundDrawableResource(R.drawable.my_background_image); - -// WRONG Sending a string resource reference into a -// method that expects a string. -this.getWindow().setTitle(R.string.main_title); - -// RIGHT Need to get the title from the Resources wrapper. -this.getWindow().setTitle(Resources.getText(R.string.main_title)); - -// Load a custom layout for the current screen. -setContentView(R.layout.main_screen); - -// Set a slide in animation for a ViewFlipper object. -mFlipper.setInAnimation(AnimationUtils.loadAnimation(this, - R.anim.hyperspace_in)); - -// Set the text on a TextView object. -TextView msgTextView = (TextView)findViewByID(R.id.msg); -msgTextView.setText(R.string.hello_message); </pre> - -<a name="ReferencesToResources" id="ReferencesToResources"></a> -<h3>References to Resources</h3> - -<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 any resource type including colors and integers.</p> - -<p>For example, if we have -<a href="available-resources.html#colordrawableresources">color -resources</a>, 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"?> -<EditText id="text" - xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" android:layout_height="fill_parent" - <strong>android:textColor="@color/opaque_red"</strong> - android:text="Hello, World!" /> -</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"?> -<EditText id="text" - xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" android:layout_height="fill_parent" - android:textColor="@<strong>android:</strong>color/opaque_red" - android:text="Hello, World!" /> -</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"?> -<EditText id="text" - xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" android:layout_height="fill_parent" - android:textColor="@android:color/opaque_red" - android:text="@string/hello_world" /> -</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> -<h3>References to Theme Attributes</h3> - -<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"?> -<EditText id="text" - xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" android:layout_height="fill_parent" - <strong>android:textColor="?android:textDisabledColor"</strong> - android:text="@string/hello_world" /> -</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>?[namespace:]type/name</code> with the type here being optional.</p> - -<a name="UsingSystemResources"></a> -<h3>Using System Resources</h3> - -<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="AlternateResources" id="AlternateResources"></a> -<h2>Alternate Resources (for alternate languages and configurations)</h2> - -<p>You can supply different resources for your product according to the UI -language or hardware configuration on the device. Note that although you can -include different string, layout, and other resources, the SDK does not expose -methods to let you specify which alternate resource set to load. Android -detects the proper set for the hardware and location, and loads them as -appropriate. Users can select alternate language settings using the settings -panel on the device. </p> -<p>To include alternate resources, create parallel resource folders with -qualifiers appended to the folder names, indicating the configuration it -applies to (language, screen orientation, and so on). For example, here is a -project that holds one string resource file for English, and another for -French:</p> - -<pre> -MyApp/ - res/ - values-en/ - strings.xml - values-fr/ - strings.xml -</pre> - -<p>Android supports several types of qualifiers, with various values for each. -Append these to the end of the resource folder name, separated by dashes. You -can add multiple qualifiers to each folder name, but they must appear in the -order they are listed here. For example, a folder containing drawable -resources for a fully specified configuration would look like:</p> - -<pre> -MyApp/ - res/ - drawable-en-rUS-port-160dpi-finger-keysexposed-qwerty-dpad-480x320/ -</pre> - -<p>More typically, you will only specify a few specific configuration options -that a resource is defined for. You may drop any of the values from the -complete list, as long as the remaining values are still in the same -order:</p> - -<pre> -MyApp/ - res/ - drawable-en-rUS-finger/ - drawable-port/ - drawable-port-160dpi/ - drawable-qwerty/ -</pre> - -<table border="1"> - <tr> - <th> Qualifier </th> - <th> Values </th> - </tr> - <tr> - <td>Language</td> - <td>The two letter <a href="http://www.loc.gov/standards/iso639-2/php/code_list.php">ISO - 639-1</a> language code in lowercase. For example: - <code>en</code>, <code>fr</code>, <code>es</code> </td> - </tr> - <tr> - <td>Region</td> - <td>The two letter - <a href="http://www.iso.org/iso/en/prods-services/iso3166ma/02iso-3166-code-lists/list-en1.html">ISO - 3166-1-alpha-2</a> language code in uppercase preceded by a lowercase - "r". For example: <code>rUS</code>, <code>rFR</code>, <code>rES</code></td> - </tr> - <tr> - <td>Screen orientation</td> - <td><code>port</code>, <code>land</code>, <code>square</code> </td> - </tr> - <tr> - <td>Screen pixel density</td> - <td><code>92dpi</code>, <code>108dpi</code>, etc. </td> - </tr> - <tr> - <td>Touchscreen type</td> - <td><code>notouch</code>, <code>stylus</code>, <code>finger</code></td> - </tr> - <tr> - <td>Whether the keyboard is available to the user</td> - <td><code>keysexposed</code>, <code>keyshidden</code> </td> - </tr> - <tr> - <td>Primary text input method</td> - <td><code>nokeys</code>, <code>qwerty</code>, <code>12key</code> </td> - </tr> - <tr> - <td>Primary non-touchscreen<br /> - navigation method</td> - <td><code>nonav</code>, <code>dpad</code>, <code>trackball</code>, <code>wheel</code> </td> - </tr> - <tr> - <td>Screen dimensions</td> - <td><code>320x240</code>, <code>640x480</code>, etc. The larger dimension - must be specified first. </td> - </tr> -</table> - -<p>This list does not include device-specific parameters such as carrier, -branding, device/hardware, or manufacturer. Everything that an application -needs to know about the device that it is running on is encoded via the -resource qualifiers in the table above.</p> - -<p>Here are some general guidelines on qualified resource directory names:</p> - -<ul> - <li>Values are separated by a dash (as well as a dash after the base directory - name) </li> - <li>Values are case-sensitive (even though they must be unique across all folder - names in a case-insensitive way)<br />For example,</li> - <ul> - <li>A portrait-specific <code>drawable</code> directory must be named - <code>drawable-port</code>, not <code>drawable-PORT</code>.</li> - <li>You may not have two directories named <code>drawable-port</code> - and <code>drawable-PORT</code>, even if you had intended "port" and - "PORT" to refer to different parameter values.</li> - </ul> - <li>Only one value for each qualifier type is supported (that is, you cannot - specify <code>drawable-rEN-rFR/</code>)</li> - <li>You can specify multiple parameters to define specific configurations, - but they must always be in the order listed above. - For example, <code>drawable-en-rUS-land</code> will apply to landscape view, - US-English devices. </li> - <li>Android will try to find the most specific matching directory for the current - configuration, as described below</li> - <li>The order of parameters listed in this table is used to break a tie in case - of multiple qualified directories (see the example given below) </li> - <li>All directories, both qualified and unqualified, live under the <code>res/</code> folder. - Qualified directories cannot be nested (you cannot have <code>res/drawable/drawable-en</code>) </li> - <li>All resources will be referenced in code or resource reference syntax by - their simple, undecorated name. So if a resource is named this:<br /> - <code>MyApp/res/drawable-port-92dp/myimage.png</code><br /> - It would be referenced as this:<br /> - <code>R.drawable.myimage</code> (code)<br /> - <code>@drawable/myimage</code> (XML)</li> -</ul> - -<h3>How Android finds the best matching directory </h3> - -<p>Android will pick which of the various underlying resource files should be -used at runtime, depending on the current configuration. The selection process -is as follows:</p> - -<ol> - <li> - Eliminate any resources whose configuration does not match the current - device configuration. For example, if the screen pixel density is 108dpi, - this would eliminate only <code>MyApp/res/drawable-port-92dpi/</code>. - <blockquote> - <pre> -MyApp/res/drawable/myimage.png -MyApp/res/drawable-en/myimage.png -MyApp/res/drawable-port/myimage.png -<strike>MyApp/res/drawable-port-92dpi/myimage.png</strike> -</pre> - </blockquote> - </li> - <li> - Pick the resources with the highest number of matching configurations. - For example, if our locale is en-GB and orientation is port, then we - have two candidates with one matching configuration each: - <code>MyApp/res/drawable-en/</code> and <code>MyApp/res/drawable-port/</code>. - The directory <code>MyApp/res/drawable/</code> is eliminated because - it has zero matching configurations, while the others have one matching - configuration. - <blockquote> - <pre> -<strike>MyApp/res/drawable/myimage.png</strike> -MyApp/res/drawable-en/myimage.png -MyApp/res/drawable-port/myimage.png -</pre> - </blockquote> - </li> - <li> - Pick the final matching file based on configuration precedence, which - is the order of parameters listed in the table above. That is, it is - more important to match the language than the orientation, so we break - the tie by picking the language-specific file, <code>MyApp/res/drawable-en/</code>. - <blockquote> - <pre>MyApp/res/drawable-en/myimage.png -<strike>MyApp/res/drawable-port/myimage.png</strike> -</pre> - </blockquote> - </li> -</ol> - -<a name="ResourcesTerminology"></a> -<h2>Terminology</h2> - -<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><strong>Asset</strong>: A single blob of data associated with an application. This -includes object files compiled from the Java source code, 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><strong>aapt</strong>: Android Asset Packaging Tool. 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><strong>Resource Table</strong>: 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><strong>Resource</strong>: An entry in the Resource Table describing a single -named value. Broadly, there are two types of resources: primitives and -bags.</p> - -<p><strong>Resource Identifier</strong>: In the Resource Table all resources are -identified by a unique integer number. In source code (resource descriptions, -XML files, Java source code) you can use symbolic names that stand as constants for -the actual resource identifier integer.</p> - -<p><strong>Primitive Resource</strong>: 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><strong>Bag Resource</strong>: 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><strong>Kind</strong>: 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><strong>Style</strong>: 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><strong>Style Class</strong>: Specifies a related set of attribute resources. -This data is not placed in the resource table itself, but used to generate -constants in the source code 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><strong>Configuration</strong>: 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><strong>Theme</strong>: A standard style resource that supplies global -attribute values for a particular context. For example, when writing an -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><strong>Overlay</strong>: 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> - -<h2>Resource Reference</h2> -<p>The <a href="available-resources.html">Available Resources</a> -document provides a detailed list of the various types of resource and how to use them -from within the Java source code, or from other references.</p> - -<a name="i18n" id="i18n"></a> -<h2>Internationalization and Localization</h2> -<p class="note"><strong>Coming Soon:</strong> Internationalization and Localization are -critical, but are also not quite ready yet in the current SDK. As the -SDK matures, this section will contain information on the Internationalization -and Localization features of the Android platform. In the meantime, it is a good -idea to start by externalizing all strings, and practicing good structure in -creating and using resources.</p> - diff --git a/docs/html/guide/topics/security/security.jd b/docs/html/guide/topics/security/security.jd deleted file mode 100644 index da201c4..0000000 --- a/docs/html/guide/topics/security/security.jd +++ /dev/null @@ -1,397 +0,0 @@ -page.title=Security and Permissions -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>In this document</h2> -<ol> -<li><a href="#arch">Security Architecture</a></li> -<li><a href="#signing">Application Signing</a></li> -<li><a href="#userid">User IDs and File Access</a></li> -<li><a href="#permissions">Using Permissions</a></li> -<li><a href="#declaring">Declaring and Enforcing Permissions</a> - <ol> - <li><a href="#manifest">...in AndroidManifest.xml</a></li> - <li><a href="#broadcasts">...when Sending Broadcasts</a></li> - <li><a href="#enforcement">Other Permission Enforcement</a></li> - </ol></li> -<li><a href="#uri">URI Permissions</a></li> -</ol> -</div> -</div> - -<p>Android is a multi-process system, in which each application (and parts of the -system) runs in its own process. Most security between applications and -the system is enforced at the process level through standard Linux facilities, -such as user and group IDs that are assigned to applications. -Additional finer-grained security features are provided -through a "permission" mechanism that enforces restrictions on the specific -operations that a particular process can perform, and per-URI permissions -for granting ad-hoc access to specific pieces of data.</p> - -<a name="arch"></a> -<h2>Security Architecture</h2> - -<p>A central design point of the Android security architecture is that no -application, by default, has permission to perform any operations that would -adversely impact other applications, the operating system, or the user. This -includes reading or writing the user's private data (such as contacts or -e-mails), reading or writing another application's files, performing -network access, keeping the device awake, etc.<p> - -<p>An application's process is a secure sandbox. It can't disrupt other -applications, except by explicitly declaring the <em>permissions</em> it needs -for additional capabilities not provided by the basic sandbox. These -permissions it requests can be handled by the operating in various ways, -typically by automatically allowing or disallowing based on certificates or -by prompting the user. The permissions required by an application are declared -statically in that application, so they can be known up-front at install time -and will not change after that.</p> - - -<a name="signing"></a> -<h2>Application Signing</h2> - -<p>All Android applications (.apk files) must be signed with a certificate whose -private key is held by their developer. This certificate identifies the author -of the application. The certificate does <em>not</em> need to be signed by -a certificate authority: it is perfectly allowable, and typical, for Android -applications to use self-signed certificates. The certificate is used only -to establish trust relationships between applications, not for wholesale -control over whether an application can be installed. The most significant -ways that signatures impact security is by determining who can access -signature-based permissions and who can share user IDs.</p> - - -<a name="userid"></a> -<h2>User IDs and File Access</h2> - -<p>Each Android package (.apk) file installed on the device is given its -own unique Linux user ID, creating a sandbox for it and preventing it from touching -other applications (or other applications from touching it). This user ID is -assigned to it when the application is installed on the device, and -remains constant for the duration of its life on that device.</p> - -<p>Because security enforcement happens at the -process level, the code of any two packages can not normally -run in the same process, since they need to run as different Linux users. -You can use the {@link android.R.attr#sharedUserId} attribute in the -<code>AndroidManifest.xml</code>'s -{@link android.R.styleable#AndroidManifest manifest} tag of each package to -have them assigned the same user ID. By doing this, for purposes of security -the two packages are then treated as being the same application, with the same -user ID and file permissions. Note that in order to retain security, only two applications -signed with the same signature (and requesting the same sharedUserId) will -be given the same user ID.</p> - -<p>Any data stored by an application will be assigned that application's user -ID, and not normally accessible to other packages. When creating a new file -with {@link android.content.Context#getSharedPreferences}, -{@link android.content.Context#openFileOutput}, or -{@link android.content.Context#openOrCreateDatabase}, -you can use the -{@link android.content.Context#MODE_WORLD_READABLE} and/or -{@link android.content.Context#MODE_WORLD_WRITEABLE} flags to allow any other -package to read/write the file. When setting these flags, the file is still -owned by your application, but its global read and/or write permissions have -been set appropriately so any other application can see it.</p> - - -<a name="permissions"></a> -<h2>Using Permissions</h2> - -<p>A basic Android application has no permissions associated with it, -meaning it can not do anything that would adversely impact the user experience -or any data on the device. To make use of protected features of the device, -you must include in your <code>AndroidManifest.xml</code> one or more -<code>{@link android.R.styleable#AndroidManifestUsesPermission <uses-permission>}</code> -tags declaring the permissions that your application needs.</p> - -<p>For example, an application that needs to monitor incoming SMS messages would -specify:</p> - -<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.android.app.myapp" > - - <uses-permission android:name="android.permission.RECEIVE_SMS" /> - -</manifest></pre> - -<p>At application install time, permissions requested by the application are -granted to it by the package installer, based on checks against the -signatures of the applications declaring those permissions and/or interaction -with the user. <em>No</em> checks with the user -are done while an application is running: it either was granted a particular -permission when installed, and can use that feature as desired, or the -permission was not granted and any attempt to use the feature will fail -without prompting the user.</p> - -<p>Often times a permission failure will result in a {@link -java.lang.SecurityException} being thrown back to the application. However, -this is not guaranteed to occur everywhere. For example, the {@link -android.content.Context#sendBroadcast} method checks permissions as data is -being delivered to each receiver, after the method call has returned, so you -will not receive an exception if there are permission failures. In almost all -cases, however, a permission failure will be printed to the system log.</p> - -<p>The permissions provided by the Android system can be found at {@link -android.Manifest.permission}. Any application may also define and enforce its -own permissions, so this is not a comprehensive list of all possible -permissions.</p> - -<p>A particular permission may be enforced at a number of places during your -program's operation:</p> - -<ul> -<li>At the time of a call into the system, to prevent an application from -executing certain functions.</li> -<li>When starting an activity, to prevent applications from launching -activities of other applications.</li> -<li>Both sending and receiving broadcasts, to control who can receive -your broadcast or who can send a broadcast to you.</li> -<li>When accessing and operating on a content provider.</li> -<li>Binding or starting a service.</li> -</ul> - - -<a name="declaring"></a> -<h2>Declaring and Enforcing Permissions</h2> - -<p>To enforce your own permissions, you must first declare them in your -<code>AndroidManifest.xml</code> using one or more -<code>{@link android.R.styleable#AndroidManifestPermission <permission>}</code> -tags.</p> - -<p>For example, an application that wants to control who can start one -of its activities could declare a permission for this operation as follows:</p> - -<pre><manifest xmlns:android="http://schemas.android.com/apk/res/android" - package="com.me.app.myapp" > - - <permission android:name="com.me.app.myapp.permission.DEADLY_ACTIVITY" - android:label="@string/permlab_deadlyActivity" - android:description="@string/permdesc_deadlyActivity" - android:permissionGroup="android.permission-group.COST_MONEY" - android:protectionLevel="dangerous" /> - -</manifest></pre> - -<p>The {@link android.R.styleable#AndroidManifestPermission_protectionLevel -<protectionLevel>} attribute is required, telling the system how the -user is to be informed of applications requiring the permission, or who is -allowed to hold that permission, as described in the linked documentation.</p> - -<p>The {@link android.R.styleable#AndroidManifestPermission_permissionGroup -<permissionGroup>} attribute is optional, and only used to help the system display -permissions to the user. You will usually want to set this to either a standard -system group (listed in {@link android.Manifest.permission_group -android.Manifest.permission_group}) or in more rare cases to one defined by -yourself. It is preferred to use an existing group, as this simplifies the -permission UI shown to the user.</p> - -<p>Note that both a label and description should be supplied for the -permission. These are string resources that can be displayed to the user when -they are viewing a list of permissions -(<code>{@link android.R.styleable#AndroidManifestPermission_label android:label}</code>) -or details on a single permission ( -<code>{@link android.R.styleable#AndroidManifestPermission_description android:description}</code>). -The label should be short, a few words -describing the key piece of functionality the permission is protecting. The -description should be a couple sentences describing what the permission allows -a holder to do. Our convention for the description is two sentences, the first -describing the permission, the second warning the user of what bad things -can happen if an application is granted the permission.</p> - -<p>Here is an example of a label and description for the CALL_PHONE -permission:</p> - -<pre> - <string name="permlab_callPhone">directly call phone numbers</string> - <string name="permdesc_callPhone">Allows the application to call - phone numbers without your intervention. Malicious applications may - cause unexpected calls on your phone bill. Note that this does not - allow the application to call emergency numbers.</string> -</pre> - -<p>You can look at the permissions currently defined in the system with the -shell command <code>adb shell pm list permissions</code>. In particular, -the '-s' option displays the permissions in a form roughly similar to how the -user will see them:</p> - -<pre> -$ adb shell pm list permissions -s -All Permissions: - -Network communication: view Wi-Fi state, create Bluetooth connections, full -Internet access, view network state - -Your location: access extra location provider commands, fine (GPS) location, -mock location sources for testing, coarse (network-based) location - -Services that cost you money: send SMS messages, directly call phone numbers - -...</pre> - -<a name="manifest"></a> -<h3>Enforcing Permissions in AndroidManifest.xml</h3> - -<p>High-level permissions restricting access to entire components of the -system or application can be applied through your -<code>AndroidManifest.xml</code>. All that this requires is including an {@link -android.R.attr#permission android:permission} attribute on the desired -component, naming the permission that will be used to control access to -it.</p> - -<p><strong>{@link android.app.Activity}</strong> permissions -(applied to the -{@link android.R.styleable#AndroidManifestActivity <activity>} tag) -restrict who can start the associated -activity. The permission is checked during -{@link android.content.Context#startActivity Context.startActivity()} and -{@link android.app.Activity#startActivityForResult Activity.startActivityForResult()}; -if the caller does not have -the required permission then {@link java.lang.SecurityException} is thrown -from the call.</p> - -<p><strong>{@link android.app.Service}</strong> permissions -(applied to the -{@link android.R.styleable#AndroidManifestService <service>} tag) -restrict who can start or bind to the -associated service. The permission is checked during -{@link android.content.Context#startService Context.startService()}, -{@link android.content.Context#stopService Context.stopService()} and -{@link android.content.Context#bindService Context.bindService()}; -if the caller does not have -the required permission then {@link java.lang.SecurityException} is thrown -from the call.</p> - -<p><strong>{@link android.content.BroadcastReceiver}</strong> permissions -(applied to the -{@link android.R.styleable#AndroidManifestReceiver <receiver>} tag) -restrict who can send broadcasts to the associated receiver. -The permission is checked <em>after</em> -{@link android.content.Context#sendBroadcast Context.sendBroadcast()} returns, -as the system tries -to deliver the submitted broadcast to the given receiver. As a result, a -permission failure will not result in an exception being thrown back to the -caller; it will just not deliver the intent. In the same way, a permission -can be supplied to -{@link android.content.Context#registerReceiver(android.content.BroadcastReceiver, android.content.IntentFilter, String, android.os.Handler) -Context.registerReceiver()} -to control who can broadcast to a programmatically registered receiver. -Going the other way, a permission can be supplied when calling -{@link android.content.Context#sendBroadcast(Intent, String) Context.sendBroadcast()} -to restrict which BroadcastReceiver objects are allowed to receive the broadcast (see -below).</p> - -<p><strong>{@link android.content.ContentProvider}</strong> permissions -(applied to the -{@link android.R.styleable#AndroidManifestProvider <provider>} tag) -restrict who can access the data in -a {@link android.content.ContentProvider}. (Content providers have an important -additional security facility available to them called -<a href="#uri">URI permissions</a> which is described later.) -Unlike the other components, -there are two separate permission attributes you can set: -{@link android.R.attr#readPermission android:readPermission} restricts who -can read from the provider, and -{@link android.R.attr#writePermission android:writePermission} restricts -who can write to it. Note that if a provider is protected with both a read -and write permission, holding only the write permission does not mean -you can read from a provider. The permissions are checked when you first -retrieve a provider (if you don't have either permission, a SecurityException -will be thrown), and as you perform operations on the provider. Using -{@link android.content.ContentResolver#query ContentResolver.query()} requires -holding the read permission; using -{@link android.content.ContentResolver#insert ContentResolver.insert()}, -{@link android.content.ContentResolver#update ContentResolver.update()}, -{@link android.content.ContentResolver#delete ContentResolver.delete()} -requires the write permission. -In all of these cases, not holding the required permission results in a -{@link java.lang.SecurityException} being thrown from the call.</p> - - -<a name="broadcasts"></a> -<h3>Enforcing Permissions when Sending Broadcasts</h3> - -<p>In addition to the permission enforcing who can send Intents to a -registered {@link android.content.BroadcastReceiver} (as described above), you -can also specify a required permission when sending a broadcast. By calling {@link -android.content.Context#sendBroadcast(android.content.Intent,String) -Context.sendBroadcast()} with a -permission string, you require that a receiver's application must hold that -permission in order to receive your broadcast.</p> - -<p>Note that both a receiver and a broadcaster can require a permission. When -this happens, both permission checks must pass for the Intent to be delivered -to the associated target.</p> - - -<a name="enforcement"></a> -<h3>Other Permission Enforcement</h3> - -<p>Arbitrarily fine-grained permissions can be enforced at any call into a -service. This is accomplished with the {@link -android.content.Context#checkCallingPermission Context.checkCallingPermission()} -method. Call with a desired -permission string and it will return an integer indicating whether that -permission has been granted to the current calling process. Note that this can -only be used when you are executing a call coming in from another process, -usually through an IDL interface published from a service or in some other way -given to another process.</p> - -<p>There are a number of other useful ways to check permissions. If you have -the pid of another process, you can use the Context method {@link -android.content.Context#checkPermission(String, int, int) Context.checkPermission(String, int, int)} -to check a permission against that pid. If you have the package name of another -application, you can use the direct PackageManager method {@link -android.content.pm.PackageManager#checkPermission(String, String) -PackageManager.checkPermission(String, String)} -to find out whether that particular package has been granted a specific permission.</p> - - -<a name="uri"></a> -<h2>URI Permissions</h2> - -<p>The standard permission system described so far is often not sufficient -when used with content providers. A content provider may want to -protect itself with read and write permissions, while its direct clients -also need to hand specific URIs to other applications for them to operate on. -A typical example is attachments in a mail application. Access to the mail -should be protected by permissions, since this is sensitive user data. However, -if a URI to an image attachment is given to an image viewer, that image viewer -will not have permission to open the attachment since it has no reason to hold -a permission to access all e-mail.</p> - -<p>The solution to this problem is per-URI permissions: when starting an -activity or returning a result to an activity, the caller can set -{@link android.content.Intent#FLAG_GRANT_READ_URI_PERMISSION -Intent.FLAG_GRANT_READ_URI_PERMISSION} and/or -{@link android.content.Intent#FLAG_GRANT_WRITE_URI_PERMISSION -Intent.FLAG_GRANT_WRITE_URI_PERMISSION}. This grants the receiving activity -permission access the specific data URI in the Intent, regardless of whether -it has any permission to access data in the content provider corresponding -to the Intent.</p> - -<p>This mechanism allows a common capability-style model where user interaction -(opening an attachment, selecting a contact from a list, etc) drives ad-hoc -granting of fine-grained permission. This can be a key facility for reducing -the permissions needed by applications to only those directly related to their -behavior.</p> - -<p>The granting of fine-grained URI permissions does, however, require some -cooperation with the content provider holding those URIs. It is strongly -recommended that content providers implement this facility, and declare that -they support it through the -{@link android.R.styleable#AndroidManifestProvider_grantUriPermissions -android:grantUriPermissions} attribute or -{@link android.R.styleable#AndroidManifestGrantUriPermission -<grant-uri-permissions>} tag.</p> - -<p>More information can be found in the -{@link android.content.Context#grantUriPermission Context.grantUriPermission()}, -{@link android.content.Context#revokeUriPermission Context.revokeUriPermission()}, and -{@link android.content.Context#checkUriPermission Context.checkUriPermission()} -methods.</p> - diff --git a/docs/html/guide/topics/sensors/accelerometer.jd b/docs/html/guide/topics/sensors/accelerometer.jd deleted file mode 100644 index da760bc..0000000 --- a/docs/html/guide/topics/sensors/accelerometer.jd +++ /dev/null @@ -1,18 +0,0 @@ -page.title=Accelerometer -parent.title=Sensors -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>In this document</h2> - <ol> - - </ol> - -</div> -</div> - - -TODO
\ No newline at end of file diff --git a/docs/html/guide/topics/sensors/camera.jd b/docs/html/guide/topics/sensors/camera.jd deleted file mode 100644 index 821333e..0000000 --- a/docs/html/guide/topics/sensors/camera.jd +++ /dev/null @@ -1,18 +0,0 @@ -page.title=Camera -parent.title=Sensors -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Key class</h2> - <ol> - <li>{@link android.hardware.Camera android.hardware.Camera}</li> - </ol> - <h2>In this document</h2> - <ol> - <li>TODO</li> - </ol> -</div> -</div>
\ No newline at end of file diff --git a/docs/html/guide/topics/sensors/compass.jd b/docs/html/guide/topics/sensors/compass.jd deleted file mode 100644 index 1e45d2d..0000000 --- a/docs/html/guide/topics/sensors/compass.jd +++ /dev/null @@ -1,18 +0,0 @@ -page.title=Compass -parent.title=Sensors -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>In this document</h2> - <ol> - - </ol> - -</div> -</div> - - -TODO
\ No newline at end of file diff --git a/docs/html/guide/topics/sensors/index.jd b/docs/html/guide/topics/sensors/index.jd deleted file mode 100644 index 54a0814..0000000 --- a/docs/html/guide/topics/sensors/index.jd +++ /dev/null @@ -1,13 +0,0 @@ -page.title=Sensors -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - - -<h2>Accelerometer</h2> -<p>The accelerometer sensors allow you to detect the various movements of the device.</p> - -<h2>Compass</h2> -<p>The compass provides data on the devices current polar orientation.</p>
\ No newline at end of file diff --git a/docs/html/guide/topics/ui/binding.jd b/docs/html/guide/topics/ui/binding.jd deleted file mode 100644 index 85aed18..0000000 --- a/docs/html/guide/topics/ui/binding.jd +++ /dev/null @@ -1,113 +0,0 @@ -page.title=Binding to Data with AdapterView -parent.title=User Interface -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#FillingTheLayout">Filling the Layout with Data</a></li> - <li><a href="#HandlingUserSelections">Handling User Selections</a></li> - </ol> - - <h2>See also</h2> - <ol> - <li><a href="{@docRoot}guide/tutorials/views/hello-spinner.html">Hello Spinner tutorial</a></li> - <li><a href="{@docRoot}guide/tutorials/views/hello-listview.html">Hello ListView tutorial</a></li> - <li><a href="{@docRoot}guide/tutorials/views/hello-gridview.html">Hello GridView tutorial</a></li> - </ol> -</div> -</div> - -<p>The {@link android.widget.AdapterView} is a ViewGroup subclass whose child Views are determined by an {@link android.widget.Adapter Adapter} that -binds to data of some type. AdapterView is useful whenever you need to display stored data (as opposed to resource strings or drawables) in your layout.</p> - -<p>{@link android.widget.Gallery Gallery}, {@link android.widget.ListView ListView}, and {@link android.widget.Spinner Spinner} are examples of AdapterView subclasses that you can use to bind to a specific type of data and display it in a certain way. </p> - - -<p>AdapterView objects have two main responsibilities: </p> -<ul> - <li>Filling the layout with data - </li> - <li>Handling user selections - </li> -</ul> - - -<h2 id="FillingTheLayout">Filling the Layout with Data</h2> -<p>Inserting data into the layout is typically done by binding the AdapterView class to an {@link -android.widget.Adapter}, which retireves data from an external source (perhaps a list that -the code supplies or query results from the device's database). </p> -<p>The following code sample does the following:</p> -<ol> - <li>Creates a {@link android.widget.Spinner Spinner} with an existing View and binds it to a new ArrayAdapter -that reads an array of colors from the local resources.</li> - <li>Creates another Spinner object from a View and binds it to a new SimpleCursorAdapter that will read -people's names from the device contacts (see {@link android.provider.Contacts.People}).</li> -</ol> - -<pre> -// Get a Spinner and bind it to an ArrayAdapter that -// references a String array. -Spinner s1 = (Spinner) findViewById(R.id.spinner1); -ArrayAdapter<CharSequence> adapter = ArrayAdapter.createFromResource( - this, R.array.colors, android.R.layout.simple_spinner_item); -adapter.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item); -s1.setAdapter(adapter); - -// Load a Spinner and bind it to a data query. -private static String[] PROJECTION = new String[] { - People._ID, People.NAME - }; - -Spinner s2 = (Spinner) findViewById(R.id.spinner2); -Cursor cur = managedQuery(People.CONTENT_URI, PROJECTION, null, null); - -SimpleCursorAdapter adapter2 = new SimpleCursorAdapter(this, - android.R.layout.simple_spinner_item, // Use a template - // that displays a - // text view - cur, // Give the cursor to the list adatper - new String[] {People.NAME}, // Map the NAME column in the - // people database to... - new int[] {android.R.id.text1}); // The "text1" view defined in - // the XML template - -adapter2.setDropDownViewResource(android.R.layout.simple_spinner_dropdown_item); -s2.setAdapter(adapter2); -</pre> - -<p>Note that it is necessary to have the People._ID column in projection used with CursorAdapter -or else you will get an exception.</p> - -<p>If, during the course of your application's life, you change the underlying data that is read by your Adapter, -you should call {@link android.widget.ArrayAdapter#notifyDataSetChanged()}. This will notify the attached View -that the data has been changed and it should refresh itself.</p> - -<h2 id="HandlingUserSelections">Handling User Selections</h2> -<p>You handle the user's selecction by setting the class's {@link -android.widget.AdapterView.OnItemClickListener} member to a listener and -catching the selection changes. </p> -<pre> -// Create a message handling object as an anonymous class. -private OnItemClickListener mMessageClickedHandler = new OnItemClickListener() { - public void onItemClick(AdapterView parent, View v, int position, long id) - { - // Display a messagebox. - Toast.makeText(mContext,"You've got an event",Toast.LENGTH_SHORT).show(); - } -}; - -// Now hook into our object and set its onItemClickListener member -// to our class handler object. -mHistoryView = (ListView)findViewById(R.id.history); -mHistoryView.setOnItemClickListener(mMessageClickedHandler); -</pre> - -<div class="special"> -<p>For more discussion on how to create different AdapterViews, read the following tutorials: -<a href="{@docRoot}guide/tutorials/views/hello-spinner.html">Hello Spinner</a>, -<a href="{@docRoot}guide/tutorials/views/hello-listview.html">Hello ListView</a>, and -<a href="{@docRoot}guide/tutorials/views/hello-gridview.html">Hello GridView</a>. -</div> diff --git a/docs/html/guide/topics/ui/custom-components.jd b/docs/html/guide/topics/ui/custom-components.jd deleted file mode 100644 index eccc2ca..0000000 --- a/docs/html/guide/topics/ui/custom-components.jd +++ /dev/null @@ -1,563 +0,0 @@ -page.title=Building Custom Components -parent.title=User Interface -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#basic">The Basic Approach</a></li> - <li><a href="#custom">Fully Customized Components</a></li> - <li><a href="#compound">Compound Controls</a></li> - <li><a href="#modifying">Modifying an Existing View Type</a></li> - </ol> -</div> -</div> - -<p>Android offers a sophisticated and powerful componentized model for building your UI, -based on the fundamental layout classes: {@link android.view.View} and -{@link android.view.ViewGroup}. To start with, the platform includes a variety of prebuilt -View and ViewGroup subclasses — called widgets and layouts, respectively — -that you can use to construct your UI.</p> - -<p>A partial list of available widgets includes {@link android.widget.Button Button}, -{@link android.widget.TextView TextView}, -{@link android.widget.EditText EditText}, -{@link android.widget.ListView ListView}, -{@link android.widget.CheckBox CheckBox}, -{@link android.widget.RadioButton RadioButton}, -{@link android.widget.Gallery Gallery}, -{@link android.widget.Spinner Spinner}, and the more special-purpose -{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, -{@link android.widget.ImageSwitcher ImageSwitcher}, and -{@link android.widget.TextSwitcher TextSwitcher}. </p> - -<p>Among the layouts available are {@link android.widget.LinearLayout LinearLayout}, -{@link android.widget.FrameLayout FrameLayout}, {@link android.widget.AbsoluteLayout AbsoluteLayout}, -and others. For more examples, see <a href="layout-objects.html">Common Layout Objects</a>.</p> - -<p>If none of the prebuilt widgets or layouts meets your needs, you can create your own View subclass. -If you only need to make small adjustments to an existing widget or layout, you can simply subclass -the widget or layout and override its methods. -</p> - -<p>Creating your own View subclasses gives you precise control over the appearance and function -of a screen element. To give an idea of the control you get with custom views, here are some -examples of what you could do with them:</p> - -<ul> - <li> - You could create a completely custom-rendered View type, for example a "volume - control" knob rendered using 2D graphics, and which resembles an - analog electronic control. - </li> - <li> - You could combine a group of View components into a new single component, perhaps - to make something like a ComboBox (a combination of popup list and free - entry text field), a dual-pane selector control (a left and right pane - with a list in each where you can re-assign which item is in which - list), and so on. - </li> - <li> - You could override the way that an EditText component is rendered on the screen - (the <a href="{@docRoot}guide/samples/NotePad/index.html">Notepad Tutorial</a> uses this to good effect, - to create a lined-notepad page). - </li> - <li> - You could capture other events like key presses and handle them in some custom - way (such as for a game). - </li> -</ul> -<p> -The sections below explain how to create custom Views and use them in your application. -For detailed reference information, see the {@link android.view.View} class. </p> - - -<h2 id="basic">The Basic Approach</h2> - -<p>Here is a high level overview of what you need to know to get started in creating your own -View components:</p> - -<ol> - <li> - Extend an existing {@link android.view.View View} class or subclass - with your own class. - </li> - <li> - Override some of the methods from the superclass. The superclass methods - to override start with '<code>on</code>', for - example, {@link android.view.View#onDraw onDraw()}, - {@link android.view.View#onMeasure onMeasure()}, and - {@link android.view.View#onKeyDown onKeyDown()}. - This is similar to the <code>on...</code> events in {@link android.app.Activity Activity} - or {@link android.app.ListActivity ListActivity} - that you override for lifecycle and other functionality hooks. - <li> - Use your new extension class. Once completed, your new extension class - can be used in place of the view upon which it was based. - </li> -</ol> -<p class="note"><strong>Tip:</strong> - Extension classes can be defined as inner classes inside the activities - that use them. This is useful because it controls access to them but - isn't necessary (perhaps you want to create a new public View for - wider use in your application). -</p> - - - -<h2 id="custom">Fully Customized Components</h2> -<p> -Fully customized components can be used to create graphical components that -appear however you wish. Perhaps a graphical VU -meter that looks like an old analog gauge, or a sing-a-long text view where -a bouncing ball moves along the words so you can sing along with a karaoke -machine. Either way, you want something that the built-in components just -won't do, no matter how you combine them.</p> -<p>Fortunately, you can easily create components that look and behave in any -way you like, limited perhaps only by your imagination, the size of the -screen, and the available processing power (remember that ultimately your -application might have to run on something with significantly less power -than your desktop workstation).</p> -<p>To create a fully customized component:</p> -<ol> - <li> - The most generic view you can extend is, unsurprisingly, {@link - android.view.View View}, so you will usually start by extending this to - create your new super component. - </li> - <li> - You can supply a constructor which can - take attributes and parameters from the XML, and you can also consume - your own such attributes and parameters (perhaps the color and range of - the VU meter, or the width and damping of the needle, etc.) - </li> - <li> - You will probably want to create your own event listeners, - property accessors and modifiers, and possibly more sophisticated - behavior in your component class as well. - </li> - <li> - You will almost certainly want to override <code>onMeasure()</code> and - are also likely to need to override <code>onDraw()</code> if you want - the component to show something. While both have default behavior, - the default <code>onDraw()</code> will do nothing, and the default - <code>onMeasure()</code> will always set a size of 100x100 — which is - probably not what you want. - </li> - <li> - Other <code>on...</code> methods may also be overridden as required. - </li> -</ol> - -<h3>Extend <code>onDraw()</code> and <code>onMeasure()</code></h3> -<p>The <code>onDraw()</code> method delivers you a {@link android.graphics.Canvas Canvas} -upon which you can implement anything you want: 2D graphics, other standard or -custom components, styled text, or anything else you can think of.</p> - -<p class="note"><strong>Note:</strong> -This does not apply to 3D graphics. If you want to -use 3D graphics, you must extend {@link android.view.SurfaceView SurfaceView} -instead of View, and draw from a seperate thread. See the -GLSurfaceViewActivity sample -for details.</p> - -<p><code>onMeasure()</code> is a little more involved. <code>onMeasure()</code> -is a critical piece of the rendering contract between your component and its -container. <code>onMeasure()</code> should be overridden to efficiently and -accurately report the measurements of its contained parts. This is made -slightly more complex by the requirements of limits from the parent -(which are passed in to the <code>onMeasure()</code> method) and by the -requirement to call the <code>setMeasuredDimension()</code> method with the -measured width and height once they have been calculated. If you fail to -call this method from an overridden <code>onMeasure()</code> method, the -result will be an exception at measurement time.</p> -<p>At a high level, implementing <code>onMeasure()</code> looks something - like this:</p> - -<ol> - <li> - The overridden <code>onMeasure()</code> method is called with width and - height measure specifications (<code>widthMeasureSpec</code> and - <code>heightMeasureSpec</code> parameters, both are integer codes - representing dimensions) which should be treated as requirements for - the restrictions on the width and height measurements you should produce. A - full reference to the kind of restrictions these specifications can require - can be found in the reference documentation under {@link - android.view.View#onMeasure View.onMeasure(int, int)} (this reference - documentation does a pretty good job of explaining the whole measurement - operation as well). - </li> - <li> - Your component's <code>onMeasure()</code> method should calculate a - measurement width and height which will be required to render the - component. It should try to stay within the specifications passed in, - although it can choose to exceed them (in this case, the parent can - choose what to do, including clipping, scrolling, throwing an exception, - or asking the <code>onMeasure()</code> to try again, perhaps with - different measurement specifications). - </li> - <li> - Once the width and height are calculated, the <code>setMeasuredDimension(int - width, int height)</code> method must be called with the calculated - measurements. Failure to do this will result in an exception being - thrown. - </li> -</ol> - -<p> -Here's a summary of some of the other standard methods that the framework calls on views: -</p> -<table border="2" width="85%" align="center" cellpadding="5"> - <thead> - <tr><th>Category</th> <th>Methods</th> <th>Description</th></tr> - </thead> - - <tbody> - <tr> - <td rowspan="2">Creation</td> - <td>Constructors</td> - <td>There is a form of the constructor that are called when the view - is created from code and a form that is called when the view is - inflated from a layout file. The second form should parse and apply - any attributes defined in the layout file. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onFinishInflate()}</code></td> - <td>Called after a view and all of its children has been inflated - from XML.</td> - </tr> - - <tr> - <td rowspan="3">Layout</td> - <td><code>{@link android.view.View#onMeasure}</code></td> - <td>Called to determine the size requirements for this view and all - of its children. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onLayout}</code></td> - <td>Called when this view should assign a size and position to all - of its children. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onSizeChanged}</code></td> - <td>Called when the size of this view has changed. - </td> - </tr> - - <tr> - <td>Drawing</td> - <td><code>{@link android.view.View#onDraw}</code></td> - <td>Called when the view should render its content. - </td> - </tr> - - <tr> - <td rowspan="4">Event processing</td> - <td><code>{@link android.view.View#onKeyDown}</code></td> - <td>Called when a new key event occurs. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onKeyUp}</code></td> - <td>Called when a key up event occurs. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onTrackballEvent}</code></td> - <td>Called when a trackball motion event occurs. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onTouchEvent}</code></td> - <td>Called when a touch screen motion event occurs. - </td> - </tr> - - <tr> - <td rowspan="2">Focus</td> - <td><code>{@link android.view.View#onFocusChanged}</code></td> - <td>Called when the view gains or loses focus. - </td> - </tr> - - <tr> - <td><code>{@link android.view.View#onWindowFocusChanged}</code></td> - <td>Called when the window containing the view gains or loses focus. - </td> - </tr> - - <tr> - <td rowspan="3">Attaching</td> - <td><code>{@link android.view.View#onAttachedToWindow()}</code></td> - <td>Called when the view is attached to a window. - </td> - </tr> - - <tr> - <td><code>{@link android.view.View#onDetachedFromWindow}</code></td> - <td>Called when the view is detached from its window. - </td> - </tr> - - <tr> - <td><code>{@link android.view.View#onWindowVisibilityChanged}</code></td> - <td>Called when the visibility of the window containing the view - has changed. - </td> - </tr> - </tbody> - - </table> - - - -<h3 id="customexample">A Custom View Example</h3> -<p>The CustomView sample in the -<a href="{@docRoot}guide/samples/ApiDemos/index.html">API Demos</a> provides an example -of a customized View. The custom View is defined in the -<a href="{@docRoot}guide/samples/ApiDemos/src/com/example/android/apis/view/LabelView.html">LabelView</a> -class.</p> -<p>The LabelView sample demonstrates a number of different aspects of custom components:</p> -<ul> - <li>Extending the View class for a completely custom component.</li> - <li>Parameterized constructor that takes the view inflation parameters - (parameters defined in the XML). Some of these are passed through to the - View superclass, but more importantly, there are some custom attributes defined - and used for LabelView.</li> - <li>Standard public methods of the type you would expect to see for a label - component, for example <code>setText()</code>, <code>setTextSize()</code>, - <code>setTextColor()</code> and so on.</li> - <li>An overridden <code>onMeasure</code> method to determine and set the - rendering size of the component. (Note that in LabelView, the real work is done - by a private <code>measureWidth()</code> method.)</li> - <li>An overridden <code>onDraw()</code> method to draw the label onto the - provided canvas.</li> -</ul> -<p>You can see some sample usages of the LabelView custom View in -<a href="{@docRoot}guide/samples/ApiDemos/res/layout/custom_view_1.html">custom_view_1.xml</a> -from the samples. In particular, you can see a mix of both <code>android:</code> -namespace parameters and custom <code>app:</code> namespace parameters. These -<code>app:</code> parameters are the custom ones that the LabelView recognizes -and works with, and are defined in a styleable inner class inside of the -samples R resources definition class.</p> - - -<h2 id="compound">Compound Controls -</h2> -<p>If you don't want to create a completely customized component, but instead -are looking to put together a reusable component that consists of a group of -existing controls, then creating a Compound Component (or Compound Control) might -fit the bill. In a nutshell, this brings together a number of more atomic -controls (or views) into a logical group of items that can be treated as a -single thing. For example, a Combo Box can be thought of as a -combination of a single line EditText field and an adjacent button with an attached - PopupList. If you press the button and select -something from the list, it populates the EditText field, but the user can -also type something directly into the EditText if they prefer.</p> -<p>In Android, there are actually two other Views readily available to do -this: {@link android.widget.Spinner Spinner} and -{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, but -regardless, the concept of a Combo Box makes an easy-to-understand -example.</p> -<p>To create a compound component:</p> -<ol> - <li> - The usual starting point is a Layout of some kind, so create a class - that extends a Layout. Perhaps in the case of a Combo box we might use - a LinearLayout with horizontal orientation. Remember that other layouts - can be nested inside, so the compound component can be arbitrarily - complex and structured. Note that just like with an Activity, you can - use either the declarative (XML-based) approach to creating the - contained components, or you can nest them programmatically from your - code. - </li> - <li> - In the constructor for the new class, take whatever parameters the - superclass expects, and pass them through to the superclass constructor - first. Then you can set up the other views to use within your new - component; this is where you would create the EditText field and the - PopupList. Note that you also might introduce your own attributes and - parameters into the XML that can be pulled out and used by your - constructor. - </li> - <li> - You can also create listeners for events that your contained views might - generate, for example, a listener method for the List Item Click Listener - to update the contents of the EditText if a list selection is made. - </li> - <li> - You might also create your own properties with accessors and modifiers, - for example, allow the EditText value to be set initially in the - component and query for its contents when needed. - </li> - <li> - In the case of extending a Layout, you don't need to override the - <code>onDraw()</code> and <code>onMeasure()</code> methods since the - layout will have default behavior that will likely work just fine. However, - you can still override them if you need to. - </li> - <li> - You might override other <code>on...</code> methods, like - <code>onKeyDown()</code>, to perhaps choose certain default values from - the popup list of a combo box when a certain key is pressed. - </li> -</ol> -<p> - To summarize, the use of a Layout as the basis for a Custom Control has a -number of advantages, including:</p> - -<ul> - <li> - You can specify the layout using the declarative XML files just like - with an activity screen, or you can create views programmatically and - nest them into the layout from your code. - </li> - <li> - The <code>onDraw()</code> and <code>onMeasure()</code> methods (plus - most of the other <code>on...</code> methods) will likely have suitable behavior so - you don't have to override them. - </li> - <li> - In the end, you can very quickly construct arbitrarily complex compound - views and re-use them as if they were a single component. - </li> -</ul> -<h4>Examples of Compound Controls</h4> -<p>In the API Demos project - that comes with the SDK, there are two List - examples — Example 4 and Example 6 under Views/Lists demonstrate a - SpeechView which extends LinearLayout to make a component for displaying - Speech quotes. The corresponding classes in the sample code are - <code>List4.java</code> and <code>List6.java</code>.</p> - - - -<h2 id="modifying">Modifying an Existing View Type</h2> -<p>There is an even easier option for creating a custom View which is -useful in certain circumstances. If there is a component that is already very -similar to what you want, you can simply extend that component and just -override the behavior that you want to change. You can do all of the things -you would do with a fully customized component, but by starting with a more -specialized class in the View heirarchy, you can also get a lot of behavior for -free that probably does exactly what you want.</p> -<p>For example, the SDK includes a <a -href="{@docRoot}guide/samples/NotePad/index.html">NotePad application</a> in the -samples. This demonstrates many aspects of using the Android platform, among -them is extending an EditText View to make a lined notepad. This is not a -perfect example, and the APIs for doing this might change from this early -preview, but it does demonstrate the principles.</p> -<p>If you haven't done so already, import the -NotePad sample into Eclipse (or -just look at the source using the link provided). In particular look at the definition of -<code>MyEditText</code> in the <a -href="{@docRoot}guide/samples/NotePad/src/com/example/android/notepad/NoteEditor.html">NoteEditor.java</a> -file.</p> -<p>Some points to note here</p> -<ol> - <li> - <strong>The Definition</strong> - <p>The class is defined with the following line:<br/> - <code>public static class MyEditText extends EditText</code></p> - - <ul> - <li> - It is defined as an inner class within the <code>NoteEditor</code> - activity, but it is public so that it could be accessed as - <code>NoteEditor.MyEditText</code> from outside of the <code>NoteEditor</code> - class if desired. - </li> - <li> - It is <code>static</code>, meaning it does not generate the so-called - "synthetic methods" that allow it to access data from the parent - class, which in turn means that it really behaves as a separate - class rather than something strongly related to <code>NoteEditor</code>. - This is a cleaner way to create inner classes if they do not need - access to state from the outer class, keeps the generated class - small, and allows it to be used easily from other classes. - </li> - <li> - It extends <code>EditText</code>, which is the View we have chosen to - customize in this case. When we are finished, the new class will be - able to substitute for a normal <code>EditText</code> view. - </li> - </ul> - </li> - <li> - <strong>Class Initialization</strong> - <p>As always, the super is called first. Furthermore, - this is not a default constructor, but a parameterized one. The - EditText is created with these parameters when it is inflated from an - XML layout file, thus, our constructor needs to both take them and pass them - to the superclass constructor as well.</p> - </li> - <li> - <strong>Overridden Methods</strong> - <p>In this example, there is only one method to be overridden: - <code>onDraw()</code> — but there could easily be others needed when you - create your own custom components.</p> - <p>For the NotePad sample, overriding the <code>onDraw()</code> method allows - us to paint the blue lines on the <code>EditText</code> view canvas (the - canvas is passed into the overridden <code>onDraw()</code> method). The - super.onDraw() method is called before the method ends. The - superclass method should be invoked, but in this case, we do it at the - end after we have painted the lines we want to include.</p> - <li> - <strong>Use the Custom Component</strong> - <p>We now have our custom component, but how can we use it? In the - NotePad example, the custom component is used directly from the - declarative layout, so take a look at <code>note_editor.xml</code> in the - <code>res/layout</code> folder.</p> -<pre> -<view - class="com.android.notepad.NoteEditor$MyEditText" - id="@+id/note" - android:layout_width="fill_parent" - android:layout_height="fill_parent" - android:background="@android:drawable/empty" - android:padding="10dip" - android:scrollbars="vertical" - android:fadingEdge="vertical" /> -</pre> - - <ul> - <li> - The custom component is created as a generic view in the XML, and - the class is specified using the full package. Note also that the - inner class we defined is referenced using the - <code>NoteEditor$MyEditText</code> notation which is a standard way to - refer to inner classes in the Java programming language. - <p>If your custom View component is not defined as an inner class, then you can, - alternatively, declare the View component - with the XML element name, and exclude the <code>class</code> attribute. For example:</p> -<pre> -<com.android.notepad.MyEditText - id="@+id/note" - ... /> -</pre> - <p>Notice that the <code>MyEditText</code> class is now a separate class file. When the class - is nested in the <code>NoteEditor</code> class, this technique will not work.</p> - </li> - <li> - The other attributes and parameters in the definition are the ones - passed into the custom component constructor, and then passed - through to the EditText constructor, so they are the same - parameters that you would use for an EditText view. Note that it is - possible to add your own parameters as well, and we will touch on - this again below. - </li> - </ul> - </li> -</ol> -<p>And that's all there is to it. Admittedly this is a simple case, but -that's the point — creating custom components is only as complicated as you -need it to be.</p> -<p>A more sophisticated component may override even more <code>on...</code> methods and -introduce some of its own helper methods, substantially customizing its properties and -behavior. The only limit is your imagination and what you need the component to -do.</p> - diff --git a/docs/html/guide/topics/ui/declaring-layout.jd b/docs/html/guide/topics/ui/declaring-layout.jd deleted file mode 100644 index 7ef22a6..0000000 --- a/docs/html/guide/topics/ui/declaring-layout.jd +++ /dev/null @@ -1,275 +0,0 @@ -page.title=Declaring Layout -parent.title=User Interface -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>Key classes</h2> - <ol> - <li>{@link android.view.View}</li> - <li>{@link android.view.ViewGroup}</li> - <li>{@link android.view.ViewGroup.LayoutParams}</li> - </ol> - <h2>In this document</h2> - <ol> - <li><a href="#write">Write the XML</a></li> - <li><a href="#load">Load the XML Resource</a></li> - <li><a href="#attributes">Attributes</a> - <ol> - <li><a href="#id">ID</a></li> - <li><a href="#layout-params">Layout Parameters</a></li> - </ol> - </li> - <li><a href="#Position">Position</a></li> - <li><a href="#SizePaddingMargin">Size, Padding and Margins</a></li> - <li><a href="#example">Example Layout</a></li> - </ol> -</div> -</div> - -<p>Your layout is the architecture for the user interface in an Activity. -It defines the layout structure and holds all the elements that appear to the user. -You can declare your layout in two ways:</p> -<ul> -<li><strong>Declare UI elements in XML</strong>. Android provides a straightforward XML -vocabulary that corresponds to the View classes and subclasses, such as those for widgets and layouts.</li> -<li><strong>Instantiate layout elements at runtime</strong>. Your -application can create View and ViewGroup objects (and manipulate their properties) programmatically. </li> -</ul> - -<p>The Android framework gives you the flexibility to use either or both of these methods for declaring and managing your application's UI. For example, you could declare your application's default layouts in XML, including the screen elements that will appear in them and their properties. You could then add code in your application that would modify the state of the screen objects, including those declared in XML, at run time. </p> - -<div class="sidebox"> - <p>The <a href="{@docRoot}guide/developing/tools/adt.html">Android Development Tools</a> - (ADT) plugin for Eclipse offers a layout preview of your XML — - with the XML file opened, select the <strong>Layout</strong> tab.</p> - <p>You should also try the - <a href="{@docRoot}guide/developing/tools/hierarchy-viewer.html">Hierarchy Viewer</a> tool, - for debugging layouts — it reveals layout property values, - draws wireframes with padding/margin indicators, and full rendered views while - you debug on the emulator or device.</p> -</div> - -<p>The advantage to declaring your UI in XML is that it enables you to better separate the presentation of your application from the code that controls its behavior. Your UI descriptions are external to your application code, which means that you can modify or adapt it without having to modify your source code and recompile. For example, you can create XML layouts for different screen orientations, different device screen sizes, and different languages. Additionally, declaring the layout in XML makes it easier to visualize the structure of your UI, so it's easier to debug problems. As such, this document focuses on teaching you how to declare your layout in XML. If you're -interested in instantiating View objects at runtime, refer to the {@link android.view.ViewGroup} and -{@link android.view.View} class references.</p> - -<p>In general, the XML vocabulary for declaring UI elements closely follows the structure and naming of the classes and methods, where element names correspond to class names and attribute names correspond to methods. In fact, the correspondence is often so direct that you can guess what XML attribute corresponds to a class method, or guess what class corresponds to a given xml element. However, note that not all vocabulary is identical. In some cases, there are slight naming differences. For -example, the EditText element has a <code>text</code> attribute that corresponds to -<code>EditText.setText()</code>. </p> - -<p class="note"><strong>Tip:</strong> Learn more about different layout types in <a href="{@docRoot}guide/topics/ui/layout-objects.html">Common -Layout Objects</a>. There are also a collection of tutorials on building various layouts in the -<a href="{@docRoot}guide/tutorials/views/index.html">Hello Views</a> tutorial guide.</p> - -<h2 id="write">Write the XML</h2> - -<div class="sidebox"><p>For your convenience, the API reference documentation for UI related classes lists the available XML attributes that correspond to the class methods, including inherited attributes.</p> -<p>To learn more about the available XML elements and attributes, as well as the format of the XML file, see <a -href="{@docRoot}guide/topics/resources/available-resources.html#layoutresources">Layout Resources</a>.</p> - </div> - -<p>Using Android's XML vocabulary, you can quickly design UI layouts and the screen elements they contain, in the same way you create web pages in HTML — with a series of nested elements. </p> - -<p>Each layout file must contain exactly one root element, which must be a View or ViewGroup object. Once you've defined the root element, you can add additional layout objects or widgets as child elements to gradually build a View hierarchy that defines your layout. For example, here's an XML layout that uses a vertical {@link android.widget.LinearLayout} -to hold a {@link android.widget.TextView} and a {@link android.widget.Button}:</p> -<pre> -<?xml version="1.0" encoding="utf-8"?> -<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" - android:layout_height="fill_parent" - android:orientation="vertical" > - <TextView android:id="@+id/text" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:text="Hello, I am a TextView" /> - <Button android:id="@+id/button" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:text="Hello, I am a Button" /> -</LinearLayout> -</pre> - -<p>After you've declared your layout in XML, save the file with the <code>.xml</code> extension, -in your Android project's <code>res/layout/</code> directory, so it will properly compile. </p> - -<p>We'll discuss each of the attributes shown here a little later.</p> - -<h2 id="load">Load the XML Resource</h2> - -<p>When you compile your application, each XML layout file is compiled into a -{@link android.view.View} resource. You should load the layout resource from your application code, in your -{@link android.app.Activity#onCreate(android.os.Bundle) Activity.onCreate()} callback implementation. -Do so by calling <code>{@link android.app.Activity#setContentView(int) setContentView()}</code>, -passing it the reference to your layout resource in the form of: -<code>R.layout.<em>layout_file_name</em></code> -For example, if your XML layout is saved as <code>main_layout.xml</code>, you would load it -for your Activity like so:</p> -<pre> -public void onCreate(Bundle savedInstanceState) { - super.onCreate(savedInstanceState); - setContentView.(R.layout.main_layout); -} -</pre> - -<p>The <code>onCreate()</code> callback method in your Activity is called by the Android framework when -your Activity is launched (see the discussion on Lifecycles, in the -<a href="{@docRoot}guide/topics/fundamentals.html#lcycles">Application Fundamantals</a>, for more on this).</p> - - -<h2 id="attributes">Attributes</h2> - -<p>Every View and ViewGroup object supports their own variety of XML attributes. -Some attributes are specific to a View object (for example, TextView supports the <code>textSize</code> -attribute), but these attributes are also inherited by any View objects that may extend this class. -Some are common to all View objects, because they are inherited from the root View class (like -the <code>id</code> attribute). And, other attributes are considered "layout parameters," which are -attributes that describe certain layout orientations of the View object, as defined by that object's -parent ViewGroup object.</p> - -<h3 id="id">ID</h3> - -<p>Any View object may have an integer ID associated with it, to uniquely identify the View within the tree. -When the application is compiled, this ID is referenced as an integer, but the ID is typically -assigned in the layout XML file as a string, in the <code>id</code> attribute. -This is an XML attribute common to all View objects -(defined by the {@link android.view.View} class) and you will use it very often. -The syntax for an ID, inside an XML tag is:</p> -<pre>android:id="@+id/my_button"</pre> - -<p>The at-symbol (@) at the beginning of the string indicates that the XML parser should parse and expand the rest -of the ID string and identify it as an ID resource. The plus-symbol (+) means that this is a new resource name that must -be created and added to our resources (in the <code>R.java</code> file). There are a number of other ID resources that -are offered by the Android framework. When referencing an Android resource ID, you do not need the plus-symbol, -but must add the <code>android</code> package namespace, like so:</p> -<pre>android:id="@android:id/empty"</pre> -<p>With the <code>android</code> package namespace in place, we're now referencing an ID from the <code>android.R</code> -resources class, rather than the local resources class.</p> - -<p>In order to create views and reference them from the application, a common pattern is to:</p> -<ol> - <li>Define a view/widget in the layout file and assign it a unique ID: -<pre> -<Button android:id="@+id/my_button" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:text="@string/my_button_text"/> -</pre> - </li> - <li>Then create an instance of the view object and capture it from the layout -(typically in the <code>{@link android.app.Activity#onCreate(Bundle) onCreate()}</code> method): -<pre> -Button myButton = (Button) findViewById(R.id.my_button); -</pre> - </li> -</ol> -<p>Defining IDs for view objects is important when creating a {@link android.widget.RelativeLayout}. -In a relative layout, sibling views can define their layout relative to another sibling view, -which is referenced by the unique ID.</p> -<p>An ID need not be unique throughout the entire tree, but it should be -unique within the part of the tree you are searching (which may often be the entire tree, so it's best -to be completely unique when possible).</p> - - -<h3 id="layout-params">Layout Parameters</h3> - -<p>XML layout attributes named <code>layout_<em>something</em></code> define -layout parameters for the View that are appropriate for the ViewGroup in which it resides.</p> - -<p>Every ViewGroup class implements a nested class that extends {@link -android.view.ViewGroup.LayoutParams}. This subclass -contains property types that define the size and position for each child view, as -appropriate for the view group. As you can see in the figure below, the parent -view group defines layout parameters for each child view (including the child view group).</p> - -<img src="{@docRoot}images/layoutparams.png" alt="" height="300" align="center"/> - -<p>Note that every LayoutParams subclass has its own syntax for setting -values. Each child element must define LayoutParams that are appropriate for its parent, -though it may also define different LayoutParams for its own children. </p> - -<p>All view groups include a width and height (<code>layout_width</code> and <code>layout_height</code>), -and each view is required to define them. -Many LayoutParams also include optional margins and -borders. You can specify width and height with exact measurements, though you probably won't want -to do this often. More often, you will tell your view to size itself either to -the dimensions required by its content, or to become as big as its parent view group -will allow (with the <var>wrap_content</var> and <var>fill_parent</var> values, respectively). -The accepted measurement types are defined in the -<a href="{@docRoot}guide/topics/resources/available-resources.html#dimension">Available Resources</a> document.</p> - - -<h2 id="Position">Layout Position</h2> - <p> - The geometry of a view is that of a rectangle. A view has a location, - expressed as a pair of <em>left</em> and <em>top</em> coordinates, and - two dimensions, expressed as a width and a height. The unit for location - and dimensions is the pixel. - </p> - - <p> - It is possible to retrieve the location of a view by invoking the methods - {@link android.view.View#getLeft()} and {@link android.view.View#getTop()}. The former returns the left, or X, - coordinate of the rectangle representing the view. The latter returns the - top, or Y, coordinate of the rectangle representing the view. These methods - both return the location of the view relative to its parent. For instance, - when getLeft() returns 20, that means the view is located 20 pixels to the - right of the left edge of its direct parent. - </p> - - <p> - In addition, several convenience methods are offered to avoid unnecessary - computations, namely {@link android.view.View#getRight()} and {@link android.view.View#getBottom()}. - These methods return the coordinates of the right and bottom edges of the - rectangle representing the view. For instance, calling {@link android.view.View#getRight()} - is similar to the following computation: <code>getLeft() + getWidth()</code>. - </p> - - -<h2 id="SizePaddingMargins">Size, Padding and Margins</h2> - <p> - The size of a view is expressed with a width and a height. A view actually - possess two pairs of width and height values. - </p> - - <p> - The first pair is known as <em>measured width</em> and - <em>measured height</em>. These dimensions define how big a view wants to be - within its parent. The - measured dimensions can be obtained by calling {@link android.view.View#getMeasuredWidth()} - and {@link android.view.View#getMeasuredHeight()}. - </p> - - <p> - The second pair is simply known as <em>width</em> and <em>height</em>, or - sometimes <em>drawing width</em> and <em>drawing height</em>. These - dimensions define the actual size of the view on screen, at drawing time and - after layout. These values may, but do not have to, be different from the - measured width and height. The width and height can be obtained by calling - {@link android.view.View#getWidth()} and {@link android.view.View#getHeight()}. - </p> - - <p> - To measure its dimensions, a view takes into account its padding. The padding - is expressed in pixels for the left, top, right and bottom parts of the view. - Padding can be used to offset the content of the view by a specific amount of - pixels. For instance, a left padding of 2 will push the view's content by - 2 pixels to the right of the left edge. Padding can be set using the - {@link android.view.View#setPadding(int, int, int, int)} method and queried by calling - {@link android.view.View#getPaddingLeft()}, {@link android.view.View#getPaddingTop()}, - {@link android.view.View#getPaddingRight()} and {@link android.view.View#getPaddingBottom()}. - </p> - - <p> - Even though a view can define a padding, it does not provide any support for - margins. However, view groups provide such a support. Refer to - {@link android.view.ViewGroup} and - {@link android.view.ViewGroup.MarginLayoutParams} for further information. - </p> - -<p>For more information about dimensions, see <a href="{@docRoot}guide/topics/resources/available-resources.html#dimension">Dimension Values</a>.</p> - - - - diff --git a/docs/html/guide/topics/ui/how-android-draws.jd b/docs/html/guide/topics/ui/how-android-draws.jd deleted file mode 100644 index a511005..0000000 --- a/docs/html/guide/topics/ui/how-android-draws.jd +++ /dev/null @@ -1,94 +0,0 @@ -page.title=How Android Draws Views -parent.title=User Interface -parent.link=index.html -@jd:body - - -<p>When an Activity receives focus, it will be requested to draw its layout. -The Android framework will handle the procedure for drawing, but the Activity must provide -the root node of its layout hierarchy.</p> - -<p>Drawing begins with the root node of the layout. It is requested to measure and -draw the layout tree. Drawing is handled by walking the tree and rendering each View that - intersects the invalid region. In turn, each View group is responsible for requesting -each of its children to be drawn (with the <code>{@link android.view.View#draw(Canvas) draw()}</code> method) -and each View is responsible for drawing itself. - Because the tree is traversed in-order, - this means that parents will be drawn before (i.e., behind) their children, with - siblings drawn in the order they appear in the tree. - </p> - -<div class="sidebox"> - <p>The framework will not draw Views that are not in the invalid region, and also - will take care of drawing the Views background for you.</p> - <p>You can force a View to draw, by calling <code>{@link android.view.View#invalidate()}</code>. - </p> -</div> - -<p> - Drawing the layout is a two pass process: a measure pass and a layout pass. The measuring - pass is implemented in <code>{@link android.view.View#measure(int, int)}</code> and is a top-down traversal - of the View tree. Each View pushes dimension specifications down the tree - during the recursion. At the end of the measure pass, every View has stored - its measurements. The second pass happens in - <code>{@link android.view.View#layout(int,int,int,int)}</code> and is also top-down. During - this pass each parent is responsible for positioning all of its children - using the sizes computed in the measure pass. - </p> - - <p> - When a View's <code>measure()</code> method returns, its <code>{@link android.view.View#getMeasuredWidth()}</code> and - <code>{@link android.view.View#getMeasuredHeight()}</code> values must be set, along with those for all of - that View's descendants. A View's measured width and measured height values - must respect the constraints imposed by the View's parents. This guarantees - that at the end of the measure pass, all parents accept all of their - children's measurements. A parent View may call <code>measure()</code> more than once on - its children. For example, the parent may measure each child once with - unspecified dimensions to find out how big they want to be, then call - <code>measure()</code> on them again with actual numbers if the sum of all the children's - unconstrained sizes is too big or too small (i.e., if the children don't agree among themselves - as to how much space they each get, the parent will intervene and set the rules on the second pass). - </p> - - <div class="sidebox"><p> - To intiate a layout, call <code>{@link android.view.View#requestLayout}</code>. This method is typically - called by a View on itself when it believes that is can no longer fit within - its current bounds.</p> - </div> - - <p> - The measure pass uses two classes to communicate dimensions. The - {@link android.view.View.MeasureSpec} class is used by Views to tell their parents how they - want to be measured and positioned. The base LayoutParams class just - describes how big the View wants to be for both width and height. For each - dimension, it can specify one of:</p> - <ul> - <li> an exact number - <li><var>FILL_PARENT</var>, which means the View wants to be as big as its parent - (minus padding)</li> - <li><var>WRAP_CONTENT</var>, which means that the View wants to be just big enough to - enclose its content (plus padding).</li> - </ul> - <p>There are subclasses of LayoutParams for different subclasses of ViewGroup. - For example, AbsoluteLayout has its own subclass of LayoutParams which adds - an X and Y value. - </p> - - <p> - MeasureSpecs are used to push requirements down the tree from parent to - child. A MeasureSpec can be in one of three modes:</p> - <ul> - <li><var>UNSPECIFIED</var>: This is used by a parent to determine the desired dimension - of a child View. For example, a LinearLayout may call <code>measure()</code> on its child - with the height set to <var>UNSPECIFIED</var> and a width of <var>EXACTLY</var> 240 to find out how - tall the child View wants to be given a width of 240 pixels.</li> - <li><var>EXACTLY</var>: This is used by the parent to impose an exact size on the - child. The child must use this size, and guarantee that all of its - descendants will fit within this size.</li> - <li><var>AT_MOST</var>: This is used by the parent to impose a maximum size on the - child. The child must gurantee that it and all of its descendants will fit - within this size.</li> - </ul> - - - diff --git a/docs/html/guide/topics/ui/index.jd b/docs/html/guide/topics/ui/index.jd deleted file mode 100644 index 6bd1d15..0000000 --- a/docs/html/guide/topics/ui/index.jd +++ /dev/null @@ -1,235 +0,0 @@ -page.title=User Interface -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>Key classes</h2> - <ol> - <li>{@link android.view.View}</li> - <li>{@link android.view.ViewGroup}</li> - <li>{@link android.widget Widget classes}</li> - </ol> - - <h2>In this document</h2> - <ol> - <li><a href="#ViewHierarchy">View Hierarchy</a></li> - <li><a href="#Layout">Layout</a></li> - <li><a href="#Widgets">Widgets</a></li> - <li><a href="#Events">UI Events</a></li> - <li><a href="#Menus">Menus</a></li> - <li><a href="#Advanced">Advanced Topics</a> - <ol> - <li><a href="#Adapters">Adapters</a></li> - <li><a href="#StylesAndThemes">Styles and Themes</a></li> - </ol> - </li> - </ol> -</div> -</div> - -<p>In an Android application, the user interface is built using {@link android.view.View} and -{@link android.view.ViewGroup} objects. There are many types of views and view groups, each of which -is a descendant of the {@link android.view.View} class.</p> - -<p>View objects are the basic units of user interface expression on the Android platform. -The View class serves as the base for subclasses called "widgets," which offer fully implemented -UI objects, like text fields and buttons. The ViewGroup class serves as the base for subclasses called "layouts," -which offer different kinds of layout architecture, like linear, tabular and relative.</p> - -<p>A View object is a data structure whose properties store the layout parameters and content for a specific -rectangular area of the screen. A View object handles its own measurement, layout, drawing, focus change, -scrolling, and key/gesture interactions for the rectangular area of the screen in which it resides. As an -object in the user interface, a View is also a point of interaction for the user and the receiver -of the interaction events.</p> - - -<h2 id="ViewHierarchy">View Hierarchy</h2> - -<p>On the Android platform, you define an Activity's UI using a hierarchy of View and ViewGroup nodes, -as shown in the diagram below. This hierarchy tree can be as simple or complex as you need it to be, and you -can build it up using Android's set of predefined widgets and layouts, or with custom Views that you -create yourself.</p> - -<img src="{@docRoot}images/viewgroup.png" alt="" width="312" height="211" align="center"/> - -<p> -In order to attach the view hierarchy tree to the screen for rendering, your Activity must call the -<code>{@link android.app.Activity#setContentView(int) setContentView()}</code> -method and pass a reference to the root node object. The Android system -receives this reference and uses it to invalidate, measure, and draw the tree. The root node of the hierarchy requests -that its child nodes draw themselves — in turn, each view group node is responsible for calling -upon each of its own child views to draw themselves. -The children may request a size and location within the parent, but the parent object has the final -decision on where how big each child can be. Android parses -the elements of your layout in-order (from the top of the hierarchy tree), instantiating the Views and -adding them to their parent(s). Because these are drawn in-order, if there are elements that -overlap positions, the last one to be drawn will lie on top of others previously drawn to that space.</p> - -<p>For a more detailed discussion on how view hierarchies are measured -and drawn, read <a href="how-android-draws.html">How Android Draws Views</a>.</p> - - -<h2 id="Layout">Layout</h2> - -<p>The most common way to define your layout and express the view hierarchy is with an XML layout file. -XML offers a human-readable structure for the layout, much like HTML. Each element in XML is -either a View or ViewGroup object (or descendent thereof). View objects are leaves in the tree, -ViewGroup objects are branches in the tree (see the View Hierarchy figure above).</p> -<p>The name of an XML element -is respective to the Java class that it represents. So a <code><TextView></code> element creates -a {@link android.widget.TextView} in your UI, and a <code><LinearLayout></code> element creates -a {@link android.widget.LinearLayout} view group. When you load a layout resource, -the Android system initializes these run-time objects, corresponding to the elements in your layout.</p> - -<p>For example, a simple vertical layout with a text view and a button looks like this:</p> -<pre> -<?xml version="1.0" encoding="utf-8"?> -<LinearLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" - android:layout_height="fill_parent" - android:orientation="vertical" > - <TextView android:id="@+id/text" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:text="Hello, I am a TextView" /> - <Button android:id="@+id/button" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:text="Hello, I am a Button" /> -</LinearLayout> -</pre> - -<p>Notice that the LinearLayout element contains both the TextView and the Button. You can nest -another LinearLayout (or other type of view group) inside here, to lengthen the view hierarchy and create a more -complex layout.</p> - -<p>For more on building a UI layout, read <a href="declaring-layout.html">Declaring Layout</a>. - -<div class="sidebox-wrapper"> -<div class="sidebox-inner"> - <p><b>Tip:</b> You can also draw View and ViewGroups objects in Java code, - using the <code>{@link android.view.ViewGroup#addView(View)}</code> methods - to dynamically insert new View and ViewGroup objects.</p> -</div> -</div> - -<p>There are a variety of ways in which you can layout your views. Using more and different kinds of view groups, -you can structure child views and view groups in an infinite number of ways. -Some pre-defined view groups offered by Android (called layouts) include LinearLayout, RelativeLayout, AbsoluteLayout, -TableLayout, GridLayout and others. Each offers a unique set of layout parameters that are used to define the -positions of child views and layout structure.</p> -<p>To learn about some of the different kinds of view groups used for a layout, -read <a href="layout-objects.html">Common Layout Objects</a>.</p> - - -<h2 id="Widgets">Widgets</h2> - -<p>A widget is a View object that serves as an interface for interaction with the user. -Android provides a set of fully implemented -widgets, like buttons, checkboxes, and text-entry fields, so you can quickly build your UI. -Some widgets provided by Android are more complex, like a date picker, a clock, and zoom controls. -But you're not limited to the kinds of widgets provided by the Android platform. If you'd -like to do something more customized and create your own actionable elements, you can, by defining your own -View object or by extending and combining existing widgets.</p> -<p>Read more in <a href="custom-components.html">Building Custom Components</a>.</p> - -<p>For a list of the widgets provided by Android, see the {@link android.widget} package.</p> - - -<h2 id="Events">UI Events</h2> - -<p>Once you've added some Views/widgets to the UI, you probably want to know about the -user's interaction with them, so you can perform actions. To be informed of UI events, you need to -do one of two things:</p> -<ul> - <li><strong>Define an event listener and register it with the View.</strong> More often than not, -this is how you'll listen for events. The View class contains a collection of nested interfaces named -On<em><something></em>Listener, each with a callback method called <code>On<em><something></em>()</code>. -For example, {@link android.view.View.OnClickListener} (for handling "clicks" on a View), -{@link android.view.View.OnTouchListener} (for handling touch screen events in a View), and -{@link android.view.View.OnKeyListener} (for handling device key presses within a View). So if you want your View -to be notified when it is "clicked" (such as when a button is selected), implement OnClickListener and define -its <code>onClick()</code> callback method (where you perform the action upon click), and register it -to the View with <code>{@link android.view.View#setOnClickListener(View.OnClickListener) setOnClickListener()}</code>. -</li> - <li><strong>Override an existing callback method for the View.</strong> This is -what you should do when you've implemented your own View class and want to listen for specific events -that occur within it. Example events you can handle include when the -screen is touched (<code>{@link android.view.View#onTouchEvent(MotionEvent) onTouchEvent()}</code>), when -the trackball is moved (<code>{@link android.view.View#onTrackballEvent(MotionEvent) onTrackballEvent()}</code>), -or when a key on the device is pressed (<code>{@link android.view.View#onKeyDown(int, KeyEvent) -onKeyDown()}</code>). This allows you to define the default behavior for each event inside your custom View and determine -whether the event should be passed on to some other child View. Again, these are callbacks to the View class, -so your only chance to define them is when you -<a href="{@docRoot}guide/topics/ui/custom-components.html">build a custom component</a>. -</li> -</ul> - -<p>Continue reading about handling user interaction with Views in the <a href="ui-events.html">Handling UI Events</a> -document.</p> - - -<h2 id="Menus">Menus</h2> - -<p>Application menus are another important part of an application's UI. Menus offers a reliable interface that reveals -application functions and settings. The most common application menu is revealed by pressing -the MENU key on the device. However, you can also add Context Menus, which may be revealed when the user presses -and holds down on an item.</p> - -<p>Menus are also structured using a View hierarchy, but you don't define this structure yourself. Instead, -you define the <code>{@link android.app.Activity#onCreateOptionsMenu(Menu) onCreateOptionsMenu()}</code> or -<code>{@link android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenu.ContextMenuInfo) onCreateContextMenu()}</code> -callback methods for your Activity and declare the items that you want to include in your menu. -At the appropriate time, Android will automatically create the necessary View hierarchy for the menu and -draw each of your menu items in it.</p> - -<p>Menus also handle their own events, so there's no need to register event listeners on the items in your menu. -When an item in your menu is selected, the <code>{@link android.app.Activity#onOptionsItemSelected(MenuItem) -onOptionsItemSelected()}</code> or -<code>{@link android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}</code> -method will be called by the framework.</p> - -<p>And just like your application layout, you have the option to declare the items for you menu in an XML file.</p> - -<p>Read <a href="{@docRoot}guide/topics/ui/menus.html">Creating Menus</a> to learn more.</p> - - -<h2 id="Advanced">Advanced Topics</h2> - -<p>Once you've grappled the fundamentals of creating a user interface, you can explore -some advanced features for creating a more complex application interface.</p> - -<h3 id="Adapters">Adapters</h3> - -<p>Sometimes you'll want to populate a view group with some information that can't be hard-coded, instead, -you want to bind your view to an external source of data. To do this, you use an AdapterView as -your view group and each child View is initialized and populated with data from the Adapter.</p> -<p>The AdapterView object is an implementation of ViewGroup that determines its child views -based on a given Adapter object. The Adapter acts like a courier between your data source (perhaps an -array of external strings) and the AdapterView, which displays it. There are several implementations -of the Adapter class, for specific tasks, such as the CursorAdapter for reading database data from a Cursor, -or an ArrayAdapter for reading from an arbitrary array.</p> -<p>To learn more about using an Adapter to populate your views, read -<a href="binding.html">Binding to Data with AdapterView</a>.</p> - - -<h3 id="StylesAndThemes">Styles and Themes</h3> - -<p>Perhaps you're not satisfied with the look of the standard widgets. To revise them, you can create some -of your own styles and themes.</p> - -<ul> - <li>A style is a set of one or more formatting attributes that you can apply as a unit to individual elements -in your layout. For example, you could define a style that specifies a certain text size and color, then -apply it to only specific View elements.</li> - <li>A theme is a set of one or more formatting attributes that you can apply as a unit to all activities in -an application, or just a single activity. For example, you could define a theme that sets specific colors for -the window frame and the panel background, and sets text sizes and colors for menus. This theme can then be -applied to specific activities or the entire application.</li> -</ul> - -<p>Styles and themes are resources. Android provides some default style and theme resources that you can use, -or you can declare your own custom style and theme resources.</p> -<p>Learn more about using styles and themes in the -<a href="themes.html">Applying Styles and Themes</a> document.</p> diff --git a/docs/html/guide/topics/ui/layout-objects.jd b/docs/html/guide/topics/ui/layout-objects.jd deleted file mode 100644 index cf85fd6..0000000 --- a/docs/html/guide/topics/ui/layout-objects.jd +++ /dev/null @@ -1,305 +0,0 @@ -page.title=Common Layout Objects -parent.title=User Interface -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#framelayout">FrameLayout</a></li> - <li><a href="#linearlayout">LinearLayout</a></li> - <li><a href="#tablelayout">TableLayout</a></li> - <li><a href="#absolutelayout">AbsoluteLayout</a></li> - <li><a href="#relativelayout">RelativeLayout</a></li> - <li><a href="#viewgroupsummary">Summary of Important View Groups</a></li> - </ol> -</div> -</div> - -<p>This section describes some of the more common types of layout objects -to use in your applications. Like all layouts, they are subclasses of {@link android.view.ViewGroup ViewGroup}.</p> - -<p>Also see the <a href="{@docRoot}guide/tutorials/views/index.html">Hello Views</a> tutorials for -some guidance on using more Android View layouts.</p> - -<h2 id="framelayout">FrameLayout</h2> -<p>{@link android.widget.FrameLayout FrameLayout} is the simplest type of layout -object. It's basically a blank space on your screen that you can -later fill with a single object — for example, a picture that you'll swap in and out. -All child elements of the FrameLayout are pinned to the top left corner of the screen; you cannot -specify a different location for a child view. Subsequent child views will simply be drawn over previous ones, -partially or totally obscuring them (unless the newer object is transparent). -</p> - - -<h2 id="linearlayout">LinearLayout</h2> -<p>{@link android.widget.LinearLayout LinearLayout} aligns all children in a -single direction — vertically or horizontally, depending on how you -define the <code>orientation</code> attribute. All children are -stacked one after the other, so a vertical list will only have one child per -row, no matter how wide they are, and a horizontal list will only be one row -high (the height of the tallest child, plus padding). A {@link -android.widget.LinearLayout LinearLayout} respects <em>margin</em>s between children -and the <em>gravity</em> (right, center, or left alignment) of each child. </p> - -<p>{@link android.widget.LinearLayout LinearLayout} also supports assigning a -<em>weight</em> to individual children. This attribute assigns an "importance" value to a view, -and allows it to expand to fill any remaining space in the parent view. -Child views can specify an integer weight value, and then any remaining space in the view group is -assigned to children in the proportion of their declared weight. Default -weight is zero. For example, if there are three text boxes and two of -them declare a weight of 1, while the other is given no weight (0), the third text box without weight -will not grow and will only occupy the area required by its content. -The other two will expand equally to fill the space remaining after all three boxes are measured. -If the third box is then given a weight of 2 (instead of 0), then it is now declared -"more important" than both the others, so it gets half the total remaining space, while the first two -share the rest equally.</p> - -<div class="sidebox"> -<p><strong>Tip</strong>: To create a proportionate size -layout on the screen, create a container view group object with the -<code>layout_width</code> and <code>layout_height</code> attributes set to <var>fill_parent</var>; assign -the children <code>height</code> or <code>width</code> to <code>0</code> (zero); then assign relative -<code>weight</code> values -to each child, depending on what proportion of the screen each should -have.</p> -</div> - -<p>The following two forms represent a {@link android.widget.LinearLayout LinearLayout} with a set of elements: a -button, some labels and text boxes. The text boxes have their width set to <var>fill_parent</var>; other -elements are set to <var>wrap_content</var>. The gravity, by default, is left. -The difference between the two versions of the form is that the form -on the left has weight values unset (0 by default), while the form on the right has -the comments text box weight set to 1. If the Name textbox had also been set -to 1, the Name and Comments text boxes would be the same height. </p> - -<img src="{@docRoot}images/linearlayout.png" alt="" /> - -<p>Within a horizontal {@link android.widget.LinearLayout LinearLayout}, items are aligned by the position of -their text base line (the first line of the first list element — topmost or -leftmost — is considered the reference line). This is so that people scanning -elements in a form shouldn't have to jump up and down to read element text in -neighboring elements. This can be turned off by setting -<code>android:baselineAligned="false"</code> in the layout XML. </p> - -<p>To view other sample code, see the -<a href="{@docRoot}guide/tutorials/views/hello-linearlayout.html">Hello LinearLayout</a> tutorial.</p> - - -<h2 id="tablelayout">TableLayout</h2> -<p>{@link android.widget.TableLayout} positions its children into rows - and columns. TableLayout containers do not display border lines for their rows, columns, - or cells. The table will have as many columns as the row with the most cells. A table can leave -cells empty, but cells cannot span columns, as they can in HTML.</p> -<p>{@link android.widget.TableRow} objects are the child views of a TableLayout -(each TableRow defines a single row in the table). -Each row has zero or more cells, each of which is defined by any kind of other View. So, the cells of a row may be -composed of a variety of View objects, like ImageView or TextView objects. -A cell may also be a ViewGroup object (for example, you can nest another TableLayout as a cell).</p> -<p>The following sample layout has two rows and two cells in each. The accompanying screenshot shows the -result, with cell borders displayed as dotted lines (added for visual effect). </p> - -<table class="columns"> - <tr> - <td> - <pre> -<?xml version="1.0" encoding="utf-8"?> -<TableLayout xmlns:android="http://schemas.android.com/apk/res/android" - android:layout_width="fill_parent" - android:layout_height="fill_parent" - android:stretchColumns="1"> - <TableRow> - <TextView - android:text="@string/table_layout_4_open" - android:padding="3dip" /> - <TextView - android:text="@string/table_layout_4_open_shortcut" - android:gravity="right" - android:padding="3dip" /> - </TableRow> - - <TableRow> - <TextView - android:text="@string/table_layout_4_save" - android:padding="3dip" /> - <TextView - android:text="@string/table_layout_4_save_shortcut" - android:gravity="right" - android:padding="3dip" /> - </TableRow> -</TableLayout> -</pre></td> - <td><img src="{@docRoot}images/table_layout.png" alt="" style="margin:0" /></td> - </tr> -</table> - -<p>Columns can be hidden, marked to stretch and fill the available screen space, - or can be marked as shrinkable to force the column to shrink until the table - fits the screen. See the {@link android.widget.TableLayout TableLayout reference} -documentation for more details. </p> - -<p>To view sample code, see the <a href="{@docRoot}guide/tutorials/views/hello-tablelayout.html">Hello -TableLayout</a> tutorial.</p> - - -<h2 id="absolutelayout">AbsoluteLayout</h2> -<p>{@link android.widget.AbsoluteLayout} enables child views to specify - their own exact x/y coordinates on the screen. Coordinates <em>(0,0)</em> is the upper left - corner, and values increase as you move down and to the right. Margins are not - supported, and overlapping elements are allowed (although not recommended). We - generally recommend against using AbsoluteLayout unless you have good reasons - to use it, because it is fairly rigid and does not adjust to different types of - displays. </p> - - -<h2 id="relativelayout">RelativeLayout</h2> -<p>{@link android.widget.RelativeLayout} lets child views specify their - position relative to the parent view or to each other (specified by ID). So you can - align two elements by right border, or make one below another, centered in - the screen, centered left, and so on. Elements are rendered in the order given, so if the first element - is centered in the screen, other elements aligning themselves to that element - will be aligned relative to screen center. Also, because of this ordering, if using XML to specify this layout, - the element that you will reference (in order to position other view objects) must be listed in the XML -file before you refer to it from the other views via its reference ID. </p> -<p>The example below shows an XML file and the resulting screen in the UI. -Note that the attributes that refer to relative elements (e.g., <var>layout_toLeft</var>) -refer to the ID using the syntax of a relative resource -(<var>@id/<em>id</em></var>). </p> - -<table class="columns"> - <tr> - <td> - <pre> -<?xml version="1.0" encoding="utf-8"?> -<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:background="@drawable/blue" - android:padding="10px" > - - <TextView android:id="@+id/label" - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:text="Type here:" /> - - <EditText android:id="@+id/entry" - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:background="@android:drawable/editbox_background" - android:layout_below="@id/label" /> - - <Button android:id="@+id/ok" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:layout_below="@id/entry" - android:layout_alignParentRight="true" - android:layout_marginLeft="10px" - android:text="OK" /> - - <Button android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:layout_toLeftOf="@id/ok" - android:layout_alignTop="@id/ok" - android:text="Cancel" /> -</RelativeLayout> -</pre></td> - <td><img src="{@docRoot}images/designing_ui_layout_example.png" alt="" style="margin:0" /></td> - </tr> -</table> - - -<p>Some of these properties are supported directly by - the element, and some are supported by its LayoutParams member (subclass RelativeLayout - for all the elements in this screen, because all elements are children of a RelativeLayout - parent object). The defined RelativeLayout parameters are: <code>width</code>, <code>height</code>, - <code>below</code>, <code>alignTop</code>, <code>toLeft</code>, <code>padding[Bottom|Left|Right|Top]</code>, - and <code>margin[Bottom|Left|Right|Top]</code>. Note that some of these parameters specifically support - relative layout positions — their values must be the ID of the element to which you'd like this view laid relative. - For example, assigning the parameter <code>toLeft="my_button"</code> to a TextView would place the TextView to - the left of the View with the ID <var>my_button</var> (which must be written in the XML <em>before</em> the TextView). </p> - -<p>To view this sample code, see the <a href="{@docRoot}guide/tutorials/views/hello-relativelayout.html">Hello -RelativeLayout</a> tutorial.</p> - - -<h2 id="viewgroupsummary">Summary of Important View Groups</h2> -<p>These objects all hold child UI elements. Some provide their own form of a visible UI, while others - are invisible structures that only manage the layout of their child views. </p> -<table width="100%" border="1"> - <tr> - <th scope="col">Class</th> - <th scope="col">Description</th> - </tr> - <tr> - <td>{@link android.widget.AbsoluteLayout AbsoluteLayout}<br /></td> - <td>Enables you to specify the location of child objects relative to the - parent in exact measurements (for example, pixels). </td> - </tr> - <tr> - <td>{@link android.widget.FrameLayout FrameLayout}</td> - <td>Layout that acts as a view frame to display - a single object. </td> - </tr> - <tr> - <td>{@link android.widget.Gallery Gallery} </td> - <td>A horizontal scrolling display of images, from a bound list. </td> - </tr> - <tr> - <td>{@link android.widget.GridView GridView} </td> - <td>Displays a scrolling grid of m columns and n rows.</td> - </tr> - <tr> - <td>{@link android.widget.LinearLayout LinearLayout} </td> - <td>A layout that organizes its children into a single horizontal or vertical - row. It creates a scrollbar if the length of the window exceeds the length - of the screen. </td> - </tr> - <tr> - <td>{@link android.widget.ListView ListView} </td> - <td>Displays a scrolling single column list. </td> - </tr> - <tr> - <td>{@link android.widget.RelativeLayout RelativeLayout} </td> - <td>Enables you to specify the location of child objects relative to each - other (child A to the left of child B) or to the parent (aligned to the - top of the parent). </td> - </tr> - <tr> - <td>{@link android.widget.ScrollView ScrollView} </td> - <td>A vertically scrolling column of elements. </td> - </tr> - <tr> - <td>{@link android.widget.Spinner Spinner} </td> - <td>Displays a single item at a time from a bound list, inside a one-row - textbox. Rather like a one-row listbox that can scroll either horizontally - or vertically. </td> - </tr> - <tr> - <td>{@link android.view.SurfaceView SurfaceView} </td> - <td>Provides direct access to a dedicated drawing surface. It can hold child - views layered on top of the surface, but is intended for applications - that need to draw pixels, rather than using widgets. </td> - </tr> - <tr> - <td>{@link android.widget.TabHost TabHost} </td> - <td>Provides a tab selection list that monitors clicks and enables the application - to change the screen whenever a tab is clicked. </td> - </tr> - <tr> - <td>{@link android.widget.TableLayout TableLayout} </td> - <td>A tabular layout with an arbitrary number of rows and columns, each cell - holding the widget of your choice. The rows resize to fit the largest - column. The cell borders are not - visible. </td> - </tr> - <tr> - <td>{@link android.widget.ViewFlipper ViewFlipper} </td> - <td>A list that displays one item at a time, inside a one-row textbox. It - can be set to swap items at timed intervals, like a slide show. </td> - </tr> - <tr> - <td>{@link android.widget.ViewSwitcher ViewSwitcher} </td> - <td>Same as ViewFlipper. </td> - </tr> -</table> diff --git a/docs/html/guide/topics/ui/menus.jd b/docs/html/guide/topics/ui/menus.jd deleted file mode 100644 index bae94ca..0000000 --- a/docs/html/guide/topics/ui/menus.jd +++ /dev/null @@ -1,522 +0,0 @@ -page.title=Creating Menus -parent.title=User Interface -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>Key classes</h2> - <ol> - <li>{@link android.view.Menu}</li> - <li>{@link android.view.ContextMenu}</li> - <li>{@link android.view.SubMenu}</li> - </ol> - <h2>In this document</h2> - <ol> - <li><a href="#options-menu">Options Menu</a></li> - <li><a href="#context-menu">Context Menu</a></li> - <li><a href="#submenu">Submenu</a></li> - <li><a href="#xml">Define Menus in XML</a></li> - <li><a href="#features">Menu Features</a> - <ol> - <li><a href="#groups">Menu groups</a></li> - <li><a href="#checkable">Checkable menu items</a></li> - <li><a href="#shortcuts">Shortcut keys</a></li> - <li><a href="#intents">Menu item intents</a></li> - </ol> - </li> - </ol> -</div> -</div> - -<p>Menus are an important part of any application. They provide familiar interfaces -that reveal application functions and settings. Android offers an easy programming interface -for developers to provide standardized application menus for various situations.</p> - -<p>Android offers three fundamental types of application menus:</p> -<dl> - <dt><strong>Options Menu</strong></dt> - <dd>This is the primary set of menu items for an Activity. It is revealed by pressing - the device MENU key. Within the Options Menu are two groups of menu items: - <dl style="margin-top:1em"> - <dt><em>Icon Menu</em></dt> - <dd>This is the collection of items initially visible at the bottom of the screen - at the press of the MENU key. It supports a maximum of six menu items. - These are the only menu items that support icons and the only menu items that <em>do not</em> support - checkboxes or radio buttons.</dd> - <dt><em>Expanded Menu</em></dt> - <dd>This is a vertical list of items exposed by the "More" menu item from the Icon Menu. - It exists only when the Icon Menu becomes over-loaded and is comprised of the sixth - Option Menu item and the rest.</dd> - </dl> - </dd> - <dt><strong>Context Menu</strong></dt> - <dd>This is a floating list of menu items that may appear when you perform a long-press on a View - (such as a list item). </dd> - <dt><strong>Submenu</strong></dt> - <dd>This is a floating list of menu items that is revealed by an item in the Options Menu - or a Context Menu. A Submenu item cannot support nested Submenus. </dd> -</dl> - - -<h2 id="options-menu">Options Menu</h2> -<img align="right" src="{@docRoot}images/options_menu.png" /> -<p>The Options Menu is opened by pressing the device MENU key. -When opened, the Icon Menu is displayed, which holds the first six menu items. -If more than six items are added to the Options Menu, then those that can't fit -in the Icon Menu are revealed in the Expanded Menu, via the "More" menu item. The Expanded Menu -is automatically added when there are more than six items.</p> - -<p>The Options Menu is where you should include basic application functions -and any necessary navigation items (e.g., to a home screen or application settings). -You can also add <a href="#submenu">Submenus</a> for organizing topics -and including extra menu functionality.</p> - -<p>When this menu is opened for the first time, -the Android system will call the Activity <code>{@link android.app.Activity#onCreateOptionsMenu(Menu) -onCreateOptionsMenu()}</code> callback method. Override this method in your Activity -and populate the {@link android.view.Menu} object given to you. You can populate the menu by -inflating a menu resource that was <a href="#xml">defined in XML</a>, or by calling -<code>{@link android.view.Menu#add(CharSequence) add()}</code> -for each item you'd like in the menu. This method adds a {@link android.view.MenuItem}, and returns the -newly created object to you. You can use the returned MenuItem to set additional properties like -an icon, a keyboard shortcut, an intent, and other settings for the item.</p> - -<p>There are multiple <code>{@link android.view.Menu#add(CharSequence) add()}</code> methods. -Usually, you'll want to use one that accepts an <var>itemId</var> argument. -This is a unique integer that allows you to identify the item during a callback.</p> - -<p>When a menu item is selected from the Options Menu, you will recieve a callback to the -<code>{@link android.app.Activity#onOptionsItemSelected(MenuItem) onOptionsItemSelected()}</code> -method of your Activity. This callback passes you the -<code>MenuItem</code> that has been selected. You can identify the item by requesting the -<var>itemId</var>, with <code>{@link android.view.MenuItem#getItemId() getItemId()}</code>, -which returns the integer that was assigned with the <code>add()</code> method. Once you identify -the menu item, you can take the appropriate action.</p> - -<p>Here's an example of this procedure, inside an Activity, wherein we create an -Options Menu and handle item selections:</p> - -<pre> -/* Creates the menu items */ -public boolean onCreateOptionsMenu(Menu menu) { - menu.add(0, MENU_NEW_GAME, 0, "New Game"); - menu.add(0, MENU_QUIT, 0, "Quit"); - return true; -} - -/* Handles item selections */ -public boolean onOptionsItemSelected(MenuItem item) { - switch (item.getItemId()) { - case MENU_NEW_GAME: - newGame(); - return true; - case MENU_QUIT: - quit(); - return true; - } - return false; -} -</pre> - -<p>The <code>add()</code> method used in this sample takes four arguments: -<var>groupId</var>, <var>itemId</var>, <var>order</var>, and <var>title</var>. -The <var>groupId</var> allows you to associate this menu item with a group of other items -(more about <a href="#groups">Menu groups</a>, below) — in -this example, we ignore it. <var>itemId</var> is a unique integer that we give the -MenuItem so that can identify it in the next callback. <var>order</var> allows us to -define the display order of the item — by default, they are displayed by the -order in which we add them. <var>title</var> is, of course, the name that goes on the -menu item (this can also be a -<a href="{@docRoot}guide/topics/resources/available-resources.html#stringresources">string resource</a>, -and we recommend you do it that way for easier localization).</p> - -<p class="note"><strong>Tip:</strong> -If you have several menu items that can be grouped together with a title, -consider organizing them into a <a href="#submenu">Submenu</a>.</p> - -<h3>Adding icons</h3> -<p>Icons can also be added to items that appears in the Icon Menu with -<code>{@link android.view.MenuItem#setIcon(Drawable) setIcon()}</code>. For example:</p> -<pre> -menu.add(0, MENU_QUIT, 0, "Quit") - .setIcon(R.drawable.menu_quit_icon);</pre> - -<h3>Modifying the menu</h3> -<p>If you want to sometimes re-write the Options Menu as it is opened, override the -<code>{@link android.app.Activity#onPrepareOptionsMenu(Menu) onPrepareOptionsMenu()}</code> method, which is -called each time the menu is opened. This will pass you the Menu object, just like the -<code>onCreateOptionsMenu()</code> callback. This is useful if you'd like to add or remove -menu options depending on the current state of an application or game.</p> - -<p class="note"><strong>Note:</strong> -When changing items in the menu, it's bad practice to do so based on the currently selected item. -Keep in mind that, when in touch mode, there will not be a selected (or focused) item. Instead, you -should use a <a href="#context-menu">Context Menu</a> for such behaviors, when you want to provide -functionality based on a particular item in the UI.</p> - - -<h2 id="context-menu">Context Menu</h2> -<p>The Android context menu is similar, in concept, to the menu revealed with a "right-click" on a PC. -When a view is registered to a context menu, -performing a "long-press" (press and hold for about two seconds) on the object -will reveal a floating menu that provides functions relating to that item. -Context menus can be registered to any View object, -however, they are most often used for items in a -{@link android.widget.ListView}, which helpfully indicates the presence of the context menu -by transforming the background color of the ListView item when pressed. -(The items in the phone's contact list offer an example of this feature.) -</p> - -<p class="note"><strong>Note:</strong> Context menu items do not support icons or shortcut keys.</p> - -<p>To create a context menu, you must override the Activity's context menu callback methods: -<code>{@link android.app.Activity#onCreateContextMenu(ContextMenu,View,ContextMenuInfo) onCreateContextMenu()}</code> and -<code>{@link android.app.Activity#onContextItemSelected(MenuItem) onContextItemSelected()}</code>. -Inside the <code>onCreateContextMenu()</code> callback method, you can add menu items using one of the -<code>{@link android.view.Menu#add(CharSequence) add()}</code> methods, or by -inflating a menu resource that was <a href="#xml">defined in XML</a>. -Then, register a {@link android.view.ContextMenu} for the View, with -<code>{@link android.app.Activity#registerForContextMenu(View) registerForContextMenu()}</code>.</p> - -<p>For example, here is some code that can be used with the -<a href="{@docRoot}guide/tutorials/notepad/index.html">Notepad application</a> -to add a context menu for each note in the list:</p> -<pre> -public void onCreateContextMenu(ContextMenu menu, View v, - ContextMenuInfo menuInfo) { - super.onCreateContextMenu(menu, v, menuInfo); - menu.add(0, EDIT_ID, 0, "Edit"); - menu.add(0, DELETE_ID, 0, "Delete"); -} - -public boolean onContextItemSelected(MenuItem item) { - AdapterContextMenuInfo info = (AdapterContextMenuInfo) item.getMenuInfo(); - switch (item.getItemId()) { - case EDIT_ID: - editNote(info.id); - return true; - case DELETE_ID: - deleteNote(info.id); - return true; - default: - return super.onContextItemSelected(item); - } -} -</pre> - -<p>In <code>onCreateContextMenu()</code>, we are given not only the ContextMenu to -which we will add {@link android.view.MenuItem}s, but also the {@link android.view.View} -that was selected and a {@link android.view.ContextMenu.ContextMenuInfo ContextMenuInfo} object, -which provides additional information about the object that was selected. -In this example, nothing special is done in <code>onCreateContextMenu()</code> — just -a couple items are added as usual. In the <code>onContextItemSelected()</code> -callback, we request the {@link android.widget.AdapterView.AdapterContextMenuInfo AdapterContextMenuInfo} -from the {@code MenuItem}, which provides information about the currently selected item. -All we need from -this is the list ID for the selected item, so whether editing a note or deleting it, -we find the ID with the {@code AdapterContextMenuInfo.info} field of the object. This ID -is passed to the <code>editNote()</code> and <code>deleteNote()</code> methods to perfrom -the respective action.</p> - -<p>Now, to register this context menu for all the items in a {@link android.widget.ListView}, -we pass the entire {@code ListView} to the -<code>{@link android.app.Activity#registerForContextMenu(View)}</code> method:</p> - -<pre>registerForContextMenu(getListView());</pre> -<p>Remember, you can pass any View object to register a context menu. Here, -<code>{@link android.app.ListActivity#getListView()}</code> returns the ListView -object used in the Notepad application's {@link android.app.ListActivity}. As such, each item -in the list is registered to this context menu.</p> - - - -<h2 id="submenu">Submenus</h2> -<p>A sub menu can be added within any menu, except another sub menu. -These are very useful when your application has a lot of functions that may be -organized in topics, like the items in a PC application's menu bar (File, Edit, View, etc.).</p> - -<p>A sub menu is created by adding it to an existing {@link android.view.Menu} -with <code>{@link android.view.Menu#addSubMenu(CharSequence) addSubMenu()}</code>. -This returns a {@link android.view.SubMenu} object (an extension of {@link android.view.Menu}). -You can then add additional items to this menu, with the normal routine, using -the <code>{@link android.view.Menu#add(CharSequence) add()}</code> methods. For example:</p> - -<pre> -public boolean onCreateOptionsMenu(Menu menu) { - boolean result = super.onCreateOptionsMenu(menu); - - SubMenu fileMenu = menu.addSubMenu("File"); - SubMenu editMenu = menu.addSubMenu("Edit"); - fileMenu.add("new"); - fileMenu.add("open"); - fileMenu.add("save"); - editMenu.add("undo"); - editMenu.add("redo"); - - return result; -} -</pre> -<p>Callbacks for items selected in a sub menu are made to the parent menu's callback method. -For the example above, selections in the sub menu will be handled by the -<code>onOptionsItemSelected()</code> callback.</p> -<p>You can also add Submenus when you <a href="#xml">define the parent menu in XML</a>.</p> - - -<h2 id="xml">Define Menus in XML</h2> -<p>Just like Android UI layouts, you can define application menus in XML, then inflate them -in your menu's <code>onCreate...()</code> callback method. This makes your application code cleaner and -separates more interface design into XML, which is easier to visualize.</p> - -<p>To start, create a new folder in your project <code>res/</code> directory called <code>menu</code>. -This is where you should keep all XML files that define your application menus.</p> - -<p>In a menu XML layout, there are -three valid elements: <code><menu></code>, <code><group></code> and <code><item></code>. The -<code>item</code> and <code>group</code> elements must be children of a <code>menu</code>, but <code>item</code> -elements may also be the children of a <code>group</code>, and another <code>menu</code> element may be the child -of an <code>item</code> (to create a Submenu). Of course, the root node of any file -must be a <code>menu</code> element.</p> - -<p>As an example, we'll define the same menu created in the <a href="#options-menu">Options Menu</a> section, -above. We start with an XML file named <code>options_menu.xml</code> inside the <code>res/menu/</code> folder:</p> -<pre> -<menu xmlns:android="http://schemas.android.com/apk/res/android"> - <item android:id="@+id/new_game" - android:title="New Game" /> - <item android:id="@+id/quit" - android:title="Quit" /> -</menu> -</pre> - -<p>Then, in the <code>onCreateOptionsMenu()</code> method, we inflate this resource using -<code>{@link android.view.MenuInflater#inflate(int,Menu) MenuInflater.inflate()}</code>:</p> -<pre> -public boolean onCreateOptionsMenu(Menu menu) { - MenuInflater inflater = getMenuInflater(); - inflater.inflate(R.menu.options_menu, menu); - return true; -} -</pre> - -<p>The <code>{@link android.app.Activity#getMenuInflater()}</code> method returns the {@link android.view.MenuInflater} -for our activity's context. We then call <code>{@link android.view.MenuInflater#inflate(int,Menu) inflate()}</code>, -passing it a pointer to our menu resource and the Menu object given by the callback.</code></p> - -<p>While this small sample may seem like more effort, compared to creating the menu items in the -<code>onCreateOptionsMenu()</code> method, this will save a lot of trouble when dealing with more items -and it keeps your application code clean.</p> - -<p>You can define <a href="#groups">menu groups</a> by wrapping <code>item</code> elements in a <code>group</code> -element, and create Submenus by nesting another <code>menu</code> inside an <code>item</code>. -Each element also supports all the necessary attributes to control features like shortcut keys, -checkboxes, icons, and more. To learn about these attributes and more about the XML syntax, see the Menus -topic in the <a href="{@docRoot}guide/topics/resources/available-resources.html#menus">Available -Resource Types</a> document.</p> - -<h2 id="features">Menu Features</h2> -<p>Here are some other features that can be applied to most menu items.</p> - -<h3 id="groups">Menu groups</h3> -<p>When adding new items to a menu, you can optionally include each item in a group. -A menu group is a collection of menu items that can share certain traits, like -whether they are visible, enabled, or checkable.</p> - -<p>A group is defined by an integer (or a resource id, in XML). A menu item is added to the group when it is -added to the menu, using one of the <code>add()</code> methods that accepts a <var>groupId</var> -as an argument, such as <code>{@link android.view.Menu#add(int,int,int,int)}</code>.</p> - -<p>You can show or hide the entire group with -<code>{@link android.view.Menu#setGroupVisible(int,boolean) setGroupVisible()}</code>; -enable or disable the group with -<code>{@link android.view.Menu#setGroupEnabled(int,boolean) setGroupEnabled()}</code>; -and set whether the items can be checkable with -<code>{@link android.view.Menu#setGroupCheckable(int,boolean,boolean) setGroupCheckable()}</code>. -</p> - -<h3 id="checkable">Checkable menu items</h3> -<img align="right" src="{@docRoot}images/radio_buttons.png" alt="" /> -<p>Any menu item can be used as an interface for turning options on and off. This can -be indicated with a checkbox for stand-alone options, or radio buttons for groups of -mutually exlusive options (see the screenshot, to the right).</p> - -<p class="note"><strong>Note:</strong> Menu items in the Icon Menu cannot -display a checkbox or radio button. If you choose to make items in the Icon Menu checkable, -then you must personally indicate the state by swapping the icon and/or text -each time the state changes between on and off.</p> - -<p>To make a single item checkable, use the <code>{@link android.view.MenuItem#setCheckable(boolean) -setCheckable()}</code> method, like so:</p> -<pre> -menu.add(0, VIBRATE_SETTING_ID, 0, "Vibrate") - .setCheckable(true); -</pre> -<p>This will display a checkbox with the menu item (unless it's in the Icon Menu). When the item -is selected, the <code>onOptionsItemSelected()</code> callback is called as usual. It is here that -you must set the state of the checkbox. You can query the current state of the item with -<code>{@link android.view.MenuItem#isChecked()}</code> and set the checked state with -<code>{@link android.view.MenuItem#setChecked(boolean) setChecked()}</code>. -Here's what this looks like inside the -<code>onOptionsItemSelected()</code> callback:</p> -<pre> -switch (item.getItemId()) { -case VIBRATE_SETTING_ID: - if (item.isChecked()) item.setChecked(false); - else item.setChecked(true); - return true; -... -} -</pre> - -<p>To make a group of mutually exclusive radio button items, simply -assign the same group ID to each menu item -and call <code>{@link android.view.Menu#setGroupCheckable(int,boolean,boolean) -setGroupCheckable()}</code>. In this case, you don't need to call <code>setCheckable()</code> -on each menu items, because the group as a whole is set checkable. Here's an example of -two mutually exclusive options in a Submenu:</p> -<pre> -SubMenu subMenu = menu.addSubMenu("Color"); -subMenu.add(COLOR_MENU_GROUP, COLOR_RED_ID, 0, "Red"); -subMenu.add(COLOR_MENU_GROUP, COLOR_BLUE_ID, 0, "Blue"); -subMenu.setGroupCheckable(COLOR_MENU_GROUP, true, true); -</pre> -<p>In the <code>setGroupCheckable()</code> method, the first argument is the group ID -that we want to set checkable. The second argument is whether we want the group items -to be checkable. The last one is whether we want each item to be exclusively checkable -(if we set this <em>false</em>, then all the items will be checkboxes instead of radio buttons). -When the group is set to be exclusive (radio buttons), each time a new item is selected, -all other are automatically de-selected.</p> -<p> - -<p class="note"><strong>Note:</strong> -Checkable menu items are intended to be used only on a per-session basis and not saved to the device -(e.g., the <em>Map mode</em> setting in the Maps application is not saved — screenshot above). -If there are application settings that you would like to save for the user, -then you should store the data using <a href="#{@docRoot}guide/topics/data/data-storage.html#pref">Preferences</a>, -and manage them with a {@link android.preference.PreferenceActivity}.</p> - - -<h3 id="shortcuts">Shortcut keys</h3> -<p>Quick access shortcut keys using letters and/or numbers can be added to menu items with -<code>setAlphabeticShortcut(char)</code> (to set char shortcut), <code>setNumericShortcut(int)</code> -(to set numeric shortcut), -or <code>setShortcut(char,int)</code> (to set both)</code>. Case is <em>not</em> sensitive. - -For example:</p> -<pre> -menu.add(0, MENU_QUIT, 0, "Quit") - .setAlphabeticShortcut('q'); -</pre> -<p>Now, when the menu is open (or while holding the MENU key), pressing the "q" key will -select this item.</p> -<p>This shortcut key will be displayed as a tip in the menu item, below the menu item name -(except for items in the Icon Menu).</p> -<p class="note"><strong>Note:</strong> Shortcuts cannot be added to items in a Context Menu.</p> - - -<h3 id="intents">Menu item intents</h3> -<p>If you've read the <a href="{@docRoot}guide/topics/fundamentals.html">Application -Fundamentals</a>, then you're at least a little familiar -with Android Intents. These allow applications to bind with each other, share information, -and perform user tasks cooperatively. Just like your application might fire an Intent to launch a web browser, -an email client, or another Activity in your application, -you can perform such actions from within a menu. -There are two ways to do this: define an Intent and assign it to a single menu item, or -define an Intent and allow Android to search the device for activities and dynamically add a -menu item for each one that meets the Intent criteria.</p> - -<p>For more information on creating Intents and providing your application's services to other applications, -read the <a href="/guide/topics/intents/intents-filters.html">Intents -and Intent Filters</a> document.</p> - -<h4>Set an intent for a single menu item</h4> -<p>If you want to offer a specific menu item that launches a new Activity, then you -can specifically define an Intent for the menu item with the -<code>{@link android.view.MenuItem#setIntent(Intent) -setIntent()}</code> method.</p> - -<p>For example, inside the <code>{@link android.app.Activity#onCreateOptionsMenu(Menu) -onCreateOptionsMenu()}</code> method, you can define a new menu item with an Intent like this:</p> -<pre> -MenuItem menuItem = menu.add(0, PHOTO_PICKER_ID, 0, "Select Photo"); -menuItem.setIntent(new Intent(this, PhotoPicker.class)); -</pre> -<p>Android will automatically launch the Activity when the item is selected.</p> - -<p class="note"><strong>Note:</strong> This will not return a result to your Activity. -If you wish to be returned a result, then do not use <code>setIntent()</code>. -Instead, handle the selection as usual in the <code>onOptionsMenuItemSelected()</code> -or <code>onContextMenuItemSelected()</code> callback and call -<code>{@link android.app.Activity#startActivityForResult(Intent,int) startActivityForResult()}</code>. -</p> - -<h4>Dynamically add intents</h4> - -<p>If there are potentially multiple activities that are relevant to your current -Activity or selected item, then the application can dynamically add menu items that execute other -services.</p> -<p>During menu creation, define an Intent with the category <var>Intent.ALTERNATIVE_CATEGORY</var> and/or -<var>Intent.SELECTED_ALTERNATIVE</var>, the MIME type currently selected (if any), and any other -requirements, the same way as you would satisfy an intent filter to open a new -Activity. Then call -<code>{@link android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) -addIntentOptions()}</code> to have Android search for any services meeting those requirements -and add them to the menu for you. If there are no applications installed -that satisfy the Intent, then no additional menu items are added.</p> - -<p class="note"><strong>Note:</strong> -<var>SELECTED_ALTERNATIVE</var> is used to handle the currently selected element on the -screen. So, it should only be used when creating a Menu in <code>onCreateContextMenu()</code> or -<code>onPrepareOptionsMenu()</code>, which is called every time the Options Menu is opened.</p> - -<p>Here's an example demonstrating how an application would search for -additional services to display on its menu.</p> - -<pre> -public boolean onCreateOptionsMenu(Menu menu){ - super.onCreateOptionsMenu(menu); - - // Create an Intent that describes the requirements to fulfill, to be included - // in our menu. The offering app must include a category value of Intent.CATEGORY_ALTERNATIVE. - Intent intent = new Intent(null, getIntent().getData()); - intent.addCategory(Intent.CATEGORY_ALTERNATIVE); - - // Search for, and populate the menu with, acceptable offering applications. - menu.addIntentOptions( - thisClass.INTENT_OPTIONS, // Menu group - 0, // Unique item ID (none) - 0, // Order for the items (none) - this.getComponentName(), // The current Activity name - null, // Specific items to place first (none) - intent, // Intent created above that describes our requirements - 0, // Additional flags to control items (none) - null); // Array of MenuItems that corrolate to specific items (none) - - return true; -}</pre> - -<p>For each Activity found that provides an Intent Filter matching the Intent defined, a menu -item will be added, using the <var>android:label</var> value of the intent filter as the text -for the menu item. -The <code>{@link android.view.Menu#addIntentOptions(int,int,int,ComponentName,Intent[],Intent,int,MenuItem[]) addIntentOptions()}</code> method will also return the number of menu items added.</p> -<p>Also be aware that, when <code>addIntentOptions()</code> is called, it will override any and all -menu items in the menu group specified in the first argument.</p> - -<p>If you wish to offer the services of your Activity to other application menus, then you -only need to define an intent filter as usual. Just be sure to include the <var>ALTERNATIVE</var> and/or -<var>SELECTED_ALTERNATIVE</var> values in the <var>name</var> attribute of -a <code><category></code> element in the intent filter. For example:</p> -<pre> -<intent-filter label="Resize Image"> - ... - <category android:name="android.intent.category.ALTERNATIVE" /> - <category android:name="android.intent.category.SELECTED_ALTERNATIVE" /> - ... -</intent-filter> -</pre> -<p>read more about writing intent filters in the -<a href="/guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> document.</p> - -<p>For a sample application using this technique, see the -<a href="{@docRoot}guide/samples/NotePad/index.html">Note Pad</a> -sample code.</p> diff --git a/docs/html/guide/topics/ui/themes.jd b/docs/html/guide/topics/ui/themes.jd deleted file mode 100644 index 956ffe1..0000000 --- a/docs/html/guide/topics/ui/themes.jd +++ /dev/null @@ -1,182 +0,0 @@ -page.title=Applying Styles and Themes -parent.title=User Interface -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#styles">Styles</a></li> - <li><a href="#themes">Themes</a> - <ol> - <li><a href="#inTheManifest">Set the theme in the manifest</a></li> - <li><a href="#fromTheApp">Set the theme from the application</a></li> - </ol> - </li> - </ol> - <h2>See also</h2> - <ol> - <li><a href="{@docRoot}guide/topics/resources/available-resources.html#stylesandthemes">Style and Theme Resources</a></li> - </ol> -</div> -</div> - -<p>When designing your application, you can use <em>styles</em> and <em>themes</em> to apply uniform formatting to its various screens and UI elements. - -<ul> - <li>A style is a set of one or more formatting attributes that you can apply as a unit to single elements in your layout XML file(s). For example, you could define a style that specifies a certain text size and color, then apply it to instances of a certain type of View element.</li> - <li>A theme is a set of one or more formatting attributes that you can apply as a unit to all activities in an application or just a single activity. For example, you could define a theme that sets specific colors for the window frame and the panel foreground and background, and sets text sizes and colors for menus, then apply it to the activities of your application.</li> -</ul> - -<p>Styles and themes are resources. Android provides some default style and theme resources that you can use, or you can declare your own custom style and theme resources.</p> - -<p>To create custom styles and themes:</p> -<ol> - <li>Create a file named <code>styles.xml</code> in the your application's <code>res/values</code> directory. Add a root <code><resources></code> node.</li> - <li>For each style or theme, add a <code><style></code> element with a unique <code>name</code> and, optionally, a <code>parent</code> attribute. - The name is used for referencing these styles later, and the parent indicates what style resource to inherit from.</li> - <li>Inside the <code>style</code> element, declare format values in one or more <code><item></code> element. - Each <code>item</code> identifies its style property with a <code>name</code> attribute and defines its style value inside the element.</li> - <li>You can then reference the custom resources from other XML resources, your manifest or application code.</li> -</ol> - - -<h2 id="styles">Styles</h2> - -<p>Here's an example declaration of a style: </p> - -<pre> -<?xml version="1.0" encoding="utf-8"?> -<resources> - <style name="SpecialText" parent="@style/Text"> - <item name="android:textSize">18sp</item> - <item name="android:textColor">#008</item> - </style> -</resources> -</pre> - -<p>As shown, you can use <code><item></code> elements to set specific formatting values for the style. -The <code>name</code> attribute in the <code>item</code> can refer to a standard string, a hex color value, -or a reference to any other resource type.</p> - -<p>Note the <code>parent</code> attribute in the <code>style</code> element. This attribute lets you specify a resource from which the current style will inherit values. The style can inherit from any type of resource that contains the style(s) you want. In general, your styles should always inherit (directly or indirectly) from a standard Android style resource. This way, you only have to define the values that you want to change.</p> - -<p>Here's how you would reference the custom style from an XML layout, in this case, for an EditText element:</p> - -<pre> -<EditText id="@+id/text1" - style="@style/SpecialText" - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:text="Hello, World!" /> -</pre> - -<p>Now this EditText widget will be styled as defined by the <code>style</code> example above.</p> - - -<h2 id="themes">Themes</h2> - -<p>Just like styles, themes are also declared in XML <code><style></code> elements, and are referenced in the same manner. -The difference is that you can add a theme style only to <code><application></code> and <code><activity></code> elements — -they cannot be applied to individual views in the layout.</p> - -<p>Here's an example declaration of a theme:</p> - -<pre> -<?xml version="1.0" encoding="utf-8"?> -<resources> - <style name="CustomTheme"> - <item name="android:windowNoTitle">true</item> - <item name="windowFrame">@drawable/screen_frame</item> - <item name="windowBackground">@drawable/screen_background_white</item> - <item name="panelForegroundColor">#FF000000</item> - <item name="panelBackgroundColor">#FFFFFFFF</item> - <item name="panelTextColor">?panelForegroundColor</item> - <item name="panelTextSize">14</item> - <item name="menuItemTextColor">?panelTextColor</item> - <item name="menuItemTextSize">?panelTextSize</item> - </style> -</resources> -</pre> - -<p>Notice the use of the at-symbol (@) and the question-mark (?) to reference resources. -The at-symbol indicates that we're referencing a resource previously defined elsewhere (which may be from -this project or from the Android framework). -The question-mark indicates that we're referencing a resource value in the currently loaded theme. This -is done by referring to a specific <code><item></code> by its <code>name</code> value. (E.g., -<em>panelTextColor</em> uses the same color assigned to <em>panelForegroundColor</em>, defined beforehand.) -This technique can be used only in XML resources. -</p> - -<h3 id="inTheManifest">Set the theme in the manifest</h3> -<p>To set this theme for all the activites of your application, open the AndroidManifest.xml file and -edit the <code><application></code> tag to include the <code>android:theme</code> attribute with the -theme name:</p> - -<pre> -<application android:theme="@style/CustomTheme"> -</pre> - -<p>If you want the theme applied to just one Activity in your application, then add the theme -attribute to the <code><activity></code> tag, instead.</p> - -<p>Just as Android provides other built-in resources, there are several themes that you swap in -without having to write one yourself. For example, you can use the Dialog theme to make your Activity -appear like a dialog box. In the manifest, reference an Android theme like so:</p> - -<pre> -<activity android:theme="@android:style/Theme.Dialog"> -</pre> - -<p>If you like a theme, but want to slightly tweak it, just add the theme as the <code>parent</code> of your custom theme. -For example, we'll modify the <code>Theme.Dialog</code> theme. First, we need to import the parent of the -<code>Dialog</code> theme: <code>Theme</code>. At the top of the <code>resources</code>, add:</p> -<pre> -<style name="Theme" parent="@android:Theme"> - <!-- no modification --> -</style> -</pre> -<p>Now create a a new theme with <code>Theme.Dialog</code> as the parent:</p> -<pre> -<style name="CustomDialogTheme" parent="@android:style/Theme.Dialog"> -</pre> -<p>There it is. We've inherited the Dialog theme, so we can adjust its styles as we like. -So, for each item in the Dialog theme that we want to override, we re-define the value under this style and -then use <var>CustomDialogTheme</var> instead of the <var>Theme.Dialog</var>.</p> - -<h3 id="fromTheApp">Set the theme from the application</h3> -<p>You can also load a theme for an Activity programmatically, if needed. -To do so, use the {@link android.app.Activity#setTheme(int) setTheme()} -method. Note that, when doing so, you must be sure to set the theme <em>before</em> -instantiating any Views in the context, for example, before calling -setContentView(View) or inflate(int, ViewGroup). This ensures that -the system applies the same theme for all of your UI screens. Here's an example:</p> - -<pre> - protected void onCreate(Bundle icicle) { - super.onCreate(icicle); - ... - setTheme(android.R.style.Theme_Light); - setContentView(R.layout.linear_layout_3); -} -</pre> - -<p>If you are considering loading a theme programmatically for the main -screen of your application, note that the theme would not be applied -in any animations the system would use to show the activity, which -would take place before your application starts. In most cases, if -you want to apply a theme to your main screen, doing so in XML - is a better approach. </p> - -<p>For detailed information about custom styles and themes and referencing them from your application, see -<a href="{@docRoot}guide/topics/resources/available-resources.html#stylesandthemes">Style -and Theme Resources</a>.</p> - -<p>For information about default themes and styles available, see {@link android.R.style}.</p> - - - - - - diff --git a/docs/html/guide/topics/ui/ui-events.jd b/docs/html/guide/topics/ui/ui-events.jd deleted file mode 100644 index f4d114a..0000000 --- a/docs/html/guide/topics/ui/ui-events.jd +++ /dev/null @@ -1,283 +0,0 @@ -page.title=Handling UI Events -parent.title=User Interface -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - <h2>In this document</h2> - <ol> - <li><a href="#EventListeners">Event Listeners</a></li> - <li><a href="#EventHandlers">Event Handlers</a></li> - <li><a href="#TouchMode">Touch Mode</a></li> - <li><a href="#HandlingFocus">Handling Focus</a></li> - </ol> - - <h2>See also</h2> - <ol> - <li><a href="{@docRoot}guide/tutorials/views/hello-formstuff.html">Hello Form Stuff tutorial</a></li> - </ol> -</div> -</div> - -<p>On Android, there's more than one way to intercept the events from a user's interaction with your application. -When considering events within your user interface, the approach is to capture the events from -the specific View object that the user interacts with. The View class provides the means to do so.</p> - -<p>Within the various View classes that you'll use to compose your layout, you may notice several public callback -methods that look useful for UI events. These methods are called by the Android framework when the -respective action occurs on that object. For instance, when a View (such as a Button) is touched, -the <code>onTouchEvent()</code> method is called on that object. However, in order to intercept this, you must extend -the class and override the method. Obviously, extending every View object -you want to use (just to handle an event) would be obsurd. This is why the View class also contains -a collection of nested interfaces with callbacks that you can much more easily define. These interfaces, -called <a href="#EventListeners">event listeners</a>, are your ticket to capturing the user interaction with your UI.</p> - -<p>While you will more commonly use the event listeners to listen for user interaction, there may -come a time when you do want to extend a View class, in order to build a custom component. -Perhaps you want to extend the {@link android.widget.Button} -class to make something more fancy. In this case, you'll be able to define the default event behaviors for your -class using the class <a href="#EventHandlers">event handlers</a>.</p> - - -<h2 id="EventListeners">Event Listeners</h2> - -<p>An event listener is an interface in the {@link android.view.View} class that contains a single -callback method. These methods will be called by the Android framework when the View to which the listener has -been registered is triggered by user interaction with the item in the UI.</p> - -<p>Included in the event listener interfaces are the following callback methods:</p> - -<dl> - <dt><code>onClick()</code></dt> - <dd>From {@link android.view.View.OnClickListener}. - This is called when the user either touches the item - (when in touch mode), or focuses upon the item with the navigation-keys or trackball and - presses the suitable "enter" key or presses down on the trackball.</dd> - <dt><code>onLongClick()</code></dt> - <dd>From {@link android.view.View.OnLongClickListener}. - This is called when the user either touches and holds the item (when in touch mode), or - focuses upon the item with the navigation-keys or trackball and - presses and holds the suitable "enter" key or presses and holds down on the trackball (for one second).</dd> - <dt><code>onFocusChange()</code></dt> - <dd>From {@link android.view.View.OnFocusChangeListener}. - This is called when the user navigates onto or away from the item, using the navigation-keys or trackball.</dd> - <dt><code>onKey()</code></dt> - <dd>From {@link android.view.View.OnKeyListener}. - This is called when the user is focused on the item and presses or releases a key on the device.</dd> - <dt><code>onTouch()</code></dt> - <dd>From {@link android.view.View.OnTouchListener}. - This is called when the user performs an action qualified as a touch event, including a press, a release, - or any movement gesture on the screen (within the bounds of the item).</dd> - <dt><code>onCreateContextMenu()</code></dt> - <dd>From {@link android.view.View.OnCreateContextMenuListener}. - This is called when a Context Menu is being built (as the result of a sustained "long click"). See the discussion - on context menus in <a href="{@docRoot}guide/topics/ui/menus.html#context-menu">Creating Menus</a> for more information.</dd> -</dl> - -<p>These methods are the sole inhabitants of their respective interface. To define one of these methods -and handle your events, implement the nested interface in your Activity or define it as an anonymous class. -Then, pass an instance of your implementation -to the respective <code>View.set...Listener()</code> method. (E.g., call -<code>{@link android.view.View#setOnClickListener(View.OnClickListener) setOnClickListener()}</code> -and pass it your implementation of the {@link android.view.View.OnClickListener OnClickListener}.)</p> - -<p>The example below shows how to register an on-click listener for a Button. </p> - -<pre> -// Create an anonymous implementation of OnClickListener -private OnClickListener mCorkyListener = new OnClickListener() { - public void onClick(View v) { - // do something when the button is clicked - } -}; - -protected void onCreate(Bundle savedValues) { - ... - // Capture our button from layout - Button button = (Button)findViewById(R.id.corky); - // Register the onClick listener with the implementation above - button.setOnClickListener(mCorkyListener); - ... -} -</pre> - -<p>You may also find it more conventient to implement OnClickListener as a part of your Activity. -This will avoid the extra class load and object allocation. For example:</p> -<pre> -public class ExampleActivity extends Activity implements OnClickListener { - protected void onCreate(Bundle savedValues) { - ... - Button button = (Button)findViewById(R.id.corky); - button.setOnClickListener(this); - } - - // Implement the OnClickListener callback - public void onClick(View v) { - // do something when the button is clicked - } - ... -} -</pre> - -<p>Notice that the <code>onClick()</code> callback in the above example has -no return value, but some other event listener methods must return a boolean. The reason -depends on the event. For the few that do, here's why:</p> -<ul> - <li><code>{@link android.view.View.OnLongClickListener#onLongClick(View) onLongClick()}</code> - - This returns a boolean to indicate whether you have consumed the event and it should not be carried further. - That is, return <em>true</em> to indicate that you have handled the event and it should stop here; - return <em>false</em> if you have not handled it and/or the event should continue to any other - on-click listeners.</li> - <li><code>{@link android.view.View.OnKeyListener#onKey(View,int,KeyEvent) onKey()}</code> - - This returns a boolean to indicate whether you have consumed the event and it should not be carried further. - That is, return <em>true</em> to indicate that you have handled the event and it should stop here; - return <em>false</em> if you have not handled it and/or the event should continue to any other - on-key listeners.</li> - <li><code>{@link android.view.View.OnTouchListener#onTouch(View,MotionEvent) onTouch()}</code> - - This returns a boolean to indicate whether your listener consumes this event. The important thing is that - this event can have multiple actions that follow each other. So, if you return <em>false</em> when the - down action event is received, you indicate that you have not consumed the event and are also - not interested in subsequent actions from this event. Thus, you will not be called for any other actions - within the event, such as a fingure gesture, or the eventual up action event.</li> -</ul> - -<p>Remember that key events are always delivered to the View currently in focus. They are dispatched starting from the top -of the View hierarchy, and then down, until they reach the appropriate destination. If your View (or a child of your View) -currently has focus, then you can see the event travel through the <code>{@link android.view.View#dispatchKeyEvent(KeyEvent) -dispatchKeyEvent()}</code> method. As an alternative to capturing key events through your View, you can also receive -all of the events inside your Activity with <code>{@link android.app.Activity#onKeyDown(int,KeyEvent) onKeyDown()}</code> -and <code>{@link android.app.Activity#onKeyUp(int,KeyEvent) onKeyUp()}</code>.</p> - -<p class="note"><strong>Note:</strong> Android will call event handlers first and then the appropriate default -handlers from the class definition second. As such, returning <em>true</em> from these event listeners will stop -the propagation of the event to other event listeners and will also block the callback to the -default event handler in the View. So be certain that you want to terminate the event when you return <em>true</em>.</p> - - -<h2 id="EventHandlers">Event Handlers</h2> - -<p>If you're building a custom component from View, then you'll be able to define several callback methods -used as default event handlers. -In the document on <a href="{@docRoot}guide/topics/ui/custom-components.html">Building Custom Components</a>, -you'll learn see some of the common callbacks used for event handling, including:</p> -<ul> - <li><code>{@link android.view.View#onKeyDown}</code> - Called when a new key event occurs.</li> - <li><code>{@link android.view.View#onKeyUp}</code> - Called when a key up event occurs.</li> - <li><code>{@link android.view.View#onTrackballEvent}</code> - Called when a trackball motion event occurs.</li> - <li><code>{@link android.view.View#onTouchEvent}</code> - Called when a touch screen motion event occurs.</li> - <li><code>{@link android.view.View#onFocusChanged}</code> - Called when the view gains or loses focus.</li> -</ul> -<p>There are some other methods that you should be awere of, which are not part of the View class, -but can directly impact the way you're able to handle events. So, when managing more complex events inside -a layout, consider these other methods:</p> -<ul> - <li><code>{@link android.app.Activity#dispatchTouchEvent(MotionEvent) - Activity.dispatchTouchEvent(MotionEvent)}</code> - This allows your {@link - android.app.Activity} to intercept all touch events before they are dispatched to the window.</li> - <li><code>{@link android.view.ViewGroup#onInterceptTouchEvent(MotionEvent) - ViewGroup.onInterceptTouchEvent(MotionEvent)}</code> - This allows a {@link - android.view.ViewGroup} to watch events as they are dispatched to child Views.</li> - <li><code>{@link android.view.ViewParent#requestDisallowInterceptTouchEvent(boolean) - ViewParent.requestDisallowInterceptTouchEvent(boolean)}</code> - Call this - upon a parent View to indicate that it should not intercept touch events with <code>{@link - android.view.ViewGroup#onInterceptTouchEvent(MotionEvent)}</code>.</li> -</ul> - -<h2 id="TouchMode">Touch Mode</h2> -<p> -When a user is navigating a user interface with directional keys or a trackball, it is -necessary to give focus to actionable items (like buttons) so the user can see -what will accept input. If the device has touch capabilities, however, and the user -begins interacting with the interface by touching it, then it is no longer necessary to -highlight items, or give focus to a particular View. Thus, there is a mode -for interaction named "touch mode." -</p> -<p> -For a touch-capable device, once the user touches the screen, the device -will enter touch mode. From this point onward, only Views for which -{@link android.view.View#isFocusableInTouchMode} is true will be focusable, such as text editing widgets. -Other Views that are touchable, like buttons, will not take focus when touched; they will -simply fire their on-click listeners when pressed. -</p> -<p> -Any time a user hits a directional key or scrolls with a trackball, the device will -exit touch mode, and find a view to take focus. Now, the user may resume interacting -with the user interface without touching the screen. -</p> -<p> -The touch mode state is maintained throughout the entire system (all windows and activities). -To query the current state, you can call -{@link android.view.View#isInTouchMode} to see whether the device is currently in touch mode. -</p> - - -<h2 id="HandlingFocus">Handling Focus</h2> - -<p>The framework will handle routine focus movement in response to user input. -This includes changing the focus as Views are removed or hidden, or as new -Views become available. Views indicate their willingness to take focus -through the <code>{@link android.view.View#isFocusable()}</code> method. To change whether a View can take -focus, call <code>{@link android.view.View#setFocusable(boolean) setFocusable()}</code>. When in touch mode, -you may query whether a View allows focus with <code>{@link android.view.View#isFocusableInTouchMode()}</code>. -You can change this with <code>{@link android.view.View#setFocusableInTouchMode(boolean) setFocusableInTouchMode()}</code>. -</p> - -<p>Focus movement is based on an algorithm which finds the nearest neighbor in a -given direction. In rare cases, the default algorithm may not match the -intended behavior of the developer. In these situations, you can provide -explicit overrides with the following XML attributes in the layout file: -<var>nextFocusDown</var>, <var>nextFocusLeft</var>, <var>nextFocusRight</var>, and -<var>nextFocusUp</var>. Add one of these attributes to the View <em>from</em> which -the focus is leaving. Define the value of the attribute to be the id of the View -<em>to</em> which focus should be given. For example:</p> -<pre> -<LinearLayout - android:orientation="vertical" - ... > - <Button android:id="@+id/top" - android:nextFocusUp="@+id/bottom" - ... /> - <Button android:id="@+id/bottom" - android:nextFocusDown="@+id/top" - ... /> -</LinearLayout> -</pre> - -<p>Ordinarily, in this vertical layout, navigating up from the first Button would not go -anywhere, nor would navigating down from the second Button. Now that the top Button has -defined the bottom one as the <var>nextFocusUp</var> (and vice versa), the navigation focus will -cycle from top-to-bottom and bottom-to-top.</p> - -<p>If you'd like to declare a View as focusable in your UI (when it is traditionally not), -add the <code>android:focusable</code> XML attribute to the View, in your layout declaration. -Set the value <var>true</var>. You can also declare a View -as focusable while in Touch Mode with <code>android:focusableInTouchMode</code>.</p> -<p>To request a particular View to take focus, call <code>{@link android.view.View#requestFocus()}</code>.</p> -<p>To listen for focus events (be notified when a View receives or looses focus), use -<code>{@link android.view.View.OnFocusChangeListener#onFocusChange(View,boolean) onFocusChange()}</code>, -as discussed in the <a href="#EventListeners">Event Listeners</a> section, above.</p> - - - -<!-- -<h2 is="EventCycle">Event Cycle</h2> - <p>The basic cycle of a View is as follows:</p> - <ol> - <li>An event comes in and is dispatched to the appropriate View. The View - handles the event and notifies any listeners.</li> - <li>If, in the course of processing the event, the View's bounds may need - to be changed, the View will call {@link android.view.View#requestLayout()}.</li> - <li>Similarly, if in the course of processing the event the View's appearance - may need to be changed, the View will call {@link android.view.View#invalidate()}.</li> - <li>If either {@link android.view.View#requestLayout()} or {@link android.view.View#invalidate()} were called, - the framework will take care of measuring, laying out, and drawing the tree - as appropriate.</li> - </ol> - - <p class="note"><strong>Note:</strong> The entire View tree is single threaded. You must always be on - the UI thread when calling any method on any View. - If you are doing work on other threads and want to update the state of a View - from that thread, you should use a {@link android.os.Handler}. - </p> ---> diff --git a/docs/html/guide/topics/views/custom-views.jd b/docs/html/guide/topics/views/custom-views.jd deleted file mode 100644 index c5f9346..0000000 --- a/docs/html/guide/topics/views/custom-views.jd +++ /dev/null @@ -1,544 +0,0 @@ -page.title=Building Custom Views -parent.title=Views and Layout -parent.link=index.html -@jd:body - -<p>Android offers a sophisticated and powerful componentized model for building your UI, based on the fundamental building block classes {@link android.view.View} and {@link android.view.ViewGroup}. To start with, the platform includes a variety of prebuilt View and ViewGroup subclasses — called widgets and layouts, respectively — that you can use to construct your UI. The widgets and layouts are fully implemented and handle all of their own measuring and drawing, so you can use them right away. You can make new types of UI elements simply by nesting and grouping the widgets and layouts. Using widgets and layouts is the recommended approach to building a UI for your applications.</p> - -<p>A partial list of available widgets includes {@link android.widget.Button Button}, -{@link android.widget.TextView TextView}, -{@link android.widget.EditText EditText}, -{@link android.widget.ListView ListView}, -{@link android.widget.CheckBox CheckBox}, -{@link android.widget.RadioButton RadioButton}, -{@link android.widget.Gallery Gallery}, -{@link android.widget.Spinner Spinner}, and the more special-purpose -{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, -{@link android.widget.ImageSwitcher ImageSwitcher}, and -{@link android.widget.TextSwitcher TextSwitcher}. </p> - -<p>Among the layouts available are {@link android.widget.LinearLayout LinearLayout}, -{@link android.widget.FrameLayout FrameLayout}, {@link android.widget.AbsoluteLayout AbsoluteLayout}, and others. For more examples, see <a href="layout">Common Layout Objects</a>.</p> - -<p>If none of the prebuilt widgets or layouts meets your needs, you can also create your own View subclass, such as a layout group or compound control. If you only need to make small adjustments to an existing widget or layout, you can simply subclass the widget or layout and override its methods. -</p> - -<p>Creating your own View subclasses gives you precise control over the appearance and function of a screen element. To give an idea of the control you get with custom views, here are some examples of what you could do with them:</p> - -<ul> - <li> - You could create a completely custom-rendered View type, for example a "volume - control" knob rendered using 2D graphics, and which resembles an - analog electronic control. - </li> - <li> - You could combine a group of View components into a new single component, perhaps - to make something like a ComboBox (a combination of popup list and free - entry text field), a dual-pane selector control (a left and right pane - with a list in each where you can re-assign which item is in which - list), and so on. - </li> - <li> - You could override the way that an EditText component is rendered on the screen - (the <a href="{@docRoot}guide/samples/NotePad/">Notepad sample</a> uses this to good effect, - to create a lined-notepad page). - </li> - <li> - You could capture other events like key presses and handle them in some custom - way (such as for a game). - </li> -</ul> -<p> -The sections below explain how to create custom Views and use them in your application. -For detailed reference information, see the {@link android.view.View} class. </p> - -<p>This document covers the following:</p> -<ol class="toc"> - <li><a href="#basic">The Basic Approach</a></li> - <li><a href="#custom">Fully Customized Views</a></li> - <li><a href="#customexample">Customized View Example</a></li> - <li><a href="#compound">Compound Controls</a></li> - <li><a href="#tweaking">Modifying an Existing Component Type</a></li> -</ol> - -<a name="basic"></a> -<h2>The Basic Approach -</h2> -<p> -These steps provide a high level overview of -what you need to know to get started in creating your own -View components:</p> - -<ol> - <li> - Extend an existing {@link android.view.View View} class or subclass - with your own class. - </li> - <li> - Override some of the methods from the superclass: the superclass methods - to override start with '<code>on</code>', for - example, {@link android.view.View#onDraw onDraw()}, - {@link android.view.View#onMeasure onMeasure()}, and - {@link android.view.View#onKeyDown onKeyDown()}. - <ul> - <li> - This is similar to the <code>on...</code> events in {@link android.app.Activity - Activity} or {@link android.app.ListActivity ListActivity} - that you override for life cycle and other functionality hooks. - </li> - </ul> - <li> - Use your new extension class: once completed, your new extension class - can be used in place of the view upon which it was based, but now with the new - functionality. - </li> -</ol> -<p class="note"><strong>Tip:</strong> - Extension classes can be defined as inner classes inside the activities - that use them. This is useful because it controls access to them but - isn't necessary (perhaps you want to create a new public View for - wider use in your application). -</p> - -<a name="custom"></a> -<h2>Fully Customized Components</h2> -<p> -Fully customized components can be used to create graphical components that -appear however you wish. Perhaps a graphical VU -meter that looks like an old analog gauge, or a sing-a-long text view where -a bouncing ball moves along the words so you can sing along with a karaoke -machine. Either way, you want something that the built-in components just -won't do, no matter how you combine them.</p> -<p>Fortunately, you can easily create components that look and behave in any -way you like, limited perhaps only by your imagination, the size of the -screen, and the available processing power (remember that ultimately your -application might have to run on something with significantly less power -than your desktop workstation).</p> -<p>To create a fully customized component:</p> -<ol> - <li> - The most generic view you can extend is, unsurprisingly, {@link - android.view.View View}, so you will usually start by extending this to - create your new super component. - </li> - <li> - You can supply a constructor which can - take attributes and parameters from the XML, and you can also consume - your own such attributes and parameters (perhaps the color and range of - the VU meter, or the width and damping of the needle, etc.) - </li> - <li> - You will probably want to create your own event listeners, - property accessors and modifiers, and possibly more sophisticated - behavior in your component class as well. - </li> - <li> - You will almost certainly want to override <code>onMeasure()</code> and - are also likely to need to override <code>onDraw()</code> if you want - the component to show something. While both have default behavior, - the default <code>onDraw()</code> will do nothing, and the default - <code>onMeasure()</code> will always set a size of 100x100 — which is - probably not what you want. - </li> - <li> - Other <code>on...</code> methods may also be overridden as required. - </li> -</ol> -<h4><code>onDraw()</code> and <code>onMeasure()</code></h4> -<p><code>onDraw()</code> delivers you a {@link android.graphics.Canvas Canvas} -upon which you can implement anything you want: 2D graphics, other standard or -custom components, styled text, or anything else you can think of.</p> -<p><em>Note:</em> -Except for 3D graphics. If you want to -use 3D graphics, you must extend {@link android.view.SurfaceView SurfaceView} -instead of View, and draw from a seperate thread. See the -GLSurfaceViewActivity sample -for details.</p> -<p><code>onMeasure()</code> is a little more involved. <code>onMeasure()</code> -is a critical piece of the rendering contract between your component and its -container. <code>onMeasure()</code> should be overridden to efficiently and -accurately report the measurements of its contained parts. This is made -slightly more complex by the requirements of limits from the parent -(which are passed in to the <code>onMeasure()</code> method) and by the -requirement to call the <code>setMeasuredDimension()</code> method with the -measured width and height once they have been calculated. If you fail to -call this method from an overridden <code>onMeasure()</code> method, the -result will be an exception at measurement time.</p> -<p>At a high level, implementing <code>onMeasure()</code> looks something - like this:</p> - -<ol> - <li> - The overridden <code>onMeasure()</code> method is called with width and - height measure specifications (<code>widthMeasureSpec</code> and - <code>heighMeasureSpec</code> parameters, both are integer codes - representing dimensions) which should be treated as requirements for - the restrictions on the width and height measurements you should produce. A - full reference to the kind of restrictions these specifications can require - can be found in the reference documentation under {@link - android.view.View#onMeasure View.onMeasure(int, int)} (this reference - documentation does a pretty good job of explaining the whole measurement - operation as well). - </li> - <li> - Your component's <code>onMeasure()</code> method should calculate a - measurement width and height which will be required to render the - component. It should try to stay within the specifications passed in, - although it can choose to exceed them (in this case, the parent can - choose what to do, including clipping, scrolling, throwing an exception, - or asking the <code>onMeasure()</code> to try again, perhaps with - different measurement specifications). - </li> - <li> - Once the width and height are calculated, the <code>setMeasuredDimension(int - width, int height)</code> method must be called with the calculated - measurements. Failure to do this will result in an exception being - thrown. - </li> -</ol> - -<p> -Here's a summary of some of the other standard methods that the framework calls on views: -</p> -<table border="2" width="85%" align="center" cellpadding="5"> - <thead> - <tr><th>Category</th> <th>Methods</th> <th>Description</th></tr> - </thead> - - <tbody> - <tr> - <td rowspan="2">Creation</td> - <td>Constructors</td> - <td>There is a form of the constructor that are called when the view - is created from code and a form that is called when the view is - inflated from a layout file. The second form should parse and apply - any attributes defined in the layout file. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onFinishInflate()}</code></td> - <td>Called after a view and all of its children has been inflated - from XML.</td> - </tr> - - <tr> - <td rowspan="3">Layout</td> - <td><code>{@link android.view.View#onMeasure}</code></td> - <td>Called to determine the size requirements for this view and all - of its children. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onLayout}</code></td> - <td>Called when this view should assign a size and position to all - of its children. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onSizeChanged}</code></td> - <td>Called when the size of this view has changed. - </td> - </tr> - - <tr> - <td>Drawing</td> - <td><code>{@link android.view.View#onDraw}</code></td> - <td>Called when the view should render its content. - </td> - </tr> - - <tr> - <td rowspan="4">Event processing</td> - <td><code>{@link android.view.View#onKeyDown}</code></td> - <td>Called when a new key event occurs. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onKeyUp}</code></td> - <td>Called when a key up event occurs. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onTrackballEvent}</code></td> - <td>Called when a trackball motion event occurs. - </td> - </tr> - <tr> - <td><code>{@link android.view.View#onTouchEvent}</code></td> - <td>Called when a touch screen motion event occurs. - </td> - </tr> - - <tr> - <td rowspan="2">Focus</td> - <td><code>{@link android.view.View#onFocusChanged}</code></td> - <td>Called when the view gains or loses focus. - </td> - </tr> - - <tr> - <td><code>{@link android.view.View#onWindowFocusChanged}</code></td> - <td>Called when the window containing the view gains or loses focus. - </td> - </tr> - - <tr> - <td rowspan="3">Attaching</td> - <td><code>{@link android.view.View#onAttachedToWindow()}</code></td> - <td>Called when the view is attached to a window. - </td> - </tr> - - <tr> - <td><code>{@link android.view.View#onDetachedFromWindow}</code></td> - <td>Called when the view is detached from its window. - </td> - </tr> - - <tr> - <td><code>{@link android.view.View#onWindowVisibilityChanged}</code></td> - <td>Called when the visibility of the window containing the view - has changed. - </td> - </tr> - </tbody> - - </table> - - -<a name="customexample"></a> -<h3>A Custom View Example</h3> -<p>The CustomView sample in the -<a href="{@docRoot}samples/ApiDemos/index.html">API Demos</a> provides an example -of a customized View. The custom View is defined in the -<a href="{@docRoot}samples/ApiDemos/src/com/example/android/apis/view/LabelView.html">LabelView</a> -class.</p> -<p>The LabelView sample demonstrates a number of different aspects of custom components:</p> -<ul> - <li>Extending the View class for a completely custom component.</li> - <li>Parameterized constructor that takes the view inflation parameters - (parameters defined in the XML). Some of these are passed through to the - View superclass, but more importantly, there are some custom attributes defined - and used for LabelView.</li> - <li>Standard public methods of the type you would expect to see for a label - component, for example <code>setText()</code>, <code>setTextSize()</code>, - <code>setTextColor()</code> and so on.</li> - <li>An overridden <code>onMeasure</code> method to determine and set the - rendering size of the component. (Note that in LabelView, the real work is done - by a private <code>measureWidth()</code> method.)</li> - <li>An overridden <code>onDraw()</code> method to draw the label onto the - provided canvas.</li> -</ul> -<p>You can see some sample usages of the LabelView custom View in -<a href="{@docRoot}samples/ApiDemos/res/layout/custom_view_1.html">custom_view_1.xml</a> -from the samples. In particular, you can see a mix of both <code>android:</code> -namespace parameters and custom <code>app:</code> namespace parameters. These -<code>app:</code> parameters are the custom ones that the LabelView recognizes -and works with, and are defined in a styleable inner class inside of the -samples R resources definition class.</p> - -<a name="compound"></a> -<h2>Compound Controls -</h2> -<p>If you don't want to create a completely customized component, but instead -are looking to put together a reusable component that consists of a group of -existing controls, then creating a Compound Component (or Compound Control) might -fit the bill. In a nutshell, this brings together a number of more atomic -controls (or views) into a logical group of items that can be treated as a -single thing. For example, a Combo Box can be thought of as a -combination of a single line EditText field and an adjacent button with an attached - PopupList. If you press the button and select -something from the list, it populates the EditText field, but the user can -also type something directly into the EditText if they prefer.</p> -<p>In Android, there are actually two other Views readily available to do -this: {@link android.widget.Spinner Spinner} and -{@link android.widget.AutoCompleteTextView AutoCompleteTextView}, but -regardless, the concept of a Combo Box makes an easy-to-understand -example.</p> -<p>To create a compound component:</p> -<ol> - <li> - The usual starting point is a Layout of some kind, so create a class - that extends a Layout. Perhaps in the case of a Combo box we might use - a LinearLayout with horizontal orientation. Remember that other layouts - can be nested inside, so the compound component can be arbitrarily - complex and structured. Note that just like with an Activity, you can - use either the declarative (XML-based) approach to creating the - contained components, or you can nest them programmatically from your - code. - </li> - <li> - In the constructor for the new class, take whatever parameters the - superclass expects, and pass them through to the superclass constructor - first. Then you can set up the other views to use within your new - component; this is where you would create the EditText field and the - PopupList. Note that you also might introduce your own attributes and - parameters into the XML that can be pulled out and used by your - constructor. - </li> - <li> - You can also create listeners for events that your contained views might - generate, for example, a listener method for the List Item Click Listener - to update the contents of the EditText if a list selection is made. - </li> - <li> - You might also create your own properties with accessors and modifiers, - for example, allow the EditText value to be set initially in the - component and query for its contents when needed. - </li> - <li> - In the case of extending a Layout, you don't need to override the - <code>onDraw()</code> and <code>onMeasure()</code> methods since the - layout will have default behavior that will likely work just fine. However, - you can still override them if you need to. - </li> - <li> - You might override other <code>on...</code> methods, like - <code>onKeyDown()</code>, to perhaps choose certain default values from - the popup list of a combo box when a certain key is pressed. - </li> -</ol> -<p> - To summarize, the use of a Layout as the basis for a Custom Control has a -number of advantages, including:</p> - -<ul> - <li> - You can specify the layout using the declarative XML files just like - with an activity screen, or you can create views programmatically and - nest them into the layout from your code. - </li> - <li> - The <code>onDraw()</code> and <code>onMeasure()</code> methods (plus - most of the other <code>on...</code> methods) will likely have suitable behavior so - you don't have to override them. - </li> - <li> - In the end, you can very quickly construct arbitrarily complex compound - views and re-use them as if they were a single component. - </li> -</ul> -<h4>Examples of Compound Controls</h4> -<p>In the API Demos project - that comes with the SDK, there are two List - examples — Example 4 and Example 6 under Views/Lists demonstrate a - SpeechView which extends LinearLayout to make a component for displaying - Speech quotes. The corresponding classes in the sample code are - <code>List4.java</code> and <code>List6.java</code>.</p> - -<a name="tweaking"></a> -<h2>Modifying an Existing View Type -</h2> -<p>There is an even easier option for creating a custom View which is -useful in certain circumstances. If there is a component that is already very -similar to what you want, you can simply extend that component and just -override the behavior that you want to change. You can do all of the things -you would do with a fully customized component, but by starting with a more -specialized class in the View heirarchy, you can also get a lot of behavior for -free that probably does exactly what you want.</p> -<p>For example, the SDK includes a <a -href="{@docRoot}samples/NotePad/index.html">NotePad application</a> in the -samples. This demonstrates many aspects of using the Android platform, among -them is extending an EditText View to make a lined notepad. This is not a -perfect example, and the APIs for doing this might change from this early -preview, but it does demonstrate the principles.</p> -<p>If you haven't done so already, import the -NotePad sample into Eclipse (or -just look at the source using the link provided). In particular look at the definition of -<code>MyEditText</code> in the <a -href="{@docRoot}samples/NotePad/src/com/example/android/notepad/NoteEditor.html">NoteEditor.java</a> -file.</p> -<p>Some points to note here</p> -<ol> - <li> - <strong>The Definition</strong> - <p>The class is defined with the following line:</p> - <code>public static class MyEditText extends EditText</code><br><br> - - <ul> - <li> - It is defined as an inner class within the <code>NoteEditor</code> - activity, but it is public so that it could be accessed as - <code>NoteEditor.MyEditText</code> from outside of the <code>NoteEditor</code> - class if desired. - </li> - <li> - It is <code>static</code>, meaning it does not generate the so-called - "synthetic methods" that allow it to access data from the parent - class, which in turn means that it really behaves as a separate - class rather than something strongly related to <code>NoteEditor</code>. - This is a cleaner way to create inner classes if they do not need - access to state from the outer class, keeps the generated class - small, and allows it to be used easily from other classes. - </li> - <li> - It extends <code>EditText</code>, which is the View we have chosen to - customize in this case. When we are finished, the new class will be - able to substitute for a normal <code>EditText</code> view.<br> - <br> - </li> - </ul> - </li> - <li> - <strong>Class Initialization</strong> - <p>As always, the super is called first. Furthermore, - this is not a default constructor, but a parameterized one. The - EditText is created with these parameters when it is inflated from an - XML layout file, thus, our constructor needs to both take them and pass them - to the superclass constructor as well.</p> - </li> - <li> - <strong>Overridden Methods</strong> - <p>In this example, there is only one method to be overridden: - <code>onDraw()</code> — but there could easily be others needed when you - create your own custom components.</p> - <p>For the NotePad sample, overriding the <code>onDraw()</code> method allows - us to paint the blue lines on the <code>EditText</code> view canvas (the - canvas is passed into the overridden <code>onDraw()</code> method). The - super.onDraw() method is called before the method ends. The - superclass method should be invoked, but in this case, we do it at the - end after we have painted the lines we want to include.</p> - <li> - <strong>Use the Custom Component</strong> - <p>We now have our custom component, but how can we use it? In the - NotePad example, the custom component is used directly from the - declarative layout, so take a look at <code>note_editor.xml</code> in the - <code>res/layout</code> folder.</p> - <pre> -<view xmlns:android="http://schemas.android.com/apk/res/android" - class="com.android.notepad.NoteEditor$MyEditText" - id="@+id/note" - android:layout_width="fill_parent" - android:layout_height="fill_parent" - android:background="@android:drawable/empty" - android:padding="10dip" - android:scrollbars="vertical" - android:fadingEdge="vertical" /> </pre> - - <ul> - <li> - The custom component is created as a generic view in the XML, and - the class is specified using the full package. Note also that the - inner class we defined is referenced using the - <code>NoteEditor$MyEditText</code> notation which is a standard way to - refer to inner classes in the Java programming language. - </li> - <li> - The other attributes and parameters in the definition are the ones - passed into the custom component constructor, and then passed - through to the EditText constructor, so they are the same - parameters that you would use for an EditText view. Note that it is - possible to add your own parameters as well, and we will touch on - this again below. - </li> - </ul> - </li> -</ol> -<p>And that's all there is to it. Admittedly this is a simple case, but -that's the point — creating custom components is only as complicated as you -need it to be.</p> -<p>A more sophisticated component may override even more <code>on...</code> methods and -introduce some of its own helper methods, substantially customizing its properties and -behavior. The only limit is your imagination and what you need the component to -do.</p> - diff --git a/docs/html/guide/topics/views/intro.jd b/docs/html/guide/topics/views/intro.jd deleted file mode 100644 index f49f547..0000000 --- a/docs/html/guide/topics/views/intro.jd +++ /dev/null @@ -1,49 +0,0 @@ -page.title=Introduction to Views -parent.title=Views and Layout -parent.link=index.html -@jd:body - -<p>The basic functional unit of an Android application is the <em>activity</em> — an object of the class {@link android.app.Activity android.app.Activity}. An activity can do many things, but by itself it does not have a presence on the screen. To give your activity a screen presence and design its UI, you work with <em>views</em> and <em>viewgroups</em> -- basic units of user interface expression on the Android platform.</p> - -<h2>Views</h2> -<p>A view is an object of base class {@link android.view.View android.view.View}. It's a data structure whose properties store the layout and content for a specific rectangular area of the screen. A View object handles measuring and layout, drawing, focus change, scrolling, and key/gestures for the screen area it represents. </p> -<p>The View class serves as a base class for <em>widgets </em> — a set of fully implemented subclasses that draw interactive screen elements. Widgets handle their own measuring and drawing, so you can use them to build your UI more quickly. The list of widgets available includes Text, EditText, InputMethod, MovementMethod, Button, RadioButton, Checkbox, and ScrollView.</p> - -<h2>Viewgroups </h2> - -<p>A viewgroup is an object of class {@link android.view.ViewGroup android.view.Viewgroup}. As its name indicates, a viewgroup is a special type of view object whose function is to contain and manage a subordinate set of views and other viewgroups, Viewgroups let you add structure to your UI and build up complex screen elements that can be addressed as a single entity. </p> - -<p>The Viewgroup class serves as a base class for <em>layouts</em> — a set of fully implemented subclasses that provide common types of screen layout. The layouts give you a way to build a structure for a set of views. </p> - -<h2>A Tree-Structured UI</h2> - -<p>On the Android platform, you define an Activity's UI using a tree of view and viewgroup nodes, as shown in the diagram below. The tree can be as simple or complex as you need to make it, and you can build it up using Android's set of predefined widgets and layouts or custom view types that you create yourself. </p> - -<img src={@docRoot}images/viewgroup.png alt="An example of a tree of views and viewgroups" width="312" height="211" align="center"/> - -<p>To attach the tree to the screen for rendering, your Activity calls its setContentView() method and passes a reference to the root node object. Once the Android system has the reference to the root node object, it can work directly with the node to invalidate, measure, and draw the tree. When your Activity becomes active and receives focus, the system notifies your activity and requests the root node to measure and draw the tree. The root node then requests that its child nodes draw themselves — in turn, each viewgroup node in the tree is responsible for drawing its direct children. </p> - -<p>As mentioned previously, each view group has the responsibility of - measuring its available space, laying out its children, and calling Draw() on - each child to let it render itself. The children may request a size and location - in the parent, but the parent object has the final decision on where how big - each child can be.</p> - -<h2>LayoutParams: How a Child Specifies Its Position and Size</h2> - -<p>Every viewgroup class uses a nested class that extends {@link -android.view.ViewGroup.LayoutParams ViewGroup.LayoutParams}. This subclass - contains property types that define a child's size and position, in properties - appropriate for that view group class. </p> - -<img src={@docRoot}images/layoutparams.png alt="An example of layoutparams" width="632" height="369" align="center"/> - -<p>Note that every LayoutParams subclass has its own syntax for setting -values. Each child element must define LayoutParams that are appropriate for its parent, although it may define different LayoutParams for its children. </p> - -<p>All viewgroups include width and height. Many also include margins and -borders. You can specify width and height exactly, though you probably won't want -to do this often. More often you will tell your view to size itself either to -the dimensions of its content, or to become as big as its containing object -will allow.</p> - diff --git a/docs/html/guide/topics/views/ui-xml.jd b/docs/html/guide/topics/views/ui-xml.jd deleted file mode 100644 index 8ae599c..0000000 --- a/docs/html/guide/topics/views/ui-xml.jd +++ /dev/null @@ -1,133 +0,0 @@ -page.title=Declaring a UI in XML -parent.title=Views and Layout -parent.link=index.html -@jd:body - -<p>You can create your application's user interface in two ways: -<ul> -<li>You can declare UI elements statically, in XML. Android provides a straightforward XML vocabulary that corresponds to the View classes and subclasses, such as those for widgets and layouts. </li> -<li>You can instantiate screen elements dynamically, at runtime, through code in your application. Your application can refer to or create View or other class objects and manipulate their properties programmatically. </li> -</ul> - -<p>One advantage of declaring your UI in XML is that it enables you to better separate the presentation of your application from the code that controls it's behavior. Your UI description is external to your application code, which means that you can modify or adapt it without having to modify your source code and recompile. For example, you can create XML layouts for different screen orientations and for a variety of device screen sizes or languages. Additionally, declaring in XML makes it easier to see the elements and structure of your UI, so it's easier to debug problems. </p> - -<p>The Android framework gives you the flexibility to use either or both of these ways of declaring and managing your application's UI. For example, you could declare your application's default layouts in XML, including the screen elements that will appear in them and their properties. You could then add code in your application that would modify the state of the screen objects, including those declared in XML, at run time. </p> - -<p>You build your application's UI in approximately the same way, whether you are declaring it in XML or programmatically. In both cases, your UI will be a tree structure that may include multiple View or Viewgroup subclasses. <p> - -<p>In general, the XML vocabulary for declaring UI elements closely follows the structure and naming of the framework's UI-related classes and methods, where element names correspond to class names and attribute names correspond to methods. In fact, the correspondence is often so direct that you can guess what XML attribute corresponds to a class method, or guess what class corresponds to a given xml element. </p> - -<p>However, note that the XML vocabulary for defining UI is not entirely identical to the framework's classes and methods. In some cases, there are slight naming differences. For -example, the EditText element has a <code>text</code> attribute that corresponds to -EditText.setText. </p> - -<div class="sidebox"><p>For your convenience, the API reference documentation for UI related classes lists the available XML attributes that correspond to the class methods, including inherited attributes.</p> - -<p>To learn more about the available XML elements and attributes, as well as the format of the XML file, see <a -href="{@docRoot}reference/available-resources.html#layoutresources">Layout Resources</a>.</p> - </div> - -<p>Using Android's XML vocabulary, you can quickly design UI layouts and the screen elements they contain, in the same way you create HTML files — as a series of nested tags. </p> - -<p>Each layout file must contain exactly one root element, and the root element must be a View or ViewGroup object. Once you've defined the root element, you can add additional layout objects or controls as child elements of the root element, if needed. In the example below, the tree of XML elements evaluates to the outermost LinearLayout object. - -<p>After you've declared your layout in XML, you must save the file, with the <code>.xml</code> extension, in the proper location, so that it will be compiled correctly. The proper location for storing layout files is in your application's <code>res/layout/</code> directory. </p> - -<p>When you compile your application, each XML layout file is compiled into an -android.view.View resource. You can then load the layout resource from your application code, by calling <code>setContentView(R.layout.<em>layout_file_name</em>)</code> in your {@link android.app.Activity#onCreate(android.os.Bundle) Activity.onCreate()} -implementation.</p> - -<p>When you load a layout resource, the Android system initializes run-time objects corresponding to the elements in your layout. It parses the elements of your layout in-order (depth-first), instantiating the Views and adding them to their parent(s). </p> - -<p>Attributes named <code>layout_<em>something</em></code> apply to that -object's LayoutParams member. <a href="{@docRoot}reference/available-resources.html#layoutresources">Layout -Resources</a> also describes how to learn the syntax for specifying -LayoutParams properties. </p> - -<p>Also note that Android draws elements in the order in which they -appear in the XML. Therefore, if elements overlap, the last one in the XML -file will probably be drawn on top of any previously listed elements in that -same space.</p> - -<p>The following values are supported for dimensions (described in {@link -android.util.TypedValue TypedValue}):</p> - -<ul> - <li>px (pixels) </li> - <li>dip (device independent pixels) </li> - <li>sp (scaled pixels — best for text size) </li> - <li>pt (points) </li> - <li>in (inches) </li> - <li>mm (millimeters) </li> -</ul> - -<p>Example: <code>android:layout_width="25px"</code> </p> - -<p>For more information about these dimensions, see <a href="{@docRoot}reference/available-resources.html#dimension">Dimension Values</a>.</p> - -<p>The example below shows an XML file and the resulting screen in the UI. Note that the text on the -top of the screen was set by calling {@link -android.app.Activity#setTitle(java.lang.CharSequence) Activity.setTitle}. Note -that the attributes that refer to relative elements (i.e., layout_toLeft) -refer to the ID using the syntax of a relative resource -(@id/<em>id_number</em>). </p> - -<table border="1"> - <tr> - <td> - <pre><?xml version="1.0" encoding="utf-8"?> -<!-- Demonstrates using a relative layout to create a form --> -<RelativeLayout xmlns:android="http://schemas.android.com/apk/res/android - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:background="@drawable/blue" - android:padding="10px"> - - <TextView id="@+id/label" - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:text="Type here:"/> - - <EditText id="@+id/entry" - android:layout_width="fill_parent" - android:layout_height="wrap_content" - android:background="@android:drawable/editbox_background" - android:layout_below="@id/label"/> - - <Button id="@+id/ok" - android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:layout_below="@id/entry" - android:layout_alignParentRight="true" - android:layout_marginLeft="10px" - android:text="OK" /> - - <Button android:layout_width="wrap_content" - android:layout_height="wrap_content" - android:layout_toLeftOf="@id/ok" - android:layout_alignTop="@id/ok" - android:text="Cancel" /> -</RelativeLayout></pre></td> - <td><img src="{@docRoot}images/designing_ui_layout_example.png" alt="Screen shot showing how this layout XML file is rendered." /></td> - </tr> -</table> - -<h3>Loading the XML Resource </h3> - -<p>Loading the compiled layout resource is very easy, and done with a single -call in the activity's onCreate() method, as shown here:</p> - -<pre> -protected void onCreate(Bundle savedValues) -{ - // Be sure to call the super class. - super.onCreate(savedValues); - - // Load the compiled layout resource into the window's - // default ViewGroup. - // The source file is res/layout/hello_activity.xml - setContentView(R.layout.hello_activity); - - // Retrieve any important stored values. - restoreValues(savedValues); -} </pre> diff --git a/docs/html/guide/topics/wireless/bluetooth.jd b/docs/html/guide/topics/wireless/bluetooth.jd deleted file mode 100644 index 710cd4c..0000000 --- a/docs/html/guide/topics/wireless/bluetooth.jd +++ /dev/null @@ -1,18 +0,0 @@ -page.title=Bluetooth -parent.title=Wireless Controls -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>In this document</h2> - <ol> - - </ol> - -</div> -</div> - - -TODO
\ No newline at end of file diff --git a/docs/html/guide/topics/wireless/index.jd b/docs/html/guide/topics/wireless/index.jd deleted file mode 100644 index a3a2b36..0000000 --- a/docs/html/guide/topics/wireless/index.jd +++ /dev/null @@ -1,19 +0,0 @@ -page.title=Wireless Controls -@jd:body - - - -<h2>Wi-Fi</h2> -<p>The Wi-Fi APIs provide a means by which application can communicate with the lower-level -wireless stack that provides Wi-Fi network access. Almost all information from the device supplicant -is available, including the connected network's link speed, IP address, negotiation state, and more. -It also provides information about all non-connected available networks. Some of the available network -interactions include the ability to scan, add, dave, terminate and initiate connections.</p> - - -<h2>Bluetooth</h2> -<p>The Bluetooth APIs allow applications to scan, connect and pair with other Bluetooth devices. -THESE APIS ARE NOT YET AVAILABLE.</p> - - - diff --git a/docs/html/guide/topics/wireless/wifi.jd b/docs/html/guide/topics/wireless/wifi.jd deleted file mode 100644 index 520feaf..0000000 --- a/docs/html/guide/topics/wireless/wifi.jd +++ /dev/null @@ -1,18 +0,0 @@ -page.title=Wi-Fi -parent.title=Wireless Controls -parent.link=index.html -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - - <h2>In this document</h2> - <ol> - - </ol> - -</div> -</div> - - -TODO
\ No newline at end of file |