application-element.jd revision 01e1b832d722a9ee4322714da739d79e24ac8d07
1page.title=<application> 2parent.title=The AndroidManifest.xml File 3parent.link=manifest-intro.html 4@jd:body 5 6<dl class="xml"> 7<dt>syntax:</dt> 8<dd><pre class="stx"><application 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="#hwaccel">hardwareAccelerated</a>=["true" | "false"] 15 android:<a href="#icon">icon</a>="<i>drawable resource</i>" 16 android:<a href="#killrst">killAfterRestore</a>=["true" | "false"] 17 android:<a href="#largeHeap">largeHeap</a>=["true" | "false"] 18 android:<a href="#label">label</a>="<i>string resource</i>" 19 android:<a href="#logo">logo</a>="<i>drawable resource</i>" 20 android:<a href="#space">manageSpaceActivity</a>="<i>string</i>" 21 android:<a href="#nm">name</a>="<i>string</i>" 22 android:<a href="#prmsn">permission</a>="<i>string</i>" 23 android:<a href="#persistent">persistent</a>=["true" | "false"] 24 android:<a href="#proc">process</a>="<i>string</i>" 25 android:<a href="#restoreany">restoreAnyVersion</a>=["true" | "false"] 26 android:<a href="#aff">taskAffinity</a>="<i>string</i>" 27 android:<a href="#theme">theme</a>="<i>resource or theme</i>" 28 android:<a href="#uioptions">uiOptions</a>=["none" | "splitActionBarWhenNarrow"] > 29 . . . 30</application></pre></dd> 31 32<dt>contained in:</dt> 33<dd><code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code></dd> 34 35<dt>can contain:</dt> 36<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 37<br/><code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code> 38<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> 39<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> 40<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> 41<br/><code><a href="{@docRoot}guide/topics/manifest/uses-library-element.html"><uses-library></a></code></dd> 42 43<dt>description:</dt> 44<dd>The declaration of the application. This element contains subelements 45that declare each of the application's components and has attributes 46that can affect all the components. Many of these attributes (such as 47{@code icon}, {@code label}, {@code permission}, {@code process}, 48{@code taskAffinity}, and {@code allowTaskReparenting}) set default values 49for corresponding attributes of the component elements. Others (such as 50{@code debuggable}, {@code enabled}, {@code description}, and 51{@code allowClearUserData}) set values for the application as a whole and 52cannot be overridden by the components.</dd> 53 54<dt>attributes</dt> 55<dd><dl class="attr"> 56 57<dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt> 58<dd>Whether or not activities that the application defines can move from 59the task that started them to the task they have an affinity for when that task 60is next brought to the front — "{@code true}" if they can move, and 61"{@code false}" if they must remain with the task where they started. 62The default value is "{@code false}". 63 64<p> 65The 66<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 67element has its own 68<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> 69attribute that can override the value set here. See that attribute for more 70information. 71</p></dd> 72 73<dt><a name="agent"></a>{@code android:backupAgent}</dt> 74<dd>The name of the class that implement's the application's backup agent, 75a subclass of {@link android.app.backup.BackupAgent}. The attribute value should be 76a fully qualified class name (such as, "{@code com.example.project.MyBackupAgent}"). 77However, as a shorthand, if the first character of the name is a period 78(for example, "{@code .MyBackupAgent}"), it is appended to the 79package name specified in the 80<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> 81element. 82 83<p> 84There is no default. The name must be specified. 85</p></dd> 86 87<dt><a name="debug"></a>{@code android:debuggable}</dt> 88<dd>Whether or not the application can be debugged, even when running 89on a device in user mode — "{@code true}" if it can be, and "{@code false}" 90if not. The default value is "{@code false}".</dd> 91 92<dt><a name="desc"></a>{@code android:description}</dt> 93<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> 94 95<dt><a name="enabled"></a>{@code android:enabled}</dt> 96<dd>Whether or not the Android system can instantiate components of 97the application — "{@code true}" if it can, and "{@code false}" 98if not. If the value is "{@code true}", each component's 99{@code enabled} attribute determines whether that component is enabled 100or not. If the value is "{@code false}", it overrides the 101component-specific values; all components are disabled. 102 103<p> 104The default value is "{@code true}". 105</p></dd> 106 107<dt><a name="code"></a>{@code android:hasCode}</dt> 108<dd>Whether or not the application contains any code — "{@code true}" 109if it does, and "{@code false}" if not. When the value is "{@code false}", 110the system does not try to load any application code when launching components. 111The default value is "{@code true}". 112 113<p> 114An application would not have any code of its own only if it's using nothing 115but built-in component classes, such as an activity that uses the {@link 116android.app.AliasActivity} class, a rare occurrence.</p> 117</dd> 118 119<dt><a name="hwaccel"></a>{@code android:hardwareAccelerated}</dt> 120<dd>Whether or not hardware-accelerated rendering should be enabled for all 121Activities and Views in this application — "{@code true}" if it 122should be enabled, and "{@code false}" if not. The default value is "{@code false}". 123 124<p>Starting from Android 3.0, a hardware-accelerated OpenGL renderer is 125available to applications, to improve performance for many common 2D graphics 126operations. When the hardware-accelerated renderer is enabled, most operations 127in Canvas, Paint, Xfermode, ColorFilter, Shader, and Camera are accelerated. 128This results in smoother animations, smoother scrolling, and improved 129responsiveness overall, even for applications that do not explicitly make use 130the framework's OpenGL libraries. </p> 131 132<p>Note that not all of the OpenGL 2D operations are accelerated. If you enable 133the hardware-accelerated renderer, test your application to ensure that it can 134make use of the renderer without errors.</p> 135</dd> 136 137<dt><a name="icon"></a>{@code android:icon}</dt> 138<dd>An icon for the application as whole, and the default icon for 139each of the application's components. See the individual 140{@code icon} attributes for 141<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, 142<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, 143<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, 144<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and 145<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. 146 147<p> 148This attribute must be set as a reference to a drawable resource containing 149the image (for example {@code "@drawable/icon"}). There is no default icon. 150</p></dd> 151 152<dt><a name="killrst"></a>{@code android:killAfterRestore}</dt> 153<dd>Whether the application in question should be terminated after its 154settings have been restored during a full-system restore operation. 155Single-package restore operations will never cause the application to 156be shut down. Full-system restore operations typically only occur once, 157when the phone is first set up. Third-party applications will not normally 158need to use this attribute. 159 160<p>The default is {@code true}, which means that after the application 161has finished processing its data during a full-system restore, it will be 162terminated. 163</p></dd> 164 165<dt><a name="largeHeap"></a>{@code android:largeHeap}</dt> 166<dd>Whether your application's processes should be created with a large Dalvik heap. This applies to 167all processes created for the application. It only applies to the first application loaded into a 168process; if you're using a shared user ID to allow multiple applications to use a process, they all 169must use this option consistently or they will have unpredictable results. 170<p>Most apps should not need this and should instead focus on reducing their overall memory usage for 171improved performance. Enabling this also does not guarantee a fixed increase in available memory, 172because some devices are constrained by their total available memory.</p> 173<p>To query the available memory size at runtime, use the methods {@link 174 android.app.ActivityManager#getMemoryClass()} or {@link 175 android.app.ActivityManager#getLargeMemoryClass()}.</p> 176</dd> 177 178<dt><a name="label"></a>{@code android:label}</dt> 179<dd>A user-readable label for the application as a whole, and a default 180label for each of the application's components. See the individual 181{@code label} attributes for 182<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, 183<code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, 184<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, 185<code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and 186<code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. 187 188<p> 189The label should be set as a reference to a string resource, so that 190it can be localized like other strings in the user interface. 191However, as a convenience while you're developing the application, 192it can also be set as a raw string. 193</p></dd> 194 195<dt><a name="logo"></a>{@code android:logo}</dt> 196<dd>A logo for the application as whole, and the default logo for activities. 197<p>This attribute must be set as a reference to a drawable resource containing 198the image (for example {@code "@drawable/logo"}). There is no default logo.</p></dd> 199 200<dt><a name="space"></a>{@code android:manageSpaceActivity}</dt> 201<dd>The fully qualified name of an Activity subclass that the system 202can launch to let users manage the memory occupied by the application 203on the device. The activity should also be declared with an 204<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element. 205</dd> 206 207<dt><a name="nm"></a>{@code android:name}</dt> 208<dd>The fully qualified name of an {@link android.app.Application} 209subclass implemented for the application. When the application process 210is started, this class is instantiated before any of the application's 211components. 212 213<p> 214The subclass is optional; most applications won't need one. 215In the absence of a subclass, Android uses an instance of the base 216Application class. 217</p></dd> 218 219<dt><a name="prmsn"></a>{@code android:permission}</dt> 220<dd>The name of a permission that clients must have in order to interact 221with the application. This attribute is a convenient way to set a 222permission that applies to all of the application's components. It can 223be overwritten by setting the {@code permission} attributes of individual 224components. 225 226<p> 227For more information on permissions, see the 228<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> 229section in the introduction and another document, 230<a href="{@docRoot}guide/topics/security/security.html">Security and 231Permissions</a>. 232</p></dd> 233 234<dt><a name="persistent"></a>{@code android:persistent}</dt> 235<dd>Whether or not the application should remain running at all times — 236"{@code true}" if it should, and "{@code false}" if not. The default value 237is "{@code false}". Applications should not normally set this flag; 238persistence mode is intended only for certain system applications.</dd> 239 240<dt><a name="proc"></a>{@code android:process}</dt> 241<dd>The name of a process where all components of the application should run. 242Each component can override this default by setting its own {@code process} 243attribute. 244 245<p> 246By default, Android creates a process for an application when the first 247of its components needs to run. All components then run in that process. 248The name of the default process matches the package name set by the 249<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. 250</p> 251 252<p>By setting this attribute to a process name that's shared with another 253application, you can arrange for components of both applications to run in 254the same process — but only if the two applications also share a 255user ID and be signed with the same certificate. 256</p> 257 258<p> 259If the name assigned to this attribute begins with a colon (':'), a new 260process, private to the application, is created when it's needed. 261If the process name begins with a lowercase character, a global process 262of that name is created. A global process can be shared with other 263applications, reducing resource usage. 264</p></dd> 265 266<dt><a name="restoreany"></a>{@code android:restoreAnyVersion}</dt> 267<dd>Indicate that the application is prepared to attempt a restore of any 268backed-up data set, even if the backup was stored by a newer version 269of the application than is currently installed on the device. Setting 270this attribute to {@code true} will permit the Backup Manager to 271attempt restore even when a version mismatch suggests that the data are 272incompatible. <em>Use with caution!</em> 273 274<p>The default value of this attribute is {@code false}. 275</p></dd> 276 277<dt><a name="aff"></a>{@code android:taskAffinity}</dt> 278<dd>An affinity name that applies to all activities within the application, 279except for those that set a different affinity with their own 280<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> 281attributes. See that attribute for more information. 282 283<p> 284By default, all activities within an application share the same 285affinity. The name of that affinity is the same as the package name 286set by the 287<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. 288</p></dd> 289 290<dt><a name="theme"></a>{@code android:theme}</dt> 291<dd>A reference to a style resource defining a default theme for all 292activities in the application. Individual activities can override 293the default by setting their own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#theme">theme</a></code> 294attributes. For more information, see the <a 295href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> developer guide. 296</dd> 297 298<!-- ##api level 14## --> 299<dt><a name="uioptions"></a>{@code android:uiOptions}</dt> 300<dd>Extra options for an activity's UI. 301 <p>Must be one of the following values.</p> 302 303 <table> 304 <tr><th>Value</th><th>Description</th></tr> 305 <tr><td>{@code "none"}</td><td>No extra UI options. This is the default.</td></tr> 306 <tr><td>{@code "splitActionBarWhenNarrow"}</td><td>Add a bar at 307the bottom of the screen to display action items in the {@link android.app.ActionBar}, when 308constrained for horizontal space (such as when in portrait mode on a handset). Instead of a small 309number of action items appearing in the action bar at the top of the screen, the action bar is 310split into the top navigation section and the bottom bar for action items. This ensures a reasonable 311amount of space is made available not only for the action items, but also for navigation and title 312elements at the top. Menu items are not split across the two bars; they always appear 313together.</td></tr> 314 </table> 315 <p>For more information about the action bar, see the <a 316href="{@docRoot}guide/topics/ui/actionbar.html">Action Bar</a> developer guide.</p> 317 <p>This attribute was added in API level 14.</p> 318</dd> 319 320</dl></dd> 321 322<!-- ##api level indication## --> 323<dt>introduced in:</dt> 324<dd>API Level 1</dd> 325 326<dt>see also:</dt> 327<dd><code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> 328<br/><code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code> 329<br/><code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code> 330<br/><code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code></dd> 331 332</dl> 333