Most visited

Recently visited

Added in API level 21

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

From class android.view.ViewGroup
From class android.view.View

Inherited constants

From class android.view.ViewGroup
From class android.view.View

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

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

TvView

Added in API level 21
TvView (Context context)

Parameters
context Context

TvView

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

Parameters
context Context
attrs AttributeSet

TvView

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

Parameters
context Context
attrs AttributeSet
defStyleAttr int

Public methods

dispatchGenericMotionEvent

Added in API level 21
boolean dispatchGenericMotionEvent (MotionEvent event)

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

Parameters
canvas Canvas: The Canvas to which the View is rendered.

gatherTransparentRegion

Added in API level 21
boolean gatherTransparentRegion (Region region)

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 Region: The transparent region for this ViewAncestor (window).
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.

getSelectedTrack

Added in API level 21
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 TYPE_AUDIO, TYPE_VIDEO or TYPE_SUBTITLE.
Returns
String

See also:

getTracks

Added in API level 21
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 TYPE_AUDIO, TYPE_VIDEO or TYPE_SUBTITLE.
Returns
List<TvTrackInfo>

See also:

onUnhandledInputEvent

Added in API level 21
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.

reset

Added in API level 21
void reset ()

Resets this TvView.

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

selectTrack

Added in API level 21
void selectTrack (int type, 
                String trackId)

Selects a track.

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

See also:

sendAppPrivateCommand

Added in API level 24
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.
data Bundle: An optional bundle to send with the command.

setCallback

Added in API level 21
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
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.

setOnUnhandledInputEventListener

Added in API level 21
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
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.

setTimeShiftPositionCallback

Added in API level 23
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.

setZOrderMediaOverlay

Added in API level 24
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
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
void timeShiftPause ()

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

timeShiftPlay

Added in API level 24
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
void timeShiftResume ()

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

timeShiftSeekTo

Added in API level 23
void timeShiftSeekTo (long timeMs)

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 long: The time position to seek to, in milliseconds since the epoch.

timeShiftSetPlaybackParams

Added in API level 23
void timeShiftSetPlaybackParams (PlaybackParams params)

Sets playback rate using PlaybackParams.

Parameters
params PlaybackParams: The playback params.

tune

Added in API level 24
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
void tune (String inputId, 
                Uri channelUri)

Tunes to a given channel.

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

Protected methods

dispatchDraw

Added in API level 21
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: the canvas on which to draw the view

onAttachedToWindow

Added in API level 21
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).

onDetachedFromWindow

Added in API level 21
void onDetachedFromWindow ()

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

onLayout

Added in API level 21
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
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
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.
visibility int: The new visibility, one of VISIBLE, INVISIBLE or GONE.

Hooray!