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

Dispatch a generic motion event.

open Boolean

Dispatch a key event to the next view on the focus path.

open Boolean

Pass the touch screen motion event down to the target view, or this view if it is the target.

open Boolean

Pass a trackball motion event down to the focused view.

open Boolean

Dispatches an unhandled input event to the next receiver.

open Unit

Called when the window containing this view gains or loses window focus.

open Unit
draw(canvas: Canvas)

Manually render this view (and all of its children) to the given Canvas.

open Boolean

This is used by the ViewRoot to perform an optimization when the view hierarchy contains one or several SurfaceView.

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

Resumes playback of the Audio, Video, and CC streams.

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

Sets whether or not the video is frozen.

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

Stops playback of the Audio, Video, and CC streams, but continue filtering the metadata.

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

Called by draw to draw the child views.

open Unit

This is called when the view is attached to a window.

open Unit

This is called when the view is detached from a window.

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

Called from layout when this view should assign a size and position to each of its children.

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

Measure the view and its content to determine the measured width and the measured height.

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

Called when the visibility of the view or an ancestor of the view has changed.

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

Dispatch a generic motion event.

Generic motion events with source class InputDevice.SOURCE_CLASS_POINTER are delivered to the view under the pointer. All other generic motion events are delivered to the focused view. Hover events are handled specially and are delivered to onHoverEvent(android.view.MotionEvent) first.

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

Dispatch a key event to the next view on the focus path. This path runs from the top of the view tree down to the currently focused view. If this view has focus, it will dispatch to itself. Otherwise it will dispatch the next node down the focus path. This method also fires any key listeners.

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

Pass the touch screen motion event down to the target view, or this view if it is the target.

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

Pass a trackball motion event down to the focused view.

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

Called when the window containing this view gains or loses window focus. ViewGroups should override to route to their children.

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

Manually render this view (and all of its children) to the given Canvas. The view must have already done a full layout before this function is called. When implementing a view, implement onDraw(android.graphics.Canvas) instead of overriding this method. If you do need to override this method, call the superclass version.
If you override this method you must call through to the superclass implementation.

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

This is used by the ViewRoot to perform an optimization when the view hierarchy contains one or several SurfaceView. SurfaceView is always considered transparent, but its children are not, therefore all View objects remove themselves from the global transparent region (passed as a parameter to this function).

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.

resumePlayback

Added in API level 36
open fun resumePlayback(): Unit

Resumes playback of the Audio, Video, and CC streams.

Note that this is different from timeShiftResume() as this is intended to be used after stopPlayback(int) has been called. This is used to resume playback from the current position in the live broadcast.

If this is the first time playback should begin, you will need to use tune(java.lang.String,android.net.Uri,android.os.Bundle) to begin playback.

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.0f and 1.0f 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 one of the following:
enabled Boolean: true if you want to enable TV message detection false otherwise.

setVideoFrozen

Added in API level 36
open fun setVideoFrozen(isFrozen: Boolean): Unit

Sets whether or not the video is frozen. While the video is frozen, audio playback will continue.

This should be invoked after a android.media.tv.interactive.TvInteractiveAppService.Session#requestCommand is received with the command to freeze the video.

This will freeze the video to the last frame when the state is set to true.

Parameters
isFrozen Boolean: whether or not the video is frozen.

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.

stopPlayback

Added in API level 36
open fun stopPlayback(mode: Int): Unit

Stops playback of the Audio, Video, and CC streams, but continue filtering the metadata.

The metadata that will continue to be filtered includes the PSI (Program specific information) and SI (Service Information), part of ISO/IEC 13818-1.

Note that this is different from timeShiftPause() as this completely drops the stream, making it impossible to resume from this position again.

Parameters
mode Int: Value is one of the following:

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

Called by draw to draw the child views. This may be overridden by derived classes to gain control just before its children are drawn (but after its own view has been drawn).

Parameters
canvas Canvas: This value cannot be null.

onAttachedToWindow

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

This is called when the view is attached to a window. At this point it has a Surface and will start drawing. Note that this function is guaranteed to be called before onDraw(android.graphics.Canvas), however it may be called any time before the first onDraw -- including before or after onMeasure(int,int).
If you override this method you must call through to the superclass implementation.

onDetachedFromWindow

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

This is called when the view is detached from a window. At this point it no longer has a surface for drawing.
If you override this method you must call through to the superclass implementation.

onLayout

Added in API level 21
protected open fun onLayout(
    changed: Boolean,
    left: Int,
    top: Int,
    right: Int,
    bottom: Int
): Unit

Called from layout when this view should assign a size and position to each of its children. Derived classes with children should override this method and call layout on each of their children.

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

Measure the view and its content to determine the measured width and the measured height. This method is invoked by measure(int,int) and should be overridden by subclasses to provide accurate and efficient measurement of their contents.

CONTRACT: When overriding this method, you must call setMeasuredDimension(int,int) to store the measured width and height of this view. Failure to do so will trigger an IllegalStateException, thrown by measure(int,int). Calling the superclass' onMeasure(int,int) is a valid use.

The base class implementation of measure defaults to the background size, unless a larger size is allowed by the MeasureSpec. Subclasses should override onMeasure(int,int) to provide better measurements of their content.

If this method is overridden, it is the subclass's responsibility to make sure the measured height and width are at least the view's minimum height and width (getSuggestedMinimumHeight() and getSuggestedMinimumWidth()).

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

Called when the visibility of the view or an ancestor of the view has changed.

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 one of the following: