Developer Console

Most visited

Recently visited

Results for

Added in API level 1
Summary: Inherited XML Attrs | Inherited Constants | Inherited Fields | Ctors | Methods | Protected Methods | Inherited Methods | [Expand All]

SurfaceView

public class SurfaceView
extends View

java.lang.Object
   ↳ android.view.View
     ↳ android.view.SurfaceView
Known Direct Subclasses

Provides a dedicated drawing surface embedded inside of a view hierarchy. You can control the format of this surface and, if you like, its size; the SurfaceView takes care of placing the surface at the correct location on the screen

The surface is Z ordered so that it is behind the window holding its SurfaceView; the SurfaceView punches a hole in its window to allow its surface to be displayed. The view hierarchy will take care of correctly compositing with the Surface any siblings of the SurfaceView that would normally appear on top of it. This can be used to place overlays such as buttons on top of the Surface, though note however that it can have an impact on performance since a full alpha-blended composite will be performed each time the Surface changes.

The transparent region that makes the surface visible is based on the layout positions in the view hierarchy. If the post-layout transform properties are used to draw a sibling view on top of the SurfaceView, the view may not be properly composited with the surface.

Access to the underlying surface is provided via the SurfaceHolder interface, which can be retrieved by calling getHolder().

The Surface will be created for you while the SurfaceView's window is visible; you should implement surfaceCreated(SurfaceHolder) and surfaceDestroyed(SurfaceHolder) to discover when the Surface is created and destroyed as the window is shown and hidden.

One of the purposes of this class is to provide a surface in which a secondary thread can render into the screen. If you are going to use it this way, you need to be aware of some threading semantics:

Note: Starting in platform version N, SurfaceView's window position is updated synchronously with other View rendering. This means that translating and scaling a SurfaceView on screen will not cause rendering artifacts. Such artifacts may occur on previous versions of the platform when its window is positioned asynchronously.

Summary

Inherited XML attributes

From class android.view.View

Inherited constants

From class android.view.View

Inherited fields

From class android.view.View

Public constructors

SurfaceView(Context context)
SurfaceView(Context context, AttributeSet attrs)
SurfaceView(Context context, AttributeSet attrs, int defStyleAttr)
SurfaceView(Context context, AttributeSet attrs, int defStyleAttr, int defStyleRes)

Public methods

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.

SurfaceHolder getHolder()

Return the SurfaceHolder providing access and control over this SurfaceView's underlying surface.

void setSecure(boolean isSecure)

Control whether the surface view's content should be treated as secure, preventing it from appearing in screenshots or from being viewed on non-secure displays.

void setVisibility(int visibility)

Set the enabled state of this view.

void setZOrderMediaOverlay(boolean isMediaOverlay)

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

void setZOrderOnTop(boolean onTop)

Control whether the surface view's surface is placed on top of its window.

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

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

void onWindowVisibilityChanged(int visibility)

Called when the window containing has change its visibility (between GONE, INVISIBLE, and VISIBLE).

Inherited methods

From class android.view.View
From class java.lang.Object
From interface android.graphics.drawable.Drawable.Callback
From interface android.view.KeyEvent.Callback
From interface android.view.accessibility.AccessibilityEventSource

Public constructors

SurfaceView

Added in API level 1
SurfaceView (Context context)

Parameters
context Context

SurfaceView

Added in API level 1
SurfaceView (Context context, 
                AttributeSet attrs)

Parameters
context Context
attrs AttributeSet

SurfaceView

Added in API level 1
SurfaceView (Context context, 
                AttributeSet attrs, 
                int defStyleAttr)

Parameters
context Context
attrs AttributeSet
defStyleAttr int

SurfaceView

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

Parameters
context Context
attrs AttributeSet
defStyleAttr int
defStyleRes int

Public methods

draw

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

getHolder

Added in API level 1
SurfaceHolder getHolder ()

Return the SurfaceHolder providing access and control over this SurfaceView's underlying surface.

Returns
SurfaceHolder SurfaceHolder The holder of the surface.

setSecure

Added in API level 17
void setSecure (boolean isSecure)

Control whether the surface view's content should be treated as secure, preventing it from appearing in screenshots or from being viewed on non-secure displays.

Note that this must be set before the surface view's containing window is attached to the window manager.

See FLAG_SECURE for details.

Parameters
isSecure boolean: True if the surface view is secure.

setVisibility

Added in API level 1
void setVisibility (int visibility)

Set the enabled state of this view.

Parameters
visibility int: One of VISIBLE, INVISIBLE, or GONE.

setZOrderMediaOverlay

Added in API level 5
void setZOrderMediaOverlay (boolean isMediaOverlay)

Control whether the surface view'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 media surface view.

Note that this must be set before the surface view's containing window is attached to the window manager.

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

Parameters
isMediaOverlay boolean

setZOrderOnTop

Added in API level 5
void setZOrderOnTop (boolean onTop)

Control whether the surface view'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 SurfaceView is in will be visible on top of its surface.

Note that this must be set before the surface view's containing window is attached to the window manager.

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

Parameters
onTop boolean

Protected methods

dispatchDraw

Added in API level 1
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 1
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 1
void onDetachedFromWindow ()

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

onMeasure

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

onWindowVisibilityChanged

Added in API level 1
void onWindowVisibilityChanged (int visibility)

Called when the window containing has change its visibility (between GONE, INVISIBLE, and VISIBLE). Note that this tells you whether or not your window is being made visible to the window manager; this does not tell you whether or not your window is obscured by other windows on the screen, even if it is itself visible.

Parameters
visibility int: The new visibility of the window.
Get news & tips
Blog Support

Except as noted, this content is licensed under Apache 2.0. For details and restrictions, see the Content License.

Android 6.0 r1 —

About Android Auto TV Wear Legal

Hooray!