TvView

public class TvView
extends ViewGroup

java.lang.Object
   ↳ 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(String, Uri) 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

interface TvView.OnUnhandledInputEventListener

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

class TvView.TimeShiftPositionCallback

Callback used to receive time shift position changes. 

class TvView.TvInputCallback

Callback used to receive various status updates on the TvView

Inherited XML attributes

Inherited constants

Inherited fields

Public constructors

TvView(Context context)
TvView(Context context, AttributeSet attrs)
TvView(Context context, AttributeSet attrs, int defStyleAttr)

Public methods

boolean dispatchGenericMotionEvent(MotionEvent event)

Dispatch a generic motion event.

boolean dispatchKeyEvent(KeyEvent event)

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

boolean dispatchTouchEvent(MotionEvent event)

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

boolean dispatchTrackballEvent(MotionEvent event)

Pass a trackball motion event down to the focused view.

boolean dispatchUnhandledInputEvent(InputEvent event)

Dispatches an unhandled input event to the next receiver.

void dispatchWindowFocusChanged(boolean hasFocus)

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

void draw(Canvas canvas)

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

boolean gatherTransparentRegion(Region region)

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

List<AudioPresentation> getAudioPresentations()

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

String getSelectedTrack(int type)

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

List<TvTrackInfo> getTracks(int type)

Returns the list of tracks.

boolean onUnhandledInputEvent(InputEvent event)

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

void overrideTvAppAttributionSource(AttributionSource tvAppAttributionSource)

Override default attribution source of TV App.

void reset()

Resets this TvView.

void selectAudioPresentation(int presentationId, int programId)

Selects an audio presentation.

void selectTrack(int type, String trackId)

Selects a track.

void sendAppPrivateCommand(String action, Bundle data)

Sends a private command to the underlying TV input.

void setCallback(TvView.TvInputCallback callback)

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

void setCaptionEnabled(boolean enabled)

Enables or disables the caption in this TvView.

void setInteractiveAppNotificationEnabled(boolean enabled)

Enables or disables interactive app notification.

void setOnUnhandledInputEventListener(TvView.OnUnhandledInputEventListener listener)

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

void setStreamVolume(float volume)

Sets the relative stream volume of this TvView.

void setTimeShiftPositionCallback(TvView.TimeShiftPositionCallback callback)

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

void setTvMessageEnabled(int type, boolean enabled)

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

void setZOrderMediaOverlay(boolean isMediaOverlay)

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

void setZOrderOnTop(boolean onTop)

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

void timeShiftPause()

Pauses playback.

void timeShiftPlay(String inputId, Uri recordedProgramUri)

Plays a given recorded TV program.

void timeShiftResume()

Resumes playback.

void timeShiftSeekTo(long timeMs)

Seeks to a specified time position.

void timeShiftSetMode(int mode)

Sets time shift mode.

void timeShiftSetPlaybackParams(PlaybackParams params)

Sets playback rate using PlaybackParams.

void tune(String inputId, Uri channelUri, Bundle params)

Tunes to a given channel.

void tune(String inputId, Uri channelUri)

Tunes to a given channel.

Protected methods

void dispatchDraw(Canvas canvas)

Called by draw to draw the child views.

void onAttachedToWindow()

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

void onDetachedFromWindow()

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

void onLayout(boolean changed, int left, int top, int right, int bottom)

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

void onMeasure(int widthMeasureSpec, int heightMeasureSpec)

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

void onVisibilityChanged(View changedView, int visibility)

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

Inherited methods

Public constructors

TvView

Added in API level 21
public TvView (Context context)

Parameters
context Context

TvView

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

Parameters
context Context

attrs AttributeSet

TvView

Added in API level 21
public TvView (Context context, 
                AttributeSet attrs, 
                int defStyleAttr)

Parameters
context Context

attrs AttributeSet

defStyleAttr int

Public methods

dispatchGenericMotionEvent

Added in API level 21
public boolean dispatchGenericMotionEvent (MotionEvent event)

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.

Returns
boolean True if the event was handled by the view, false otherwise.

dispatchKeyEvent

Added in API level 21
public boolean dispatchKeyEvent (KeyEvent event)

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.

Returns
boolean True if the event was handled, false otherwise.

dispatchTouchEvent

Added in API level 21
public boolean dispatchTouchEvent (MotionEvent event)

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.

Returns
boolean True if the event was handled by the view, false otherwise.

dispatchTrackballEvent

Added in API level 21
public boolean dispatchTrackballEvent (MotionEvent event)

Pass a trackball motion event down to the focused view.

Parameters
event MotionEvent: The motion event to be dispatched.

Returns
boolean True if the event was handled by the view, false otherwise.

dispatchUnhandledInputEvent

Added in API level 21
public boolean dispatchUnhandledInputEvent (InputEvent event)

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.

Returns
boolean true if the event was handled by the view, false otherwise.

dispatchWindowFocusChanged

Added in API level 21
public void dispatchWindowFocusChanged (boolean hasFocus)

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
public void draw (Canvas canvas)

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
public boolean gatherTransparentRegion (Region region)

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.

Returns
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
public List<AudioPresentation> getAudioPresentations ()

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

Returns
List<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
public String getSelectedTrack (int type)

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.

Returns
String

getTracks

Added in API level 21
public List<TvTrackInfo> getTracks (int type)

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.

Returns
List<TvTrackInfo>

onUnhandledInputEvent

Added in API level 21
public boolean onUnhandledInputEvent (InputEvent event)

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.

Returns
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
public void overrideTvAppAttributionSource (AttributionSource tvAppAttributionSource)

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
public void reset ()

Resets this TvView.

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

selectAudioPresentation

Added in API level 34
public void selectAudioPresentation (int presentationId, 
                int programId)

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
public void selectTrack (int type, 
                String trackId)

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
public void sendAppPrivateCommand (String action, 
                Bundle data)

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
public void setCallback (TvView.TvInputCallback callback)

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
public void setCaptionEnabled (boolean enabled)

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
public void setInteractiveAppNotificationEnabled (boolean enabled)

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
public void setOnUnhandledInputEventListener (TvView.OnUnhandledInputEventListener listener)

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
public void setStreamVolume (float volume)

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
public void setTimeShiftPositionCallback (TvView.TimeShiftPositionCallback callback)

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
public void setTvMessageEnabled (int type, 
                boolean enabled)

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 TvInputManager.TV_MESSAGE_TYPE_WATERMARK, TvInputManager.TV_MESSAGE_TYPE_CLOSED_CAPTION, or TvInputManager.TV_MESSAGE_TYPE_OTHER

enabled boolean: true if you want to enable TV message detection false otherwise.

setZOrderMediaOverlay

Added in API level 24
public void setZOrderMediaOverlay (boolean isMediaOverlay)

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(boolean).

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

setZOrderOnTop

Added in API level 24
public void setZOrderOnTop (boolean onTop)

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(boolean).

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

timeShiftPause

Added in API level 23
public void timeShiftPause ()

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

timeShiftPlay

Added in API level 24
public void timeShiftPlay (String inputId, 
                Uri recordedProgramUri)

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
public void timeShiftResume ()

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

timeShiftSeekTo

Added in API level 23
public void timeShiftSeekTo (long timeMs)

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
public void timeShiftSetPlaybackParams (PlaybackParams params)

Sets playback rate using PlaybackParams.

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

tune

Added in API level 24
public void tune (String inputId, 
                Uri channelUri, 
                Bundle params)

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.

tune

Added in API level 21
public void tune (String inputId, 
                Uri channelUri)

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.

Protected methods

dispatchDraw

Added in API level 21
protected void dispatchDraw (Canvas canvas)

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 void onAttachedToWindow ()

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 void onDetachedFromWindow ()

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 void onLayout (boolean changed, 
                int left, 
                int top, 
                int right, 
                int bottom)

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 void onMeasure (int widthMeasureSpec, 
                int heightMeasureSpec)

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 View.MeasureSpec.

heightMeasureSpec int: vertical space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.

onVisibilityChanged

Added in API level 21
protected void onVisibilityChanged (View changedView, 
                int visibility)

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 View.VISIBLE, View.INVISIBLE or View.GONE. Value is View.VISIBLE, View.INVISIBLE, or View.GONE