1 /*
2  * Copyright 2024 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 @file:JvmName("ComposeRuntimeFlags")
17 
18 package androidx.compose.ui
19 
20 import kotlin.jvm.JvmField
21 import kotlin.jvm.JvmName
22 
23 /**
24  * This is a collection of flags which are used to guard against regressions in some of the
25  * "riskier" refactors or new feature support that is added to this module. These flags are always
26  * "on" in the published artifact of this module, however these flags allow end consumers of this
27  * module to toggle them "off" in case this new path is causing a regression.
28  *
29  * These flags are considered temporary, and there should be no expectation for these flags be
30  * around for an extended period of time. If you have a regression that one of these flags fixes, it
31  * is strongly encouraged for you to file a bug ASAP.
32  *
33  * **Usage:**
34  *
35  * In order to turn a feature off in a debug environment, it is recommended to set this to false in
36  * as close to the initial loading of the application as possible. Changing this value after compose
37  * library code has already been loaded can result in undefined behavior.
38  *
39  *      class MyApplication : Application() {
40  *          override fun onCreate() {
41  *              ComposeUiFlags.SomeFeatureEnabled = false
42  *              super.onCreate()
43  *          }
44  *      }
45  *
46  * In order to turn this off in a release environment, it is recommended to additionally utilize R8
47  * rules which force a single value for the entire build artifact. This can result in the new code
48  * paths being completely removed from the artifact, which can often have nontrivial positive
49  * performance impact.
50  *
51  *      -assumevalues class androidx.compose.runtime.ComposeUiFlags {
52  *          public static int isRectTrackingEnabled return false
53  *      }
54  */
55 @ExperimentalComposeUiApi
56 object ComposeUiFlags {
57     /**
58      * With this flag on, during layout we will do some additional work to store the minimum
59      * bounding rectangles for all Layout Nodes. This introduces some additional maintenance burden,
60      * but will be used in the future to enable certain features that are not possible to do
61      * efficiently at this point, as well as speed up some other areas of the system such as
62      * semantics, focus, pointer input, etc. If significant performance overhead is noticed during
63      * layout phases, it is possible that the addition of this tracking is the culprit.
64      */
65     @Suppress("MutableBareField") @JvmField var isRectTrackingEnabled: Boolean = true
66 
67     /**
68      * With this flag on, the new semantic version of Autofill APIs will be enabled. Turning this
69      * flag off will disable the new Semantic Autofill APIs, and the new refactored semantics.
70      */
71     @Suppress("MutableBareField") @JvmField var isSemanticAutofillEnabled: Boolean = true
72 
73     /**
74      * This enables fixes for View focus. The changes are large enough to require a flag to allow
75      * disabling them.
76      */
77     @Suppress("MutableBareField") @JvmField var isViewFocusFixEnabled: Boolean = false
78 
79     /**
80      * When an embedded view that is focused is removed from the hierarchy, it triggers a
81      * requestFocus() which tries to re-assign focus before the previous composition is complete.
82      * This flag enables a fix for this issue.
83      */
84     @Suppress("MutableBareField") @JvmField var isRemoveFocusedViewFixEnabled: Boolean = false
85 
86     /**
87      * With this flag on, the new focus state management implementation is enabled. The new
88      * implementation removes the focus state previously stored in each FocusTargetNode and instead
89      * keeps track of the current active focus node centrally in FocusOwnerImpl. This change reduces
90      * the cost of initializing the focus system.
91      */
92     @Suppress("MutableBareField") @JvmField var isTrackFocusEnabled: Boolean = true
93 
94     /**
95      * With this flag on, when an AccessibilityService performs ACTION_FOCUS on a Composable node,
96      * if it is in touch mode, it will exit touch mode first, then try to request focus on the node.
97      */
98     @Suppress("MutableBareField") @JvmField var isFocusActionExitsTouchModeEnabled: Boolean = true
99 
100     /**
101      * With this flag on, Modifier.focusRestorer() will not pin the item that needs to be restored.
102      * Users are responsible for providing a key for the item that needs to be restored b/330696779.
103      */
104     @Suppress("MutableBareField") @JvmField var isNoPinningInFocusRestorationEnabled: Boolean = true
105 
106     /*
107      * Enable lower-level logging of input events where a cancellation event does not stop input
108      * events from finishing processing before the cancellation event. This is to track down why a
109      * certain build of CI is failing with this functionality enabled: b/399055247
110      */
111     @Suppress("MutableBareField") @JvmField var isHitPathTrackerLoggingEnabled: Boolean = false
112 
113     /**
114      * With this flag on, SubcomposeLayout will deactivate not used content slots outside of the
115      * frame, not as part of a regular recomposition phase. It allows to not block the drawing
116      * phase, improving the scrolling performance for lazy layouts.
117      */
118     @Suppress("MutableBareField") @JvmField var isOutOfFrameDeactivationEnabled: Boolean = true
119 
120     /** Enable clearing focus when a focused item is removed from a lazyList. */
121     @Suppress("MutableBareField") @JvmField var isClearFocusOnResetEnabled: Boolean = true
122 
123     /**
124      * With this flag on, the adaptive refresh rate (ARR) feature will be enabled. A preferred frame
125      * rate can be set on a Composable through frame rate modifier:
126      * Modifier.requestedFrameRate(frameRate: Float)
127      */
128     @Suppress("MutableBareField") @JvmField var isAdaptiveRefreshRateEnabled: Boolean = true
129 }
130