android.support.v4.view
Class ViewPager

java.lang.Object
  extended by ViewGroup
      extended by android.support.v4.view.ViewPager

public class ViewPager
extends ViewGroup

Layout manager that allows the user to flip left and right through pages of data. You supply an implementation of a PagerAdapter to generate the pages that the view shows.

Note this class is currently under early design and development. The API will likely change in later updates of the compatibility library, requiring changes to the source code of apps when they are compiled against the newer version.

ViewPager is most often used in conjunction with android.app.Fragment, which is a convenient way to supply and manage the lifecycle of each page. There are standard adapters implemented for using fragments with the ViewPager, which cover the most common use cases. These are FragmentPagerAdapter, FragmentStatePagerAdapter, FragmentPagerAdapter, and FragmentStatePagerAdapter; each of these classes have simple code showing how to build a full user interface with them.

Here is a more complicated example of ViewPager, using it in conjuction with android.app.ActionBar tabs. You can find other examples of using ViewPager in the API 4+ Support Demos and API 13+ Support Demos sample code.


Nested Class Summary
static class ViewPager.LayoutParams
          Layout parameters that should be supplied for views added to a ViewPager.
static interface ViewPager.OnPageChangeListener
          Callback interface for responding to changing state of the selected page.
static class ViewPager.SavedState
          This is the persistent state that is saved by ViewPager.
static class ViewPager.SimpleOnPageChangeListener
          Simple implementation of the ViewPager.OnPageChangeListener interface with stub implementations of each method.
 
Field Summary
static int SCROLL_STATE_DRAGGING
          Indicates that the pager is currently being dragged by the user.
static int SCROLL_STATE_IDLE
          Indicates that the pager is in an idle, settled state.
static int SCROLL_STATE_SETTLING
          Indicates that the pager is in the process of settling to a final position.
 
Constructor Summary
ViewPager(Context context)
           
ViewPager(Context context, AttributeSet attrs)
           
 
Method Summary
 void addFocusables(java.util.ArrayList<View> views, int direction, int focusableMode)
          We only want the current page that is being shown to be focusable.
 void addTouchables(java.util.ArrayList<View> views)
          We only want the current page that is being shown to be touchable.
 void addView(View child, int index, ViewGroup.LayoutParams params)
           
 boolean arrowScroll(int direction)
           
 boolean beginFakeDrag()
          Start a fake drag of the pager.
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.
protected  boolean checkLayoutParams(ViewGroup.LayoutParams p)
           
 void computeScroll()
           
 boolean dispatchKeyEvent(KeyEvent event)
           
 boolean dispatchPopulateAccessibilityEvent(AccessibilityEvent event)
           
 void draw(Canvas canvas)
           
protected  void drawableStateChanged()
           
 void endFakeDrag()
          End a fake drag of the pager.
 boolean executeKeyEvent(KeyEvent event)
          You can call this function yourself to have the scroll view perform scrolling from a key event, just as if the event had been dispatched to it by the view hierarchy.
 void fakeDragBy(float xOffset)
          Fake drag by an offset in pixels.
protected  ViewGroup.LayoutParams generateDefaultLayoutParams()
           
 ViewGroup.LayoutParams generateLayoutParams(AttributeSet attrs)
           
protected  ViewGroup.LayoutParams generateLayoutParams(ViewGroup.LayoutParams p)
           
 PagerAdapter getAdapter()
          Retrieve the current adapter supplying pages.
 int getCurrentItem()
           
 int getOffscreenPageLimit()
          Returns the number of pages that will be retained to either side of the current page in the view hierarchy in an idle state.
 int getPageMargin()
          Return the margin between pages.
 boolean isFakeDragging()
          Returns true if a fake drag is in progress.
protected  void onAttachedToWindow()
           
protected  void onDraw(Canvas canvas)
           
 boolean onInterceptTouchEvent(MotionEvent ev)
           
protected  void onLayout(boolean changed, int l, int t, int r, int b)
           
protected  void onMeasure(int widthMeasureSpec, int heightMeasureSpec)
           
protected  void onPageScrolled(int position, float offset, int offsetPixels)
          This method will be invoked when the current page is scrolled, either as part of a programmatically initiated smooth scroll or a user initiated touch scroll.
protected  boolean onRequestFocusInDescendants(int direction, Rect previouslyFocusedRect)
          We only want the current page that is being shown to be focusable.
 void onRestoreInstanceState(Parcelable state)
           
 Parcelable onSaveInstanceState()
           
protected  void onSizeChanged(int w, int h, int oldw, int oldh)
           
 boolean onTouchEvent(MotionEvent ev)
           
 void setAdapter(PagerAdapter adapter)
          Set a PagerAdapter that will supply views for this pager as needed.
 void setCurrentItem(int item)
          Set the currently selected page.
 void setCurrentItem(int item, boolean smoothScroll)
          Set the currently selected page.
 void setOffscreenPageLimit(int limit)
          Set the number of pages that should be retained to either side of the current page in the view hierarchy in an idle state.
 void setOnPageChangeListener(ViewPager.OnPageChangeListener listener)
          Set a listener that will be invoked whenever the page changes or is incrementally scrolled.
 void setPageMargin(int marginPixels)
          Set the margin between pages.
 void setPageMarginDrawable(Drawable d)
          Set a drawable that will be used to fill the margin between pages.
protected  boolean verifyDrawable(Drawable who)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SCROLL_STATE_IDLE

public static final int SCROLL_STATE_IDLE
Indicates that the pager is in an idle, settled state. The current page is fully in view and no animation is in progress.

See Also:
Constant Field Values

SCROLL_STATE_DRAGGING

public static final int SCROLL_STATE_DRAGGING
Indicates that the pager is currently being dragged by the user.

See Also:
Constant Field Values

SCROLL_STATE_SETTLING

public static final int SCROLL_STATE_SETTLING
Indicates that the pager is in the process of settling to a final position.

See Also:
Constant Field Values
Constructor Detail

ViewPager

public ViewPager(Context context)

ViewPager

public ViewPager(Context context,
                 AttributeSet attrs)
Method Detail

setAdapter

public void setAdapter(PagerAdapter adapter)
Set a PagerAdapter that will supply views for this pager as needed.

Parameters:
adapter - Adapter to use

getAdapter

public PagerAdapter getAdapter()
Retrieve the current adapter supplying pages.

Returns:
The currently registered PagerAdapter

setCurrentItem

public void setCurrentItem(int item)
Set the currently selected page. If the ViewPager has already been through its first layout with its current adapter there will be a smooth animated transition between the current item and the specified item.

Parameters:
item - Item index to select

setCurrentItem

public void setCurrentItem(int item,
                           boolean smoothScroll)
Set the currently selected page.

Parameters:
item - Item index to select
smoothScroll - True to smoothly scroll to the new item, false to transition immediately

getCurrentItem

public int getCurrentItem()

setOnPageChangeListener

public void setOnPageChangeListener(ViewPager.OnPageChangeListener listener)
Set a listener that will be invoked whenever the page changes or is incrementally scrolled. See ViewPager.OnPageChangeListener.

Parameters:
listener - Listener to set

getOffscreenPageLimit

public int getOffscreenPageLimit()
Returns the number of pages that will be retained to either side of the current page in the view hierarchy in an idle state. Defaults to 1.

Returns:
How many pages will be kept offscreen on either side
See Also:
setOffscreenPageLimit(int)

setOffscreenPageLimit

public void setOffscreenPageLimit(int limit)
Set the number of pages that should be retained to either side of the current page in the view hierarchy in an idle state. Pages beyond this limit will be recreated from the adapter when needed.

This is offered as an optimization. If you know in advance the number of pages you will need to support or have lazy-loading mechanisms in place on your pages, tweaking this setting can have benefits in perceived smoothness of paging animations and interaction. If you have a small number of pages (3-4) that you can keep active all at once, less time will be spent in layout for newly created view subtrees as the user pages back and forth.

You should keep this limit low, especially if your pages have complex layouts. This setting defaults to 1.

Parameters:
limit - How many pages will be kept offscreen in an idle state.

setPageMargin

public void setPageMargin(int marginPixels)
Set the margin between pages.

Parameters:
marginPixels - Distance between adjacent pages in pixels
See Also:
getPageMargin(), setPageMarginDrawable(Drawable), #setPageMarginDrawable(int)

getPageMargin

public int getPageMargin()
Return the margin between pages.

Returns:
The size of the margin in pixels

setPageMarginDrawable

public void setPageMarginDrawable(Drawable d)
Set a drawable that will be used to fill the margin between pages.

Parameters:
d - Drawable to display between pages

verifyDrawable

protected boolean verifyDrawable(Drawable who)

drawableStateChanged

protected void drawableStateChanged()

onSaveInstanceState

public Parcelable onSaveInstanceState()

onRestoreInstanceState

public void onRestoreInstanceState(Parcelable state)

addView

public void addView(View child,
                    int index,
                    ViewGroup.LayoutParams params)

onAttachedToWindow

protected void onAttachedToWindow()

onMeasure

protected void onMeasure(int widthMeasureSpec,
                         int heightMeasureSpec)

onSizeChanged

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

onLayout

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

computeScroll

public void computeScroll()

onPageScrolled

protected void onPageScrolled(int position,
                              float offset,
                              int offsetPixels)
This method will be invoked when the current page is scrolled, either as part of a programmatically initiated smooth scroll or a user initiated touch scroll. If you override this method you must call through to the superclass implementation (e.g. super.onPageScrolled(position, offset, offsetPixels)) before onPageScrolled returns.

Parameters:
position - Position index of the first page currently being displayed. Page position+1 will be visible if positionOffset is nonzero.
offset - Value from [0, 1) indicating the offset from the page at position.
offsetPixels - Value in pixels indicating the offset from position.

onInterceptTouchEvent

public boolean onInterceptTouchEvent(MotionEvent ev)

onTouchEvent

public boolean onTouchEvent(MotionEvent ev)

draw

public void draw(Canvas canvas)

onDraw

protected void onDraw(Canvas canvas)

beginFakeDrag

public boolean beginFakeDrag()
Start a fake drag of the pager.

A fake drag can be useful if you want to synchronize the motion of the ViewPager with the touch scrolling of another view, while still letting the ViewPager control the snapping motion and fling behavior. (e.g. parallax-scrolling tabs.) Call fakeDragBy(float) to simulate the actual drag motion. Call endFakeDrag() to complete the fake drag and fling as necessary.

During a fake drag the ViewPager will ignore all touch events. If a real drag is already in progress, this method will return false.

Returns:
true if the fake drag began successfully, false if it could not be started.
See Also:
fakeDragBy(float), endFakeDrag()

endFakeDrag

public void endFakeDrag()
End a fake drag of the pager.

See Also:
beginFakeDrag(), fakeDragBy(float)

fakeDragBy

public void fakeDragBy(float xOffset)
Fake drag by an offset in pixels. You must have called beginFakeDrag() first.

Parameters:
xOffset - Offset in pixels to drag by.
See Also:
beginFakeDrag(), endFakeDrag()

isFakeDragging

public boolean isFakeDragging()
Returns true if a fake drag is in progress.

Returns:
true if currently in a fake drag, false otherwise.
See Also:
beginFakeDrag(), fakeDragBy(float), endFakeDrag()

canScroll

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.

dispatchKeyEvent

public boolean dispatchKeyEvent(KeyEvent event)

executeKeyEvent

public boolean executeKeyEvent(KeyEvent event)
You can call this function yourself to have the scroll view perform scrolling from a key event, just as if the event had been dispatched to it by the view hierarchy.

Parameters:
event - The key event to execute.
Returns:
Return true if the event was handled, else false.

arrowScroll

public boolean arrowScroll(int direction)

addFocusables

public void addFocusables(java.util.ArrayList<View> views,
                          int direction,
                          int focusableMode)
We only want the current page that is being shown to be focusable.


addTouchables

public void addTouchables(java.util.ArrayList<View> views)
We only want the current page that is being shown to be touchable.


onRequestFocusInDescendants

protected boolean onRequestFocusInDescendants(int direction,
                                              Rect previouslyFocusedRect)
We only want the current page that is being shown to be focusable.


dispatchPopulateAccessibilityEvent

public boolean dispatchPopulateAccessibilityEvent(AccessibilityEvent event)

generateDefaultLayoutParams

protected ViewGroup.LayoutParams generateDefaultLayoutParams()

generateLayoutParams

protected ViewGroup.LayoutParams generateLayoutParams(ViewGroup.LayoutParams p)

checkLayoutParams

protected boolean checkLayoutParams(ViewGroup.LayoutParams p)

generateLayoutParams

public ViewGroup.LayoutParams generateLayoutParams(AttributeSet attrs)