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 17 package 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 * <p>For example, {@link com.android.setupwizardlib.items.Item} is a representation of a single 24 * item, 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 */ 27 public 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 content 36 * has occurred. 37 * 38 * <p>Note: This is a catch-all notification, but recycler view will have a harder time figuring 39 * out the animations for the change, and might even not animate the change at all. 40 */ onChanged(ItemHierarchy itemHierarchy)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 removing 46 * items. 47 */ onItemRangeChanged(ItemHierarchy itemHierarchy, int positionStart, int itemCount)48 void onItemRangeChanged(ItemHierarchy itemHierarchy, int positionStart, int itemCount); 49 50 /** Called when items are inserted at the given position. */ onItemRangeInserted(ItemHierarchy itemHierarchy, int positionStart, int itemCount)51 void onItemRangeInserted(ItemHierarchy itemHierarchy, int positionStart, int itemCount); 52 53 /** Called when the given items are moved to a different position. */ onItemRangeMoved( ItemHierarchy itemHierarchy, int fromPosition, int toPosition, int itemCount)54 void onItemRangeMoved( 55 ItemHierarchy itemHierarchy, int fromPosition, int toPosition, int itemCount); 56 57 /** Called when the given items are removed from the item hierarchy. */ onItemRangeRemoved(ItemHierarchy itemHierarchy, int positionStart, int itemCount)58 void onItemRangeRemoved(ItemHierarchy itemHierarchy, int positionStart, int itemCount); 59 } 60 61 /** Register an observer to observe changes for this item hierarchy. */ registerObserver(Observer observer)62 void registerObserver(Observer observer); 63 64 /** Unregister a previously registered observer. */ unregisterObserver(Observer observer)65 void unregisterObserver(Observer observer); 66 67 /** @return the number of items this item hierarchy represent. */ getCount()68 int getCount(); 69 70 /** 71 * Get the item at position. 72 * 73 * @param position An integer from 0 to {@link #getCount()}}, which indicates the position in this 74 * item hierarchy to get the child item. 75 * @return A representation of the item at {@code position}. Must not be {@code null}. 76 */ getItemAt(int position)77 IItem getItemAt(int position); 78 79 /** 80 * Find an item hierarchy within this hierarchy which has the given ID. Or null if no match is 81 * found. This hierarchy will be returned if our ID matches. Same restrictions for Android 82 * resource IDs apply to this ID. In fact, typically this ID is a resource ID generated from XML. 83 * 84 * @param id An ID to search for in this item hierarchy. 85 * @return An ItemHierarchy which matches the given ID. 86 */ findItemById(int id)87 ItemHierarchy findItemById(int id); 88 } 89