android.view
Class SurfaceView

java.lang.Object
  android.view.View
      android.view.SurfaceView

All Implemented Interfaces:

Drawable.Callback, KeyEvent.Callback

Direct Known Subclasses:

VideoView

public class SurfaceView
extends View

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 SurfaceHolder.Callback.surfaceCreated(android.view.SurfaceHolder) and SurfaceHolder.Callback.surfaceDestroyed(android.view.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:

• All SurfaceView and SurfaceHolder.Callback methods will be called from the thread running the SurfaceView's window (typically the main thread of the application). They thus need to correctly synchronize with any state that is also touched by the drawing thread.
• You must ensure that the drawing thread only touches the underlying Surface while it is valid -- between SurfaceHolder.Callback.surfaceCreated() and SurfaceHolder.Callback.surfaceDestroyed().

Nested Class Summary

Nested classes/interfaces inherited from class android.view.View

View.AttachInfo, View.BaseSavedState, View.CheckForLongPress, View.MeasureSpec, View.OnClickListener, View.OnCreateContextMenuListener, View.OnFocusChangeListener, View.OnKeyListener, View.OnLongClickListener, View.OnTouchListener

Field Summary

(package private) static int	GET_NEW_SURFACE_MSG
(package private) static int	KEEP_SCREEN_ON_MSG
(package private) ArrayList<SurfaceHolder.Callback>	mCallbacks
(package private) Rect	mCoveredInsets
(package private) boolean	mDestroyReportNeeded
(package private) boolean	mDrawingStopped
(package private) int	mFormat
(package private) Handler	mHandler
(package private) boolean	mHaveFrame
(package private) int	mHeight
(package private) boolean	mIsCreating
(package private) long	mLastLockTime
(package private) WindowManager.LayoutParams	mLayout
(package private) int	mLeft
(package private) boolean	mNewSurfaceNeeded
(package private) int	mRequestedFormat
(package private) int	mRequestedHeight
(package private) int	mRequestedType
(package private) boolean	mRequestedVisible
(package private) int	mRequestedWidth
(package private) IWindowSession	mSession
(package private) Surface	mSurface
(package private) Rect	mSurfaceFrame
(package private) ReentrantLock	mSurfaceLock
(package private) int	mTop
(package private) int	mType
(package private) boolean	mVisible
(package private) int	mWidth
(package private) android.view.SurfaceView.MyWindow	mWindow
(package private) Rect	mWinFrame

Fields inherited from class android.view.View

ALPHA_SET, ANIMATION_STARTED, CLICKABLE, DISABLED, DRAW_MASK, DRAWABLE_STATE_DIRTY, DRAWING_CACHE_ENABLED, DRAWING_CACHE_QUALITY_AUTO, DRAWING_CACHE_QUALITY_HIGH, DRAWING_CACHE_QUALITY_LOW, DRAWING_CACHE_QUALITY_MASK, DRAWING_CACHE_VALID, DRAWN, DUPLICATE_PARENT_STATE, EMPTY_STATE_SET, ENABLED, ENABLED_FOCUSED_SELECTED_STATE_SET, ENABLED_FOCUSED_SELECTED_WINDOW_FOCUSED_STATE_SET, ENABLED_FOCUSED_STATE_SET, ENABLED_FOCUSED_WINDOW_FOCUSED_STATE_SET, ENABLED_MASK, ENABLED_SELECTED_STATE_SET, ENABLED_SELECTED_WINDOW_FOCUSED_STATE_SET, ENABLED_STATE_SET, ENABLED_WINDOW_FOCUSED_STATE_SET, FADING_EDGE_HORIZONTAL, FADING_EDGE_MASK, FADING_EDGE_NONE, FADING_EDGE_VERTICAL, FIRST_STATE_SET, FOCUS_BACKWARD, FOCUS_DOWN, FOCUS_FORWARD, FOCUS_LEFT, FOCUS_RIGHT, FOCUS_UP, FOCUSABLE_IN_TOUCH_MODE, FOCUSED, FOCUSED_SELECTED_STATE_SET, FOCUSED_SELECTED_WINDOW_FOCUSED_STATE_SET, FOCUSED_STATE_SET, FOCUSED_WINDOW_FOCUSED_STATE_SET, FORCE_LAYOUT, GONE, HAS_BOUNDS, INVISIBLE, IS_ROOT_NAMESPACE, KEEP_SCREEN_ON, LAST_STATE_SET, LONG_CLICKABLE, mAttachInfo, mBottom, mContext, mCurrentAnimation, MEASURED_DIMENSION_SET, mID, MIDDLE_STATE_SET, mLayoutParams, mLocation, mMeasuredHeight, mMeasuredWidth, mOnClickListener, mOnCreateContextMenuListener, mOnFocusChangeListener, mOnLongClickListener, mPaddingBottom, mPaddingLeft, mPaddingRight, mPaddingTop, mParent, mPrivateFlags, mRight, mScrollX, mScrollY, mTag, mUserPaddingBottom, mUserPaddingRight, mViewFlags, mWindowAttachCount, NO_ID, ONLY_DRAWS_BACKGROUND, PRESSED_ENABLED_FOCUSED_SELECTED_STATE_SET, PRESSED_ENABLED_FOCUSED_SELECTED_WINDOW_FOCUSED_STATE_SET, PRESSED_ENABLED_FOCUSED_STATE_SET, PRESSED_ENABLED_FOCUSED_WINDOW_FOCUSED_STATE_SET, PRESSED_ENABLED_SELECTED_STATE_SET, PRESSED_ENABLED_SELECTED_WINDOW_FOCUSED_STATE_SET, PRESSED_ENABLED_STATE_SET, PRESSED_ENABLED_WINDOW_FOCUSED_STATE_SET, PRESSED_FIRST_STATE_SET, PRESSED_FOCUSED_SELECTED_STATE_SET, PRESSED_FOCUSED_SELECTED_WINDOW_FOCUSED_STATE_SET, PRESSED_FOCUSED_STATE_SET, PRESSED_FOCUSED_WINDOW_FOCUSED_STATE_SET, PRESSED_LAST_STATE_SET, PRESSED_MIDDLE_STATE_SET, PRESSED_SELECTED_STATE_SET, PRESSED_SELECTED_WINDOW_FOCUSED_STATE_SET, PRESSED_SINGLE_STATE_SET, PRESSED_STATE_SET, PRESSED_WINDOW_FOCUSED_STATE_SET, REQUEST_TRANSPARENT_REGIONS, SAVE_DISABLED, SAVE_DISABLED_MASK, SCROLLBARS_HORIZONTAL, SCROLLBARS_INSET_MASK, SCROLLBARS_INSIDE_INSET, SCROLLBARS_INSIDE_OVERLAY, SCROLLBARS_MASK, SCROLLBARS_NONE, SCROLLBARS_OUTSIDE_INSET, SCROLLBARS_OUTSIDE_MASK, SCROLLBARS_OUTSIDE_OVERLAY, SCROLLBARS_STYLE_MASK, SCROLLBARS_VERTICAL, SELECTED, SELECTED_STATE_SET, SELECTED_WINDOW_FOCUSED_STATE_SET, SINGLE_STATE_SET, sInstanceCount, SKIP_DRAW, SOUND_EFFECTS_ENABLED, VIEW_LOG_TAG, VISIBILITY_MASK, VISIBLE, WANTS_FOCUS, WILL_NOT_CACHE_DRAWING, WILL_NOT_DRAW, WINDOW_FOCUSED_STATE_SET

Constructor Summary

SurfaceView(Context context)

SurfaceView(Context context, AttributeSet attrs)

SurfaceView(Context context, AttributeSet attrs, int defStyle)

Method Summary

protected void	dispatchDraw(Canvas canvas) Called by draw to draw the child views.
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.
(package private) void	handleGetNewSurface()
protected void	onAttachedToWindow() This is called when the view is attached to a window.
protected void	onDetachedFromWindow() This is called when the view is detached from a window.
protected void	onMeasure(int widthMeasureSpec, int heightMeasureSpec) Measure the view and its content to determine the measured width and the measured height.
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).
protected void	onSizeChanged(int w, int h, int oldw, int oldh) This is called during layout when the size of this view has changed.
protected void	onWindowVisibilityChanged(int visibility) Called when the window containing has change its visibility (between View.GONE, View.INVISIBLE, and View.VISIBLE).

Methods inherited from class android.view.View

addFocusables, addTouchables, applyDrawableToTransparentRegion, assignParent, bringToFront, buildDrawingCache, cancelLongPress, clearAnimation, clearFocus, clearFocusForRemoval, computeHorizontalScrollExtent, computeHorizontalScrollOffset, computeHorizontalScrollRange, computeScroll, computeVerticalScrollExtent, computeVerticalScrollOffset, computeVerticalScrollRange, createContextMenu, debug, debug, debugIndent, destroyDrawingCache, dispatchAttachedToWindow, dispatchCollectViewAttributes, dispatchDetachedFromWindow, dispatchKeyEvent, dispatchKeyShortcutEvent, dispatchRestoreInstanceState, dispatchSaveInstanceState, dispatchSetPressed, dispatchSetSelected, dispatchTouchEvent, dispatchTrackballEvent, dispatchUnhandledMove, dispatchWindowFocusChanged, dispatchWindowVisibilityChanged, drawableStateChanged, finalize, findFocus, findUserSetNextFocus, findViewById, findViewTraversal, findViewWithTag, findViewWithTagTraversal, fitSystemWindows, focusSearch, forceLayout, getAnimation, getApplicationWindowToken, getBackground, getBaseline, getBottom, getBottomFadingEdgeStrength, getContext, getContextMenuInfo, getDefaultSize, getDrawableState, getDrawingCache, getDrawingCacheBackgroundColor, getDrawingCacheQuality, getDrawingRect, getDrawingTime, getFocusables, getFocusedRect, getGlobalVisibleRect, getGlobalVisibleRect, getHandler, getHeight, getHitRect, getHorizontalFadingEdgeLength, getHorizontalScrollbarHeight, getId, getKeepScreenOn, getLayoutParams, getLeft, getLeftFadingEdgeStrength, getLocalVisibleRect, getLocationInWindow, getLocationOnScreen, getMeasuredHeight, getMeasuredWidth, getNextFocusDownId, getNextFocusLeftId, getNextFocusRightId, getNextFocusUpId, getOnFocusChangeListener, getPaddingBottom, getPaddingLeft, getPaddingRight, getPaddingTop, getParent, getResources, getRight, getRightFadingEdgeStrength, getRootView, getScrollBarStyle, getScrollX, getScrollY, getSolidColor, getSuggestedMinimumHeight, getSuggestedMinimumWidth, getTag, getTop, getTopFadingEdgeStrength, getTouchables, getTouchDelegate, getVerticalFadingEdgeLength, getVerticalScrollbarWidth, getViewTreeObserver, getVisibility, getWidth, getWindowAttachCount, getWindowSession, getWindowToken, getWindowVisibility, handleFocusGainInternal, hasFocus, hasFocusable, hasWindowFocus, inflate, initializeFadingEdge, initializeScrollbars, invalidate, invalidate, invalidate, invalidateDrawable, isClickable, isDrawingCacheEnabled, isDuplicateParentStateEnabled, isEnabled, isFocusable, isFocusableInTouchMode, isFocused, isHorizontalFadingEdgeEnabled, isHorizontalScrollBarEnabled, isInTouchMode, isLayoutRequested, isLongClickable, isPressed, isRootNamespace, isSaveEnabled, isSelected, isShown, isSoundEffectsEnabled, isVerticalFadingEdgeEnabled, isVerticalScrollBarEnabled, layout, measure, mergeDrawableStates, needGlobalAttributesUpdate, offsetLeftAndRight, offsetTopAndBottom, onAnimationEnd, onAnimationStart, onCreateContextMenu, onCreateDrawableState, onDraw, onFinishInflate, onFocusChanged, onKeyDown, onKeyMultiple, onKeyShortcut, onKeyUp, onLayout, onRestoreInstanceState, onSaveInstanceState, onSetAlpha, onTouchEvent, onTrackballEvent, onWindowFocusChanged, performClick, performCollectViewAttributes, performLongClick, playSoundEffect, post, postDelayed, postInvalidate, postInvalidate, postInvalidateDelayed, postInvalidateDelayed, refreshDrawableState, removeCallbacks, requestFocus, requestFocus, requestFocus, requestFocusFromTouch, requestLayout, requestRectangleOnScreen, requestRectangleOnScreen, resolveSize, restoreHierarchyState, saveHierarchyState, scheduleDrawable, scrollBy, scrollTo, setAnimation, setBackgroundColor, setBackgroundDrawable, setBackgroundResource, setClickable, setDrawingCacheBackgroundColor, setDrawingCacheEnabled, setDrawingCacheQuality, setDuplicateParentStateEnabled, setEnabled, setFadingEdgeLength, setFlags, setFocusable, setFocusableInTouchMode, setFrame, setHorizontalFadingEdgeEnabled, setHorizontalScrollBarEnabled, setId, setIsRootNamespace, setKeepScreenOn, setLayoutParams, setLongClickable, setMeasuredDimension, setMinimumHeight, setMinimumWidth, setNextFocusDownId, setNextFocusLeftId, setNextFocusRightId, setNextFocusUpId, setOnClickListener, setOnCreateContextMenuListener, setOnFocusChangeListener, setOnKeyListener, setOnLongClickListener, setOnTouchListener, setPadding, setPressed, setSaveEnabled, setScrollBarStyle, setSelected, setSoundEffectsEnabled, setTag, setTouchDelegate, setVerticalFadingEdgeEnabled, setVerticalScrollBarEnabled, setVisibility, setWillNotCacheDrawing, setWillNotDraw, showContextMenu, startAnimation, unFocus, unscheduleDrawable, unscheduleDrawable, verifyDrawable, willNotCacheDrawing, willNotDraw

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

mCallbacks

final ArrayList<SurfaceHolder.Callback> mCallbacks

mSurfaceLock

final ReentrantLock mSurfaceLock

mSurface

final Surface mSurface

mDrawingStopped

boolean mDrawingStopped

mLayout

final WindowManager.LayoutParams mLayout

mSession

IWindowSession mSession

mWindow

android.view.SurfaceView.MyWindow mWindow

mWinFrame

final Rect mWinFrame

mCoveredInsets

final Rect mCoveredInsets

KEEP_SCREEN_ON_MSG

static final int KEEP_SCREEN_ON_MSG

See Also:

Constant Field Values

GET_NEW_SURFACE_MSG

static final int GET_NEW_SURFACE_MSG

See Also:

Constant Field Values

mIsCreating

boolean mIsCreating

mHandler

final Handler mHandler

mRequestedVisible

boolean mRequestedVisible

mRequestedWidth

int mRequestedWidth

mRequestedHeight

int mRequestedHeight

mRequestedFormat

int mRequestedFormat

mRequestedType

int mRequestedType

mHaveFrame

boolean mHaveFrame

mDestroyReportNeeded

boolean mDestroyReportNeeded

mNewSurfaceNeeded

boolean mNewSurfaceNeeded

mLastLockTime

long mLastLockTime

mVisible

boolean mVisible

mLeft

int mLeft

mTop

int mTop

mWidth

int mWidth

mHeight

int mHeight

mFormat

int mFormat

mType

int mType

mSurfaceFrame

final Rect mSurfaceFrame

Constructor Detail

SurfaceView

public SurfaceView(Context context)

SurfaceView

public SurfaceView(Context context,
                   AttributeSet attrs)

SurfaceView

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

Method Detail

getHolder

public SurfaceHolder getHolder()

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

Returns:

SurfaceHolder The holder of the surface.

onAttachedToWindow

protected void onAttachedToWindow()

Description copied from class: View

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

Overrides:

onAttachedToWindow in class View

See Also:

View.onDetachedFromWindow()

onWindowVisibilityChanged

protected void onWindowVisibilityChanged(int visibility)

Description copied from class: View

Called when the window containing has change its visibility (between View.GONE, View.INVISIBLE, and View.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.

Overrides:

onWindowVisibilityChanged in class View

Parameters:

visibility - The new visibility of the window.

onDetachedFromWindow

protected void onDetachedFromWindow()

Description copied from class: View

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

Overrides:

onDetachedFromWindow in class View

See Also:

View.onAttachedToWindow()

onMeasure

protected void onMeasure(int widthMeasureSpec,
                         int heightMeasureSpec)

Description copied from class: View

Measure the view and its content to determine the measured width and the measured height. This method is invoked by View.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 View.setMeasuredDimension(int, int) to store the measured width and height of this view. Failure to do so will trigger an IllegalStateException, thrown by View.measure(int, int). Calling the superclass' View.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 View.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 (View.getSuggestedMinimumHeight() and View.getSuggestedMinimumWidth()).

Overrides:

onMeasure in class View

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.

See Also:

View.getMeasuredWidth(), View.getMeasuredHeight(), View.setMeasuredDimension(int, int), View.getSuggestedMinimumHeight(), View.getSuggestedMinimumWidth(), View.MeasureSpec.getMode(int), View.MeasureSpec.getSize(int)

onScrollChanged

protected void onScrollChanged(int l,
                               int t,
                               int oldl,
                               int oldt)

Description copied from class: View

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 View.scrollBy(int, int) or View.scrollTo(int, int) having been called.

Overrides:

onScrollChanged in class View

Parameters:

l - Current horizontal scroll origin.

t - Current vertical scroll origin.

oldl - Previous horizontal scroll origin.

oldt - Previous vertical scroll origin.

onSizeChanged

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

Description copied from class: View

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.

Overrides:

onSizeChanged in class View

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.

gatherTransparentRegion

public boolean gatherTransparentRegion(Region region)

Description copied from class: View

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

Overrides:

gatherTransparentRegion in class View

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.

draw

public void draw(Canvas canvas)

Description copied from class: View

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 View.onDraw(android.graphics.Canvas).

Overrides:

draw in class View

Parameters:

canvas - The Canvas to which the View is rendered.

dispatchDraw

protected void dispatchDraw(Canvas canvas)

Description copied from class: View

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

Overrides:

dispatchDraw in class View

Parameters:

canvas - the canvas on which to draw the view

handleGetNewSurface

void handleGetNewSurface()