1 /* 2 * Copyright (C) 2021 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.car.ui.recyclerview; 18 19 import static java.lang.annotation.RetentionPolicy.SOURCE; 20 21 import android.content.Context; 22 import android.util.AttributeSet; 23 import android.view.View; 24 25 import androidx.annotation.IntDef; 26 import androidx.annotation.NonNull; 27 import androidx.annotation.Nullable; 28 import androidx.recyclerview.widget.RecyclerView; 29 30 import com.android.car.ui.sharedlibrarysupport.SharedLibraryFactorySingleton; 31 32 import java.lang.annotation.Retention; 33 34 /** 35 * A class to access the {@link CarUiRecyclerView} methods. The appearance and layout is 36 * customizable by OEM. 37 * <p> 38 * This is the base class for CarUiRecyclerView implementation. 39 */ 40 public abstract class CarUiRecyclerView extends RecyclerView { 41 42 /** 43 * Use this method to create an instance of CarUiRecyclerView at runtime. 44 */ create(Context context)45 public static CarUiRecyclerView create(Context context) { 46 return SharedLibraryFactorySingleton.get(context) 47 .createRecyclerView(context, null); 48 } 49 50 /** 51 * Use this method to create an instance of CarUiRecyclerView at runtime. 52 */ create(Context context, AttributeSet attributeSet)53 public static CarUiRecyclerView create(Context context, AttributeSet attributeSet) { 54 return SharedLibraryFactorySingleton.get(context) 55 .createRecyclerView(context, attributeSet); 56 } 57 58 /** 59 * Describes the expected relative size of the {@link CarUiRecyclerView}. The list may be 60 * rendered differently for each expected size. 61 */ 62 @Retention(SOURCE) 63 @IntDef({SIZE_SMALL, SIZE_MEDIUM, SIZE_LARGE}) 64 public @interface Size {} 65 public static final int SIZE_SMALL = 0; 66 public static final int SIZE_MEDIUM = 1; 67 public static final int SIZE_LARGE = 2; 68 69 /** 70 * The possible values for setScrollBarPosition. The default value is {@link 71 * CarUiRecyclerViewLayout#LINEAR}. 72 */ 73 @IntDef({ 74 CarUiRecyclerViewLayout.LINEAR, 75 CarUiRecyclerViewLayout.GRID, 76 }) 77 @Retention(SOURCE) 78 public @interface CarUiRecyclerViewLayout { 79 /** 80 * Arranges items either horizontally in a single row or vertically in a single column. This 81 * is default. 82 */ 83 int LINEAR = 0; 84 85 /** 86 * Arranges items in a Grid. 87 */ 88 int GRID = 1; 89 } 90 91 /** 92 * Interface for a {@link RecyclerView.Adapter} to cap the number of items. 93 * 94 * <p>NOTE: it is still up to the adapter to use maxItems in {@link 95 * RecyclerView.Adapter#getItemCount()}. 96 * 97 * <p>the recommended way would be with: 98 * 99 * <pre>{@code 100 * {@literal@}Override 101 * public int getItemCount() { 102 * return Math.min(super.getItemCount(), mMaxItems); 103 * } 104 * }</pre> 105 */ 106 public interface ItemCap { 107 108 /** 109 * A value to pass to {@link #setMaxItems(int)} that indicates there should be no limit. 110 */ 111 int UNLIMITED = -1; 112 113 /** 114 * Sets the maximum number of items available in the adapter. A value less than '0' means 115 * the list should not be capped. 116 */ setMaxItems(int maxItems)117 void setMaxItems(int maxItems); 118 } 119 CarUiRecyclerView(Context context)120 public CarUiRecyclerView(Context context) { 121 super(context); 122 } 123 CarUiRecyclerView(Context context, AttributeSet attrs)124 public CarUiRecyclerView(Context context, AttributeSet attrs) { 125 super(context, attrs); 126 } 127 CarUiRecyclerView(Context context, AttributeSet attrs, int defStyleAttr)128 public CarUiRecyclerView(Context context, AttributeSet attrs, int defStyleAttr) { 129 super(context, attrs, defStyleAttr); 130 } 131 132 /** 133 * Return's the container which contains the scrollbar and this RecyclerView. 134 */ getContainer()135 public abstract View getContainer(); 136 137 /** 138 * Set the {@link LayoutManager} that this RecyclerView will use. 139 * 140 * <p>In contrast to other adapter-backed views such as {@link android.widget.ListView} 141 * or {@link android.widget.GridView}, RecyclerView allows client code to provide custom layout 142 * arrangements for child views. These arrangements are controlled by the {@link LayoutManager}. 143 * A LayoutManager must be provided for RecyclerView to function.</p> 144 * 145 * <p>Several default strategies are provided for common uses such as lists and grids.</p> 146 * 147 * @param layoutManager LayoutManager to use 148 * @deprecated to be implemented by OEM 149 */ 150 @Deprecated 151 @Override setLayoutManager(@ullable LayoutManager layoutManager)152 public void setLayoutManager(@Nullable LayoutManager layoutManager) { 153 super.setLayoutManager(layoutManager); 154 } 155 156 /** 157 * Return the {@link LayoutManager} currently responsible for 158 * layout policy for this RecyclerView. 159 * 160 * @return The currently bound LayoutManager 161 * @deprecated will return null for OEM implementation. 162 */ 163 @Deprecated 164 @Nullable 165 @Override getLayoutManager()166 public LayoutManager getLayoutManager() { 167 return super.getLayoutManager(); 168 } 169 170 /** 171 * Add an {@link ItemDecoration} to this RecyclerView. Item decorations can affect both 172 * measurement and drawing of individual item views. 173 * 174 * <p>Item decorations are ordered. Decorations placed earlier in the list will 175 * be run/queried/drawn first for their effects on item views. Padding added to views will be 176 * nested; a padding added by an earlier decoration will mean further item decorations in the 177 * list will be asked to draw/pad within the previous decoration's given area.</p> 178 * 179 * @param decor Decoration to add 180 * @deprecated to be implemented by OEMs 181 */ 182 @Deprecated 183 @Override addItemDecoration(@onNull ItemDecoration decor)184 public void addItemDecoration(@NonNull ItemDecoration decor) { 185 super.addItemDecoration(decor); 186 } 187 188 /** 189 * Add an {@link ItemDecoration} to this RecyclerView. Item decorations can affect both 190 * measurement and drawing of individual item views. 191 * 192 * <p>Item decorations are ordered. Decorations placed earlier in the list will 193 * be run/queried/drawn first for their effects on item views. Padding added to views will be 194 * nested; a padding added by an earlier decoration will mean further item decorations in the 195 * list will be asked to draw/pad within the previous decoration's given area.</p> 196 * 197 * @param decor Decoration to add 198 * @param index Position in the decoration chain to insert this decoration at. If this value is 199 * negative the decoration will be added at the end. 200 * @deprecated to be implemented by OEM 201 */ 202 @Deprecated 203 @Override addItemDecoration(@onNull ItemDecoration decor, int index)204 public void addItemDecoration(@NonNull ItemDecoration decor, int index) { 205 super.addItemDecoration(decor, index); 206 } 207 208 /** 209 * Returns an {@link ItemDecoration} previously added to this RecyclerView. 210 * 211 * @param index The index position of the desired ItemDecoration. 212 * @return the ItemDecoration at index position 213 * @throws IndexOutOfBoundsException on invalid index 214 * @deprecated to be handled by OEM 215 */ 216 @Deprecated 217 @Override 218 @NonNull getItemDecorationAt(int index)219 public ItemDecoration getItemDecorationAt(int index) { 220 return super.getItemDecorationAt(index); 221 } 222 223 /** 224 * Returns the number of {@link ItemDecoration} currently added to this RecyclerView. 225 * 226 * @return number of ItemDecorations currently added added to this RecyclerView. 227 * @deprecated to be handled by OEM 228 */ 229 @Deprecated 230 @Override getItemDecorationCount()231 public int getItemDecorationCount() { 232 return super.getItemDecorationCount(); 233 } 234 235 /** 236 * Removes the {@link ItemDecoration} associated with the supplied index position. 237 * 238 * @param index The index position of the ItemDecoration to be removed. 239 * @deprecated to be handled by OEM 240 */ 241 @Deprecated 242 @Override removeItemDecorationAt(int index)243 public void removeItemDecorationAt(int index) { 244 super.removeItemDecorationAt(index); 245 } 246 247 /** 248 * Remove an {@link ItemDecoration} from this RecyclerView. 249 * 250 * <p>The given decoration will no longer impact the measurement and drawing of 251 * item views.</p> 252 * 253 * @param decor Decoration to remove 254 * @see #addItemDecoration(ItemDecoration) 255 * @deprecated to be handled by OEM 256 */ 257 @Deprecated 258 @Override removeItemDecoration(@onNull ItemDecoration decor)259 public void removeItemDecoration(@NonNull ItemDecoration decor) { 260 super.removeItemDecoration(decor); 261 } 262 263 /** 264 * @deprecated this will return incorrect value when there is a oem implementation 265 */ 266 @Override 267 @Deprecated getChildCount()268 public int getChildCount() { 269 return super.getChildCount(); 270 } 271 272 /** 273 * @deprecated this will return incorrect value when there is a oem implementation 274 */ 275 @Deprecated 276 @Override getChildAt(int index)277 public View getChildAt(int index) { 278 return super.getChildAt(index); 279 } 280 281 /** 282 * Use this instead of setLayoutManager 283 * @param layoutStyle 284 */ setLayoutStyle(CarUiLayoutStyle layoutStyle)285 public abstract void setLayoutStyle(CarUiLayoutStyle layoutStyle); 286 } 287