Android APIs
public class

TvView

extends ViewGroup
java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.media.tv.TvView

Class Overview

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
[Expand]
Inherited XML Attributes
From class android.view.ViewGroup
From class android.view.View
[Expand]
Inherited Constants
From class android.view.ViewGroup
From class android.view.View
[Expand]
Inherited Fields
From class android.view.View
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 RootView to perform an optimization when the view hierarchy contains one or several SurfaceView.
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 reset()
Resets this TvView.
void selectTrack(int type, String trackId)
Selects a track.
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 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 timeShiftPause()
Pauses playback.
void timeShiftResume()
Resumes playback.
void timeShiftSeekTo(long timeMs)
Seeks to a specified time position.
void timeShiftSetPlaybackParams(PlaybackParams params)
Sets playback rate using PlaybackParams.
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.
[Expand]
Inherited Methods
From class android.view.ViewGroup
From class android.view.View
From class java.lang.Object
From interface android.view.ViewParent
From interface android.view.ViewManager
From interface android.graphics.drawable.Drawable.Callback
From interface android.view.KeyEvent.Callback
From interface android.view.accessibility.AccessibilityEventSource

Public Constructors

public TvView (Context context)

Added in API level 21

public TvView (Context context, AttributeSet attrs)

Added in API level 21

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

Added in API level 21

Public Methods

public boolean dispatchGenericMotionEvent (MotionEvent event)

Added in API level 21

Dispatch a generic motion event.

Generic motion events with source class 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(MotionEvent).

Parameters
event The motion event to be dispatched.
Returns
  • True if the event was handled by the view, false otherwise.

public boolean dispatchKeyEvent (KeyEvent event)

Added in API level 21

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 The key event to be dispatched.
Returns
  • True if the event was handled, false otherwise.

public boolean dispatchTouchEvent (MotionEvent event)

Added in API level 21

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

Parameters
event The motion event to be dispatched.
Returns
  • True if the event was handled by the view, false otherwise.

public boolean dispatchTrackballEvent (MotionEvent event)

Added in API level 21

Pass a trackball motion event down to the focused view.

Parameters
event The motion event to be dispatched.
Returns
  • True if the event was handled by the view, false otherwise.

public boolean dispatchUnhandledInputEvent (InputEvent event)

Added in API level 21

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 The input event.
Returns
  • true if the event was handled by the view, false otherwise.

public void dispatchWindowFocusChanged (boolean hasFocus)

Added in API level 21

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

Parameters
hasFocus True if the window containing this view now has focus, false otherwise.

public void draw (Canvas canvas)

Added in API level 21

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.

Parameters
canvas The Canvas to which the View is rendered.

public boolean gatherTransparentRegion (Region region)

Added in API level 21

This is used by the RootView 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 The transparent region for this ViewAncestor (window).
Returns
  • 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.

public String getSelectedTrack (int type)

Added in API level 21

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 The type of the selected tracks. The type can be TYPE_AUDIO, TYPE_VIDEO or TYPE_SUBTITLE.

public List<TvTrackInfo> getTracks (int type)

Added in API level 21

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

Parameters
type The type of the tracks. The type can be TYPE_AUDIO, TYPE_VIDEO or TYPE_SUBTITLE.

public boolean onUnhandledInputEvent (InputEvent event)

Added in API level 21

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 The input event.
Returns
  • If you handled the event, return true. If you want to allow the event to be handled by the next receiver, return false.

public void reset ()

Added in API level 21

Resets this TvView.

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

public void selectTrack (int type, String trackId)

Added in API level 21

Selects a track.

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

public void setCallback (TvView.TvInputCallback callback)

Added in API level 21

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

Parameters
callback The callback to receive events. A value of null removes the existing callback.

public void setCaptionEnabled (boolean enabled)

Added in API level 21

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 true to enable, false to disable.

public void setOnUnhandledInputEventListener (TvView.OnUnhandledInputEventListener listener)

Added in API level 21

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

Parameters
listener The callback to be invoked when the unhandled input event is received.

public void setStreamVolume (float volume)

Added in API level 21

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 A volume value between 0.0f to 1.0f.

public void setTimeShiftPositionCallback (TvView.TimeShiftPositionCallback callback)

Added in API level 23

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

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

public void timeShiftPause ()

Added in API level 23

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

public void timeShiftResume ()

Added in API level 23

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

public void timeShiftSeekTo (long timeMs)

Added in API level 23

Seeks to a specified time position. timeMs must be equal to or greater than the start position returned by onTimeShiftStartPositionChanged(String, long) and equal to or less than the current time.

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

public void timeShiftSetPlaybackParams (PlaybackParams params)

Added in API level 23

Sets playback rate using PlaybackParams.

Parameters
params The playback params.

public void tune (String inputId, Uri channelUri)

Added in API level 21

Tunes to a given channel.

Parameters
inputId The ID of the TV input for the given channel.
channelUri The URI of a channel.

Protected Methods

protected void dispatchDraw (Canvas canvas)

Added in API level 21

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 the canvas on which to draw the view

protected void onAttachedToWindow ()

Added in API level 21

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

protected void onDetachedFromWindow ()

Added in API level 21

This is called when the view is detached from a window. At this point it no longer has a surface for drawing.

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

Added in API level 21

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 This is a new size or position for this view
left Left position, relative to parent
top Top position, relative to parent
right Right position, relative to parent
bottom Bottom position, relative to parent

protected void onMeasure (int widthMeasureSpec, int heightMeasureSpec)

Added in API level 21

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 horizontal space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.
heightMeasureSpec vertical space requirements as imposed by the parent. The requirements are encoded with View.MeasureSpec.

protected void onVisibilityChanged (View changedView, int visibility)

Added in API level 21

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

Parameters
changedView The view whose visibility changed. May be this or an ancestor view.
visibility The new visibility, one of VISIBLE, INVISIBLE or GONE.