PagerAdapter.java revision 8fffe01871be1806a1bdefa1f7213b660fcf5ac0 
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.database.DataSetObservable;
20import android.database.DataSetObserver;
21import android.os.Parcelable;
22import android.view.View;
23
24/**
25 * Base class providing the adapter to populate pages inside of
26 * a {@link ViewPager}.  You will most likely want to use a more
27 * specific implementation of this, such as
28 * {@link android.support.v4.app.FragmentPagerAdapter} or
29 * {@link android.support.v4.app.FragmentStatePagerAdapter}.
30 */
31public abstract class PagerAdapter {
32    private DataSetObservable mObservable = new DataSetObservable();
33
34    public static final int POSITION_UNCHANGED = -1;
35    public static final int POSITION_NONE = -2;
36
37    /**
38     * Return the number of views available.
39     */
40    public abstract int getCount();
41
42    /**
43     * Called when a change in the shown pages is going to start being made.
44     * @param container The containing View which is displaying this adapter's
45     * page views.
46     */
47    public abstract void startUpdate(View container);
48
49    /**
50     * Create the page for the given position.  The adapter is responsible
51     * for adding the view to the container given here, although it only
52     * must ensure this is done by the time it returns from
53     * {@link #finishUpdate()}.
54     *
55     * @param container The containing View in which the page will be shown.
56     * @param position The page position to be instantiated.
57     * @return Returns an Object representing the new page.  This does not
58     * need to be a View, but can be some other container of the page.
59     */
60    public abstract Object instantiateItem(View container, int position);
61
62    /**
63     * Remove a page for the given position.  The adapter is responsible
64     * for removing the view from its container, although it only must ensure
65     * this is done by the time it returns from {@link #finishUpdate()}.
66     *
67     * @param container The containing View from which the page will be removed.
68     * @param position The page position to be removed.
69     * @param object The same object that was returned by
70     * {@link #instantiateItem(View, int)}.
71     */
72    public abstract void destroyItem(View container, int position, Object object);
73
74    /**
75     * Called to inform the adapter of which item is currently considered to
76     * be the "primary", that is the one show to the user as the current page.
77     *
78     * @param container The containing View from which the page will be removed.
79     * @param position The page position that is now the primary.
80     * @param object The same object that was returned by
81     * {@link #instantiateItem(View, int)}.
82     */
83    public void setPrimaryItem(View container, int position, Object object) {
84    }
85
86    /**
87     * Called when the a change in the shown pages has been completed.  At this
88     * point you must ensure that all of the pages have actually been added or
89     * removed from the container as appropriate.
90     * @param container The containing View which is displaying this adapter's
91     * page views.
92     */
93    public abstract void finishUpdate(View container);
94
95    public abstract boolean isViewFromObject(View view, Object object);
96
97    public abstract Parcelable saveState();
98
99    public abstract void restoreState(Parcelable state, ClassLoader loader);
100
101    /**
102     * Called when the host view is attempting to determine if an item's position
103     * has changed. Returns {@link #POSITION_UNCHANGED} if the position of the given
104     * item has not changed or {@link #POSITION_NONE} if the item is no longer present
105     * in the adapter.
106     *
107     * <p>The default implementation assumes that items will never
108     * change position and always returns {@link #POSITION_UNCHANGED}.
109     *
110     * @param object Object representing an item, previously returned by a call to
111     *               {@link #instantiateItem(View, int)}.
112     * @return object's new position index from [0, {@link #getCount()}),
113     *         {@link #POSITION_UNCHANGED} if the object's position has not changed,
114     *         or {@link #POSITION_NONE} if the item is no longer present.
115     */
116    public int getItemPosition(Object object) {
117        return POSITION_UNCHANGED;
118    }
119
120    /**
121     * This method should be called by the application if the data backing this adapter has changed
122     * and associated views should update.
123     */
124    public void notifyDataSetChanged() {
125        mObservable.notifyChanged();
126    }
127
128    void registerDataSetObserver(DataSetObserver observer) {
129        mObservable.registerObserver(observer);
130    }
131
132    void unregisterDataSetObserver(DataSetObserver observer) {
133        mObservable.unregisterObserver(observer);
134    }
135
136    /**
137     * This method may be called by the ViewPager to obtain a title string
138     * to describe the specified page. This method may return null
139     * indicating no title for this page. The default implementation returns
140     * null.
141     *
142     * @param position The position of the title requested
143     * @return A title for the requested page
144     */
145    public CharSequence getPageTitle(int position) {
146        return null;
147    }
148}
149