Added in API level 21

TvView

open class TvView : ViewGroup
kotlin.Any
   ↳ android.view.View
   ↳ android.view.ViewGroup
   ↳ android.media.tv.TvView

Displays TV contents. The TvView class provides a high level interface for applications to show TV programs from various TV sources that implement TvInputService. (Note that the list of TV inputs available on the system can be obtained by calling TvInputManager.getTvInputList().)

Once the application supplies the URI for a specific TV channel to #tune method, it takes care of underlying service binding (and unbinding if the current TvView is already bound to a service) and automatically allocates/deallocates resources needed. In addition to a few essential methods to control how the contents are presented, it also provides a way to dispatch input events to the connected TvInputService in order to enable custom key actions for the TV input.

Summary

Nested classes
abstract

Interface definition for a callback to be invoked when the unhandled input event is received.

abstract

Callback used to receive time shift position changes.

abstract

Callback used to receive various status updates on the TvView.

Inherited XML attributes
Inherited constants
Public constructors
TvView(context: Context!)

TvView(context: Context!, attrs: AttributeSet!)

TvView(context: Context!, attrs: AttributeSet!, defStyleAttr: Int)

Public methods
open Boolean

open Boolean

open Boolean

open Boolean

open Boolean

Dispatches an unhandled input event to the next receiver.

open Unit

open Unit
draw(canvas: Canvas)

open Boolean

open MutableList<AudioPresentation!>

Returns the list of audio presentations from the selected track of type TvTrackInfo#TYPE_AUDIO.

open String!

Returns the ID of the selected track for a given type.

open MutableList<TvTrackInfo!>!
getTracks(type: Int)

Returns the list of tracks.

open Boolean

Called when an unhandled input event also has not been handled by the user provided callback.

open Unit

Override default attribution source of TV App.

open Unit

Resets this TvView.

open Unit
selectAudioPresentation(presentationId: Int, programId: Int)

Selects an audio presentation.

open Unit
selectTrack(type: Int, trackId: String!)

Selects a track.

open Unit

Sends a private command to the underlying TV input.

open Unit

Sets the callback to be invoked when an event is dispatched to this TvView.

open Unit

Enables or disables the caption in this TvView.

open Unit

Enables or disables interactive app notification.

open Unit

Registers a callback to be invoked when an input event is not handled by the bound TV input.

open Unit

Sets the relative stream volume of this TvView.

open Unit

Sets the callback to be invoked when the time shift position is changed.

open Unit
setTvMessageEnabled(type: Int, enabled: Boolean)

Enables or disables TV message detection in the stream of the bound TV input.

open Unit
setZOrderMediaOverlay(isMediaOverlay: Boolean)

Controls whether the TvView's surface is placed on top of another regular surface view in the window (but still behind the window itself).

open Unit

Controls whether the TvView's surface is placed on top of its window.

open Unit

Pauses playback.

open Unit
timeShiftPlay(inputId: String!, recordedProgramUri: Uri!)

Plays a given recorded TV program.

open Unit

Resumes playback.

open Unit

Seeks to a specified time position.

open Unit

Sets time shift mode.

open Unit

Sets playback rate using android.media.PlaybackParams.

open Unit
tune(inputId: String, channelUri: Uri!)

Tunes to a given channel.

open Unit
tune(inputId: String!, channelUri: Uri!, params: Bundle!)

Tunes to a given channel.

Protected methods
open Unit

open Unit

open Unit

open Unit
onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int)

open Unit
onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int)

open Unit
onVisibilityChanged(changedView: View, visibility: Int)

Inherited functions
Inherited properties

Public constructors

TvView

Added in API level 21
TvView(context: Context!)

TvView

Added in API level 21
TvView(
    context: Context!,
    attrs: AttributeSet!)

TvView

Added in API level 21
TvView(
    context: Context!,
    attrs: AttributeSet!,
    defStyleAttr: Int)

Public methods

dispatchGenericMotionEvent

Added in API level 21
open fun dispatchGenericMotionEvent(event: MotionEvent!): Boolean
Parameters
event MotionEvent!: The motion event to be dispatched.
Return
Boolean True if the event was handled by the view, false otherwise.

dispatchKeyEvent

Added in API level 21
open fun dispatchKeyEvent(event: KeyEvent!): Boolean
Parameters
event KeyEvent!: The key event to be dispatched.
Return
Boolean True if the event was handled, false otherwise.

dispatchTouchEvent

Added in API level 21
open fun dispatchTouchEvent(event: MotionEvent!): Boolean
Parameters
event MotionEvent!: The motion event to be dispatched.
Return
Boolean True if the event was handled by the view, false otherwise.

dispatchTrackballEvent

Added in API level 21
open fun dispatchTrackballEvent(event: MotionEvent!): Boolean
Parameters
event MotionEvent!: The motion event to be dispatched.
Return
Boolean True if the event was handled by the view, false otherwise.

dispatchUnhandledInputEvent

Added in API level 21
open fun dispatchUnhandledInputEvent(event: InputEvent!): Boolean

Dispatches an unhandled input event to the next receiver.

Except system keys, TvView always consumes input events in the normal flow. This is called asynchronously from where the event is dispatched. It gives the host application a chance to dispatch the unhandled input events.

Parameters
event InputEvent!: The input event.
Return
Boolean true if the event was handled by the view, false otherwise.

dispatchWindowFocusChanged

Added in API level 21
open fun dispatchWindowFocusChanged(hasFocus: Boolean): Unit
Parameters
hasFocus Boolean: True if the window containing this view now has focus, false otherwise.

draw

Added in API level 21
open fun draw(canvas: Canvas): Unit
Parameters
canvas Canvas: The Canvas to which the View is rendered. This value cannot be null.

gatherTransparentRegion

Added in API level 21
open fun gatherTransparentRegion(region: Region?): Boolean
Parameters
region Region?: The transparent region for this ViewAncestor (window). This value may be null.
Return
Boolean Returns true if the effective visibility of the view at this point is opaque, regardless of the transparent region; returns false if it is possible for underlying windows to be seen behind the view.

getAudioPresentations

Added in API level 34
open fun getAudioPresentations(): MutableList<AudioPresentation!>

Returns the list of audio presentations from the selected track of type TvTrackInfo#TYPE_AUDIO.

Return
MutableList<AudioPresentation!> the list of audio presentations from the selected audio track, or an empty list if no audio presentations are available. This value cannot be null.

getSelectedTrack

Added in API level 21
open fun getSelectedTrack(type: Int): String!

Returns the ID of the selected track for a given type. Returns null if the information is not available or the track is not selected.

Parameters
type Int: The type of the selected tracks. The type can be TvTrackInfo#TYPE_AUDIO, TvTrackInfo#TYPE_VIDEO or TvTrackInfo#TYPE_SUBTITLE.

getTracks

Added in API level 21
open fun getTracks(type: Int): MutableList<TvTrackInfo!>!

Returns the list of tracks. Returns null if the information is not available.

Parameters
type Int: The type of the tracks. The type can be TvTrackInfo#TYPE_AUDIO, TvTrackInfo#TYPE_VIDEO or TvTrackInfo#TYPE_SUBTITLE.

onUnhandledInputEvent

Added in API level 21
open fun onUnhandledInputEvent(event: InputEvent!): Boolean

Called when an unhandled input event also has not been handled by the user provided callback. This is the last chance to handle the unhandled input event in the TvView.

Parameters
event InputEvent!: The input event.
Return
Boolean If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

overrideTvAppAttributionSource

Added in API level 34
open fun overrideTvAppAttributionSource(tvAppAttributionSource: AttributionSource): Unit

Override default attribution source of TV App.

An attribution source of TV App is used to attribute work to TV Input Service. The default attribution source is created by Context#getAttributionSource(). Call this method before calling tune(java.lang.String,android.net.Uri,android.os.Bundle) or timeShiftPlay(java.lang.String,android.net.Uri) to override the default attribution source.

Parameters
tvAppAttributionSource AttributionSource: The attribution source of the TV App. This value cannot be null.

reset

Added in API level 21
open fun reset(): Unit

Resets this TvView.

This method is primarily used to un-tune the current TvView.

selectAudioPresentation

Added in API level 34
open fun selectAudioPresentation(
    presentationId: Int,
    programId: Int
): Unit

Selects an audio presentation.

Parameters
presentationId Int: The ID of the audio presentation to select.
programId Int: The ID of the program providing the selected audio presentation.

selectTrack

Added in API level 21
open fun selectTrack(
    type: Int,
    trackId: String!
): Unit

Selects a track.

Parameters
type Int: The type of the track to select. The type can be TvTrackInfo#TYPE_AUDIO, TvTrackInfo#TYPE_VIDEO or TvTrackInfo#TYPE_SUBTITLE.
trackId String!: The ID of the track to select. null means to unselect the current track for a given type.

sendAppPrivateCommand

Added in API level 24
open fun sendAppPrivateCommand(
    action: String,
    data: Bundle!
): Unit

Sends a private command to the underlying TV input. This can be used to provide domain-specific features that are only known between certain clients and their TV inputs.

Parameters
action String: The name of the private command to send. This must be a scoped name, i.e. prefixed with a package name you own, so that different developers will not create conflicting commands. This value cannot be null.
data Bundle!: An optional bundle to send with the command.

setCallback

Added in API level 21
open fun setCallback(callback: TvView.TvInputCallback?): Unit

Sets the callback to be invoked when an event is dispatched to this TvView.

Parameters
callback TvView.TvInputCallback?: The callback to receive events. A value of null removes the existing callback.

setCaptionEnabled

Added in API level 21
open fun setCaptionEnabled(enabled: Boolean): Unit

Enables or disables the caption in this TvView.

Note that this method does not take any effect unless the current TvView is tuned.

Parameters
enabled Boolean: true to enable, false to disable.

setInteractiveAppNotificationEnabled

Added in API level 33
open fun setInteractiveAppNotificationEnabled(enabled: Boolean): Unit

Enables or disables interactive app notification.

This method enables or disables the event detection from the corresponding TV input. When it's enabled, the TV input service detects events related to interactive app, such as AIT (Application Information Table) and sends to TvView or the linked TV interactive app service.

Parameters
enabled Boolean: true if you want to enable interactive app notifications. false otherwise.

setOnUnhandledInputEventListener

Added in API level 21
open fun setOnUnhandledInputEventListener(listener: TvView.OnUnhandledInputEventListener!): Unit

Registers a callback to be invoked when an input event is not handled by the bound TV input.

Parameters
listener TvView.OnUnhandledInputEventListener!: The callback to be invoked when the unhandled input event is received.

setStreamVolume

Added in API level 21
open fun setStreamVolume(volume: Float): Unit

Sets the relative stream volume of this TvView.

This method is primarily used to handle audio focus changes or mute a specific TvView when multiple views are displayed. If the method has not yet been called, the TvView assumes the default value of 1.0f.

Parameters
volume Float: A volume value between 0.0f to 1.0f. Value is between 0.0 and 1.0 inclusive

setTimeShiftPositionCallback

Added in API level 23
open fun setTimeShiftPositionCallback(callback: TvView.TimeShiftPositionCallback?): Unit

Sets the callback to be invoked when the time shift position is changed.

Parameters
callback TvView.TimeShiftPositionCallback?: The callback to receive time shift position changes. A value of null removes the existing callback.

setTvMessageEnabled

Added in API level 34
open fun setTvMessageEnabled(
    type: Int,
    enabled: Boolean
): Unit

Enables or disables TV message detection in the stream of the bound TV input.

Parameters
type Int: The type of message received, such as TvInputManager#TV_MESSAGE_TYPE_WATERMARK Value is android.media.tv.TvInputManager#TV_MESSAGE_TYPE_WATERMARK, android.media.tv.TvInputManager#TV_MESSAGE_TYPE_CLOSED_CAPTION, or android.media.tv.TvInputManager#TV_MESSAGE_TYPE_OTHER
enabled Boolean: true if you want to enable TV message detection false otherwise.

setZOrderMediaOverlay

Added in API level 24
open fun setZOrderMediaOverlay(isMediaOverlay: Boolean): Unit

Controls whether the TvView's surface is placed on top of another regular surface view in the window (but still behind the window itself). This is typically used to place overlays on top of an underlying TvView.

Note that this must be set before the TvView's containing window is attached to the window manager.

Calling this overrides any previous call to setZOrderOnTop.

Parameters
isMediaOverlay Boolean: true to be on top of another regular surface, false otherwise.

setZOrderOnTop

Added in API level 24
open fun setZOrderOnTop(onTop: Boolean): Unit

Controls whether the TvView's surface is placed on top of its window. Normally it is placed behind the window, to allow it to (for the most part) appear to composite with the views in the hierarchy. By setting this, you cause it to be placed above the window. This means that none of the contents of the window this TvView is in will be visible on top of its surface.

Note that this must be set before the TvView's containing window is attached to the window manager.

Calling this overrides any previous call to setZOrderMediaOverlay.

Parameters
onTop Boolean: true to be on top of its window, false otherwise.

timeShiftPause

Added in API level 23
open fun timeShiftPause(): Unit

Pauses playback. No-op if it is already paused. Call timeShiftResume to resume.

timeShiftPlay

Added in API level 24
open fun timeShiftPlay(
    inputId: String!,
    recordedProgramUri: Uri!
): Unit

Plays a given recorded TV program.

Parameters
inputId String!: The ID of the TV input that created the given recorded program.
recordedProgramUri Uri!: The URI of a recorded program.

timeShiftResume

Added in API level 23
open fun timeShiftResume(): Unit

Resumes playback. No-op if it is already resumed. Call timeShiftPause to pause.

timeShiftSeekTo

Added in API level 23
open fun timeShiftSeekTo(timeMs: Long): Unit

Seeks to a specified time position. timeMs must be equal to or greater than the start position returned by TimeShiftPositionCallback#onTimeShiftStartPositionChanged and equal to or less than the current time.

Parameters
timeMs Long: The time position to seek to, in milliseconds since the epoch.

timeShiftSetPlaybackParams

Added in API level 23
open fun timeShiftSetPlaybackParams(params: PlaybackParams): Unit

Sets playback rate using android.media.PlaybackParams.

Parameters
params PlaybackParams: The playback params. This value cannot be null.

tune

Added in API level 21
open fun tune(
    inputId: String,
    channelUri: Uri!
): Unit

Tunes to a given channel.

Parameters
inputId String: The ID of the TV input for the given channel. This value cannot be null.
channelUri Uri!: The URI of a channel.

tune

Added in API level 24
open fun tune(
    inputId: String!,
    channelUri: Uri!,
    params: Bundle!
): Unit

Tunes to a given channel. This can be used to provide domain-specific features that are only known between certain clients and their TV inputs.

Parameters
inputId String!: The ID of TV input for the given channel.
channelUri Uri!: The URI of a channel.
params Bundle!: Domain-specific data for this tune request. Keys must be a scoped name, i.e. prefixed with a package name you own, so that different developers will not create conflicting keys.

Protected methods

dispatchDraw

Added in API level 21
protected open fun dispatchDraw(canvas: Canvas): Unit
Parameters
canvas Canvas: This value cannot be null.

onAttachedToWindow

Added in API level 21
protected open fun onAttachedToWindow(): Unit

onDetachedFromWindow

Added in API level 21
protected open fun onDetachedFromWindow(): Unit

onLayout

Added in API level 21
protected open fun onLayout(
    changed: Boolean,
    left: Int,
    top: Int,
    right: Int,
    bottom: Int
): Unit
Parameters
changed Boolean: This is a new size or position for this view
left Int: Left position, relative to parent
top Int: Top position, relative to parent
right Int: Right position, relative to parent
bottom Int: Bottom position, relative to parent

onMeasure

Added in API level 21
protected open fun onMeasure(
    widthMeasureSpec: Int,
    heightMeasureSpec: Int
): Unit
Parameters
widthMeasureSpec Int: horizontal space requirements as imposed by the parent. The requirements are encoded with android.view.View.MeasureSpec.
heightMeasureSpec Int: vertical space requirements as imposed by the parent. The requirements are encoded with android.view.View.MeasureSpec.

onVisibilityChanged

Added in API level 21
protected open fun onVisibilityChanged(
    changedView: View,
    visibility: Int
): Unit
Parameters
changedView View: The view whose visibility changed. May be this or an ancestor view. This value cannot be null.
visibility Int: The new visibility, one of VISIBLE, INVISIBLE or GONE. Value is android.view.View#VISIBLE, android.view.View#INVISIBLE, or android.view.View#GONE