PreviewChannelHelper
public
class
PreviewChannelHelper
extends Object
java.lang.Object | |
↳ | 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 | |
---|---|
PreviewChannelHelper(Context context)
|
|
PreviewChannelHelper(Context context, int urlConnectionTimeoutMillis, int urlReadTimeoutMillis)
|
Public methods | |
---|---|
void
|
deletePreviewChannel(long channelId)
Removes a preview channel from the system's content provider (aka TvProvider). |
void
|
deletePreviewProgram(long programId)
Removes programs from a preview channel. |
List<PreviewChannel>
|
getAllChannels()
The TvProvider does not allow select queries. |
PreviewChannel
|
getPreviewChannel(long channelId)
Retrieves a single preview channel from the TvProvider. |
PreviewProgram
|
getPreviewProgram(long programId)
Retrieves a single preview program from the system content provider (aka TvProvider). |
WatchNextProgram
|
getWatchNextProgram(long programId)
Retrieves a single WatchNext program from the system content provider (aka TvProvider). |
long
|
publishChannel(PreviewChannel channel)
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. |
long
|
publishDefaultChannel(PreviewChannel channel)
This is a convenience method that simply publishes your first channel for you. |
long
|
publishPreviewProgram(PreviewProgram program)
Adds programs to a preview channel. |
long
|
publishWatchNextProgram(WatchNextProgram program)
Adds a program to the Watch Next channel |
void
|
updatePreviewChannel(long channelId, PreviewChannel update)
To update a preview channel, you need to use the |
void
|
updatePreviewProgram(long programId, PreviewProgram update)
Updates programs in a preview channel. |
void
|
updateWatchNextProgram(WatchNextProgram upgrade, long programId)
Updates a WatchNext program. |
Protected methods | |
---|---|
Bitmap
|
downloadBitmap(Uri logoUri)
Downloads a Bitmap from a remote server. |
Inherited methods | |
---|---|
Public constructors
PreviewChannelHelper
public PreviewChannelHelper (Context context, int urlConnectionTimeoutMillis, int urlReadTimeoutMillis)
Parameters | |
---|---|
context |
Context |
urlConnectionTimeoutMillis |
int : see URLConnection.setConnectTimeout(int) |
urlReadTimeoutMillis |
int : see URLConnection.setReadTimeout(int)
|
Public methods
deletePreviewChannel
public void deletePreviewChannel (long channelId)
Removes a preview channel from the system's content provider (aka TvProvider).
Parameters | |
---|---|
channelId |
long |
deletePreviewProgram
public void deletePreviewProgram (long programId)
Removes programs from a preview channel.
Parameters | |
---|---|
programId |
long |
getAllChannels
public List<PreviewChannel> getAllChannels ()
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.
Returns | |
---|---|
List<PreviewChannel> |
getPreviewChannel
public PreviewChannel getPreviewChannel (long channelId)
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 |
Returns | |
---|---|
PreviewChannel |
PreviewChannel or null if not found |
getPreviewProgram
public PreviewProgram getPreviewProgram (long programId)
Retrieves a single preview program from the system content provider (aka TvProvider).
Parameters | |
---|---|
programId |
long |
Returns | |
---|---|
PreviewProgram |
getWatchNextProgram
public WatchNextProgram getWatchNextProgram (long programId)
Retrieves a single WatchNext program from the system content provider (aka TvProvider).
Parameters | |
---|---|
programId |
long |
Returns | |
---|---|
WatchNextProgram |
publishChannel
public long publishChannel (PreviewChannel channel)
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)
.
Parameters | |
---|---|
channel |
PreviewChannel |
Returns | |
---|---|
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. |
Throws | |
---|---|
IOException |
publishDefaultChannel
public long publishDefaultChannel (PreviewChannel channel)
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)
.
Parameters | |
---|---|
channel |
PreviewChannel |
Returns | |
---|---|
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. |
Throws | |
---|---|
IOException |
publishPreviewProgram
public long publishPreviewProgram (PreviewProgram program)
Adds programs to a preview channel.
Parameters | |
---|---|
program |
PreviewProgram |
Returns | |
---|---|
long |
publishWatchNextProgram
public long publishWatchNextProgram (WatchNextProgram program)
Adds a program to the Watch Next channel
Parameters | |
---|---|
program |
WatchNextProgram |
Returns | |
---|---|
long |
updatePreviewChannel
public void updatePreviewChannel (long channelId, PreviewChannel update)
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)
.
Parameters | |
---|---|
channelId |
long |
update |
PreviewChannel |
Throws | |
---|---|
IOException |
updatePreviewProgram
public void updatePreviewProgram (long programId, PreviewProgram update)
Updates programs in a preview channel.
Parameters | |
---|---|
programId |
long |
update |
PreviewProgram |
updateWatchNextProgram
public void updateWatchNextProgram (WatchNextProgram upgrade, long programId)
Updates a WatchNext program.
Parameters | |
---|---|
upgrade |
WatchNextProgram |
programId |
long |