Android APIs
public class

SlidingPaneLayout

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

Class Overview

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
[Expand]
Inherited XML Attributes
From class android.view.ViewGroup
From class android.view.View
[Expand]
Inherited Constants
From class android.view.ViewGroup
From class android.view.View
[Expand]
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)
Set a drawable to use as a shadow cast by the right pane onto the left pane 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.
[Expand]
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

public SlidingPaneLayout (Context context)

public SlidingPaneLayout (Context context, AttributeSet attrs)

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

Public Methods

public boolean canSlide ()

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

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

public boolean closePane ()

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

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

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

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

public ViewGroup.LayoutParams generateLayoutParams (AttributeSet attrs)

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

Parameters
attrs the attributes to build the layout parameters from
Returns

public int getCoveredFadeColor ()

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

public int getParallaxDistance ()

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

public int getSliderFadeColor ()

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

public 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
  • true if sliding panels are completely open

public 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
  • true if content in this layout can be slid open and closed

public 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 The motion event being dispatched down the hierarchy.
Returns
  • 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.

public 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 The motion event.
Returns
  • True if the event was handled, false otherwise.

public boolean openPane ()

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

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

public void requestChildFocus (View child, View focused)

Called when a child of this parent wants focus

Parameters
child 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 The view that is a descendant of child that actually has focus

public 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 An ARGB-packed color value

public void setPanelSlideListener (SlidingPaneLayout.PanelSlideListener listener)

public 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 Distance to parallax by in pixels

public 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 to use as a shadow

public 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 to use as a shadow

public 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 to use as a shadow

public void setShadowResource (int resId)

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

Parameters
resId Resource ID of a drawable to use

public 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 Resource ID of a drawable to use

public 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 Resource ID of a drawable to use

public 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 An ARGB-packed color value

public void smoothSlideClosed ()

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

public void smoothSlideOpen ()

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

Protected Methods

protected 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 to test for horizontal scrollability
checkV Whether the view v passed should itself be checked for scrollability (true), or just its children (false).
dx Delta scrolled in pixels
x X coordinate of the active touch point
y Y coordinate of the active touch point
Returns
  • true if child views of v can be scrolled by delta of dx.

protected boolean checkLayoutParams (ViewGroup.LayoutParams p)

protected 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 The canvas on which to draw the child
child Who to draw
drawingTime The time at which draw is occurring
Returns
  • True if an invalidate() was issued

protected 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
  • a set of default layout parameters or null

protected 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 The layout parameters to convert into a suitable set of layout parameters for this ViewGroup.
Returns

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(android.graphics.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 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 This is a new size or position for this view
l Left position, relative to parent
t Top position, relative to parent
r Right position, relative to parent
b Bottom position, relative to parent

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 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 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 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 The frozen state that had previously been returned by onSaveInstanceState().

protected 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
  • 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.

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.