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