From 4c3a07ba052126f71a7a5348170e6382606edcb1 Mon Sep 17 00:00:00 2001 From: Scott Rowe Date: Wed, 29 Oct 2014 13:32:30 -0700 Subject: [PATCH] docs: b/18119632 isGame, b/18119595 banner Change-Id: I171b4aff3359ec96b2ea1003870739ad586971c7 --- docs/html/design/tv/patterns.jd | 2 + .../guide/topics/manifest/activity-element.jd | 24 +++ .../topics/manifest/application-element.jd | 174 ++++++++++-------- docs/html/training/tv/games/index.jd | 24 +-- 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 768dcfcab703c..be7ae319ac91d 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. +

See Provide a home screen banner +in Get Started with TV Apps for more information.

Recommendation Icons

diff --git a/docs/html/guide/topics/manifest/activity-element.jd b/docs/html/guide/topics/manifest/activity-element.jd index ade05c98af5b5..7374a67e5e16c 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:allowTaskReparenting=["true" | "false"] android:alwaysRetainTaskState=["true" | "false"] android:autoRemoveFromRecents=["true" | "false"] + android:banner="drawable resource" android:clearTaskOnLaunch=["true" | "false"] android:configChanges=["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}". +
{@code android:banner}
+
A drawable resource +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 +<application> +tag to supply a banner for all application activities. + +

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.

+ +

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. +

+ +

+See +Banners in the UI Patterns for TV design guide, and +Provide a home screen banner in Get Started with TV Apps for more information. +

+ +
{@code android:clearTaskOnLaunch}
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 33f6bce368012..8a0e837629b89 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> 
<application android:allowTaskReparenting=["true" | "false"]
              android:allowBackup=["true" | "false"]
              android:backupAgent="string"
+             android:banner="drawable resource"
              android:debuggable=["true" | "false"]
              android:description="string resource"
              android:enabled=["true" | "false"]
              android:hasCode=["true" | "false"]
              android:hardwareAccelerated=["true" | "false"]
              android:icon="drawable resource"
+             android:isGame=["true" | "false"]
              android:killAfterRestore=["true" | "false"]
              android:largeHeap=["true" | "false"]
              android:label="string resource"
@@ -48,13 +50,13 @@ page.title=<application>
 
 
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.

 
 
@@ -65,18 +67,18 @@ cannot be overridden by the components.
{@code android:allowTaskReparenting}
-
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. +
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"}.

-The -<activity> -element has its own +The +<activity> +element has its own allowTaskReparenting -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.

@@ -92,46 +94,68 @@ The default value of this attribute is true.
{@code android:backupAgent}
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 -<manifest> +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 +<manifest> element.

There is no default. The name must be specified.

+
{@code android:banner}
+
A drawable resource +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 +<activity> +tag to supply a banner for a specific activity. + +

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.

+ +

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. +

+ +

+See +Banners in the UI Patterns for TV design guide, and +Provide a home screen banner in Get Started with TV Apps for more information. +

+
{@code android:debuggable}
-
Whether or not the application can be debugged, even when running +
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"}.
+if not. The default value is {@code "false"}.
{@code android:description}
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.
{@code android:enabled}
-
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 +
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.

The default value is {@code "true"}. -

+

{@code android:hasCode}
-
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. +
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"}.

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.

@@ -140,7 +164,7 @@ android.app.AliasActivity} class, a rare occurrence.

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 {@code minSdkVersion} -or {@code targetSdkVersion} to {@code "14"} or higher; otherwise, it's {@code "false"}. @@ -161,20 +185,26 @@ make use of the renderer without errors.

{@code android:icon}
-
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 -<activity>, +
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 +<activity>, <activity-alias>, -<service>, +<service>, <receiver>, and <provider> elements.

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.

+
{@code android:isGame}
+
Whether or not the application is a game. The system may group together applications classifed +as games or display them separately from other applications. + +

The default is {@code false}.

+
{@code android:killAfterRestore}
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.

{@code android:label}
-
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 -<activity>, +
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 +<activity>, <activity-alias>, -<service>, +<service>, <receiver>, and <provider> elements.

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.

{@code android:logo}
A logo for the application as whole, and the default logo for activities.

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.

+the image (for example {@code "@drawable/logo"}). There is no default logo.

{@code android:manageSpaceActivity}
-
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 +
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 <activity> element.
{@code android:name}
-
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. +
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.

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.

{@code android:permission}
-
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 +
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.

-For more information on permissions, see the -Permissions -section in the introduction and another document, +For more information on permissions, see the +Permissions +section in the introduction and another document, Security and Permissions.

{@code android:persistent}
-
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; +
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.
{@code android:process}
@@ -282,9 +312,9 @@ user ID and be signed with the same certificate.

-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.

@@ -307,7 +337,7 @@ incompatible. Use with caution! 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".

The default value is null and indicates that the application can work without any accounts. @@ -369,13 +399,13 @@ direction associated to the user's Locale choice (your layouts will always be le

{@code android:taskAffinity}
An affinity name that applies to all activities within the application, except for those that set a different affinity with their own -taskAffinity +taskAffinity attributes. See that attribute for more information.

-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 <manifest> element.

@@ -389,7 +419,7 @@ only through adb.
{@code android:theme}
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 theme +the default by setting their own theme attributes. For more information, see the Styles and Themes developer guide.
diff --git a/docs/html/training/tv/games/index.jd b/docs/html/training/tv/games/index.jd index 2f510a948cf6c..8a998e092841b 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

There are a some special things games should include in the Android manifest.

-

Show your game in the launcher

+

Show your game on the home screen

- 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 - <meta-data> tag in your app manifest with android:name - set to "isGame" and android:value - set to "true". 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 + + {@code android:isGame} attribute to "true" in your app manifest's + <application> + tag. For example: 

-<application>
-  ...
-  <meta-data android:name="isGame" android:value="true" >
-  ...
-</application>
+<application
+    ...
+    android:isGame="true"
+    ...
+>
diff --git a/docs/html/training/tv/start/start.jd b/docs/html/training/tv/start/start.jd index bebeeddb1098c..3b26abf1a4c31 100644 --- a/docs/html/training/tv/start/start.jd +++ b/docs/html/training/tv/start/start.jd @@ -100,7 +100,8 @@ startpage=true

The following code snippet shows how to include this intent filter in your manifest:

-<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.
 

 
+
+
+

+  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:
+

+
+
+<application
+    . . .
+    android:banner="@drawable/banner" >
+    . . .
+</application>
+

+
+

+  Use the {@code android:banner}
+  attribute with the <application>
+  tag to supply a default banner for all application activities, or with the
+  <activity>
+  tag to supply a banner for a specific activity.
+

+
+

+  See Banners in the UI Patterns for TV
+  design guide.
+

 
 
Add TV support libraries