added in version 22.1.0
belongs to Maven artifact com.android.support:viewpager:28.0.0-alpha1
Summary: Nested Classes | Constants | Inherited Constants | Inherited Fields | Ctors | Methods | Protected Methods | Inherited Methods | [Expand All]

ViewPager

public class ViewPager
extends ViewGroup

java.lang.Object
   ↳ android.view.View
     ↳ android.view.ViewGroup
       ↳ android.support.v4.view.ViewPager

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.

ViewPager is most often used in conjunction with 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 and FragmentStatePagerAdapter; each of these classes have simple code showing how to build a full user interface with them.

Views which are annotated with the ViewPager.DecorView annotation are treated as part of the view pagers 'decor'. Each decor view's position can be controlled via its android:layout_gravity attribute. For example: 

 <android.support.v4.view.ViewPager
     android:layout_width="match_parent"
     android:layout_height="match_parent">

     <android.support.v4.view.PagerTitleStrip
         android:layout_width="match_parent"
         android:layout_height="wrap_content"
         android:layout_gravity="top" />

 </android.support.v4.view.ViewPager>

For more information about how to use ViewPager, read Creating Swipe Views with Tabs.

You can find examples of using ViewPager in the API 4+ Support Demos and API 13+ Support Demos sample code.

Summary

Nested classes

@interface ViewPager.DecorView

Annotation which allows marking of views to be decoration views when added to a view pager. 

class ViewPager.LayoutParams

Layout parameters that should be supplied for views added to a ViewPager. 

interface ViewPager.OnAdapterChangeListener

Callback interface for responding to adapter changes. 

interface ViewPager.OnPageChangeListener

Callback interface for responding to changing state of the selected page. 

interface ViewPager.PageTransformer

A PageTransformer is invoked whenever a visible/attached page is scrolled. 

class ViewPager.SavedState

This is the persistent state that is saved by ViewPager. 

class ViewPager.SimpleOnPageChangeListener

Simple implementation of the ViewPager.OnPageChangeListener interface with stub implementations of each method. 

Constants

int SCROLL_STATE_DRAGGING

Indicates that the pager is currently being dragged by the user.

int SCROLL_STATE_IDLE

Indicates that the pager is in an idle, settled state.

int SCROLL_STATE_SETTLING

Indicates that the pager is in the process of settling to a final position.

Inherited constants

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

Inherited fields

From class android.view.View

Public constructors

ViewPager(Context context)
ViewPager(Context context, AttributeSet attrs)

Public methods

void addFocusables(ArrayList<View> views, int direction, int focusableMode)

We only want the current page that is being shown to be focusable.

void addOnAdapterChangeListener(ViewPager.OnAdapterChangeListener listener)

Add a listener that will be invoked whenever the adapter for this ViewPager changes.

void addOnPageChangeListener(ViewPager.OnPageChangeListener listener)

Add a listener that will be invoked whenever the page changes or is incrementally scrolled.

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

Handle scrolling in response to a left or right arrow click.

boolean beginFakeDrag()

Start a fake drag of the pager.

boolean canScrollHorizontally(int direction)

Check if this ViewPager can be scrolled horizontally in a certain direction.

void clearOnPageChangeListeners()

Remove all listeners that are notified of any changes in scroll state or position.

void computeScroll()
boolean dispatchKeyEvent(KeyEvent event)
boolean dispatchPopulateAccessibilityEvent(AccessibilityEvent event)
void draw(Canvas canvas)
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.

ViewGroup.LayoutParams generateLayoutParams(AttributeSet attrs)
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.

boolean onInterceptTouchEvent(MotionEvent ev)
void onRestoreInstanceState(Parcelable state)
Parcelable onSaveInstanceState()
boolean onTouchEvent(MotionEvent ev)
void removeOnAdapterChangeListener(ViewPager.OnAdapterChangeListener listener)

Remove a listener that was previously added via addOnAdapterChangeListener(OnAdapterChangeListener).

void removeOnPageChangeListener(ViewPager.OnPageChangeListener listener)

Remove a listener that was previously added via addOnPageChangeListener(OnPageChangeListener).

void removeView(View view)
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)

This method was deprecated in API level 24.1.0. Use addOnPageChangeListener(OnPageChangeListener) and removeOnPageChangeListener(OnPageChangeListener) instead.

void setPageMargin(int marginPixels)

Set the margin between pages.

void setPageMarginDrawable(int resId)

Set a drawable that will be used to fill the margin between pages.

void setPageMarginDrawable(Drawable d)

Set a drawable that will be used to fill the margin between pages.

void setPageTransformer(boolean reverseDrawingOrder, ViewPager.PageTransformer transformer, int pageLayerType)

Sets a ViewPager.PageTransformer that will be called for each attached page whenever the scroll position is changed.

void setPageTransformer(boolean reverseDrawingOrder, ViewPager.PageTransformer transformer)

Sets a ViewPager.PageTransformer that will be called for each attached page whenever the scroll position is changed.

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)
void drawableStateChanged()
ViewGroup.LayoutParams generateDefaultLayoutParams()
ViewGroup.LayoutParams generateLayoutParams(ViewGroup.LayoutParams p)
int getChildDrawingOrder(int childCount, int i)
void onAttachedToWindow()
void onDetachedFromWindow()
void onDraw(Canvas canvas)
void onLayout(boolean changed, int l, int t, int r, int b)
void onMeasure(int widthMeasureSpec, int heightMeasureSpec)
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.

boolean onRequestFocusInDescendants(int direction, Rect previouslyFocusedRect)

We only want the current page that is being shown to be focusable.

void onSizeChanged(int w, int h, int oldw, int oldh)
boolean verifyDrawable(Drawable who)

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

Constants

SCROLL_STATE_DRAGGING

added in version 22.1.0 
int SCROLL_STATE_DRAGGING

Indicates that the pager is currently being dragged by the user.

Constant Value: 1 (0x00000001)

SCROLL_STATE_IDLE

added in version 22.1.0 
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.

Constant Value: 0 (0x00000000)

SCROLL_STATE_SETTLING

added in version 22.1.0 
int SCROLL_STATE_SETTLING

Indicates that the pager is in the process of settling to a final position.

Constant Value: 2 (0x00000002)

Public constructors

ViewPager

added in version 22.1.0
ViewPager (Context context)

Parameters
context Context

ViewPager

added in version 22.1.0
ViewPager (Context context, 
                AttributeSet attrs)

Parameters
context Context

attrs AttributeSet

Public methods

addFocusables

void addFocusables (ArrayList<View> views, 
                int direction, 
                int focusableMode)

We only want the current page that is being shown to be focusable.

Parameters
views ArrayList

direction int

focusableMode int

addOnAdapterChangeListener

added in version 24.1.0
void addOnAdapterChangeListener (ViewPager.OnAdapterChangeListener listener)

Add a listener that will be invoked whenever the adapter for this ViewPager changes.

Parameters
listener ViewPager.OnAdapterChangeListener: listener to add

addOnPageChangeListener

added in version 24.1.0
void addOnPageChangeListener (ViewPager.OnPageChangeListener listener)

Add a listener that will be invoked whenever the page changes or is incrementally scrolled. See ViewPager.OnPageChangeListener.

Components that add a listener should take care to remove it when finished. Other components that take ownership of a view may call clearOnPageChangeListeners() to remove all attached listeners.

Parameters
listener ViewPager.OnPageChangeListener: listener to add

addTouchables

void addTouchables (ArrayList<View> views)

We only want the current page that is being shown to be touchable.

Parameters
views ArrayList

addView

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

Parameters
child View

index int

params ViewGroup.LayoutParams

arrowScroll

added in version 22.1.0
boolean arrowScroll (int direction)

Handle scrolling in response to a left or right arrow click.

Parameters
direction int: The direction corresponding to the arrow key that was pressed. It should be either FOCUS_LEFT or FOCUS_RIGHT.
Returns
boolean Whether the scrolling was handled successfully.

beginFakeDrag

added in version 22.1.0
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
boolean true if the fake drag began successfully, false if it could not be started.

canScrollHorizontally

boolean canScrollHorizontally (int direction)

Check if this ViewPager can be scrolled horizontally in a certain direction.

Parameters
direction int: Negative to check scrolling left, positive to check scrolling right.
Returns
boolean Whether this ViewPager can be scrolled in the specified direction. It will always return false if the specified direction is 0.

clearOnPageChangeListeners

added in version 24.1.0
void clearOnPageChangeListeners ()

Remove all listeners that are notified of any changes in scroll state or position.

computeScroll

void computeScroll ()

dispatchKeyEvent

boolean dispatchKeyEvent (KeyEvent event)

Parameters
event KeyEvent

Returns
boolean

dispatchPopulateAccessibilityEvent

boolean dispatchPopulateAccessibilityEvent (AccessibilityEvent event)

Parameters
event AccessibilityEvent

Returns
boolean

draw

void draw (Canvas canvas)

Parameters
canvas Canvas

endFakeDrag

added in version 22.1.0
void endFakeDrag ()

End a fake drag of the pager.

executeKeyEvent

added in version 22.1.0
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 KeyEvent: The key event to execute.
Returns
boolean Return true if the event was handled, else false.

fakeDragBy

added in version 22.1.0
void fakeDragBy (float xOffset)

Fake drag by an offset in pixels. You must have called beginFakeDrag() first.

Parameters
xOffset float: Offset in pixels to drag by.

generateLayoutParams

ViewGroup.LayoutParams generateLayoutParams (AttributeSet attrs)

Parameters
attrs AttributeSet

Returns
ViewGroup.LayoutParams

getAdapter

added in version 22.1.0
PagerAdapter getAdapter ()

Retrieve the current adapter supplying pages.

Returns
PagerAdapter The currently registered PagerAdapter

getCurrentItem

added in version 22.1.0
int getCurrentItem ()

Returns
int

getOffscreenPageLimit

added in version 22.1.0
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
int How many pages will be kept offscreen on either side

getPageMargin

added in version 22.1.0
int getPageMargin ()

Return the margin between pages.

Returns
int The size of the margin in pixels

isFakeDragging

added in version 22.1.0
boolean isFakeDragging ()

Returns true if a fake drag is in progress.

Returns
boolean true if currently in a fake drag, false otherwise.

onInterceptTouchEvent

boolean onInterceptTouchEvent (MotionEvent ev)

Parameters
ev MotionEvent

Returns
boolean

onRestoreInstanceState

added in version 22.1.0
void onRestoreInstanceState (Parcelable state)

Parameters
state Parcelable

onSaveInstanceState

added in version 22.1.0
Parcelable onSaveInstanceState ()

Returns
Parcelable

onTouchEvent

boolean onTouchEvent (MotionEvent ev)

Parameters
ev MotionEvent

Returns
boolean

removeOnAdapterChangeListener

added in version 24.1.0
void removeOnAdapterChangeListener (ViewPager.OnAdapterChangeListener listener)

Remove a listener that was previously added via addOnAdapterChangeListener(OnAdapterChangeListener).

Parameters
listener ViewPager.OnAdapterChangeListener: listener to remove

removeOnPageChangeListener

added in version 24.1.0
void removeOnPageChangeListener (ViewPager.OnPageChangeListener listener)

Remove a listener that was previously added via addOnPageChangeListener(OnPageChangeListener).

Parameters
listener ViewPager.OnPageChangeListener: listener to remove

removeView

void removeView (View view)

Parameters
view View

setAdapter

added in version 22.1.0
void setAdapter (PagerAdapter adapter)

Set a PagerAdapter that will supply views for this pager as needed.

Parameters
adapter PagerAdapter: Adapter to use

setCurrentItem

added in version 22.1.0
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 int: Item index to select

setCurrentItem

added in version 22.1.0
void setCurrentItem (int item, 
                boolean smoothScroll)

Set the currently selected page.

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

setOffscreenPageLimit

added in version 22.1.0
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 int: How many pages will be kept offscreen in an idle state.

setOnPageChangeListener

added in version 22.1.0
void setOnPageChangeListener (ViewPager.OnPageChangeListener listener)

This method was deprecated in API level 24.1.0.
Use addOnPageChangeListener(OnPageChangeListener) and removeOnPageChangeListener(OnPageChangeListener) instead.

Set a listener that will be invoked whenever the page changes or is incrementally scrolled. See ViewPager.OnPageChangeListener.

Parameters
listener ViewPager.OnPageChangeListener: Listener to set

setPageMargin

added in version 22.1.0
void setPageMargin (int marginPixels)

Set the margin between pages.

Parameters
marginPixels int: Distance between adjacent pages in pixels

setPageMarginDrawable

added in version 22.1.0
void setPageMarginDrawable (int resId)

Set a drawable that will be used to fill the margin between pages.

Parameters
resId int: Resource ID of a drawable to display between pages

setPageMarginDrawable

added in version 22.1.0
void setPageMarginDrawable (Drawable d)

Set a drawable that will be used to fill the margin between pages.

Parameters
d Drawable: Drawable to display between pages

setPageTransformer

added in version 25.1.0
void setPageTransformer (boolean reverseDrawingOrder, 
                ViewPager.PageTransformer transformer, 
                int pageLayerType)

Sets a ViewPager.PageTransformer that will be called for each attached page whenever the scroll position is changed. This allows the application to apply custom property transformations to each page, overriding the default sliding behavior.

Parameters
reverseDrawingOrder boolean: true if the supplied PageTransformer requires page views to be drawn from last to first instead of first to last.
transformer ViewPager.PageTransformer: PageTransformer that will modify each page's animation properties
pageLayerType int: View layer type that should be used for ViewPager pages. It should be either LAYER_TYPE_HARDWARE, LAYER_TYPE_SOFTWARE, or LAYER_TYPE_NONE.

setPageTransformer

added in version 22.1.0
void setPageTransformer (boolean reverseDrawingOrder, 
                ViewPager.PageTransformer transformer)

Sets a ViewPager.PageTransformer that will be called for each attached page whenever the scroll position is changed. This allows the application to apply custom property transformations to each page, overriding the default sliding behavior.

Note: By default, calling this method will cause contained pages to use LAYER_TYPE_HARDWARE. This layer type allows custom alpha transformations, but it will cause issues if any of your pages contain a SurfaceView and you have not called setZOrderOnTop(boolean) to put that SurfaceView above your app content. To disable this behavior, call setPageTransformer(boolean, PageTransformer, int) and pass LAYER_TYPE_NONE for pageLayerType.

Parameters
reverseDrawingOrder boolean: true if the supplied PageTransformer requires page views to be drawn from last to first instead of first to last.
transformer ViewPager.PageTransformer: PageTransformer that will modify each page's animation properties

Protected methods

canScroll

added in version 22.1.0
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

drawableStateChanged

void drawableStateChanged ()

generateDefaultLayoutParams

ViewGroup.LayoutParams generateDefaultLayoutParams ()

Returns
ViewGroup.LayoutParams

generateLayoutParams

ViewGroup.LayoutParams generateLayoutParams (ViewGroup.LayoutParams p)

Parameters
p ViewGroup.LayoutParams

Returns
ViewGroup.LayoutParams

getChildDrawingOrder

int getChildDrawingOrder (int childCount, 
                int i)

Parameters
childCount int

i int

Returns
int

onAttachedToWindow

void onAttachedToWindow ()

onDetachedFromWindow

void onDetachedFromWindow ()

onDraw

void onDraw (Canvas canvas)

Parameters
canvas Canvas

onLayout

added in version 22.1.0
void onLayout (boolean changed, 
                int l, 
                int t, 
                int r, 
                int b)

Parameters
changed boolean

l int

t int

r int

b int

onMeasure

void onMeasure (int widthMeasureSpec, 
                int heightMeasureSpec)

Parameters
widthMeasureSpec int

heightMeasureSpec int

onPageScrolled

added in version 22.1.0
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 int: Position index of the first page currently being displayed. Page position+1 will be visible if positionOffset is nonzero.
offset float: Value from [0, 1) indicating the offset from the page at position.
offsetPixels int: Value in pixels indicating the offset from position.

onRequestFocusInDescendants

boolean onRequestFocusInDescendants (int direction, 
                Rect previouslyFocusedRect)

We only want the current page that is being shown to be focusable.

Parameters
direction int

previouslyFocusedRect Rect

Returns
boolean

onSizeChanged

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

Parameters
w int

h int

oldw int

oldh int

verifyDrawable

boolean verifyDrawable (Drawable who)

Parameters
who Drawable

Returns
boolean