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