public class

SurfaceView

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

Class Overview

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.

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 in to the screen. If you are going to use it this way, you need to be aware of some threading semantics:

Summary

[Expand]
Inherited XML Attributes
From class android.view.View
[Expand]
Inherited Constants
From class android.view.View
Public Constructors
SurfaceView(Context context)
SurfaceView(Context context, AttributeSet attrs)
SurfaceView(Context context, AttributeSet attrs, int defStyle)
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.
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 onScrollChanged(int l, int t, int oldl, int oldt)
This is called in response to an internal scroll in this view (i.e., the view scrolled its own contents).
void onSizeChanged(int w, int h, int oldw, int oldh)
This is called during layout when the size of this view has changed.
void onWindowVisibilityChanged(int visibility)
Called when the window containing has change its visibility (between GONE, INVISIBLE, and VISIBLE).
[Expand]
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

public SurfaceView (Context context)

Since: API Level 1

public SurfaceView (Context context, AttributeSet attrs)

Since: API Level 1

public SurfaceView (Context context, AttributeSet attrs, int defStyle)

Since: API Level 1

Public Methods

public void draw (Canvas canvas)

Since: API Level 1

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, do not override this method; instead, you should implement onDraw(Canvas).

Parameters
canvas The Canvas to which the View is rendered.

public boolean gatherTransparentRegion (Region region)

Since: API Level 1

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 ViewRoot (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 SurfaceHolder getHolder ()

Since: API Level 1

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

Returns
  • SurfaceHolder The holder of the surface.

Protected Methods

protected void dispatchDraw (Canvas canvas)

Since: API Level 1

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

Since: API Level 1

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(Canvas), however it may be called any time before the first onDraw -- including before or after onMeasure(int, int).

protected void onDetachedFromWindow ()

Since: API Level 1

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

protected void onMeasure (int widthMeasureSpec, int heightMeasureSpec)

Since: API Level 1

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 overriden 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 onScrollChanged (int l, int t, int oldl, int oldt)

Since: API Level 1

This is called in response to an internal scroll in this view (i.e., the view scrolled its own contents). This is typically as a result of scrollBy(int, int) or scrollTo(int, int) having been called.

Parameters
l Current horizontal scroll origin.
t Current vertical scroll origin.
oldl Previous horizontal scroll origin.
oldt Previous vertical scroll origin.

protected void onSizeChanged (int w, int h, int oldw, int oldh)

Since: API Level 1

This is called during layout when the size of this view has changed. If you were just added to the view hierarchy, you're called with the old values of 0.

Parameters
w Current width of this view.
h Current height of this view.
oldw Old width of this view.
oldh Old height of this view.

protected void onWindowVisibilityChanged (int visibility)

Since: API Level 1

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 The new visibility of the window.