1 /* 2 * Copyright (C) 2018 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.view; 18 19 import android.annotation.FlaggedApi; 20 import android.annotation.IntDef; 21 import android.annotation.NonNull; 22 import android.annotation.Nullable; 23 import android.graphics.Insets; 24 import android.inputmethodservice.InputMethodService; 25 import android.os.Build; 26 import android.os.CancellationSignal; 27 import android.view.WindowInsets.Type; 28 import android.view.WindowInsets.Type.InsetsType; 29 import android.view.animation.Interpolator; 30 import android.view.flags.Flags; 31 32 import java.lang.annotation.Retention; 33 import java.lang.annotation.RetentionPolicy; 34 35 /** 36 * Interface to control windows that generate insets. 37 * 38 * For guidance, see <a href="https://developer.android.com/develop/ui/views/layout/immersive"> 39 * Hide system bars for immersive mode</a>. 40 */ 41 public interface WindowInsetsController { 42 43 /** 44 * Makes status bars become opaque with solid dark background and light foreground. 45 * @hide 46 */ 47 int APPEARANCE_OPAQUE_STATUS_BARS = 1; 48 49 /** 50 * Makes navigation bars become opaque with solid dark background and light foreground. 51 * @hide 52 */ 53 int APPEARANCE_OPAQUE_NAVIGATION_BARS = 1 << 1; 54 55 /** 56 * Makes items on system bars become less noticeable without changing the layout of the bars. 57 * @hide 58 */ 59 int APPEARANCE_LOW_PROFILE_BARS = 1 << 2; 60 61 /** 62 * Changes the foreground color for light status bars so that the items on the bar can be read 63 * clearly. 64 */ 65 int APPEARANCE_LIGHT_STATUS_BARS = 1 << 3; 66 67 /** 68 * Changes the foreground color for light navigation bars so that the items on the bar can be 69 * read clearly. 70 */ 71 int APPEARANCE_LIGHT_NAVIGATION_BARS = 1 << 4; 72 73 /** 74 * Makes status bars semi-transparent with dark background and light foreground. 75 * @hide 76 */ 77 int APPEARANCE_SEMI_TRANSPARENT_STATUS_BARS = 1 << 5; 78 79 /** 80 * Makes navigation bars semi-transparent with dark background and light foreground. 81 * @hide 82 */ 83 int APPEARANCE_SEMI_TRANSPARENT_NAVIGATION_BARS = 1 << 6; 84 85 /** 86 * Makes the caption bar transparent. 87 */ 88 @FlaggedApi(Flags.FLAG_CUSTOMIZABLE_WINDOW_HEADERS) 89 int APPEARANCE_TRANSPARENT_CAPTION_BAR_BACKGROUND = 1 << 7; 90 91 /** 92 * When {@link WindowInsetsController#APPEARANCE_TRANSPARENT_CAPTION_BAR_BACKGROUND} is set, 93 * changes the foreground color of the caption bars so that the items on the bar can be read 94 * clearly on light backgrounds. 95 */ 96 @FlaggedApi(Flags.FLAG_CUSTOMIZABLE_WINDOW_HEADERS) 97 int APPEARANCE_LIGHT_CAPTION_BARS = 1 << 8; 98 99 /** 100 * Same as {@link #APPEARANCE_LIGHT_NAVIGATION_BARS} but set by the system. The system will 101 * respect {@link #APPEARANCE_LIGHT_NAVIGATION_BARS} when this is cleared. 102 * @hide 103 */ 104 int APPEARANCE_FORCE_LIGHT_NAVIGATION_BARS = 1 << 9; 105 106 /** 107 * Determines the appearance of system bars. 108 * @hide 109 */ 110 @Retention(RetentionPolicy.SOURCE) 111 @IntDef(flag = true, value = { 112 APPEARANCE_OPAQUE_STATUS_BARS, 113 APPEARANCE_OPAQUE_NAVIGATION_BARS, 114 APPEARANCE_LOW_PROFILE_BARS, 115 APPEARANCE_LIGHT_STATUS_BARS, 116 APPEARANCE_LIGHT_NAVIGATION_BARS, 117 APPEARANCE_SEMI_TRANSPARENT_STATUS_BARS, 118 APPEARANCE_SEMI_TRANSPARENT_NAVIGATION_BARS, 119 APPEARANCE_TRANSPARENT_CAPTION_BAR_BACKGROUND, 120 APPEARANCE_LIGHT_CAPTION_BARS, 121 APPEARANCE_FORCE_LIGHT_NAVIGATION_BARS}) 122 @interface Appearance { 123 } 124 125 /** 126 * Option for {@link #setSystemBarsBehavior(int)}. System bars will be forcibly shown on any 127 * user interaction on the corresponding display if navigation bars are hidden by 128 * {@link #hide(int)} or 129 * {@link WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float)}. 130 * @deprecated This is not supported on Android {@link Build.VERSION_CODES#S} and later. Use 131 * {@link #BEHAVIOR_DEFAULT} or {@link #BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE} 132 * instead. 133 */ 134 @Deprecated 135 int BEHAVIOR_SHOW_BARS_BY_TOUCH = 0; 136 137 /** 138 * The default option for {@link #setSystemBarsBehavior(int)}: Window would like to remain 139 * interactive when hiding navigation bars by calling {@link #hide(int)} or 140 * {@link WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float)}. 141 * 142 * <p>When system bars are hidden in this mode, they can be revealed with system gestures, such 143 * as swiping from the edge of the screen where the bar is hidden from.</p> 144 * 145 * <p>When the gesture navigation is enabled, the system gestures can be triggered regardless 146 * the visibility of system bars.</p> 147 */ 148 int BEHAVIOR_DEFAULT = 1; 149 150 /** 151 * Option for {@link #setSystemBarsBehavior(int)}: Window would like to remain interactive when 152 * hiding navigation bars by calling {@link #hide(int)} or 153 * {@link WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float)}. 154 * 155 * <p>When system bars are hidden in this mode, they can be revealed with system gestures, such 156 * as swiping from the edge of the screen where the bar is hidden from.</p> 157 * @deprecated Use {@link #BEHAVIOR_DEFAULT} instead. 158 */ 159 @Deprecated 160 int BEHAVIOR_SHOW_BARS_BY_SWIPE = BEHAVIOR_DEFAULT; 161 162 /** 163 * Option for {@link #setSystemBarsBehavior(int)}: Window would like to remain interactive when 164 * hiding navigation bars by calling {@link #hide(int)} or 165 * {@link WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float)}. 166 * 167 * <p>When system bars are hidden in this mode, they can be revealed temporarily with system 168 * gestures, such as swiping from the edge of the screen where the bar is hidden from. These 169 * transient system bars will overlay app’s content, may have some degree of transparency, and 170 * will automatically hide after a short timeout.</p> 171 */ 172 int BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE = 2; 173 174 /** 175 * Determines the behavior of system bars when hiding them by calling {@link #hide}. 176 * @hide 177 */ 178 @Retention(RetentionPolicy.SOURCE) 179 @IntDef(value = {BEHAVIOR_DEFAULT, BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE}) 180 @interface Behavior { 181 } 182 183 /** 184 * Makes a set of windows that cause insets appear on screen. 185 * <p> 186 * Note that if the window currently doesn't have control over a certain type, it will apply the 187 * change as soon as the window gains control. The app can listen to the event by observing 188 * {@link View#onApplyWindowInsets} and checking visibility with {@link WindowInsets#isVisible}. 189 * 190 * @param types A bitmask of {@link WindowInsets.Type} specifying what windows the app 191 * would like to make appear on screen. 192 */ show(@nsetsType int types)193 void show(@InsetsType int types); 194 195 /** 196 * Makes a set of windows causing insets disappear. 197 * <p> 198 * Note that if the window currently doesn't have control over a certain type, it will apply the 199 * change as soon as the window gains control. The app can listen to the event by observing 200 * {@link View#onApplyWindowInsets} and checking visibility with {@link WindowInsets#isVisible}. 201 * 202 * @param types A bitmask of {@link WindowInsets.Type} specifying what windows the app 203 * would like to make disappear. 204 */ hide(@nsetsType int types)205 void hide(@InsetsType int types); 206 207 /** 208 * Lets the application control window inset animations in a frame-by-frame manner by modifying 209 * the position of the windows in the system causing insets directly. 210 * 211 * @param types The {@link WindowInsets.Type}s the application has requested to control. 212 * @param durationMillis Duration of animation in 213 * {@link java.util.concurrent.TimeUnit#MILLISECONDS}, or -1 if the 214 * animation doesn't have a predetermined duration. This value will be 215 * passed to {@link WindowInsetsAnimation#getDurationMillis()} 216 * @param interpolator The interpolator used for this animation, or {@code null} if this 217 * animation doesn't follow an interpolation curve. This value will be 218 * passed to {@link WindowInsetsAnimation#getInterpolator()} and used to 219 * calculate {@link WindowInsetsAnimation#getInterpolatedFraction()}. 220 * @param listener The {@link WindowInsetsAnimationControlListener} that gets called when the 221 * windows are ready to be controlled, among other callbacks. 222 * @param cancellationSignal A cancellation signal that the caller can use to cancel the 223 * request to obtain control, or once they have control, to cancel the 224 * control. 225 * @see WindowInsetsAnimation#getFraction() 226 * @see WindowInsetsAnimation#getInterpolatedFraction() 227 * @see WindowInsetsAnimation#getInterpolator() 228 * @see WindowInsetsAnimation#getDurationMillis() 229 */ controlWindowInsetsAnimation(@nsetsType int types, long durationMillis, @Nullable Interpolator interpolator, @Nullable CancellationSignal cancellationSignal, @NonNull WindowInsetsAnimationControlListener listener)230 void controlWindowInsetsAnimation(@InsetsType int types, long durationMillis, 231 @Nullable Interpolator interpolator, 232 @Nullable CancellationSignal cancellationSignal, 233 @NonNull WindowInsetsAnimationControlListener listener); 234 235 /** 236 * Lets the application add non-controllable listener object that can be called back 237 * when animation is invoked by the system by host calling methods such as {@link #show} or 238 * {@link #hide}. 239 * 240 * The listener is supposed to be used for logging only, using the control or 241 * relying on the timing of the callback in any other way is not supported. 242 * 243 * @param listener The {@link WindowInsetsAnimationControlListener} that gets called when 244 * the animation is driven by the system and not the host 245 * @hide 246 */ setSystemDrivenInsetsAnimationLoggingListener( @ullable WindowInsetsAnimationControlListener listener)247 void setSystemDrivenInsetsAnimationLoggingListener( 248 @Nullable WindowInsetsAnimationControlListener listener); 249 250 /** 251 * Controls the appearance of system bars. 252 * <p> 253 * For example, the following statement adds {@link #APPEARANCE_LIGHT_STATUS_BARS}: 254 * <pre> 255 * setSystemBarsAppearance(APPEARANCE_LIGHT_STATUS_BARS, APPEARANCE_LIGHT_STATUS_BARS) 256 * </pre> 257 * And the following statement clears it: 258 * <pre> 259 * setSystemBarsAppearance(0, APPEARANCE_LIGHT_STATUS_BARS) 260 * </pre> 261 * 262 * @param appearance Bitmask of appearance flags. 263 * @param mask Specifies which flags of appearance should be changed. 264 * @see #getSystemBarsAppearance 265 */ setSystemBarsAppearance(@ppearance int appearance, @Appearance int mask)266 void setSystemBarsAppearance(@Appearance int appearance, @Appearance int mask); 267 268 /** 269 * Similar to {@link #setSystemBarsAppearance} but the given flag will only take effect when it 270 * is not controlled by {@link #setSystemBarsAppearance}. 271 * 272 * @see WindowInsetsController#getSystemBarsAppearance() 273 * @see android.R.attr#windowLightStatusBar 274 * @see android.R.attr#windowLightNavigationBar 275 * @hide 276 */ setSystemBarsAppearanceFromResource(@ppearance int appearance, @Appearance int mask)277 void setSystemBarsAppearanceFromResource(@Appearance int appearance, @Appearance int mask); 278 279 /** 280 * Retrieves the requested appearance of system bars. 281 * 282 * @return The requested bitmask of system bar appearance controlled by this window. 283 * @see #setSystemBarsAppearance(int, int) 284 * @see android.R.attr#windowLightStatusBar 285 * @see android.R.attr#windowLightNavigationBar 286 */ getSystemBarsAppearance()287 @Appearance int getSystemBarsAppearance(); 288 289 /** 290 * Sets the insets height for the IME caption bar, which corresponds to the 291 * "fake" IME navigation bar. 292 * 293 * @param height the insets height of the IME caption bar. 294 * @hide 295 */ setImeCaptionBarInsetsHeight(int height)296 default void setImeCaptionBarInsetsHeight(int height) { 297 } 298 299 /** 300 * Controls the behavior of system bars. 301 * 302 * @param behavior Determines how the bars behave when being hidden by the application. 303 * @see #getSystemBarsBehavior 304 */ setSystemBarsBehavior(@ehavior int behavior)305 void setSystemBarsBehavior(@Behavior int behavior); 306 307 /** 308 * Retrieves the requested behavior of system bars. 309 * 310 * @return the system bar behavior controlled by this window. 311 * @see #setSystemBarsBehavior(int) 312 */ getSystemBarsBehavior()313 @Behavior int getSystemBarsBehavior(); 314 315 /** 316 * Disables or enables the animations. 317 * 318 * @hide 319 */ setAnimationsDisabled(boolean disable)320 void setAnimationsDisabled(boolean disable); 321 322 /** 323 * @hide 324 */ getState()325 InsetsState getState(); 326 327 /** 328 * @return Insets types that have been requested to be visible. 329 * @hide 330 */ getRequestedVisibleTypes()331 @InsetsType int getRequestedVisibleTypes(); 332 333 /** 334 * Adds a {@link OnControllableInsetsChangedListener} to the window insets controller. 335 * 336 * @param listener The listener to add. 337 * 338 * @see OnControllableInsetsChangedListener 339 * @see #removeOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 340 */ addOnControllableInsetsChangedListener( @onNull OnControllableInsetsChangedListener listener)341 void addOnControllableInsetsChangedListener( 342 @NonNull OnControllableInsetsChangedListener listener); 343 344 /** 345 * Removes a {@link OnControllableInsetsChangedListener} from the window insets controller. 346 * 347 * @param listener The listener to remove. 348 * 349 * @see OnControllableInsetsChangedListener 350 * @see #addOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 351 */ removeOnControllableInsetsChangedListener( @onNull OnControllableInsetsChangedListener listener)352 void removeOnControllableInsetsChangedListener( 353 @NonNull OnControllableInsetsChangedListener listener); 354 355 /** 356 * Listener to be notified when the set of controllable {@link WindowInsets.Type} controlled by 357 * a {@link WindowInsetsController} changes. 358 * <p> 359 * Once a {@link WindowInsets.Type} becomes controllable, the app will be able to control the 360 * window that is causing this type of insets by calling {@link #controlWindowInsetsAnimation}. 361 * <p> 362 * Note: When listening to controllability of the {@link Type#ime}, 363 * {@link #controlWindowInsetsAnimation} may still fail in case the {@link InputMethodService} 364 * decides to cancel the show request. This could happen when there is a hardware keyboard 365 * attached. 366 * 367 * @see #addOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 368 * @see #removeOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 369 */ 370 interface OnControllableInsetsChangedListener { 371 372 /** 373 * Called when the set of controllable {@link WindowInsets.Type} changes. 374 * 375 * @param controller The controller for which the set of controllable 376 * {@link WindowInsets.Type}s are changing. 377 * @param typeMask Bitwise type-mask of the {@link WindowInsets.Type}s the controller is 378 * currently able to control. 379 */ onControllableInsetsChanged(@onNull WindowInsetsController controller, @InsetsType int typeMask)380 void onControllableInsetsChanged(@NonNull WindowInsetsController controller, 381 @InsetsType int typeMask); 382 } 383 } 384