Android
android.view
public class

android.view.SurfaceView

java.lang.Object
android.view.View Drawable.Callback KeyEvent.Callback
android.view.SurfaceView

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:

Known Direct Subclasses

Summary

XML Attributes inherited from class android.view.View
Constants inherited from class android.view.View
Fields inherited 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).
Methods inherited from class android.view.View
Methods inherited from class java.lang.Object
Methods inherited from interface android.graphics.drawable.Drawable.Callback
Methods inherited from interface android.view.KeyEvent.Callback

Details

Public Constructors

public SurfaceView(Context context)

public SurfaceView(Context context, AttributeSet attrs)

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

Public Methods

public 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, 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)

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

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)

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

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

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)

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)

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)

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)

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.
Copyright 2007 Google Inc. Build 0.9_r1-98467 - 14 Aug 2008 18:56