Customizing the Reference TV App

本文转载自：https://source.android.google.cn/devices/tv/customize-tv-app

Live TV is a reference TV app designed for Android television devices. However,device manufacturers may want to add more product-specific functions, which arenot covered by the default implementation of Live TV, such as pictureadjustment, game mode, or 3D mode. To support these device-specific functions oroptions, Live TV supports these customizations:

• Enabling time-shifting mode, which allows users to pause, fast forward, and rewind. Configuring time-shifting mode to use external storage instead of internal storage.
• Adding options to the TV options row.
• Adding a custom row and adding options in it.

Note: LiveChannels is Google's implementation of Live TV that can be used as is ondevices with Google services. To customize Live Channels, replacecom.android.tv.* with com.google.android.tv.* in theseinstructions.

Customizing Live TV

To customize Live TV, the target Android TV device needs a customization packageinstalled, which must be a prebuilt system app with thecom.android.tv.permission.CUSTOMIZE_TV_APP permission.

Live TV searches for a system package with this permission, checks the resourcefiles, and detects the package's Activitiesmarked with specific categoriesto process customization.

Key point: Only one package can customize Live TV.

Configuring time-shifting mode

Time-shifting (trickplay) allows Android television devices to pause, rewind,and fast forward channel playback. In the Live TV implementation, time-shiftingcan be used via the Play controls UI. Time-shifting is enabled by default inLive TV, but can be disabled. Time-shifting can also be configured to useexternal storage only.

To configure time-shifting, add the string resource trickplay_modeand set its value to one of these options:

• enabled: Enable time-shifting. This is the default value when no options are given.
• disabled: Disable time-shifting.
• use_external_storage_only: Configure time-shifting to use external storage.

<string name="trickplay_mode">use_external_storage_only</string>

Figure 1. Play controls UI is activated after pressing theD-pad center button.

Customizing TV options

Device manufacturers can add custom options for Live TV settings to the existingTV options menu, such as adding a shortcut to the Sound Picture settings.

To indicate a custom option, declare an intent-filter that filters the categorycom.android.tv.category.OPTIONS_ROW in an activity. The custom featureis implemented by the device manufacturer in the activity. The activitylaunches if the option is clicked. The activity's title and icon are used forthe option. Customized TV options should match the existing UI to provide thebest user experience.

Note: An activity can only handle one optionbecause Live TV cannot differentiate intent-filters in an activity with the samecategory due to the Android limitation. See Handle multiple options in anactivity for a workaround.

Device manufacturers can also place a custom option before or after the existingoptions by defining android:priority in AndroidManifest.xml.An option with a defined priority value lower than 100 shows before the existingitems and a value higher than 100 shows after. Multiple custom options (eitherbefore or after existing options) are sorted by their priority in ascendingorder. If options have the same priority, order among them is undefined.

In this example, the option appears first in the TV options row, andPictureSettingsActivity launches if the option is clicked.

<activity android:name=".PictureSettingsActivity"
    android:label="@string/activity_label_picture_settings"
          android:theme="@style/Theme.Panel">
    <intent-filter
        android:icon="@drawable/ic_tvoptions_brightness"
        android:label="@string/option_label_brightness"
        android:priority="0">
        <action android:name="android.intent.action.MAIN" />
        <category android:name="com.android.tv.category.OPTIONS_ROW" />
    </intent-filter>
</activity>

Figure 2. Sample customized TV options row (Brightness andEnergy Saving).

Figure 3. Sample custom TV options.

Handling multiple options in an activity

An option maps to an activity's intent-filter and vice-versa. Because Androiddoesn't differentiate intent-filters with the same categories and actions, anactivity only handles one option, even if multiple intent-filters are declaredin it. To handle multiple options in an activity, use<activity-alias> in AndroidManifest.xml. In theactivity, use getIntent().getComponent() to identify the clicked option.

<activity-alias android:name=".AnyUniqueName"
    android:targetActivity=".PictureSettingsActivity">
    <intent-filter
        android:icon="@drawable/ic_tvoptions_energy_saving"
        android:label="@string/option_label_energy_saving"
        android:priority="1">
        <action android:name="android.intent.action.MAIN" />
        <category android:name="com.android.tv.category.OPTIONS_ROW" />
    </intent-filter>
</activity-alias>

Creating a custom row

Device manufacturers can add and customize a row above the TV options row.This custom row is optional.

Row Title

Define a partner_row_title string inres/values/strings.xml. The string's value is used for the customrow title.

<string name="partner_row_title">Partner Row</string>

Custom options

To add custom options to the custom row, follow the process for adding optionsto the TV options menu, but change the category name tocom.android.tv.category.PARTNER_ROW instead.

<activity android:name=".ThreeDimensionalSettingDialogActivity"
    android:label="@string/activity_label_3d"
    android:theme="@android:style/Theme.Material.Light.Dialog">
    <intent-filter
        android:icon="@drawable/ic_tvoptions_3d"
        android:priority="0">
        <action android:name="android.intent.action.MAIN" />
        <category android:name="com.android.tv.category.PARTNER_ROW" />
    </intent-filter>
</activity>

Figure 4. Sample optional custom row.

Figure 5. Sample custom option dialog.