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 
17 package androidx.compose.ui.text.font
18 
19 /**
20  * Font loading strategy for a [Font] in a [FontListFontFamily].
21  *
22  * This controls how font loading resolves when displaying text in Compose.
23  *
24  * For more information about font family resolution see [FontFamily].
25  */
26 @kotlin.jvm.JvmInline
27 value class FontLoadingStrategy private constructor(val value: Int) {
toStringnull28     override fun toString(): String {
29         return when (this) {
30             Blocking -> "Blocking"
31             OptionalLocal -> "Optional"
32             Async -> "Async"
33             else -> "Invalid(value=$value)"
34         }
35     }
36 
37     companion object {
38         /**
39          * Resolving this font will always block until the font loads.
40          *
41          * This means that the first frame that uses this font will always display using the desired
42          * font, and text will never reflow.
43          *
44          * This should typically be used for fonts that stored on-device. It is acceptable to block
45          * the first frame of an application to read a font from disk.
46          *
47          * This should typically not be used for fonts that are fetched from a remote source such as
48          * over http, as it will block all rendering until the font loads. Instead use [Async].
49          */
50         val Blocking = FontLoadingStrategy(0)
51 
52         /**
53          * Resolving this font is best-effort and will attempt to load from a local resource that
54          * MAY be available.
55          *
56          * Resolving this font will always block until the font resolves, and text will never
57          * reflow.
58          *
59          * An [OptionalLocal] font describes a font that is installed locally, such as an optional
60          * system installed font. Resolution of an [OptionalLocal] font is expected to fail whenever
61          * the resource is not available, which will fallback to the next font in the [FontFamily].
62          *
63          * Typical usages involve following the [OptionalLocal] font with the same font loaded from
64          * a remote [Async] source. It may also be followed by other [OptionalLocal] fonts or
65          * [Blocking] fonts that have less specific styling to avoid async delay.
66          *
67          * Apps should expect that [OptionalLocal] fonts will fail to load on devices where the font
68          * is not available.
69          * *
70          * This should typically not be used for fonts that are fetched from a remote source such as
71          * over http, as it will block all rendering until the font loads. Instead use [Async].
72          */
73         val OptionalLocal = FontLoadingStrategy(1)
74 
75         /**
76          * Loading this font will never block, and will load on a background thread.
77          *
78          * During loading, the app will not block but instead will find the next available font that
79          * is immediately available ([Blocking] or [OptionalLocal]). When the font finishes loading,
80          * text will reflow with the resolved typeface.
81          *
82          * If no fallback fonts are available immediately, the platform default typeface will be
83          * used to draw text during loading.
84          *
85          * If loading fails, the failure is stored permanently, and future uses of the font will
86          * always use the fallback.
87          *
88          * This should typically not be used for fonts that are stored on-device and needed for the
89          * first frame. Instead use [Blocking] or [OptionalLocal].
90          *
91          * This should always be used for fonts that are fetched from a remote source such as over
92          * http.
93          */
94         val Async = FontLoadingStrategy(2)
95     }
96 }
97