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