1 /*
2  * Copyright 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 package androidx.leanback.widget;
17 
18 import org.jspecify.annotations.NonNull;
19 import org.jspecify.annotations.Nullable;
20 
21 /**
22  * This is the query interface to supply optional features(aka facets) on an object without the need
23  * of letting the object to subclass or implement java interfaces. Facets allow leanback to
24  * re-compose optional features from leanback ViewHolder to RecyclerView ViewHolder. A typical
25  * "facet" class is {@link ItemAlignmentFacet} that defines how to align a ViewHolder inside
26  * VerticalGridView or HorizontalGridView.
27  * A FacetProvider could be retrieved from two sources by VerticalGridView/HorizontalGridView in
28  * the following order.
29  * <ul>
30  * <li>
31  *     <p>
32  *     ViewHolder based facet:
33  *     </p>
34  *     <p>
35  *     RecyclerView.ViewHolder can implement FacetProvider. If app uses leanback
36  *     Presenter.ViewHolder, the facet of Presenter.ViewHolder will be relayed by
37  *     ItemBridgeAdapter.ViewHolder which is a wrapper of Presenter.ViewHolder.
38  *     ViewHolder based facet is used less frequently than item view type based facet because
39  *     in most cases ViewHolders of same type share the same alignment definition.
40  *     </p>
41  *     <p>
42  *     For example, app calls viewHolder.setFacet(ItemAlignmentFacet.class, itemAlignmentFacet) to
43  *     set alignment of the ViewHolder instance.
44  *     </p>
45  * </li>
46  * <li>
47  *     <p>
48  *     RecyclerView item view type based facet:
49  *     </p>
50  *     <p>
51  *     RecyclerView.Adapter can implement {@link FacetProviderAdapter} which returns FacetProvider
52  *     for each item view type. If app uses leanback ObjectAdapter and Presenter, app wraps
53  *     the ObjectAdapter and Presenter using {@link ItemBridgeAdapter}.  The implementation of
54  *     {@link ItemBridgeAdapter#getFacetProvider(int)} will return the FacetProvider implemented
55  *     by {@link Presenter} which is mapped to the item view type.
56  *     </p>
57  *     <p>
58  *     For example, app calls presenter.setFacet(ItemAlignmentFacet.class, itemAlignmentFacet) to
59  *     set alignment of all ViewHolders created by this Presenter.
60  *     </p>
61  * </li>
62  * </ul>
63  */
64 public interface FacetProvider {
65 
66     /**
67      * Queries optional implemented facet.
68      *
69      * @param facetClass Facet classes to query,  examples are: class of
70      *                   {@link ItemAlignmentFacet}.
71      * @return Facet implementation for the facetClass or null if feature not implemented.
72      */
getFacet(@onNull Class<?> facetClass)73     @Nullable Object getFacet(@NonNull Class<?> facetClass);
74 }
75