Most visited

Recently visited

SlidingPaneLayout

public class SlidingPaneLayout
extends ViewGroup

java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.support.v4.widget.SlidingPaneLayout


SlidingPaneLayout provides a horizontal, multi-pane layout for use at the top level of a UI. A left (or first) pane is treated as a content list or browser, subordinate to a primary detail view for displaying content.

Child views may overlap if their combined width exceeds the available width in the SlidingPaneLayout. When this occurs the user may slide the topmost view out of the way by dragging it, or by navigating in the direction of the overlapped view using a keyboard. If the content of the dragged child view is itself horizontally scrollable, the user may grab it by the very edge.

Thanks to this sliding behavior, SlidingPaneLayout may be suitable for creating layouts that can smoothly adapt across many different screen sizes, expanding out fully on larger screens and collapsing on smaller screens.

SlidingPaneLayout is distinct from a navigation drawer as described in the design guide and should not be used in the same scenarios. SlidingPaneLayout should be thought of only as a way to allow a two-pane layout normally used on larger screens to adapt to smaller screens in a natural way. The interaction patterns expressed by SlidingPaneLayout imply a physicality and direct information hierarchy between panes that does not necessarily exist in a scenario where a navigation drawer should be used instead.

Appropriate uses of SlidingPaneLayout include pairings of panes such as a contact list and subordinate interactions with those contacts, or an email thread list with the content pane displaying the contents of the selected thread. Inappropriate uses of SlidingPaneLayout include switching between disparate functions of your app, such as jumping from a social stream view to a view of your personal profile - cases such as this should use the navigation drawer pattern instead. (DrawerLayout implements this pattern.)

Like LinearLayout, SlidingPaneLayout supports the use of the layout parameter layout_weight on child views to determine how to divide leftover space after measurement is complete. It is only relevant for width. When views do not overlap weight behaves as it does in a LinearLayout.

When views do overlap, weight on a slideable pane indicates that the pane should be sized to fill all available space in the closed state. Weight on a pane that becomes covered indicates that the pane should be sized to fill all available space except a small minimum strip that the user may use to grab the slideable view and pull it back over into a closed state.

Summary

Nested classes

class SlidingPaneLayout.LayoutParams

 

interface SlidingPaneLayout.PanelSlideListener

Listener for monitoring events about sliding panes. 

class SlidingPaneLayout.SimplePanelSlideListener

No-op stubs for SlidingPaneLayout.PanelSlideListener

Inherited XML attributes

From class android.view.ViewGroup
From class android.view.View

Inherited constants

From class android.view.ViewGroup
From class android.view.View

Inherited fields

From class android.view.View

Public constructors

SlidingPaneLayout(Context context)
SlidingPaneLayout(Context context, AttributeSet attrs)
SlidingPaneLayout(Context context, AttributeSet attrs, int defStyle)

Public methods

boolean canSlide()

This method is deprecated. Renamed to isSlideable() - this method is going away soon!

boolean closePane()

Close the sliding pane if it is currently slideable.

void computeScroll()

Called by a parent to request that a child update its values for mScrollX and mScrollY if necessary.

void draw(Canvas c)

Manually render this view (and all of its children) to the given Canvas.

ViewGroup.LayoutParams generateLayoutParams(AttributeSet attrs)

Returns a new set of layout parameters based on the supplied attributes set.

int getCoveredFadeColor()
int getParallaxDistance()
int getSliderFadeColor()
boolean isOpen()

Check if the layout is completely open.

boolean isSlideable()

Check if the content in this layout cannot fully fit side by side and therefore the content pane can be slid back and forth.

boolean onInterceptTouchEvent(MotionEvent ev)

Implement this method to intercept all touch screen motion events.

boolean onTouchEvent(MotionEvent ev)

Implement this method to handle touch screen motion events.

boolean openPane()

Open the sliding pane if it is currently slideable.

void requestChildFocus(View child, View focused)

Called when a child of this parent wants focus

void setCoveredFadeColor(int color)

Set the color used to fade the pane covered by the sliding pane out when the pane will become fully covered in the closed state.

void setPanelSlideListener(SlidingPaneLayout.PanelSlideListener listener)
void setParallaxDistance(int parallaxBy)

Set a distance to parallax the lower pane by when the upper pane is in its fully closed state.

void setShadowDrawable(Drawable d)

This method is deprecated. Renamed to setShadowDrawableLeft(Drawable) to support LTR (left to right language) and setShadowDrawableRight(Drawable) to support RTL (right to left language) during opening/closing.

void setShadowDrawableLeft(Drawable d)

Set a drawable to use as a shadow cast by the right pane onto the left pane during opening/closing.

void setShadowDrawableRight(Drawable d)

Set a drawable to use as a shadow cast by the left pane onto the right pane during opening/closing to support right to left language.

void setShadowResource(int resId)

This method is deprecated. Renamed to setShadowResourceLeft(int) to support LTR (left to right language) and setShadowResourceRight(int) to support RTL (right to left language) during opening/closing.

void setShadowResourceLeft(int resId)

Set a drawable to use as a shadow cast by the right pane onto the left pane during opening/closing.

void setShadowResourceRight(int resId)

Set a drawable to use as a shadow cast by the left pane onto the right pane during opening/closing to support right to left language.

void setSliderFadeColor(int color)

Set the color used to fade the sliding pane out when it is slid most of the way offscreen.

void smoothSlideClosed()

This method is deprecated. Renamed to closePane() - this method is going away soon!

void smoothSlideOpen()

This method is deprecated. Renamed to openPane() - this method is going away soon!

Protected methods

boolean canScroll(View v, boolean checkV, int dx, int x, int y)

Tests scrollability within child views of v given a delta of dx.

boolean checkLayoutParams(ViewGroup.LayoutParams p)
boolean drawChild(Canvas canvas, View child, long drawingTime)

Draw one child of this View Group.

ViewGroup.LayoutParams generateDefaultLayoutParams()

Returns a set of default layout parameters.

ViewGroup.LayoutParams generateLayoutParams(ViewGroup.LayoutParams p)

Returns a safe set of layout parameters based on the supplied layout params.

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 l, int t, int r, int b)

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.

void onRestoreInstanceState(Parcelable state)

Hook allowing a view to re-apply a representation of its internal state that had previously been generated by onSaveInstanceState().

Parcelable onSaveInstanceState()

Hook allowing a view to generate a representation of its internal state that can later be used to create a new instance with that same state.

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

This is called during layout when the size of this view has changed.

Inherited methods

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

Public constructors

SlidingPaneLayout

SlidingPaneLayout (Context context)

Parameters
context Context

SlidingPaneLayout

SlidingPaneLayout (Context context, 
                AttributeSet attrs)

Parameters
context Context
attrs AttributeSet

SlidingPaneLayout

SlidingPaneLayout (Context context, 
                AttributeSet attrs, 
                int defStyle)

Parameters
context Context
attrs AttributeSet
defStyle int

Public methods

canSlide

boolean canSlide ()

This method is deprecated.
Renamed to isSlideable() - this method is going away soon!

Returns
boolean true if content in this layout can be slid open and closed

closePane

boolean closePane ()

Close the sliding pane if it is currently slideable. If first layout has already completed this will animate.

Returns
boolean true if the pane was slideable and is now closed/in the process of closing

computeScroll

void computeScroll ()

Called by a parent to request that a child update its values for mScrollX and mScrollY if necessary. This will typically be done if the child is animating a scroll using a Scroller object.

draw

void draw (Canvas c)

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
c Canvas: The Canvas to which the View is rendered.

generateLayoutParams

ViewGroup.LayoutParams generateLayoutParams (AttributeSet attrs)

Returns a new set of layout parameters based on the supplied attributes set.

Parameters
attrs AttributeSet: the attributes to build the layout parameters from
Returns
ViewGroup.LayoutParams an instance of ViewGroup.LayoutParams or one of its descendants

getCoveredFadeColor

int getCoveredFadeColor ()

Returns
int The ARGB-packed color value used to fade the fixed pane

getParallaxDistance

int getParallaxDistance ()

Returns
int The distance the lower pane will parallax by when the upper pane is fully closed.

See also:

getSliderFadeColor

int getSliderFadeColor ()

Returns
int The ARGB-packed color value used to fade the sliding pane

isOpen

boolean isOpen ()

Check if the layout is completely open. It can be open either because the slider itself is open revealing the left pane, or if all content fits without sliding.

Returns
boolean true if sliding panels are completely open

isSlideable

boolean isSlideable ()

Check if the content in this layout cannot fully fit side by side and therefore the content pane can be slid back and forth.

Returns
boolean true if content in this layout can be slid open and closed

onInterceptTouchEvent

boolean onInterceptTouchEvent (MotionEvent ev)

Implement this method to intercept all touch screen motion events. This allows you to watch events as they are dispatched to your children, and take ownership of the current gesture at any point.

Using this function takes some care, as it has a fairly complicated interaction with View.onTouchEvent(MotionEvent), and using it requires implementing that method as well as this one in the correct way. Events will be received in the following order:

  1. You will receive the down event here.
  2. The down event will be handled either by a child of this view group, or given to your own onTouchEvent() method to handle; this means you should implement onTouchEvent() to return true, so you will continue to see the rest of the gesture (instead of looking for a parent view to handle it). Also, by returning true from onTouchEvent(), you will not receive any following events in onInterceptTouchEvent() and all touch processing must happen in onTouchEvent() like normal.
  3. For as long as you return false from this function, each following event (up to and including the final up) will be delivered first here and then to the target's onTouchEvent().
  4. If you return true from here, you will not receive any following events: the target view will receive the same event but with the action ACTION_CANCEL, and all further events will be delivered to your onTouchEvent() method and no longer appear here.

Parameters
ev MotionEvent: The motion event being dispatched down the hierarchy.
Returns
boolean Return true to steal motion events from the children and have them dispatched to this ViewGroup through onTouchEvent(). The current target will receive an ACTION_CANCEL event, and no further messages will be delivered here.

onTouchEvent

boolean onTouchEvent (MotionEvent ev)

Implement this method to handle touch screen motion events.

If this method is used to detect click actions, it is recommended that the actions be performed by implementing and calling performClick(). This will ensure consistent system behavior, including:

  • obeying click sound preferences
  • dispatching OnClickListener calls
  • handling ACTION_CLICK when accessibility features are enabled

Parameters
ev MotionEvent: The motion event.
Returns
boolean True if the event was handled, false otherwise.

openPane

boolean openPane ()

Open the sliding pane if it is currently slideable. If first layout has already completed this will animate.

Returns
boolean true if the pane was slideable and is now open/in the process of opening

requestChildFocus

void requestChildFocus (View child, 
                View focused)

Called when a child of this parent wants focus

Parameters
child View: The child of this ViewParent that wants focus. This view will contain the focused view. It is not necessarily the view that actually has focus.
focused View: The view that is a descendant of child that actually has focus

setCoveredFadeColor

void setCoveredFadeColor (int color)

Set the color used to fade the pane covered by the sliding pane out when the pane will become fully covered in the closed state.

Parameters
color int: An ARGB-packed color value

setPanelSlideListener

void setPanelSlideListener (SlidingPaneLayout.PanelSlideListener listener)

Parameters
listener SlidingPaneLayout.PanelSlideListener

setParallaxDistance

void setParallaxDistance (int parallaxBy)

Set a distance to parallax the lower pane by when the upper pane is in its fully closed state. The lower pane will scroll between this position and its fully open state.

Parameters
parallaxBy int: Distance to parallax by in pixels

setShadowDrawable

void setShadowDrawable (Drawable d)

This method is deprecated.
Renamed to setShadowDrawableLeft(Drawable) to support LTR (left to right language) and setShadowDrawableRight(Drawable) to support RTL (right to left language) during opening/closing.

Parameters
d Drawable: drawable to use as a shadow

setShadowDrawableLeft

void setShadowDrawableLeft (Drawable d)

Set a drawable to use as a shadow cast by the right pane onto the left pane during opening/closing.

Parameters
d Drawable: drawable to use as a shadow

setShadowDrawableRight

void setShadowDrawableRight (Drawable d)

Set a drawable to use as a shadow cast by the left pane onto the right pane during opening/closing to support right to left language.

Parameters
d Drawable: drawable to use as a shadow

setShadowResource

void setShadowResource (int resId)

This method is deprecated.
Renamed to setShadowResourceLeft(int) to support LTR (left to right language) and setShadowResourceRight(int) to support RTL (right to left language) during opening/closing.

Set a drawable to use as a shadow cast by the right pane onto the left pane during opening/closing.

Parameters
resId int: Resource ID of a drawable to use

setShadowResourceLeft

void setShadowResourceLeft (int resId)

Set a drawable to use as a shadow cast by the right pane onto the left pane during opening/closing.

Parameters
resId int: Resource ID of a drawable to use

setShadowResourceRight

void setShadowResourceRight (int resId)

Set a drawable to use as a shadow cast by the left pane onto the right pane during opening/closing to support right to left language.

Parameters
resId int: Resource ID of a drawable to use

setSliderFadeColor

void setSliderFadeColor (int color)

Set the color used to fade the sliding pane out when it is slid most of the way offscreen.

Parameters
color int: An ARGB-packed color value

smoothSlideClosed

void smoothSlideClosed ()

This method is deprecated.
Renamed to closePane() - this method is going away soon!

smoothSlideOpen

void smoothSlideOpen ()

This method is deprecated.
Renamed to openPane() - this method is going away soon!

Protected methods

canScroll

boolean canScroll (View v, 
                boolean checkV, 
                int dx, 
                int x, 
                int y)

Tests scrollability within child views of v given a delta of dx.

Parameters
v View: View to test for horizontal scrollability
checkV boolean: Whether the view v passed should itself be checked for scrollability (true), or just its children (false).
dx int: Delta scrolled in pixels
x int: X coordinate of the active touch point
y int: Y coordinate of the active touch point
Returns
boolean true if child views of v can be scrolled by delta of dx.

checkLayoutParams

boolean checkLayoutParams (ViewGroup.LayoutParams p)

Parameters
p ViewGroup.LayoutParams
Returns
boolean

drawChild

boolean drawChild (Canvas canvas, 
                View child, 
                long drawingTime)

Draw one child of this View Group. This method is responsible for getting the canvas in the right state. This includes clipping, translating so that the child's scrolled origin is at 0, 0, and applying any animation transformations.

Parameters
canvas Canvas: The canvas on which to draw the child
child View: Who to draw
drawingTime long: The time at which draw is occurring
Returns
boolean True if an invalidate() was issued

generateDefaultLayoutParams

ViewGroup.LayoutParams generateDefaultLayoutParams ()

Returns a set of default layout parameters. These parameters are requested when the View passed to addView(View) has no layout parameters already set. If null is returned, an exception is thrown from addView.

Returns
ViewGroup.LayoutParams a set of default layout parameters or null

generateLayoutParams

ViewGroup.LayoutParams generateLayoutParams (ViewGroup.LayoutParams p)

Returns a safe set of layout parameters based on the supplied layout params. When a ViewGroup is passed a View whose layout params do not pass the test of checkLayoutParams(android.view.ViewGroup.LayoutParams), this method is invoked. This method should return a new set of layout params suitable for this ViewGroup, possibly by copying the appropriate attributes from the specified set of layout params.

Parameters
p ViewGroup.LayoutParams: The layout parameters to convert into a suitable set of layout parameters for this ViewGroup.
Returns
ViewGroup.LayoutParams an instance of ViewGroup.LayoutParams or one of its descendants

onAttachedToWindow

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

void onDetachedFromWindow ()

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

onLayout

void onLayout (boolean changed, 
                int l, 
                int t, 
                int r, 
                int b)

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
l int: Left position, relative to parent
t int: Top position, relative to parent
r int: Right position, relative to parent
b int: Bottom position, relative to parent

onMeasure

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.

onRestoreInstanceState

void onRestoreInstanceState (Parcelable state)

Hook allowing a view to re-apply a representation of its internal state that had previously been generated by onSaveInstanceState(). This function will never be called with a null state.

Parameters
state Parcelable: The frozen state that had previously been returned by onSaveInstanceState().

onSaveInstanceState

Parcelable onSaveInstanceState ()

Hook allowing a view to generate a representation of its internal state that can later be used to create a new instance with that same state. This state should only contain information that is not persistent or can not be reconstructed later. For example, you will never store your current position on screen because that will be computed again when a new instance of the view is placed in its view hierarchy.

Some examples of things you may store here: the current cursor position in a text view (but usually not the text itself since that is stored in a content provider or other persistent storage), the currently selected item in a list view.

Returns
Parcelable Returns a Parcelable object containing the view's current dynamic state, or null if there is nothing interesting to save. The default implementation returns null.

onSizeChanged

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 int: Current width of this view.
h int: Current height of this view.
oldw int: Old width of this view.
oldh int: Old height of this view.

Hooray!