1 /*
2  * Copyright (C) 2023 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 android.content.res;
18 
19 
20 import android.annotation.AnyThread;
21 import android.annotation.FlaggedApi;
22 import android.annotation.Nullable;
23 
24 /**
25  * A converter for non-linear font scaling. Converts font sizes given in "sp" dimensions to a
26  * "dp" dimension according to a non-linear curve.
27  *
28  * <p>This is meant to improve readability at larger font scales: larger fonts will scale up more
29  * slowly than smaller fonts, so we don't get ridiculously huge fonts that don't fit on the screen.
30  *
31  * <p>The thinking here is that large fonts are already big enough to read, but we still want to
32  * scale them slightly to preserve the visual hierarchy when compared to smaller fonts.
33  */
34 @FlaggedApi(Flags.FLAG_FONT_SCALE_CONVERTER_PUBLIC)
35 public interface FontScaleConverter {
36     /**
37      * Converts a dimension in "sp" to "dp".
38      */
convertSpToDp(float sp)39     float convertSpToDp(float sp);
40 
41     /**
42      * Converts a dimension in "dp" back to "sp".
43      */
convertDpToSp(float dp)44     float convertDpToSp(float dp);
45 
46     /**
47      * Returns true if non-linear font scaling curves would be in effect for the given scale, false
48      * if the scaling would follow a linear curve or for no scaling.
49      *
50      * <p>Example usage: {@code
51      * isNonLinearFontScalingActive(getResources().getConfiguration().fontScale)}
52      */
53     @AnyThread
isNonLinearFontScalingActive(float fontScale)54     static boolean isNonLinearFontScalingActive(float fontScale) {
55         return FontScaleConverterFactory.isNonLinearFontScalingActive(fontScale);
56     }
57 
58     /**
59      * Finds a matching FontScaleConverter for the given fontScale factor.
60      *
61      * Generally you shouldn't need this; you can use {@link
62      * android.util.TypedValue#applyDimension(int, float, DisplayMetrics)} directly and it will do
63      * the scaling conversion for you. Dimens and resources loaded from XML will also be
64      * automatically converted. But for UI frameworks or other situations where you need to do the
65      * conversion without an Android Context, you can use this method.
66      *
67      * @param fontScale the scale factor, usually from {@link Configuration#fontScale}.
68      *
69      * @return a converter for the given scale, or null if non-linear scaling should not be used.
70      */
71     @Nullable
72     @AnyThread
forScale(float fontScale)73     static FontScaleConverter forScale(float fontScale) {
74         return FontScaleConverterFactory.forScale(fontScale);
75     }
76 }
77