diff options
| -rw-r--r-- | docs/html/design/tv/patterns.jd | 2 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/activity-element.jd | 24 | ||||
| -rw-r--r-- | docs/html/guide/topics/manifest/application-element.jd | 174 | ||||
| -rw-r--r-- | docs/html/training/tv/games/index.jd | 24 | ||||
| -rw-r--r-- | docs/html/training/tv/start/start.jd | 31 |
5 files changed, 170 insertions, 85 deletions
diff --git a/docs/html/design/tv/patterns.jd b/docs/html/design/tv/patterns.jd index 768dcfc..be7ae31 100644 --- a/docs/html/design/tv/patterns.jd +++ b/docs/html/design/tv/patterns.jd @@ -41,6 +41,8 @@ page.title=UI Patterns for TV language, you must provide versions of the banner image for each supported language.</li> </ul> +<p>See <a href="{@docRoot}training/tv/start/start.html#banner">Provide a home screen banner</a> +in Get Started with TV Apps for more information.</p> <h3>Recommendation Icons</h3> diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index ade05c9..7374a67 100644 --- a/docs/html/guide/topics/manifest/activity-element.jd +++ b/docs/html/guide/topics/manifest/activity-element.jd @@ -9,6 +9,7 @@ parent.link=manifest-intro.html android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] android:<a href="#always">alwaysRetainTaskState</a>=["true" | "false"] android:<a href="#autoremrecents">autoRemoveFromRecents</a>=["true" | "false"] + android:<a href="#banner">banner</a>="<i>drawable resource</i>" android:<a href="#clear">clearTaskOnLaunch</a>=["true" | "false"] android:<a href="#config">configChanges</a>=["mcc", "mnc", "locale", "touchscreen", "keyboard", "keyboardHidden", @@ -153,6 +154,29 @@ automatically removed from the overview screen. This overrides the caller's use "{@code true}" or "{@code false}".</dd> +<dt><a name="banner"></a>{@code android:banner}</dt> +<dd>A <a href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resource</a> +providing an extended graphical banner for its associated item. Use with the +{@code <activity>} tag to supply a default banner for a specific activity, or with the +<a href="{@docRoot}guide/topics/manifest/application-element.html"><code><application></code></a> +tag to supply a banner for all application activities. + +<p>The system uses the banner to represent an app in +the Android TV home screen. Since the banner is displayed only in the home screen, it +should only be specified by applications with an activity that handles the +{@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent.</p> + +<p>This attribute must be set as a reference to a drawable resource containing +the image (for example {@code "@drawable/banner"}). There is no default banner. +</p> + +<p> +See <a href="{@docRoot}design/tv/patterns.html#banner"> +Banners</a> in the UI Patterns for TV design guide, and <a href="{@docRoot}training/tv/start/start.html#banner"> +Provide a home screen banner</a> in Get Started with TV Apps for more information. +</p></dd> + + <dt><a name="clear"></a>{@code android:clearTaskOnLaunch}</dt> <dd>Whether or not all activities will be removed from the task, except for the root activity, whenever it is re-launched from the home screen — diff --git a/docs/html/guide/topics/manifest/application-element.jd b/docs/html/guide/topics/manifest/application-element.jd index 33f6bce..8a0e837 100644 --- a/docs/html/guide/topics/manifest/application-element.jd +++ b/docs/html/guide/topics/manifest/application-element.jd @@ -7,12 +7,14 @@ page.title=<application> <dd><pre class="stx"><application android:<a href="#reparent">allowTaskReparenting</a>=["true" | "false"] android:<a href="#allowbackup">allowBackup</a>=["true" | "false"] android:<a href="#agent">backupAgent</a>="<i>string</i>" + android:<a href="#banner">banner</a>="<i>drawable resource</i>" android:<a href="#debug">debuggable</a>=["true" | "false"] android:<a href="#desc">description</a>="<i>string resource</i>" android:<a href="#enabled">enabled</a>=["true" | "false"] android:<a href="#code">hasCode</a>=["true" | "false"] android:<a href="#hwaccel">hardwareAccelerated</a>=["true" | "false"] android:<a href="#icon">icon</a>="<i>drawable resource</i>" + android:<a href="#isGame">isGame</a>=["true" | "false"] android:<a href="#killrst">killAfterRestore</a>=["true" | "false"] android:<a href="#largeHeap">largeHeap</a>=["true" | "false"] android:<a href="#label">label</a>="<i>string resource</i>" @@ -48,13 +50,13 @@ page.title=<application> <dt>description:</dt> <dd itemprop="description">The declaration of the application. This element contains subelements -that declare each of the application's components and has attributes -that can affect all the components. Many of these attributes (such as -{@code icon}, {@code label}, {@code permission}, {@code process}, -{@code taskAffinity}, and {@code allowTaskReparenting}) set default values +that declare each of the application's components and has attributes +that can affect all the components. Many of these attributes (such as +{@code icon}, {@code label}, {@code permission}, {@code process}, +{@code taskAffinity}, and {@code allowTaskReparenting}) set default values for corresponding attributes of the component elements. Others (such as -{@code debuggable}, {@code enabled}, {@code description}, and -{@code allowClearUserData}) set values for the application as a whole and +{@code debuggable}, {@code enabled}, {@code description}, and +{@code allowClearUserData}) set values for the application as a whole and cannot be overridden by the components.</dd> @@ -65,18 +67,18 @@ cannot be overridden by the components.</dd> <dd><dl class="attr"> <dt><a name="reparent"></a>{@code android:allowTaskReparenting}</dt> -<dd>Whether or not activities that the application defines can move from -the task that started them to the task they have an affinity for when that task -is next brought to the front — {@code "true"} if they can move, and -{@code "false"} if they must remain with the task where they started. +<dd>Whether or not activities that the application defines can move from +the task that started them to the task they have an affinity for when that task +is next brought to the front — {@code "true"} if they can move, and +{@code "false"} if they must remain with the task where they started. The default value is {@code "false"}. <p> -The -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> -element has its own +The +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> +element has its own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#reparent">allowTaskReparenting</a></code> -attribute that can override the value set here. See that attribute for more +attribute that can override the value set here. See that attribute for more information. </p></dd> @@ -92,46 +94,68 @@ The default value of this attribute is true.</dd> <dt><a name="agent"></a>{@code android:backupAgent}</dt> <dd>The name of the class that implement's the application's backup agent, a subclass of {@link android.app.backup.BackupAgent}. The attribute value should be -a fully qualified class name (such as, {@code "com.example.project.MyBackupAgent"}). -However, as a shorthand, if the first character of the name is a period -(for example, {@code ".MyBackupAgent"}), it is appended to the -package name specified in the -<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> +a fully qualified class name (such as, {@code "com.example.project.MyBackupAgent"}). +However, as a shorthand, if the first character of the name is a period +(for example, {@code ".MyBackupAgent"}), it is appended to the +package name specified in the +<code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. <p> There is no default. The name must be specified. </p></dd> +<dt><a name="banner"></a>{@code android:banner}</dt> +<dd>A <a href="{@docRoot}guide/topics/resources/drawable-resource.html">drawable resource</a> +providing an extended graphical banner for its associated item. Use with the +{@code <application>} tag to supply a default banner for all application activities, or with the +<a href="{@docRoot}guide/topics/manifest/activity-element.html"><code><activity></code></a> +tag to supply a banner for a specific activity. + +<p>The system uses the banner to represent an app in +the Android TV home screen. Since the banner is displayed only in the home screen, it +should only be specified by applications with an activity that handles the +{@link android.content.Intent#CATEGORY_LEANBACK_LAUNCHER} intent.</p> + +<p>This attribute must be set as a reference to a drawable resource containing +the image (for example {@code "@drawable/banner"}). There is no default banner. +</p> + +<p> +See <a href="{@docRoot}design/tv/patterns.html#banner"> +Banners</a> in the UI Patterns for TV design guide, and <a href="{@docRoot}training/tv/start/start.html#banner"> +Provide a home screen banner</a> in Get Started with TV Apps for more information. +</p></dd> + <dt><a name="debug"></a>{@code android:debuggable}</dt> -<dd>Whether or not the application can be debugged, even when running +<dd>Whether or not the application can be debugged, even when running on a device in user mode — {@code "true"} if it can be, and {@code "false"} -if not. The default value is {@code "false"}.</dd> +if not. The default value is {@code "false"}.</dd> <dt><a name="desc"></a>{@code android:description}</dt> <dd>User-readable text about the application, longer and more descriptive than the application label. The value must be set as a reference to a string resource. Unlike the label, it cannot be a raw string. There is no default value.</dd> <dt><a name="enabled"></a>{@code android:enabled}</dt> -<dd>Whether or not the Android system can instantiate components of -the application — {@code "true"} if it can, and {@code "false"} -if not. If the value is {@code "true"}, each component's -{@code enabled} attribute determines whether that component is enabled -or not. If the value is {@code "false"}, it overrides the +<dd>Whether or not the Android system can instantiate components of +the application — {@code "true"} if it can, and {@code "false"} +if not. If the value is {@code "true"}, each component's +{@code enabled} attribute determines whether that component is enabled +or not. If the value is {@code "false"}, it overrides the component-specific values; all components are disabled. <p> The default value is {@code "true"}. -</p></dd> +</p></dd> <dt><a name="code"></a>{@code android:hasCode}</dt> -<dd>Whether or not the application contains any code — {@code "true"} -if it does, and {@code "false"} if not. When the value is {@code "false"}, -the system does not try to load any application code when launching components. +<dd>Whether or not the application contains any code — {@code "true"} +if it does, and {@code "false"} if not. When the value is {@code "false"}, +the system does not try to load any application code when launching components. The default value is {@code "true"}. <p> An application would not have any code of its own only if it's using nothing -but built-in component classes, such as an activity that uses the {@link +but built-in component classes, such as an activity that uses the {@link android.app.AliasActivity} class, a rare occurrence.</p> </dd> @@ -140,7 +164,7 @@ android.app.AliasActivity} class, a rare occurrence.</p> activities and views in this application — {@code "true"} if it should be enabled, and {@code "false"} if not. The default value is {@code "true"} if you've set either <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#min">{@code minSdkVersion}</a> -or <a +or <a href="{@docRoot}guide/topics/manifest/uses-sdk-element.html#target">{@code targetSdkVersion}</a> to {@code "14"} or higher; otherwise, it's {@code "false"}. @@ -161,20 +185,26 @@ make use of the renderer without errors.</p> </dd> <dt><a name="icon"></a>{@code android:icon}</dt> -<dd>An icon for the application as whole, and the default icon for -each of the application's components. See the individual -{@code icon} attributes for -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, +<dd>An icon for the application as whole, and the default icon for +each of the application's components. See the individual +{@code icon} attributes for +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, <code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, +<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, <code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. <p> This attribute must be set as a reference to a drawable resource containing -the image (for example {@code "@drawable/icon"}). There is no default icon. +the image (for example {@code "@drawable/icon"}). There is no default icon. </p></dd> +<dt><a name="isGame"></a>{@code android:isGame}</dt> +<dd>Whether or not the application is a game. The system may group together applications classifed +as games or display them separately from other applications. + +<p>The default is {@code false}.</p></dd> + <dt><a name="killrst"></a>{@code android:killAfterRestore}</dt> <dd>Whether the application in question should be terminated after its settings have been restored during a full-system restore operation. @@ -202,65 +232,65 @@ because some devices are constrained by their total available memory.</p> </dd> <dt><a name="label"></a>{@code android:label}</dt> -<dd>A user-readable label for the application as a whole, and a default -label for each of the application's components. See the individual -{@code label} attributes for -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, +<dd>A user-readable label for the application as a whole, and a default +label for each of the application's components. See the individual +{@code label} attributes for +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code>, <code><a href="{@docRoot}guide/topics/manifest/activity-alias-element.html"><activity-alias></a></code>, -<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, +<code><a href="{@docRoot}guide/topics/manifest/service-element.html"><service></a></code>, <code><a href="{@docRoot}guide/topics/manifest/receiver-element.html"><receiver></a></code>, and <code><a href="{@docRoot}guide/topics/manifest/provider-element.html"><provider></a></code> elements. <p> The label should be set as a reference to a string resource, so that -it can be localized like other strings in the user interface. -However, as a convenience while you're developing the application, +it can be localized like other strings in the user interface. +However, as a convenience while you're developing the application, it can also be set as a raw string. </p></dd> <dt><a name="logo"></a>{@code android:logo}</dt> <dd>A logo for the application as whole, and the default logo for activities. <p>This attribute must be set as a reference to a drawable resource containing -the image (for example {@code "@drawable/logo"}). There is no default logo.</p></dd> +the image (for example {@code "@drawable/logo"}). There is no default logo.</p></dd> <dt><a name="space"></a>{@code android:manageSpaceActivity}</dt> -<dd>The fully qualified name of an Activity subclass that the system -can launch to let users manage the memory occupied by the application -on the device. The activity should also be declared with an +<dd>The fully qualified name of an Activity subclass that the system +can launch to let users manage the memory occupied by the application +on the device. The activity should also be declared with an <code><a href="{@docRoot}guide/topics/manifest/activity-element.html"><activity></a></code> element. </dd> <dt><a name="nm"></a>{@code android:name}</dt> -<dd>The fully qualified name of an {@link android.app.Application} -subclass implemented for the application. When the application process -is started, this class is instantiated before any of the application's -components. +<dd>The fully qualified name of an {@link android.app.Application} +subclass implemented for the application. When the application process +is started, this class is instantiated before any of the application's +components. <p> The subclass is optional; most applications won't need one. -In the absence of a subclass, Android uses an instance of the base +In the absence of a subclass, Android uses an instance of the base Application class. </p></dd> <dt><a name="prmsn"></a>{@code android:permission}</dt> -<dd>The name of a permission that clients must have in order to interact -with the application. This attribute is a convenient way to set a -permission that applies to all of the application's components. It can -be overwritten by setting the {@code permission} attributes of individual +<dd>The name of a permission that clients must have in order to interact +with the application. This attribute is a convenient way to set a +permission that applies to all of the application's components. It can +be overwritten by setting the {@code permission} attributes of individual components. <p> -For more information on permissions, see the -<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> -section in the introduction and another document, +For more information on permissions, see the +<a href="{@docRoot}guide/topics/manifest/manifest-intro.html#sectperm">Permissions</a> +section in the introduction and another document, <a href="{@docRoot}guide/topics/security/security.html">Security and Permissions</a>. </p></dd> <dt><a name="persistent"></a>{@code android:persistent}</dt> -<dd>Whether or not the application should remain running at all times — -{@code "true"} if it should, and {@code "false"} if not. The default value -is {@code "false"}. Applications should not normally set this flag; +<dd>Whether or not the application should remain running at all times — +{@code "true"} if it should, and {@code "false"} if not. The default value +is {@code "false"}. Applications should not normally set this flag; persistence mode is intended only for certain system applications.</dd> <dt><a name="proc"></a>{@code android:process}</dt> @@ -282,9 +312,9 @@ user ID and be signed with the same certificate. </p> <p> -If the name assigned to this attribute begins with a colon (':'), a new +If the name assigned to this attribute begins with a colon (':'), a new process, private to the application, is created when it's needed. -If the process name begins with a lowercase character, a global process +If the process name begins with a lowercase character, a global process of that name is created. A global process can be shared with other applications, reducing resource usage. </p></dd> @@ -307,7 +337,7 @@ incompatible. <em>Use with caution!</em> If your app requires an {@link android.accounts.Account}, the value for this attribute must correspond to the account authenticator type used by your app (as defined by {@link android.accounts.AuthenticatorDescription}), -such as "com.google". +such as "com.google". <p>The default value is null and indicates that the application can work <em>without</em> any accounts. @@ -369,13 +399,13 @@ direction associated to the user's Locale choice (your layouts will always be le <dt><a name="aff"></a>{@code android:taskAffinity}</dt> <dd>An affinity name that applies to all activities within the application, except for those that set a different affinity with their own -<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> +<code><a href="{@docRoot}guide/topics/manifest/activity-element.html#aff">taskAffinity</a></code> attributes. See that attribute for more information. <p> -By default, all activities within an application share the same -affinity. The name of that affinity is the same as the package name -set by the +By default, all activities within an application share the same +affinity. The name of that affinity is the same as the package name +set by the <code><a href="{@docRoot}guide/topics/manifest/manifest-element.html"><manifest></a></code> element. </p></dd> @@ -389,7 +419,7 @@ only through adb.</dd> <dt><a name="theme"></a>{@code android:theme}</dt> <dd>A reference to a style resource defining a default theme for all activities in the application. Individual activities can override -the default by setting their own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#theme">theme</a></code> +the default by setting their own <code><a href="{@docRoot}guide/topics/manifest/activity-element.html#theme">theme</a></code> attributes. For more information, see the <a href="{@docRoot}guide/topics/ui/themes.html">Styles and Themes</a> developer guide. </dd> diff --git a/docs/html/training/tv/games/index.jd b/docs/html/training/tv/games/index.jd index 2f510a9..8a998e0 100644 --- a/docs/html/training/tv/games/index.jd +++ b/docs/html/training/tv/games/index.jd @@ -194,22 +194,22 @@ It includes a white controller on black background and a black controller on whi <p>There are a some special things games should include in the Android manifest.</p> -<h3 id="Launcher">Show your game in the launcher</h3> +<h3 id="Launcher">Show your game on the home screen</h3> <p> - The Android TV launcher home screen displays games in a separate row from regular apps. - To make your game appear in the list of games, add the - <a href="{@docRoot}guide/topics/manifest/meta-data-element.html" - ><code><meta-data></code></a> tag in your app manifest with <code>android:name</code> - set to <code>"isGame"</code> and <code>android:value</code> - set to <code>"true"</code>. For example: + The Android TV home screen displays games in a separate row from regular apps. + To make your game appear in the list of games, set the + <a href="{@docRoot}guide/topics/manifest/application-element.html#isGame"> + {@code android:isGame}</a> attribute to <code>"true"</code> in your app manifest's + <a href="{@docRoot}guide/topics/manifest/application-element.html"><code><application></code> + </a> tag. For example: </p> <pre class="fragment"> -<application> - ... - <meta-data android:name="isGame" android:value="true" > - ... -</application> +<application + ... + android:isGame="true" + ... +> </pre> diff --git a/docs/html/training/tv/start/start.jd b/docs/html/training/tv/start/start.jd index bebeedd..3b26abf 100644 --- a/docs/html/training/tv/start/start.jd +++ b/docs/html/training/tv/start/start.jd @@ -100,7 +100,8 @@ startpage=true <p>The following code snippet shows how to include this intent filter in your manifest:</p> <pre> -<application> +<application + android:banner="@drawable/banner" > ... <activity android:name="com.example.android.MainActivity" @@ -141,6 +142,34 @@ startpage=true "{@docRoot}training/tv/start/layouts.html">Building TV Layouts</a>. </p> +<h3 id="banner">Provide a home screen banner</h3> + +<p> + An application must provide a home screen banner if it includes a Leanback launcher intent + filter. The banner is the app launch point that appears on the home screen in the apps and + games rows. Desribe the banner in the manifest as follows: +</p> + +<pre> +<application + . . . + android:banner="@drawable/banner" > + . . . +</application> +</pre> + +<p> + Use the <a href="{@docRoot}guide/topics/manifest/application-element.html#banner">{@code android:banner}</a> + attribute with the <a href="{@docRoot}guide/topics/manifest/application.html"><code><application></code></a> + tag to supply a default banner for all application activities, or with the + <a href="{@docRoot}guide/topics/manifest/activity-element.html"><code><activity></code></a> + tag to supply a banner for a specific activity. +</p> + +<p> + See <a href="{@docRoot}design/tv/patterns.html#banner">Banners</a> in the UI Patterns for TV + design guide. +</p> <h3 id="tv-libraries">Add TV support libraries</h3> |