diff options
| -rw-r--r-- | docs/html/guide/topics/manifest/manifest-intro.jd | 366 |
1 files changed, 189 insertions, 177 deletions
diff --git a/docs/html/guide/topics/manifest/manifest-intro.jd b/docs/html/guide/topics/manifest/manifest-intro.jd index d7b176e810a0..c843567488e5 100644 --- a/docs/html/guide/topics/manifest/manifest-intro.jd +++ b/docs/html/guide/topics/manifest/manifest-intro.jd @@ -31,27 +31,27 @@ page.title=App Manifest <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 +<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 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 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 +<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 +<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 level of the Android API that the application +<li>It declares the minimum level of the Android API that the application requires.</li> <li>It lists the libraries that the application must be linked against.</li> @@ -61,12 +61,12 @@ requires.</li> <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, +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. +other mention of the element name. </p> <pre> @@ -126,9 +126,9 @@ other mention of the element name. </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. +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"> @@ -158,74 +158,86 @@ add your own elements or attributes. </p> - + <h2 id="filec">File Conventions</h2> <p> -Some conventions and rules apply generally to all elements and attributes +Some conventions and rules apply generally to all elements and attributes in the manifest: </p> <dl> <dt><b>Elements</b></dt> -<dd>Only the +<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 +<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. +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.) +<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. There are two key exceptions to this +rule, however: +<ul> + <li> + An <code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> + element must follow the + <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> + it is an alias for. + </li> + <li> + The <code><a href="{@docRoot}guide/topics/manifest/application-element.html"><application></a></code> + element must be the last element inside the + <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> + element. In other words, the <code></application></code> closing tag + must appear immediately before the <code></manifest></code> closing + tag. + </li> </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 +<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 +<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>). +<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. +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> @@ -239,12 +251,12 @@ For example, an {@link android.app.Service} subclass might be declared as follow </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: +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" . . . > @@ -257,13 +269,13 @@ attribute). The following assignment is the same as the one above: </manifest></pre> <p> -When starting a component, Android creates an instance of the named subclass. +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. +<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 . . . > @@ -274,24 +286,24 @@ For example, an intent filter can list several actions: </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 +<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. +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 ?}' +Values from a theme are expressed in a similar manner, but with an initial '{@code ?}' rather than '{@code @}': </p> @@ -299,8 +311,8 @@ rather than '{@code @}': </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 +<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> @@ -308,7 +320,7 @@ a newline or '{@code \\uxxxx}' for a Unicode character.</dd> <h2 id="filef">File Features</h2> <p> -The following sections describe how some Android features are reflected +The following sections describe how some Android features are reflected in the manifest file. </p> @@ -316,23 +328,23 @@ in the manifest file. <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 +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 +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> @@ -344,9 +356,9 @@ filters. </p> <p> -For information on how Intent objects are tested against intent filters, -see a separate document, -<a href="{@docRoot}guide/components/intents-filters.html">Intents +For information on how Intent objects are tested against intent filters, +see a separate document, +<a href="{@docRoot}guide/components/intents-filters.html">Intents and Intent Filters</a>. </p> @@ -354,42 +366,42 @@ and Intent Filters</a>. <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 +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 +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> +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 +<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 +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 +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 +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> @@ -397,14 +409,14 @@ set in the filter are therefore the ones displayed in the launcher. <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. +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 +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> @@ -418,26 +430,26 @@ 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. +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> +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> @@ -457,43 +469,43 @@ element. For example, an activity could be protected as follows: </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. +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>. +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 +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 +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; +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> +<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> @@ -501,17 +513,17 @@ attribute. <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, +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 +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> |