TvAdView


public class TvAdView
extends ViewGroup

java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.media.tv.ad.TvAdView


Displays contents of TV advertisement services.

Summary

Nested classes

interface TvAdView.OnUnhandledInputEventListener

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

class TvAdView.TvAdCallback

Callback used to receive various status updates on the TvAdView

Inherited XML attributes

Constants

String ERROR_KEY_ERROR_CODE

The error code of an error.

String ERROR_KEY_METHOD_NAME

The name of the method where the error happened, if applicable.

Inherited constants

Inherited fields

Public constructors

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

Public methods

void clearCallback()

Clears the callback.

void clearOnUnhandledInputEventListener()

Clears the OnUnhandledInputEventListener.

boolean dispatchKeyEvent(KeyEvent event)

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

boolean dispatchUnhandledInputEvent(InputEvent event)

Dispatches an unhandled input event to the next receiver.

TvAdView.OnUnhandledInputEventListener getOnUnhandledInputEventListener()

Gets the OnUnhandledInputEventListener.

void notifyError(String errMsg, Bundle params)

Notifies the corresponding TvAdService when there is an error.

void notifyTvMessage(int type, Bundle data)

This is called to notify the corresponding TV AD service when a new TV message is received.

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.

boolean onUnhandledInputEvent(InputEvent event)

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

void onVisibilityChanged(View changedView, int visibility)

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

void prepareAdService(String serviceId, String type)

Prepares the AD service of corresponding TvAdService.

void reset()

Resets this TvAdView to release its resources.

void resetAdService()

Resets the AD service.

void sendCurrentChannelUri(Uri channelUri)

Sends current channel URI to related TV AD service.

void sendCurrentTvInputId(String inputId)

Sends current TV input ID to related TV AD service.

void sendCurrentVideoBounds(Rect bounds)

Sends current video bounds to related TV AD service.

void sendSigningResult(String signingId, byte[] result)

Sends signing result to related TV AD service.

void sendTrackInfoList(List<TvTrackInfo> tracks)

Sends track info list to related TV AD service.

void setCallback(Executor executor, TvAdView.TvAdCallback callback)

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

void setOnUnhandledInputEventListener(TvAdView.OnUnhandledInputEventListener listener)

Sets a listener to be invoked when an input event is not handled by the TV AD service.

boolean setTvView(TvView tvView)

Sets the TvAdView to receive events from TvInputService.

void setZOrderMediaOverlay(boolean isMediaOverlay)

Controls whether the TvAdView's surface is placed on top of other regular surface views in the window (but still behind the window itself).

void setZOrderOnTop(boolean onTop)

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

void startAdService()

Starts the AD service.

void stopAdService()

Stops the AD service.

Inherited methods

Constants

ERROR_KEY_ERROR_CODE

public static final String ERROR_KEY_ERROR_CODE

The error code of an error.

It can be TvAdManager.ERROR_WEAK_SIGNAL, TvAdManager.ERROR_RESOURCE_UNAVAILABLE, etc.

Constant Value: "error_code"

ERROR_KEY_METHOD_NAME

public static final String ERROR_KEY_METHOD_NAME

The name of the method where the error happened, if applicable. For example, if there is an error during signing, the request name is "onRequestSigning".

Constant Value: "method_name"

Public constructors

TvAdView

public TvAdView (Context context)

Parameters
context Context: This value cannot be null.

TvAdView

public TvAdView (Context context, 
                AttributeSet attrs)

Parameters
context Context: This value cannot be null.

attrs AttributeSet: This value may be null.

TvAdView

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

Parameters
context Context: This value cannot be null.

attrs AttributeSet: This value may be null.

defStyleAttr int

Public methods

clearCallback

public void clearCallback ()

Clears the callback.

clearOnUnhandledInputEventListener

public void clearOnUnhandledInputEventListener ()

Clears the OnUnhandledInputEventListener.

dispatchKeyEvent

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: This value may be null.

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

dispatchUnhandledInputEvent

public boolean dispatchUnhandledInputEvent (InputEvent event)

Dispatches an unhandled input event to the next receiver. It gives the host application a chance to dispatch the unhandled input events.

Parameters
event InputEvent: The input event. This value cannot be null.

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

getOnUnhandledInputEventListener

public TvAdView.OnUnhandledInputEventListener getOnUnhandledInputEventListener ()

Gets the OnUnhandledInputEventListener.

Returns null if the listener is not set or is cleared.

Returns
TvAdView.OnUnhandledInputEventListener

notifyError

public void notifyError (String errMsg, 
                Bundle params)

Notifies the corresponding TvAdService when there is an error.

Parameters
errMsg String: the message of the error. This value cannot be null.

params Bundle: additional parameters of the error. For example, the signingId of TvAdView.TvAdCallback.onRequestSigning(java.lang.String, java.lang.String, java.lang.String, java.lang.String, byte[]) can be included to identify the related signing request, and the method name "onRequestSigning" can also be added to the params. This value cannot be null.

notifyTvMessage

public void notifyTvMessage (int type, 
                Bundle data)

This is called to notify the corresponding TV AD service when a new TV message is received.

Parameters
type int: The type of message received, such as TvInputManager.TV_MESSAGE_TYPE_WATERMARK This value cannot be null. Value is TvInputManager.TV_MESSAGE_TYPE_WATERMARK, TvInputManager.TV_MESSAGE_TYPE_CLOSED_CAPTION, or TvInputManager.TV_MESSAGE_TYPE_OTHER

data Bundle: The raw data of the message. The bundle keys are: TvInputManager.TV_MESSAGE_KEY_STREAM_ID, TvInputManager.TV_MESSAGE_KEY_GROUP_ID, TvInputManager.TV_MESSAGE_KEY_SUBTYPE, TvInputManager.TV_MESSAGE_KEY_RAW_DATA. See TvInputManager.TV_MESSAGE_KEY_SUBTYPE for more information on how to parse this data. This value cannot be null.

onAttachedToWindow

public 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

public 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

public 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

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

onUnhandledInputEvent

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

Parameters
event InputEvent: The input event. This value cannot be null.

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.

onVisibilityChanged

public void onVisibilityChanged (View changedView, 
                int visibility)

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

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

prepareAdService

public void prepareAdService (String serviceId, 
                String type)

Prepares the AD service of corresponding TvAdService.

This should be called before calling startAdService(). Otherwise, startAdService() is a no-op.

Parameters
serviceId String: the AD service ID, which can be found in TvAdServiceInfo#getId(). This value cannot be null.

type String: This value cannot be null.

reset

public void reset ()

Resets this TvAdView to release its resources.

It can be reused by call prepareAdService(java.lang.String, java.lang.String).

resetAdService

public void resetAdService ()

Resets the AD service.

This releases the resources of the corresponding TvAdService.Session.

sendCurrentChannelUri

public void sendCurrentChannelUri (Uri channelUri)

Sends current channel URI to related TV AD service.

Parameters
channelUri Uri: The current channel URI; null if there is no currently tuned channel.

sendCurrentTvInputId

public void sendCurrentTvInputId (String inputId)

Sends current TV input ID to related TV AD service.

Parameters
inputId String: The current TV input ID whose channel is tuned. null if no channel is tuned.

See also:

sendCurrentVideoBounds

public void sendCurrentVideoBounds (Rect bounds)

Sends current video bounds to related TV AD service.

Parameters
bounds Rect: the rectangle area for rendering the current video. This value cannot be null.

sendSigningResult

public void sendSigningResult (String signingId, 
                byte[] result)

Sends signing result to related TV AD service.

This is used when the corresponding server of the ADs requires signing during handshaking, and the AD service doesn't have the built-in private key. The private key is provided by the content providers and pre-built in the related app, such as TV app.

Parameters
signingId String: the ID to identify the request. It's the same as the corresponding ID in TvAdService.Session.requestSigning(String, String, String, byte[]) This value cannot be null.

result byte: the signed result. This value cannot be null.

sendTrackInfoList

public void sendTrackInfoList (List<TvTrackInfo> tracks)

Sends track info list to related TV AD service.

Parameters
tracks List: This value may be null.

setCallback

public void setCallback (Executor executor, 
                TvAdView.TvAdCallback callback)

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

Parameters
executor Executor: This value cannot be null. Callback and listener events are dispatched through this Executor, providing an easy way to control which thread is used. To dispatch events through the main thread of your application, you can use Context.getMainExecutor(). Otherwise, provide an Executor that dispatches to an appropriate thread.

callback TvAdView.TvAdCallback: the callback to receive events. MUST NOT be null.

See also:

setOnUnhandledInputEventListener

public void setOnUnhandledInputEventListener (TvAdView.OnUnhandledInputEventListener listener)

Sets a listener to be invoked when an input event is not handled by the TV AD service.

Parameters
listener TvAdView.OnUnhandledInputEventListener: The callback to be invoked when the unhandled input event is received. This value cannot be null.

setTvView

public boolean setTvView (TvView tvView)

Sets the TvAdView to receive events from TvInputService. This method links the session of TvAdManager to TvInputManager session, so the TvAdService can get the TvInputService events.

Parameters
tvView TvView: the TvView to be linked to this TvAdView via linking of Sessions. null to unlink the TvView.

Returns
boolean true if it's linked successfully; false otherwise.

setZOrderMediaOverlay

public void setZOrderMediaOverlay (boolean isMediaOverlay)

Controls whether the TvAdView's surface is placed on top of other regular surface views in the window (but still behind the window itself).

Calling this overrides any previous call to setZOrderOnTop(boolean).

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

setZOrderOnTop

public void setZOrderOnTop (boolean onTop)

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

Calling this overrides any previous call to setZOrderMediaOverlay(boolean).

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

startAdService

public void startAdService ()

Starts the AD service.

This should be called after calling prepareAdService(java.lang.String, java.lang.String). Otherwise, it's a no-op.

stopAdService

public void stopAdService ()

Stops the AD service.

It's a no-op if the service is not started.