PagerAdapter.java revision 2a4d8518f36346ea25a22a736453ff28f2954165 
1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package android.support.v4.view;
18
19import android.os.Parcelable;
20import android.view.View;
21
22/**
23 * Base class providing the adapter to populate pages inside of
24 * a {@link ViewPager}.  You will most likely want to use a more
25 * specific implementation of this, such as
26 * {@link android.support.v4.app.FragmentPagerAdapter} or
27 * {@link android.support.v4.app.FragmentStatePagerAdapter}.
28 */
29public abstract class PagerAdapter {
30    private DataSetObserver mObserver;
31
32    public static final int POSITION_UNCHANGED = -1;
33    public static final int POSITION_NONE = -2;
34
35    /**
36     * Used to watch for changes within the adapter.
37     */
38    interface DataSetObserver {
39        public void onDataSetChanged();
40    }
41
42    /**
43     * Return the number of views available.
44     */
45    public abstract int getCount();
46
47    /**
48     * Called when a change in the shown pages is going to start being made.
49     * @param container The containing View which is displaying this adapter's
50     * page views.
51     */
52    public abstract void startUpdate(View container);
53
54    /**
55     * Create the page for the given position.  The adapter is responsible
56     * for adding the view to the container given here, although it only
57     * must ensure this is done by the time it returns from
58     * {@link #finishUpdate()}.
59     *
60     * @param container The containing View in which the page will be shown.
61     * @param position The page position to be instantiated.
62     * @return Returns an Object representing the new page.  This does not
63     * need to be a View, but can be some other container of the page.
64     */
65    public abstract Object instantiateItem(View container, int position);
66
67    /**
68     * Remove a page for the given position.  The adapter is responsible
69     * for removing the view from its container, although it only must ensure
70     * this is done by the time it returns from {@link #finishUpdate()}.
71     *
72     * @param container The containing View from which the page will be removed.
73     * @param position The page position to be removed.
74     * @param object The same object that was returned by
75     * {@link #instantiateItem(View, int)}.
76     */
77    public abstract void destroyItem(View container, int position, Object object);
78
79    /**
80     * Called to inform the adapter of which item is currently considered to
81     * be the "primary", that is the one show to the user as the current page.
82     *
83     * @param container The containing View from which the page will be removed.
84     * @param position The page position that is now the primary.
85     * @param object The same object that was returned by
86     * {@link #instantiateItem(View, int)}.
87     */
88    public void setPrimaryItem(View container, int position, Object object) {
89    }
90
91    /**
92     * Called when the a change in the shown pages has been completed.  At this
93     * point you must ensure that all of the pages have actually been added or
94     * removed from the container as appropriate.
95     * @param container The containing View which is displaying this adapter's
96     * page views.
97     */
98    public abstract void finishUpdate(View container);
99
100    public abstract boolean isViewFromObject(View view, Object object);
101
102    public abstract Parcelable saveState();
103
104    public abstract void restoreState(Parcelable state, ClassLoader loader);
105
106    /**
107     * Called when the host view is attempting to determine if an item's position
108     * has changed. Returns {@link #POSITION_UNCHANGED} if the position of the given
109     * item has not changed or {@link #POSITION_NONE} if the item is no longer present
110     * in the adapter.
111     *
112     * <p>The default implementation assumes that items will never
113     * change position and always returns {@link #POSITION_UNCHANGED}.
114     *
115     * @param object Object representing an item, previously returned by a call to
116     *               {@link #instantiateItem(View, int)}.
117     * @return object's new position index from [0, {@link #getCount()}),
118     *         {@link #POSITION_UNCHANGED} if the object's position has not changed,
119     *         or {@link #POSITION_NONE} if the item is no longer present.
120     */
121    public int getItemPosition(Object object) {
122        return POSITION_UNCHANGED;
123    }
124
125    /**
126     * This method should be called by the application if the data backing this adapter has changed
127     * and associated views should update.
128     */
129    public void notifyDataSetChanged() {
130        if (mObserver != null) {
131            mObserver.onDataSetChanged();
132        }
133    }
134
135    void setDataSetObserver(DataSetObserver observer) {
136        mObserver = observer;
137    }
138}
139