application-element.jd revision 4e14a829129feee14ebe453f61a124784c870610
1page.title=<application> 2@jd:body 3 4<dl class="xml"> 5<dt>syntax:</dt> 6<dd><pre class="stx"><application android:<a href="#backup">allowBackup</a>=["true" | "false"] 7 android:<a href="#clear">allowClearUserData</a>=["true" | "false"] 8 android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] 9 android:<a href="#agent">backupAgent</a>="<i>string</i>" 10 android:<a href="#debug">debuggable</a>=["true" | "false"] 11 android:<a href="#desc">description</a>="<i>string resource</i>" 12 android:<a href="#enabled">enabled</a>=["true" | "false"] 13 android:<a href="#code">hasCode</a>=["true" | "false"] 14 android:<a href="#icon">icon</a>="<i>drawable resource</i>" 15 android:<a href="#killrst">killAfterRestore</a>=["true" | "false"] 16 android:<a href="#label">label</a>="<i>string resource</i>" 17 android:<a href="#space">manageSpaceActivity</a>="<i>string</i>" 18 android:<a href="#nm">name</a>="<i>string</i>" 19 android:<a href="#prmsn">permission</a>="<i>string</i>" 20 android:<a href="#persistent">persistent</a>=["true" | "false"] 21 android:<a href="#proc">process</a>="<i>string</i>" 22 android:<a href="#restoreany">restoreAnyVersion</a>=["true" | "false"] 23 android:<a href="#aff">taskAffinity</a>="<i>string</i>" 24 android:<a href="#theme">theme</a>="<i>resource or theme</i>" > 25 . . . 26</application></pre></dd> 27 28<dt>contained in:</dt> 29<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> 30 31<dt>can contain:</dt> 32<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 33<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> 34<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> 35<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> 36<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> 37<br/><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code></dd> 38 39<dt>description:</dt> 40<dd>The declaration of the application. This element contains subelements 41that declare each of the application's components and has attributes 42that can affect all the components. Many of these attributes (such as 43{@code icon}, {@code label}, {@code permission}, {@code process}, 44{@code taskAffinity}, and {@code allowTaskReparenting}) set default values 45for corresponding attributes of the component elements. Others (such as 46{@code debuggable}, {@code enabled}, {@code description}, and 47{@code allowClearUserData}) set values for the application as a whole and 48cannot be overridden by the components.</dd> 49 50<dt>attributes</dt> 51<dd><dl class="attr"> 52<dt><a name="backup"></a>{@code android:allowBackup}</dt> 53<dd>Whether the application allows its data to be backed up through the Android 54Backup Manager — "{@code true}" if it does, "{@code false}" if not. By 55default this attribute is "{@code true}". If an application declares this 56attribute to be "{@code false}" the Backup Manager will never attempt to 57perform any backup or restore operation, even if the application declares a 58valid <a href="#agent">{@code android:backupAgent}</a> attribute in its 59manifest. 60</dd> 61 62<dt><a name="clear"></a>{@code android:allowClearUserData}</dt> 63<dd>Whether or not users are given the option to remove user data — 64"{@code true}" if they are, and "{@code false}" if not. If the value is 65"{@code true}", as it is by default, the application manager includes an 66option that allows users to clear the data.</dd> 67 68<dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt> 69<dd>Whether or not activities that the application defines can move from 70the task that started them to the task they have an affinity for when that task 71is next brought to the front — "{@code true}" if they can move, and 72"{@code false}" if they must remain with the task where they started. 73The default value is "{@code false}". 74 75<p> 76The 77<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 78element has its own 79<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> 80attribute that can override the value set here. See that attribute for more 81information. 82</p></dd> 83 84<dt><a name="agent"></a>{@code android:backupAgent}</dt> 85<dd>The name of the class that implement's the application's backup agent, 86a subclass of {@link android.app.backup.BackupAgent}. The attribute value should be 87a fully qualified class name (such as, "{@code com.example.project.MyBackupAgent}"). 88However, as a shorthand, if the first character of the name is a period 89(for example, "{@code .MyBackupAgent}"), it is appended to the 90package name specified in the 91<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 92element. 93 94<p> 95There is no default. The name must be specified. 96</p></dd> 97 98<dt><a name="debug"></a>{@code android:debuggable}</dt> 99<dd>Whether or not the application can be debugged, even when running 100on a device in user mode — "{@code true}" if it can be, and "{@code false}" 101if not. The default value is "{@code false}".</dd> 102 103<dt><a name="desc"></a>{@code android:description}</dt> 104<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> 105 106<dt><a name="enabled"></a>{@code android:enabled}</dt> 107<dd>Whether or not the Android system can instantiate components of 108the application — "{@code true}" if it can, and "{@code false}" 109if not. If the value is "{@code true}", each component's 110{@code enabled} attribute determines whether that component is enabled 111or not. If the value is "{@code false}", it overrides the 112component-specific values; all components are disabled. 113 114<p> 115The default value is "{@code true}". 116</p></dd> 117 118<dt><a name="code"></a>{@code android:hasCode}</dt> 119<dd>Whether or not the application contains any code — "{@code true}" 120if it does, and "{@code false}" if not. When the value is "{@code false}", 121the system does not try to load any application code when launching components. 122The default value is "{@code true}". 123 124<p> 125An application would not have any code of its own only if it's using nothing 126but built-in component classes, such as an activity that uses the {@link 127android.app.AliasActivity} class, a rare occurrence. 128 129<dt><a name="icon"></a>{@code android:icon}</dt> 130<dd>An icon for the application as whole, and the default icon for 131each of the application's components. See the individual 132{@code icon} attributes for 133<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, 134<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, 135<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, 136<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and 137<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. 138 139<p> 140This attribute must be set as a reference to a drawable resource containing 141the image definition. There is no default icon. 142</p></dd> 143 144<dt><a name="killrst"></a>{@code android:killAfterRestore}</dt> 145<dd>Whether the application in question should be terminated after its 146settings have been restored during a full-system restore operation. 147Single-package restore operations will never cause the application to 148be shut down. Full-system restore operations typically only occur once, 149when the phone is first set up. Third-party applications will not normally 150need to use this attribute. 151 152<p>The default is {@code true}, which means that after the application 153has finished processing its data during a full-system restore, it will be 154terminated. 155</p></dd> 156 157<dt><a name="label"></a>{@code android:label}</dt> 158<dd>A user-readable label for the application as a whole, and a default 159label for each of the application's components. See the individual 160{@code label} attributes for 161<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, 162<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, 163<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, 164<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and 165<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. 166 167<p> 168The label should be set as a reference to a string resource, so that 169it can be localized like other strings in the user interface. 170However, as a convenience while you're developing the application, 171it can also be set as a raw string. 172</p></dd> 173 174<dt><a name="space"></a>{@code android:manageSpaceActivity}</dt> 175<dd>The fully qualified name of an Activity subclass that the system 176can launch to let users manage the memory occupied by the application 177on the device. The activity should also be declared with an 178<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element. 179</dd> 180 181<dt><a name="nm"></a>{@code android:name}</dt> 182<dd>The fully qualified name of an {@link android.app.Application} 183subclass implemented for the application. When the application process 184is started, this class is instantiated before any of the application's 185components. 186 187<p> 188The subclass is optional; most applications won't need one. 189In the absence of a subclass, Android uses an instance of the base 190Application class. 191</p></dd> 192 193<dt><a name="prmsn"></a>{@code android:permission}</dt> 194<dd>The name of a permission that clients must have in order to interact 195with the application. This attribute is a convenient way to set a 196permission that applies to all of the application's components. It can 197be overwritten by setting the {@code permission} attributes of individual 198components. 199 200<p> 201For more information on permissions, see the 202<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> 203section in the introduction and another document, 204<a href="{@docRoot}guide/topics/security/security.html">Security and 205Permissions</a>. 206</p></dd> 207 208<dt><a name="persistent"></a>{@code android:persistent}</dt> 209<dd>Whether or not the application should remain running at all times — 210"{@code true}" if it should, and "{@code false}" if not. The default value 211is "{@code false}". Applications should not normally set this flag; 212persistence mode is intended only for certain system applications.</dd> 213 214<dt><a name="proc"></a>{@code android:process}</dt> 215<dd>The name of a process where all components of the application should run. 216Each component can override this default by setting its own {@code process} 217attribute. 218 219<p> 220By default, Android creates a process for an application when the first 221of its components needs to run. All components then run in that process. 222The name of the default process matches the package name set by the 223<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. 224</p> 225 226<p>By setting this attribute to a process name that's shared with another 227application, you can arrange for components of both applications to run in 228the same process — but only if the two applications also share a 229user ID and be signed with the same certificate. 230</p> 231 232<p> 233If the name assigned to this attribute begins with a colon (':'), a new 234process, private to the application, is created when it's needed. 235If the process name begins with a lowercase character, a global process 236of that name is created. A global process can be shared with other 237applications, reducing resource usage. 238</p></dd> 239 240<dt><a href name="restoreany"></a>{@code android:restoreAnyVersion}</dt> 241<dd>Indicate that the application is prepared to attempt a restore of any 242backed-up data set, even if the backup was stored by a newer version 243of the application than is currently installed on the device. Setting 244this attribute to {@code true} will permit the Backup Manager to 245attempt restore even when a version mismatch suggests that the data are 246incompatible. <em>Use with caution!</em> 247 248<p>The default value of this attribute is {@code false}. 249</p></dd> 250 251<dt><a href name="aff"></a>{@code android:taskAffinity}</dt> 252<dd>An affinity name that applies to all activities within the application, 253except for those that set a different affinity with their own 254<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> 255attributes. See that attribute for more information. 256 257<p> 258By default, all activities within an application share the same 259affinity. The name of that affinity is the same as the package name 260set by the 261<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. 262</p></dd> 263 264<dt><a name="theme"></a>{@code android:theme}</dt> 265<dd>A reference to a style resource defining a default theme for all 266activities in the application. Individual activities can override 267the default by setting their own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#theme">theme</a></code> 268attributes; see that attribute for more information.</dd> 269 270</dl></dd> 271 272<!-- ##api level indication## --> 273<dt>introduced in:</dt> 274<dd>API Level 1</dd> 275 276<dt>see also:</dt> 277<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 278<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> 279<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> 280<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code></dd> 281 282</dl> 283