diff options
Diffstat (limited to 'docs/html/guide/topics/fundamentals.jd')
| -rw-r--r-- | docs/html/guide/topics/fundamentals.jd | 518 |
1 files changed, 0 insertions, 518 deletions
diff --git a/docs/html/guide/topics/fundamentals.jd b/docs/html/guide/topics/fundamentals.jd deleted file mode 100644 index a86d905..0000000 --- a/docs/html/guide/topics/fundamentals.jd +++ /dev/null @@ -1,518 +0,0 @@ -page.title=Application Fundamentals -@jd:body - -<div id="qv-wrapper"> -<div id="qv"> - -<h2>Quickview</h2> -<ul> - <li>Android applications are composed of one or more application components (activities, -services, content providers, and broadcast receivers)</li> - <li>Each component performs a different role in the overall application behavior, and each -one can be activated individually (even by other applications)</li> - <li>The manifest file must declare all components in the application and should also declare -all application requirements, such as the minimum version of Android required and any hardware -configurations required</li> - <li>Non-code application resources (images, strings, layout files, etc.) should include -alternatives for different device configurations (such as different strings for different -languages and different layouts for different screen sizes)</li> -</ul> - - -<h2>In this document</h2> -<ol> -<li><a href="#Components">Application Components</a> - <ol> - <li><a href="#ActivatingComponents">Activating components</a></li> - </ol> -</li> -<li><a href="#Manifest">The Manifest File</a> - <ol> - <li><a href="#DeclaringComponents">Declaring components</a></li> - <li><a href="#DeclaringRequirements">Declaring application requirements</a></li> - </ol> -</li> -<li><a href="#Resources">Application Resources</a></li> -</ol> -</div> -</div> - -<p>Android applications are written in the Java programming language. The Android SDK tools compile -the code—along with any data and resource files—into an <i>Android package</i>, an -archive file with an {@code .apk} suffix. All the code in a single {@code .apk} file is considered -to be one application and is the file that Android-powered devices use to install the -application.</p> - -<p>Once installed on a device, each Android application lives in its own security sandbox: </p> - -<ul> - <li>The Android operating system is a multi-user Linux system in which each application is a -different user.</li> - -<li>By default, the system assigns each application a unique Linux user ID (the ID is used only by -the system and is unknown to the application). The system sets permissions for all the files in an -application so that only the user ID assigned to that application can access them. </li> - -<li>Each process has its own virtual machine (VM), so an application's code runs in isolation from -other applications.</li> - -<li>By default, every application runs in its own Linux process. Android starts the process when any -of the application's components need to be executed, then shuts down the process when it's no longer -needed or when the system must recover memory for other applications.</li> -</ul> - -<p>In this way, the Android system implements the <em>principle of least privilege</em>. That is, -each application, by default, has access only to the components that it requires to do its work and -no more. This creates a very secure environment in which an application cannot access parts of -the system for which it is not given permission.</p> - -<p>However, there are ways for an application to share data with other applications and for an -application to access system services:</p> - -<ul> - <li>It's possible to arrange for two applications to share the same Linux user ID, in which case -they are able to access each other's files. To conserve system resources, applications with the -same user ID can also arrange to run in the same Linux process and share the same VM (the -applications must also be signed with the same certificate).</li> - <li>An application can request permission to access device data such as the user's -contacts, SMS messages, the mountable storage (SD card), camera, Bluetooth, and more. All -application permissions must be granted by the user at install time.</li> -</ul> - -<p>That covers the basics regarding how an Android application exists within the system. The rest of -this document introduces you to:</p> -<ul> - <li>The core framework components that define your application.</li> - <li>The manifest file in which you declare components and required device features for your -application.</li> - <li>Resources that are separate from the application code and allow your application to -gracefully optimize its behavior for a variety of device configurations.</li> -</ul> - -<!-- -<p class="note"><strong>Tip:</strong> If you're new to Android development, we suggest that you -follow the Beginner's Path link at the bottom of this page. For each document in the Application -Fundamentals, the Beginner's Path points you to the document we suggest you read next, in order -to get up to speed on the core Android concepts.</p> ---> - - -<h2 id="Components">Application Components</h2> - -<p>Application components are the essential building blocks of an Android application. Each -component is a different point through which the system can enter your application. Not all -components are actual entry points for the user and some depend on each other, but each one exists -as its own entity and plays a specific role—each one is a unique building block that -helps define your application's overall behavior.</p> - -<p>There are four different types of application components. Each type serves a distinct purpose -and has a distinct lifecycle that defines how the component is created and destroyed.</p> - -<p>Here are the four types of application components:</p> - -<dl> - -<dt><b>Activities</b></dt> - -<dd>An <i>activity</i> represents a single screen with a user interface. For example, -an email application might have one activity that shows a list of new -emails, another activity to compose an email, and another activity for reading emails. Although -the activities work together to form a cohesive user experience in the email application, each one -is independent of the others. As such, a different application can start any one of these -activities (if the email application allows it). For example, a camera application can start the -activity in the email application that composes new mail, in order for the user to share a picture. - -<p>An activity is implemented as a subclass of {@link android.app.Activity} and you can learn more -about it in the <a href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a> -developer guide.</p> -</dd> - - -<dt><b>Services</b></dt> - -<dd>A <i>service</i> is a component that runs in the background to perform long-running -operations or to perform work for remote processes. A service -does not provide a user interface. For example, a service might play music in the background while -the user is in a different application, or it might fetch data over the network without -blocking user interaction with an activity. Another component, such as an activity, can start the -service and let it run or bind to it in order to interact with it. - -<p>A service is implemented as a subclass of {@link android.app.Service} and you can learn more -about it in the <a href="{@docRoot}guide/topics/fundamentals/services.html">Services</a> developer -guide.</p> -</dd> - - -<dt><b>Content providers</b></dt> - -<dd>A <i>content provider</i> manages a shared set of application data. You can store the data in -the file system, an SQLite database, on the web, or any other persistent storage location your -application can access. Through the content provider, other applications can query or even modify -the data (if the content provider allows it). For example, the Android system provides a content -provider that manages the user's contact information. As such, any application with the proper -permissions can query part of the content provider (such as {@link -android.provider.ContactsContract.Data}) to read and write information about a particular person. - -<p>Content providers are also useful for reading and writing data that is private to your -application and not shared. For example, the <a -href="{@docRoot}resources/samples/NotePad/index.html">Note Pad</a> sample application uses a -content provider to save notes.</p> - -<p>A content provider is implemented as a subclass of {@link android.content.ContentProvider} -and must implement a standard set of APIs that enable other applications to perform -transactions. For more information, see the <a -href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a> developer -guide.</p> -</dd> - - -<dt><b>Broadcast receivers</b></dt> - -<dd>A <i>broadcast receiver</i> is a component that responds to system-wide broadcast -announcements. Many broadcasts originate from the system—for example, a broadcast announcing -that the screen has turned off, the battery is low, or a picture was captured. -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. Although broadcast -receivers don't display a user interface, they may <a -href="{@docRoot}guide/topics/ui/notifiers/notifications.html">create a status bar notification</a> -to alert the user when a broadcast event occurs. More commonly, though, a broadcast receiver is -just a "gateway" to other components and is intended to do a very minimal amount of work. For -instance, it might initiate a service to perform some work based on the event. - -<p>A broadcast receiver is implemented as a subclass of {@link android.content.BroadcastReceiver} -and each broadcast is delivered as an {@link android.content.Intent} object. For more information, -see the {@link android.content.BroadcastReceiver} class.</p> -</dd> - -</dl> - - - -<p>A unique aspect of the Android system design is that any application can start another -application’s component. For example, if you want the user to capture a -photo with the device camera, there's probably another application that does that and your -application can use it, instead of developing an activity to capture a photo yourself. You don't -need to incorporate or even link to the code from the camera application. -Instead, you can simply start the activity in the camera application that captures a -photo. When complete, the photo is even returned to your application so you can use it. To the user, -it seems as if the camera is actually a part of your application.</p> - -<p>When the system starts a component, it starts the process for that application (if it's not -already running) and instantiates the classes needed for the component. For example, if your -application starts the activity in the camera application that captures a photo, that activity -runs in the process that belongs to the camera application, not in your application's process. -Therefore, unlike applications on most other systems, Android applications don't have a single entry -point (there's no {@code main()} function, for example).</p> - -<p>Because the system runs each application in a separate process with file permissions that -restrict access to other applications, your application cannot directly activate a component from -another application. The Android system, however, can. So, to activate a component in -another application, you must deliver a message to the system that specifies your <em>intent</em> to -start a particular component. The system then activates the component for you.</p> - - -<h3 id="ActivatingComponents">Activating Components</h3> - -<p>Three of the four component types—activities, services, and -broadcast receivers—are activated by an asynchronous message called an <em>intent</em>. -Intents bind individual components to each other at runtime (you can think of them -as the messengers that request an action from other components), whether the component belongs -to your application or another.</p> - -<p>An intent is created with an {@link android.content.Intent} object, which defines a message to -activate either a specific component or a specific <em>type</em> of component—an intent -can be either explicit or implicit, respectively.</p> - -<p>For activities and services, an intent defines the action to perform (for example, to "view" or -"send" something) and may specify the URI of the data to act on (among other things that the -component being started might need to know). For example, an intent might convey a request for an -activity to show an image or to open a web page. In some cases, you can start an -activity to receive a result, in which case, the activity also returns -the result in an {@link android.content.Intent} (for example, you can issue an intent to let -the user pick a personal contact and have it returned to you—the return intent includes a -URI pointing to the chosen contact).</p> - -<p>For broadcast receivers, the intent simply defines the -announcement being broadcast (for example, a broadcast to indicate the device battery is low -includes only a known action string that indicates "battery is low").</p> - -<p>The other component type, content provider, is not activated by intents. Rather, it is -activated when targeted by a request from a {@link android.content.ContentResolver}. The content -resolver handles all direct transactions with the content provider so that the component that's -performing transactions with the provider doesn't need to and instead calls methods on the {@link -android.content.ContentResolver} object. This leaves a layer of abstraction between the content -provider and the component requesting information (for security).</p> - -<p>There are separate methods for activating each type of component:</p> -<ul> - <li>You can start an activity (or give it something new to do) by -passing an {@link android.content.Intent} to {@link android.content.Context#startActivity -startActivity()} or {@link android.app.Activity#startActivityForResult startActivityForResult()} -(when you want the activity to return a result).</li> - <li>You can start a service (or give new instructions to an ongoing service) by -passing an {@link android.content.Intent} to {@link android.content.Context#startService -startService()}. Or you can bind to the service by passing an {@link android.content.Intent} to -{@link android.content.Context#bindService bindService()}.</li> - <li>You can initiate a broadcast by passing an {@link android.content.Intent} to methods like -{@link android.content.Context#sendBroadcast(Intent) sendBroadcast()}, {@link -android.content.Context#sendOrderedBroadcast(Intent, String) sendOrderedBroadcast()}, or {@link -android.content.Context#sendStickyBroadcast sendStickyBroadcast()}.</li> - <li>You can perform a query to a content provider by calling {@link -android.content.ContentProvider#query query()} on a {@link android.content.ContentResolver}.</li> -</ul> - -<p>For more information about using intents, see the <a -href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and -Intent Filters</a> document. More information about activating specific components is also provided -in the following documents: <a -href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a>, <a -href="{@docRoot}guide/topics/fundamentals/services.html">Services</a>, {@link -android.content.BroadcastReceiver} and <a -href="{@docRoot}guide/topics/providers/content-providers.html">Content Providers</a>.</p> - - -<h2 id="Manifest">The Manifest File</h2> - -<p>Before the Android system can start an application component, the system must know that the -component exists by reading the application's {@code AndroidManifest.xml} file (the "manifest" -file). Your application must declare all its components in this file, which must be at the root of -the application project directory.</p> - -<p>The manifest does a number of things in addition to declaring the application's components, -such as:</p> -<ul> - <li>Identify any user permissions the application requires, such as Internet access or -read-access to the user's contacts.</li> - <li>Declare the minimum <a href="{@docRoot}guide/appendix/api-levels.html">API Level</a> -required by the application, based on which APIs the application uses.</li> - <li>Declare hardware and software features used or required by the application, such as a camera, -bluetooth services, or a multitouch screen.</li> - <li>API libraries the application needs to be linked against (other than the Android framework -APIs), such as the <a -href="http://code.google.com/android/add-ons/google-apis/maps-overview.html">Google Maps -library</a>.</li> - <li>And more</li> -</ul> - - -<h3 id="DeclaringComponents">Declaring components</h3> - -<p>The primary task of the manifest is to inform the system about the application's components. For -example, a manifest file can declare an activity as follows: </p> - -<pre> -<?xml version="1.0" encoding="utf-8"?> -<manifest ... > - <application android:icon="@drawable/app_icon.png" ... > - <activity android:name="com.example.project.ExampleActivity" - android:label="@string/example_label" ... > - </activity> - ... - </application> -</manifest></pre> - -<p>In the <code><a -href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> -element, the {@code android:icon} attribute points to resources for an icon that identifies the -application.</p> - -<p>In the <code><a -href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element, -the {@code android:name} attribute specifies the fully qualified class name of the {@link -android.app.Activity} subclass and the {@code android:label} attributes specifies a string -to use as the user-visible label for the activity.</p> - -<p>You must declare all application components this way:</p> -<ul> - <li><code><a -href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> elements -for activities</li> - <li><code><a -href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> elements for -services</li> - <li><code><a -href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> elements -for broadcast receivers</li> - <li><code><a -href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements -for content providers</li> -</ul> - -<p>Activities, services, and content providers that you include in your source but do not declare -in the manifest are not visible to the system and, consequently, can never run. However, -broadcast -receivers can be either declared in the manifest or created dynamically in code (as -{@link android.content.BroadcastReceiver} objects) and registered with the system by calling -{@link android.content.Context#registerReceiver registerReceiver()}.</p> - -<p>For more about how to structure the manifest file for your application, see the <a -href="{@docRoot}guide/topics/manifest/manifest-intro.html">The AndroidManifest.xml File</a> -documentation. </p> - - - -<h3 id="DeclaringComponentCapabilities">Declaring component capabilities</h3> - -<p>As discussed above, in <a href="#ActivatingComponents">Activating Components</a>, you can use an -{@link android.content.Intent} to start activities, services, and broadcast receivers. You can do so -by explicitly naming the target component (using the component class name) in the intent. However, -the real power of intents lies in the concept of intent actions. With intent actions, you simply -describe the type of action you want to perform (and optionally, the data upon which you’d like to -perform the action) and allow the system to find a component on the device that can perform the -action and start it. If there are multiple components that can perform the action described by the -intent, then the user selects which one to use.</p> - -<p>The way the system identifies the components that can respond to an intent is by comparing the -intent received to the <i>intent filters</i> provided in the manifest file of other applications on -the device.</p> - -<p>When you declare a component in your application's manifest, you can optionally include -intent filters that declare the capabilities of the component so it can respond to intents -from other applications. You can declare an intent filter for your component by -adding an <a href="{@docRoot}guide/topics/manifest/intent-filter-element.html">{@code -<intent-filter>}</a> element as a child of the component's declaration element.</p> - -<p>For example, an email application with an activity for composing a new email might declare an -intent filter in its manifest entry to respond to "send" intents (in order to send email). An -activity in your application can then create an intent with the “send” action ({@link -android.content.Intent#ACTION_SEND}), which the system matches to the email application’s “send” -activity and launches it when you invoke the intent with {@link android.app.Activity#startActivity -startActivity()}.</p> - -<p>For more about creating intent filters, see the <a -href="{@docRoot}guide/topics/intents/intents-filters.html">Intents and Intent Filters</a> document. -</p> - - - -<h3 id="DeclaringRequirements">Declaring application requirements</h3> - -<p>There are a variety of devices powered by Android and not all of them provide the -same features and capabilities. In order to prevent your application from being installed on devices -that lack features needed by your application, it's important that you clearly define a profile for -the types of devices your application supports by declaring device and software requirements in your -manifest file. Most of these declarations are informational only and the system does not read -them, but external services such as Google Play do read them in order to provide filtering -for users when they search for applications from their device.</p> - -<p>For example, if your application requires a camera and uses APIs introduced in Android 2.1 (<a -href="{@docRoot}guide/appendix/api-levels.html">API Level</a> 7), you should declare these as -requirements in your manifest file. That way, devices that do <em>not</em> have a camera and have an -Android version <em>lower</em> than 2.1 cannot install your application from Google Play.</p> - -<p>However, you can also declare that your application uses the camera, but does not -<em>require</em> it. In that case, your application must perform a check at runtime to determine -if the device has a camera and disable any features that use the camera if one is not available.</p> - -<p>Here are some of the important device characteristics that you should consider as you design and -develop your application:</p> - -<dl> - <dt>Screen size and density</dt> - <dd>In order to categorize devices by their screen type, Android defines two characteristics for -each device: screen size (the physical dimensions of the screen) and screen density (the physical -density of the pixels on the screen, or dpi—dots per inch). To simplify all the different -types of screen configurations, the Android system generalizes them into select groups that make -them easier to target. -<p>The screen sizes are: small, normal, large, and extra large.<br/> -The screen densities are: low density, medium density, high density, and extra high density.</p> - -<p>By default, your application is compatible with all screen sizes and densities, -because the Android system makes the appropriate adjustments to your UI layout and image -resources. However, you should create specialized layouts for certain screen sizes and provide -specialized images for certain densities, using alternative layout resources, and by declaring in -your manifest exactly which screen sizes your application supports with the <a -href="{@docRoot}guide/topics/manifest/supports-screens-element.html">{@code -<supports-screens>}</a> element.</p> -<p>For more information, see the <a -href="{@docRoot}guide/practices/screens_support.html">Supporting Multiple Screens</a> -document.</p></dd> - - <dt>Input configurations</dt> - <dd>Many devices provide a different type of user input mechanism, such as a hardware keyboard, a -trackball, or a five-way navigation pad. If your application requires a particular kind of input -hardware, then you should declare it in your manifest with the <a -href="{@docRoot}guide/topics/manifest/uses-configuration-element.html">{@code -<uses-configuration>}</a> element. However, it is rare that an application should require -a certain input configuration.</dd> - - <dt>Device features</dt> - <dd>There are many hardware and software features that may or may not exist on a given -Android-powered device, such as a camera, a light sensor, bluetooth, a certain -version of OpenGL, or the fidelity of the touchscreen. You should never assume that a certain -feature is available on all Android-powered devices (other than the availability of the standard -Android library), so you should declare any features used by your application with the <a -href="{@docRoot}guide/topics/manifest/uses-feature-element.html">{@code <uses-feature>}</a> -element.</dd> - - <dt>Platform Version</dt> - <dd>Different Android-powered devices often run different versions of the Android platform, -such as Android 1.6 or Android 2.3. Each successive version often includes additional APIs not -available in the previous version. In order to indicate which set of APIs are available, each -platform version specifies an <a -href="{@docRoot}guide/appendix/api-levels.html">API Level</a> (for example, Android 1.0 is API Level -1 and Android 2.3 is API Level 9). If you use any APIs that were added to the platform after -version 1.0, you should declare the minimum API Level in which those APIs were introduced using the -<a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html">{@code <uses-sdk>}</a> -element.</dd> -</dl> - -<p>It's important that you declare all such requirements for your application, because, when you -distribute your application on Google Play, the store uses these declarations to filter which -applications are available on each device. As such, your application should be available only to -devices that meet all your application requirements.</p> - -<p>For more information about how Google Play filters applications based on these (and other) -requirements, see the <a href="{@docRoot}guide/appendix/market-filters.html">Filters on Google Play</a> -document.</p> - - - -<h2 id="Resources">Application Resources</h2> - -<p>An Android application is composed of more than just code—it requires resources that are -separate from the source code, such as images, audio files, and anything relating to the visual -presentation of the application. For example, you should define animations, menus, styles, colors, -and the layout of activity user interfaces with XML files. Using application resources makes it easy -to update various characteristics of your application without modifying code and—by providing -sets of alternative resources—enables you to optimize your application for a variety of -device configurations (such as different languages and screen sizes).</p> - -<p>For every resource that you include in your Android project, the SDK build tools define a unique -integer ID, which you can use to reference the resource from your application code or from -other resources defined in XML. For example, if your application contains an image file named {@code -logo.png} (saved in the {@code res/drawable/} directory), the SDK tools generate a resource ID -named {@code R.drawable.logo}, which you can use to reference the image and insert it in your -user interface.</p> - -<p>One of the most important aspects of providing resources separate from your source code -is the ability for you to provide alternative resources for different device -configurations. For example, by defining UI strings in XML, you can translate the strings into other -languages and save those strings in separate files. Then, based on a language <em>qualifier</em> -that you append to the resource directory's name (such as {@code res/values-fr/} for French string -values) and the user's language setting, the Android system applies the appropriate language strings -to your UI.</p> - -<p>Android supports many different <em>qualifiers</em> for your alternative resources. The -qualifier is a short string that you include in the name of your resource directories in order to -define the device configuration for which those resources should be used. As another -example, you should often create different layouts for your activities, depending on the -device's screen orientation and size. For example, when the device screen is in portrait -orientation (tall), you might want a layout with buttons to be vertical, but when the screen is in -landscape orientation (wide), the buttons should be aligned horizontally. To change the layout -depending on the orientation, you can define two different layouts and apply the appropriate -qualifier to each layout's directory name. Then, the system automatically applies the appropriate -layout depending on the current device orientation.</p> - -<p>For more about the different kinds of resources you can include in your application and how -to create alternative resources for various device configurations, see the <a -href="{@docRoot}guide/topics/resources/index.html">Application Resources</a> developer guide.</p> - - -<!-- -<h2>Beginner's Path</h2> - -<p>For a close look at implementing activities—the components your users use to -interact with your application—continue with the <b><a -href="{@docRoot}guide/topics/fundamentals/activities.html">Activities</a></b> document.</p> ---> |