PreviewChannelHelper

Kotlin |Java

@WorkerThread open class PreviewChannelHelper

kotlin.Any
↳	androidx.tvprovider.media.tv.PreviewChannelHelper

From a user's perspective, the TV home screen has two types of channels: the single Live Channels row versus the App preview Channels. This class is concerned with App Channels; or more precisely: your app's preview Channels. In API 26+, all TV apps are allowed to create multiple channels and publish those Channels to the home screen.

This class provides convenience methods to help you publish, update and delete channels; add, update or remove programs in a channel. You do not need to know anything about Content Providers, Content Resolvers, Cursors or such to publish your channels. This class abstracts away all database interactions for you.

To make it easy for you to distinguish classes that help you build App Channels, the support library uses the prefix Preview- to denote the classes that pertain to app Channels. Hence, the classes PreviewChannel and PreviewProgram help your app add channels to the TV home page. All calls to methods in the class should be made on worker threads.

Summary

Public constructors
<init>(context: Context!)
<init>(context: Context!, urlConnectionTimeoutMillis: Int, urlReadTimeoutMillis: Int)

Public methods
open Unit	deletePreviewChannel(channelId: Long) Removes a preview channel from the system's content provider (aka TvProvider).
open Unit	deletePreviewProgram(programId: Long) Removes programs from a preview channel.
open MutableList<PreviewChannel!>!	getAllChannels() The TvProvider does not allow select queries.
open PreviewChannel?	getPreviewChannel(channelId: Long) Retrieves a single preview channel from the TvProvider.
open PreviewProgram?	getPreviewProgram(programId: Long) Retrieves a single preview program from the system content provider (aka TvProvider).
open WatchNextProgram?	getWatchNextProgram(programId: Long) Retrieves a single WatchNext program from the system content provider (aka TvProvider).
open Long	publishChannel(@NonNull channel: PreviewChannel) Publishing a channel to the TV home screen is a two step process: first, you add the channel to the TV content provider; second, you make the channel browsable (i.e. visible).
open Long	publishDefaultChannel(@NonNull channel: PreviewChannel) This is a convenience method that simply publishes your first channel for you.
open Long	publishPreviewProgram(@NonNull program: PreviewProgram) Adds programs to a preview channel.
open Long	publishWatchNextProgram(@NonNull program: WatchNextProgram) Adds a program to the Watch Next channel
open Unit	updatePreviewChannel(channelId: Long, @NonNull update: PreviewChannel) To update a preview channel, you need to use the PreviewChannel.Builder to set the attributes you wish to change.
open Unit	updatePreviewProgram(programId: Long, @NonNull update: PreviewProgram) Updates programs in a preview channel.
open Unit	updateWatchNextProgram(@NonNull upgrade: WatchNextProgram, programId: Long) Updates a WatchNext program.

Protected methods
open Bitmap!	downloadBitmap(@NonNull logoUri: Uri) Downloads a Bitmap from a remote server.

Public constructors

<init>

PreviewChannelHelper(context: Context!)

<init>

PreviewChannelHelper(
    context: Context!, 
    urlConnectionTimeoutMillis: Int, 
    urlReadTimeoutMillis: Int)

Parameters
urlConnectionTimeoutMillis	Int: see URLConnection#setConnectTimeout(int)
urlReadTimeoutMillis	Int: see URLConnection#setReadTimeout(int)

Public methods

deletePreviewChannel

open fun deletePreviewChannel(channelId: Long): Unit

Removes a preview channel from the system's content provider (aka TvProvider).

deletePreviewProgram

open fun deletePreviewProgram(programId: Long): Unit

Removes programs from a preview channel.

getAllChannels

open fun getAllChannels(): MutableList<PreviewChannel!>!

The TvProvider does not allow select queries. Hence, unless you are querying for a single PreviewChannel by id, you must get all of your channels at once and then use the returned list as necessary.

getPreviewChannel

@Nullable open fun getPreviewChannel(channelId: Long): PreviewChannel?

Retrieves a single preview channel from the TvProvider. When you publish a preview channel, the TvProvider assigns an ID to it. That's the channelId to use here.

Parameters
channelId	Long: ID of preview channel in TvProvider

Return
PreviewChannel?	PreviewChannel or null if not found

getPreviewProgram

@Nullable open fun getPreviewProgram(programId: Long): PreviewProgram?

Retrieves a single preview program from the system content provider (aka TvProvider).

getWatchNextProgram

@Nullable open fun getWatchNextProgram(programId: Long): WatchNextProgram?

Retrieves a single WatchNext program from the system content provider (aka TvProvider).

publishChannel

open fun publishChannel(@NonNull channel: PreviewChannel): Long

Publishing a channel to the TV home screen is a two step process: first, you add the channel to the TV content provider; second, you make the channel browsable (i.e. visible). This method adds the channel to the TV content provider for you and returns a channelId. Next you must use the channelId to make the channel browsable.
There are two ways you can make a channel browsable:
a) For your first channel, simply ask the system to make the channel browsable: TvContractCompat.requestChannelBrowsable(context,channelId)
b) For any additional channel beyond the first channel, you must get permission from the user. So if this channel is not your first channel, you must request user permission through the following intent. So take the channelId returned by this method and do the following inside an Activity or Fragment:

intent = new Intent(TvContractCompat.ACTION_REQUEST_CHANNEL_BROWSABLE);
      intent.putExtra(TvContractCompat.EXTRA_CHANNEL_ID, channelId);
      startActivityForResult(intent, REQUEST_CHANNEL_BROWSABLE);
      

Creating a PreviewChannel, you may pass to the builder a url as your logo. In such case, updatePreviewChannel(long, PreviewChannel) will load the logo over the network. To use your own networking code, override downloadBitmap(Uri).

Return
Long	channelId or -1 if insertion fails. This is the id the system assigns to your published channel. You can use it later to get a reference to this published PreviewChannel.

publishDefaultChannel

open fun publishDefaultChannel(@NonNull channel: PreviewChannel): Long

This is a convenience method that simply publishes your first channel for you. After calling publishChannel(PreviewChannel) to add the channel to the TvProvider, it calls TvContractCompat#requestChannelBrowsable(Context, long) to make the channel visible.

Only use this method to publish your first channel as you do not need user permission to make your first channel browsable (i.e. visible on home screen). For additional channels, see the documentations for publishChannel(PreviewChannel).

Creating a PreviewChannel, you may pass to the builder a url as your logo. In such case, updatePreviewChannel(long, PreviewChannel) will load the logo over the network. To use your own networking code, override downloadBitmap(Uri).

Return
Long	channelId: This is the id the system assigns to your published channel. You can use it later to get a reference to this published PreviewChannel.

publishPreviewProgram

open fun publishPreviewProgram(@NonNull program: PreviewProgram): Long

Adds programs to a preview channel.

publishWatchNextProgram

open fun publishWatchNextProgram(@NonNull program: WatchNextProgram): Long

Adds a program to the Watch Next channel

updatePreviewChannel

open fun updatePreviewChannel(
    channelId: Long, 
    @NonNull update: PreviewChannel
): Unit

To update a preview channel, you need to use the PreviewChannel.Builder to set the attributes you wish to change. Then simply pass in the built channel and the channelId of the preview channel. (The channelId is the ID you received when you originally published the preview channel.)

Creating a PreviewChannel, you may pass to the builder a url as your logo. In such case, updatePreviewChannel(long, PreviewChannel) will load the logo over the network. To use your own networking code, override downloadBitmap(Uri).

updatePreviewProgram

open fun updatePreviewProgram(
    programId: Long, 
    @NonNull update: PreviewProgram
): Unit

Updates programs in a preview channel.

updateWatchNextProgram

open fun updateWatchNextProgram(
    @NonNull upgrade: WatchNextProgram, 
    programId: Long
): Unit

Updates a WatchNext program.

Protected methods

downloadBitmap

protected open fun downloadBitmap(@NonNull logoUri: Uri): Bitmap!

Downloads a Bitmap from a remote server. It is declared protected to allow you to override it to use your own networking implementation if you so wish.