1/*
2 * Copyright (C) 2017 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
17package androidx.core.widget;
18
19import static androidx.annotation.RestrictTo.Scope.LIBRARY_GROUP;
20
21import android.os.Build;
22import android.util.TypedValue;
23
24import androidx.annotation.NonNull;
25import androidx.annotation.RestrictTo;
26
27/**
28 * Interface which allows a {@link android.widget.TextView} to receive background auto-sizing calls
29 * from {@link TextViewCompat} when running on API v26 devices or lower.
30 *
31 * @hide Internal use only
32 */
33@RestrictTo(LIBRARY_GROUP)
34public interface AutoSizeableTextView {
35    /**
36     * @hide
37     */
38    @RestrictTo(LIBRARY_GROUP)
39    boolean PLATFORM_SUPPORTS_AUTOSIZE = Build.VERSION.SDK_INT >= 27;
40
41    /**
42     * Specify whether this widget should automatically scale the text to try to perfectly fit
43     * within the layout bounds by using the default auto-size configuration.
44     *
45     * @param autoSizeTextType the type of auto-size. Must be one of
46     *        {@link TextViewCompat#AUTO_SIZE_TEXT_TYPE_NONE} or
47     *        {@link TextViewCompat#AUTO_SIZE_TEXT_TYPE_UNIFORM}
48     *
49     * @see #getAutoSizeTextType()
50     */
51    void setAutoSizeTextTypeWithDefaults(@TextViewCompat.AutoSizeTextType int autoSizeTextType);
52
53    /**
54     * Specify whether this widget should automatically scale the text to try to perfectly fit
55     * within the layout bounds. If all the configuration params are valid the type of auto-size is
56     * set to {@link TextViewCompat#AUTO_SIZE_TEXT_TYPE_UNIFORM}.
57     *
58     * @param autoSizeMinTextSize the minimum text size available for auto-size
59     * @param autoSizeMaxTextSize the maximum text size available for auto-size
60     * @param autoSizeStepGranularity the auto-size step granularity. It is used in conjunction with
61     *                                the minimum and maximum text size in order to build the set of
62     *                                text sizes the system uses to choose from when auto-sizing
63     * @param unit the desired dimension unit for all sizes above. See {@link TypedValue} for the
64     *             possible dimension units
65     *
66     * @throws IllegalArgumentException if any of the configuration params are invalid.
67     *
68     * @see #setAutoSizeTextTypeWithDefaults(int)
69     * @see #setAutoSizeTextTypeUniformWithPresetSizes(int[], int)
70     * @see #getAutoSizeMinTextSize()
71     * @see #getAutoSizeMaxTextSize()
72     * @see #getAutoSizeStepGranularity()
73     * @see #getAutoSizeTextAvailableSizes()
74     */
75    void setAutoSizeTextTypeUniformWithConfiguration(
76            int autoSizeMinTextSize,
77            int autoSizeMaxTextSize,
78            int autoSizeStepGranularity,
79            int unit) throws IllegalArgumentException;
80
81    /**
82     * Specify whether this widget should automatically scale the text to try to perfectly fit
83     * within the layout bounds. If at least one value from the <code>presetSizes</code> is valid
84     * then the type of auto-size is set to {@link TextViewCompat#AUTO_SIZE_TEXT_TYPE_UNIFORM}.
85     *
86     * @param presetSizes an {@code int} array of sizes in pixels
87     * @param unit the desired dimension unit for the preset sizes above. See {@link TypedValue} for
88     *             the possible dimension units
89     *
90     * @throws IllegalArgumentException if all of the <code>presetSizes</code> are invalid.
91     *_
92     * @see #setAutoSizeTextTypeWithDefaults(int)
93     * @see #setAutoSizeTextTypeUniformWithConfiguration(int, int, int, int)
94     * @see #getAutoSizeMinTextSize()
95     * @see #getAutoSizeMaxTextSize()
96     * @see #getAutoSizeTextAvailableSizes()
97     */
98    void setAutoSizeTextTypeUniformWithPresetSizes(@NonNull int[] presetSizes, int unit)
99            throws IllegalArgumentException;
100
101    /**
102     * Returns the type of auto-size set for this widget.
103     *
104     * @return an {@code int} corresponding to one of the auto-size types:
105     *         {@link TextViewCompat#AUTO_SIZE_TEXT_TYPE_NONE} or
106     *         {@link TextViewCompat#AUTO_SIZE_TEXT_TYPE_UNIFORM}
107     *
108     * @see #setAutoSizeTextTypeWithDefaults(int)
109     * @see #setAutoSizeTextTypeUniformWithConfiguration(int, int, int, int)
110     * @see #setAutoSizeTextTypeUniformWithPresetSizes(int[], int)
111     */
112    @TextViewCompat.AutoSizeTextType
113    int getAutoSizeTextType();
114
115    /**
116     * @return the current auto-size step granularity in pixels.
117     *
118     * @see #setAutoSizeTextTypeUniformWithConfiguration(int, int, int, int)
119     */
120    int getAutoSizeStepGranularity();
121
122    /**
123     * @return the current auto-size minimum text size in pixels (the default is 12sp). Note that
124     *         if auto-size has not been configured this function returns {@code -1}.
125     *
126     * @see #setAutoSizeTextTypeUniformWithConfiguration(int, int, int, int)
127     * @see #setAutoSizeTextTypeUniformWithPresetSizes(int[], int)
128     */
129    int getAutoSizeMinTextSize();
130
131    /**
132     * @return the current auto-size maximum text size in pixels (the default is 112sp). Note that
133     *         if auto-size has not been configured this function returns {@code -1}.
134     *
135     * @see #setAutoSizeTextTypeUniformWithConfiguration(int, int, int, int)
136     * @see #setAutoSizeTextTypeUniformWithPresetSizes(int[], int)
137     */
138    int getAutoSizeMaxTextSize();
139
140    /**
141     * @return the current auto-size {@code int} sizes array (in pixels).
142     *
143     * @see #setAutoSizeTextTypeUniformWithConfiguration(int, int, int, int)
144     * @see #setAutoSizeTextTypeUniformWithPresetSizes(int[], int)
145     */
146    int[] getAutoSizeTextAvailableSizes();
147}
148