ItemAlignmentFacet.java revision 08c56822b71ab0aa0b9bb03e5fd45e28f6e358b8 
1/*
2 * Copyright (C) 2015 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except
5 * in compliance with the License. You may obtain a copy of the License at
6 *
7 * http://www.apache.org/licenses/LICENSE-2.0
8 *
9 * Unless required by applicable law or agreed to in writing, software distributed under the License
10 * is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express
11 * or implied. See the License for the specific language governing permissions and limitations under
12 * the License.
13 */
14package android.support.v17.leanback.widget;
15
16import android.view.View;
17
18import static android.support.v17.leanback.widget.BaseGridView.ITEM_ALIGN_OFFSET_PERCENT_DISABLED;
19
20import android.support.v7.widget.RecyclerView;
21
22/**
23 * Optional facet provided by {@link RecyclerView.Adapter} or {@link RecyclerView.ViewHolder} for
24 * use in {@link HorizontalGridView} and {@link VerticalGridView}. Apps using {@link Presenter} may
25 * set facet using {@link Presenter#setFacet(Class, Object)} or
26 * {@link Presenter.ViewHolder#setFacet(Class, Object)}. Facet on ViewHolder has a higher priority
27 * than Presenter or Adapter.
28 * <p>
29 * ItemAlignmentFacet contains single or multiple {@link ItemAlignmentDef}s. First
30 * {@link ItemAlignmentDef} describes the default alignment position for ViewHolder, it also
31 * overrides the default item alignment settings on {@link VerticalGridView} and
32 * {@link HorizontalGridView}. When there are multiple {@link ItemAlignmentDef}s, the extra
33 * {@link ItemAlignmentDef}s are used to calculate deltas from first alignment position. When a
34 * descendant view is focused within the ViewHolder, grid view will visit focused view and its
35 * ancestors till the root of ViewHolder to match extra {@link ItemAlignmentDef}s'
36 * {@link ItemAlignmentDef#getItemAlignmentViewId()}. Once a match found, the
37 * {@link ItemAlignmentDef} is used to adjust a scroll delta from default alignment position.
38 */
39public final class ItemAlignmentFacet {
40
41    /**
42     * Value indicates that percent is not used.
43     */
44    public final static float ITEM_ALIGN_OFFSET_PERCENT_DISABLED = -1;
45
46    /**
47     * Definition of an alignment position under a view.
48     */
49    public static class ItemAlignmentDef {
50        int mViewId = View.NO_ID;
51        int mOffset = 0;
52        float mOffsetPercent = 50f;
53        boolean mOffsetWithPadding = false;
54
55        /**
56         * Sets number of pixels to offset. Can be negative for alignment from the high edge, or
57         * positive for alignment from the low edge.
58         */
59        public final void setItemAlignmentOffset(int offset) {
60            mOffset = offset;
61        }
62
63        /**
64         * Gets number of pixels to offset. Can be negative for alignment from the high edge, or
65         * positive for alignment from the low edge.
66         */
67        public final int getItemAlignmentOffset() {
68            return mOffset;
69        }
70
71        /**
72         * Sets whether to include left/top padding for positive item offset, include
73         * right/bottom padding for negative item offset.
74         */
75        public final void setItemAlignmentOffsetWithPadding(boolean withPadding) {
76            mOffsetWithPadding = withPadding;
77        }
78
79        /**
80         * When it is true: we include left/top padding for positive item offset, include
81         * right/bottom padding for negative item offset.
82         */
83        public final boolean isItemAlignmentOffsetWithPadding() {
84            return mOffsetWithPadding;
85        }
86
87        /**
88         * Sets the offset percent for item alignment in addition to offset.  E.g., 40
89         * means 40% of the width from the low edge. Use {@link #ITEM_ALIGN_OFFSET_PERCENT_DISABLED}
90         * to disable.
91         */
92        public final void setItemAlignmentOffsetPercent(float percent) {
93            if ( (percent < 0 || percent > 100) &&
94                    percent != ITEM_ALIGN_OFFSET_PERCENT_DISABLED) {
95                throw new IllegalArgumentException();
96            }
97            mOffsetPercent = percent;
98        }
99
100        /**
101         * Gets the offset percent for item alignment in addition to offset. E.g., 40
102         * means 40% of the width from the low edge. Use {@link #ITEM_ALIGN_OFFSET_PERCENT_DISABLED}
103         * to disable.
104         */
105        public final float getItemAlignmentOffsetPercent() {
106            return mOffsetPercent;
107        }
108
109        /**
110         * Sets Id of which child view to be aligned.  View.NO_ID refers to root view and should
111         * be only used in first one.  Extra ItemAlignmentDefs should provide view id to match
112         * currently focused view.
113         */
114        public final void setItemAlignmentViewId(int viewId) {
115            mViewId = viewId;
116        }
117
118        /**
119         * Gets Id of which child view to be aligned.  View.NO_ID refers to root view and should
120         * be only used in first one.  Extra ItemAlignmentDefs should provide view id to match
121         * currently focused view.
122         */
123        public final int getItemAlignmentViewId() {
124            return mViewId;
125        }
126
127    }
128
129    private ItemAlignmentDef[] mAlignmentDefs = new ItemAlignmentDef[]{new ItemAlignmentDef()};
130
131    public boolean isMultiAlignment() {
132        return mAlignmentDefs.length > 1;
133    }
134
135    /**
136     * Sets definitions of alignment positions.
137     */
138    public void setAlignmentDefs(ItemAlignmentDef[] defs) {
139        if (defs == null || defs.length < 1) {
140            throw new IllegalArgumentException();
141        }
142        mAlignmentDefs = defs;
143    }
144
145    /**
146     * Returns read only definitions of alignment positions.
147     */
148    public ItemAlignmentDef[] getAlignmentDefs() {
149        return mAlignmentDefs;
150    }
151
152}
153