Adapter.java revision 54b6cfa9a9e5b861a9930af873580d6dc20f773c 
1/*
2 * Copyright (C) 2006 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.widget;
18
19import android.database.DataSetObserver;
20import android.view.KeyEvent;
21import android.view.View;
22import android.view.ViewGroup;
23
24/**
25 * An Adapter object acts as a bridge between an {@link AdapterView} and the
26 * underlying data for that view. The Adapter provides access to the data items.
27 * The Adapter is also responsible for making a {@link android.view.View} for
28 * each item in the data set.
29 *
30 * @see android.widget.ArrayAdapter
31 * @see android.widget.CursorAdapter
32 * @see android.widget.SimpleCursorAdapter
33 */
34public interface Adapter {
35    /**
36     * Register an observer that is called when changes happen to the data used by this adapter.
37     *
38     * @param observer the object that gets notified when the data set changes.
39     */
40    void registerDataSetObserver(DataSetObserver observer);
41
42    /**
43     * Unregister an observer that has previously been registered with this
44     * adapter via {@link #registerDataSetObserver}.
45     *
46     * @param observer the object to unregister.
47     */
48    void unregisterDataSetObserver(DataSetObserver observer);
49
50    /**
51     * How many items are in the data set represented by this Adapter.
52     *
53     * @return Count of items.
54     */
55    int getCount();
56
57    /**
58     * Get the data item associated with the specified position in the data set.
59     *
60     * @param position Position of the item whose data we want within the adapter's
61     * data set.
62     * @return The data at the specified position.
63     */
64    Object getItem(int position);
65
66    /**
67     * Get the row id associated with the specified position in the list.
68     *
69     * @param position The position of the item within the adapter's data set whose row id we want.
70     * @return The id of the item at the specified position.
71     */
72    long getItemId(int position);
73
74    /**
75     * Indicated whether the item ids are stable across changes to the
76     * underlying data.
77     *
78     * @return True if the same id always refers to the same object.
79     */
80    boolean hasStableIds();
81
82    /**
83     * Get a View that displays the data at the specified position in the data set. You can either
84     * create a View manually or inflate it from an XML layout file. When the View is inflated, the
85     * parent View (GridView, ListView...) will apply default layout parameters unless you use
86     * {@link android.view.LayoutInflater#inflate(int, android.view.ViewGroup, boolean)}
87     * to specify a root view and to prevent attachment to the root.
88     *
89     * @param position The position of the item within the adapter's data set of the item whose view
90     *        we want.
91     * @param convertView The old view to reuse, if possible. Note: You should check that this view
92     *        is non-null and of an appropriate type before using. If it is not possible to convert
93     *        this view to display the correct data, this method can create a new view.
94     * @param parent The parent that this view will eventually be attached to
95     * @return A View corresponding to the data at the specified position.
96     */
97    View getView(int position, View convertView, ViewGroup parent);
98
99    /**
100     * An item view type that causes the {@link AdapterView} to ignore the item
101     * view. For example, this can be used if the client does not want a
102     * particular view to be given for conversion in
103     * {@link #getView(int, View, ViewGroup)}.
104     *
105     * @see #getItemViewType(int)
106     * @see #getViewTypeCount()
107     */
108    static final int IGNORE_ITEM_VIEW_TYPE = AdapterView.ITEM_VIEW_TYPE_IGNORE;
109
110    /**
111     * Get the type of View that will be created by {@link #getView} for the specified item.
112     *
113     * @param position The position of the item within the adapter's data set whose view type we
114     *        want.
115     * @return An integer representing the type of View. Two views should share the same type if one
116     *         can be converted to the other in {@link #getView}. Note: Integers must be in the
117     *         range 0 to {@link #getViewTypeCount} - 1. {@link #IGNORE_ITEM_VIEW_TYPE} can
118     *         also be returned.
119     * @see IGNORE_ITEM_VIEW_TYPE
120     */
121    int getItemViewType(int position);
122
123    /**
124     * <p>
125     * Returns the number of types of Views that will be created by
126     * {@link #getView}. Each type represents a set of views that can be
127     * converted in {@link #getView}. If the adapter always returns the same
128     * type of View for all items, this method should return 1.
129     * </p>
130     * <p>
131     * This method will only be called when when the adapter is set on the
132     * the {@link AdapterView}.
133     * </p>
134     *
135     * @return The number of types of Views that will be created by this adapter
136     */
137    int getViewTypeCount();
138
139    static final int NO_SELECTION = Integer.MIN_VALUE;
140
141     /**
142      * @return true if this adapter doesn't contain any data.  This is used to determine
143      * whether the empty view should be displayed.  A typical implementation will return
144      * getCount() == 0 but since getCount() includes the headers and footers, specialized
145      * adapters might want a different behavior.
146      */
147     boolean isEmpty();
148}
149
150