ItemHierarchy.java revision ab45bdf67a01ba13efb45334cc43f9632de6f034 
1/*
2 * Copyright (C) 2015 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 com.android.setupwizardlib.items;
18
19/**
20 * Representation of zero or more items in a list. Each instance of ItemHierarchy should be capable
21 * of being wrapped in ItemAdapter and be displayed.
22 *
23 * For example, {@link com.android.setupwizardlib.items.Item} is a representation of a single item,
24 * typically with data provided from XML. {@link com.android.setupwizardlib.items.ItemGroup}
25 * represents a list of child item hierarchies it contains, but itself does not do any display.
26 */
27public interface ItemHierarchy {
28
29    /**
30     * Observer for any changes in this hierarchy. If anything updated that causes this hierarchy to
31     * show different content, this observer should be called.
32     */
33    interface Observer {
34        /**
35         * Called when an underlying data update that can cause this hierarchy to show different
36         * content has occurred.
37         *
38         * <p>Note: This is a catch-all notification, but recycler view will have a harder time
39         * figuring out the animations for the change, and might even not animate the change at all.
40         */
41        void onChanged(ItemHierarchy itemHierarchy);
42
43        /**
44         * Called when an underlying data update that can cause changes that are local to the given
45         * items. This method indicates that there are no structural changes like inserting or
46         * removing items.
47         */
48        void onItemRangeChanged(ItemHierarchy itemHierarchy, int positionStart, int itemCount);
49
50        /**
51         * Called when items are inserted at the given position.
52         */
53        void onItemRangeInserted(ItemHierarchy itemHierarchy, int positionStart, int itemCount);
54
55        /**
56         * Called when the given items are moved to a different position.
57         */
58        void onItemRangeMoved(ItemHierarchy itemHierarchy, int fromPosition, int toPosition,
59                int itemCount);
60
61        /**
62         * Called when the given items are removed from the item hierarchy.
63         */
64        void onItemRangeRemoved(ItemHierarchy itemHierarchy, int positionStart, int itemCount);
65    }
66
67    /**
68     * Register an observer to observe changes for this item hierarchy.
69     */
70    void registerObserver(Observer observer);
71
72    /**
73     * Unregister a previously registered observer.
74     */
75    void unregisterObserver(Observer observer);
76
77    /**
78     * @return the number of items this item hierarchy represent.
79     */
80    int getCount();
81
82    /**
83     * Get the item at position.
84     *
85     * @param position An integer from 0 to {@link #getCount()}}, which indicates the position in
86     *                 this item hierarchy to get the child item.
87     * @return A representation of the item at {@code position}. Must not be {@code null}.
88     */
89    IItem getItemAt(int position);
90
91    /**
92     * Find an item hierarchy within this hierarchy which has the given ID. Or null if no match is
93     * found. This hierarchy will be returned if our ID matches. Same restrictions for Android
94     * resource IDs apply to this ID. In fact, typically this ID is a resource ID generated from
95     * XML.
96     *
97     * @param id An ID to search for in this item hierarchy.
98     * @return An ItemHierarchy which matches the given ID.
99     */
100    ItemHierarchy findItemById(int id);
101}
102