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        void onChanged(ItemHierarchy itemHierarchy);
39    }
40
41    /**
42     * Register an observer to observe changes for this item hierarchy.
43     */
44    void registerObserver(Observer observer);
45
46    /**
47     * Unregister a previously registered observer.
48     */
49    void unregisterObserver(Observer observer);
50
51    /**
52     * @return the number of items this item hierarchy represent.
53     */
54    int getCount();
55
56    /**
57     * Get the item at position.
58     *
59     * @param position An integer from 0 to {@link #getCount()}}, which indicates the position in
60     *                 this item hierarchy to get the child item.
61     * @return A representation of the item at {@code position}. Must not be {@code null}.
62     */
63    IItem getItemAt(int position);
64
65    /**
66     * Find an item hierarchy within this hierarchy which has the given ID. Or null if no match is
67     * found. This hierarchy will be returned if our ID matches. Same restrictions for Android
68     * resource IDs apply to this ID. In fact, typically this ID is a resource ID generated from
69     * XML.
70     *
71     * @param id An ID to search for in this item hierarchy.
72     * @return An ItemHierarchy which matches the given ID.
73     */
74    ItemHierarchy findItemById(int id);
75}
76