1 /*
2  * Copyright (C) 2020 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.media;
18 
19 
20 /**
21  * Interface for helper objects that hide elements from lists that are too long. The limiting
22  * happens around a pivot element that can be anywhere in the list. Elements near that pivot will
23  * be visible, while elements at the head and / or tail of the list will be replaced by a message
24  * telling the user about the truncation.
25  * When no restrictions are in effect, the {@link #PASS_THROUGH} instance should be used.
26  */
27 public interface UxrPivotFilter {
28 
29     int INVALID_INDEX = -1;
30     int INVALID_POSITION = -1;
31 
32     /**
33      * Computes new restrictions when the list (and optionally) the pivot have changed.
34      * The implementation doesn't send any notification.
35      */
recompute(int newCount, int pivotIndex)36     void recompute(int newCount, int pivotIndex);
37 
38     /**
39      * Computes new restrictions when only the pivot has changed.
40      * The implementation must send notification changes (ideally incremental ones).
41      */
updatePivotIndex(int pivotIndex)42     void updatePivotIndex(int pivotIndex);
43 
44     /** Returns the number of elements in the resulting list, including the message(s). */
getFilteredCount()45     int getFilteredCount();
46 
47     /**
48      * Converts an index in the unfiltered data set to a RV position in the filtered UI in the
49      * 0 .. {@link #getFilteredCount} range which includes the limits message(s).
50      * Returns INVALID_POSITION if that element has been filtered out.
51      */
indexToPosition(int index)52     int indexToPosition(int index);
53 
54     /**
55      * Converts a RV position in the filtered UI to an index in the unfiltered data set.
56      * Returns INVALID_INDEX if a message is shown at that position.
57      */
positionToIndex(int position)58     int positionToIndex(int position);
59 
60     /** Send notification changes for the restriction message(s) if there are any. */
invalidateMessagePositions()61     void invalidateMessagePositions();
62 
63 
64     /**
65      * A trivial implementation that doesn't do any filtering (simplifies the filter's code).
66      */
67     UxrPivotFilter PASS_THROUGH = new UxrPivotFilter() {
68         private int mCount;
69 
70         @Override
71         public void recompute(int newCount, int pivotIndex) {
72             mCount = newCount;
73         }
74 
75         @Override
76         public void updatePivotIndex(int pivotIndex) {
77         }
78 
79         @Override
80         public int getFilteredCount() {
81             return mCount;
82         }
83 
84         @Override
85         public int indexToPosition(int index) {
86             return index;
87         }
88 
89         @Override
90         public int positionToIndex(int position) {
91             return position;
92         }
93 
94         @Override
95         public void invalidateMessagePositions() {
96         }
97     };
98 }
99