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 * Controls the appearance of system bars. 205 * <p> 206 * For example, the following statement adds {@link #APPEARANCE_LIGHT_STATUS_BARS}: 207 * <pre> 208 * setSystemBarsAppearance(APPEARANCE_LIGHT_STATUS_BARS, APPEARANCE_LIGHT_STATUS_BARS) 209 * </pre> 210 * And the following statement clears it: 211 * <pre> 212 * setSystemBarsAppearance(0, APPEARANCE_LIGHT_STATUS_BARS) 213 * </pre> 214 * 215 * @param appearance Bitmask of appearance flags. 216 * @param mask Specifies which flags of appearance should be changed. 217 * @see #getSystemBarsAppearance 218 */ setSystemBarsAppearance(@ppearance int appearance, @Appearance int mask)219 void setSystemBarsAppearance(@Appearance int appearance, @Appearance int mask); 220 221 /** 222 * Retrieves the requested appearance of system bars. 223 * 224 * @return The requested bitmask of system bar appearance controlled by this window. 225 * @see #setSystemBarsAppearance(int, int) 226 */ getSystemBarsAppearance()227 @Appearance int getSystemBarsAppearance(); 228 229 /** 230 * Notify the caption insets height change. The information will be used on the client side to, 231 * make sure the InsetsState has the correct caption insets. 232 * 233 * @param height the height of caption bar insets. 234 * @hide 235 */ setCaptionInsetsHeight(int height)236 void setCaptionInsetsHeight(int height); 237 238 /** 239 * Controls the behavior of system bars. 240 * 241 * @param behavior Determines how the bars behave when being hidden by the application. 242 * @see #getSystemBarsBehavior 243 */ setSystemBarsBehavior(@ehavior int behavior)244 void setSystemBarsBehavior(@Behavior int behavior); 245 246 /** 247 * Retrieves the requested behavior of system bars. 248 * 249 * @return the system bar behavior controlled by this window. 250 * @see #setSystemBarsBehavior(int) 251 */ getSystemBarsBehavior()252 @Behavior int getSystemBarsBehavior(); 253 254 /** 255 * Disables or enables the animations. 256 * 257 * @hide 258 */ setAnimationsDisabled(boolean disable)259 void setAnimationsDisabled(boolean disable); 260 261 /** 262 * @hide 263 */ getState()264 InsetsState getState(); 265 266 /** 267 * @return Whether the specified insets source is currently requested to be visible by the 268 * application. 269 * @hide 270 */ isRequestedVisible(@nternalInsetsType int type)271 boolean isRequestedVisible(@InternalInsetsType int type); 272 273 /** 274 * Adds a {@link OnControllableInsetsChangedListener} to the window insets controller. 275 * 276 * @param listener The listener to add. 277 * 278 * @see OnControllableInsetsChangedListener 279 * @see #removeOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 280 */ addOnControllableInsetsChangedListener( @onNull OnControllableInsetsChangedListener listener)281 void addOnControllableInsetsChangedListener( 282 @NonNull OnControllableInsetsChangedListener listener); 283 284 /** 285 * Removes a {@link OnControllableInsetsChangedListener} from the window insets controller. 286 * 287 * @param listener The listener to remove. 288 * 289 * @see OnControllableInsetsChangedListener 290 * @see #addOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 291 */ removeOnControllableInsetsChangedListener( @onNull OnControllableInsetsChangedListener listener)292 void removeOnControllableInsetsChangedListener( 293 @NonNull OnControllableInsetsChangedListener listener); 294 295 /** 296 * Listener to be notified when the set of controllable {@link WindowInsets.Type} controlled by 297 * a {@link WindowInsetsController} changes. 298 * <p> 299 * Once a {@link WindowInsets.Type} becomes controllable, the app will be able to control the 300 * window that is causing this type of insets by calling {@link #controlWindowInsetsAnimation}. 301 * <p> 302 * Note: When listening to controllability of the {@link Type#ime}, 303 * {@link #controlWindowInsetsAnimation} may still fail in case the {@link InputMethodService} 304 * decides to cancel the show request. This could happen when there is a hardware keyboard 305 * attached. 306 * 307 * @see #addOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 308 * @see #removeOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 309 */ 310 interface OnControllableInsetsChangedListener { 311 312 /** 313 * Called when the set of controllable {@link WindowInsets.Type} changes. 314 * 315 * @param controller The controller for which the set of controllable 316 * {@link WindowInsets.Type}s are changing. 317 * @param typeMask Bitwise type-mask of the {@link WindowInsets.Type}s the controller is 318 * currently able to control. 319 */ onControllableInsetsChanged(@onNull WindowInsetsController controller, @InsetsType int typeMask)320 void onControllableInsetsChanged(@NonNull WindowInsetsController controller, 321 @InsetsType int typeMask); 322 } 323 } 324