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.CancellationSignal; 25 import android.view.InsetsState.InternalInsetsType; 26 import android.view.WindowInsets.Type; 27 import android.view.WindowInsets.Type.InsetsType; 28 import android.view.animation.Interpolator; 29 30 import java.lang.annotation.Retention; 31 import java.lang.annotation.RetentionPolicy; 32 33 /** 34 * Interface to control windows that generate insets. 35 * 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 * Determines the appearance of system bars. 71 * @hide 72 */ 73 @Retention(RetentionPolicy.SOURCE) 74 @IntDef(flag = true, value = {APPEARANCE_OPAQUE_STATUS_BARS, APPEARANCE_OPAQUE_NAVIGATION_BARS, 75 APPEARANCE_LOW_PROFILE_BARS, APPEARANCE_LIGHT_STATUS_BARS, 76 APPEARANCE_LIGHT_NAVIGATION_BARS}) 77 @interface Appearance { 78 } 79 80 /** 81 * The default option for {@link #setSystemBarsBehavior(int)}. System bars will be forcibly 82 * shown on any user interaction on the corresponding display if navigation bars are hidden by 83 * {@link #hide(int)} or 84 * {@link WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float)}. 85 */ 86 int BEHAVIOR_SHOW_BARS_BY_TOUCH = 0; 87 88 /** 89 * Option for {@link #setSystemBarsBehavior(int)}: Window would like to remain interactive when 90 * hiding navigation bars by calling {@link #hide(int)} or 91 * {@link WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float)}. 92 * 93 * <p>When system bars are hidden in this mode, they can be revealed with system gestures, such 94 * as swiping from the edge of the screen where the bar is hidden from.</p> 95 */ 96 int BEHAVIOR_SHOW_BARS_BY_SWIPE = 1; 97 98 /** 99 * Option for {@link #setSystemBarsBehavior(int)}: Window would like to remain interactive when 100 * hiding navigation bars by calling {@link #hide(int)} or 101 * {@link WindowInsetsAnimationController#setInsetsAndAlpha(Insets, float, float)}. 102 * 103 * <p>When system bars are hidden in this mode, they can be revealed temporarily with system 104 * gestures, such as swiping from the edge of the screen where the bar is hidden from. These 105 * transient system bars will overlay app’s content, may have some degree of transparency, and 106 * will automatically hide after a short timeout.</p> 107 */ 108 int BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE = 2; 109 110 /** 111 * Determines the behavior of system bars when hiding them by calling {@link #hide}. 112 * @hide 113 */ 114 @Retention(RetentionPolicy.SOURCE) 115 @IntDef(value = {BEHAVIOR_SHOW_BARS_BY_TOUCH, BEHAVIOR_SHOW_BARS_BY_SWIPE, 116 BEHAVIOR_SHOW_TRANSIENT_BARS_BY_SWIPE}) 117 @interface Behavior { 118 } 119 120 /** 121 * Makes a set of windows that cause insets appear on screen. 122 * <p> 123 * Note that if the window currently doesn't have control over a certain type, it will apply the 124 * change as soon as the window gains control. The app can listen to the event by observing 125 * {@link View#onApplyWindowInsets} and checking visibility with {@link WindowInsets#isVisible}. 126 * 127 * @param types A bitmask of {@link InsetsType} specifying what windows the app 128 * would like to make appear on screen. 129 */ show(@nsetsType int types)130 void show(@InsetsType int types); 131 132 /** 133 * Makes a set of windows causing insets disappear. 134 * <p> 135 * Note that if the window currently doesn't have control over a certain type, it will apply the 136 * change as soon as the window gains control. The app can listen to the event by observing 137 * {@link View#onApplyWindowInsets} and checking visibility with {@link WindowInsets#isVisible}. 138 * 139 * @param types A bitmask of {@link InsetsType} specifying what windows the app 140 * would like to make disappear. 141 */ hide(@nsetsType int types)142 void hide(@InsetsType int types); 143 144 /** 145 * Lets the application control window inset animations in a frame-by-frame manner by modifying 146 * the position of the windows in the system causing insets directly. 147 * 148 * @param types The {@link InsetsType}s the application has requested to control. 149 * @param durationMillis Duration of animation in 150 * {@link java.util.concurrent.TimeUnit#MILLISECONDS}, or -1 if the 151 * animation doesn't have a predetermined duration. This value will be 152 * passed to {@link WindowInsetsAnimation#getDurationMillis()} 153 * @param interpolator The interpolator used for this animation, or {@code null} if this 154 * animation doesn't follow an interpolation curve. This value will be 155 * passed to {@link WindowInsetsAnimation#getInterpolator()} and used to 156 * calculate {@link WindowInsetsAnimation#getInterpolatedFraction()}. 157 * @param listener The {@link WindowInsetsAnimationControlListener} that gets called when the 158 * windows are ready to be controlled, among other callbacks. 159 * @param cancellationSignal A cancellation signal that the caller can use to cancel the 160 * request to obtain control, or once they have control, to cancel the 161 * control. 162 * @see WindowInsetsAnimation#getFraction() 163 * @see WindowInsetsAnimation#getInterpolatedFraction() 164 * @see WindowInsetsAnimation#getInterpolator() 165 * @see WindowInsetsAnimation#getDurationMillis() 166 */ controlWindowInsetsAnimation(@nsetsType int types, long durationMillis, @Nullable Interpolator interpolator, @Nullable CancellationSignal cancellationSignal, @NonNull WindowInsetsAnimationControlListener listener)167 void controlWindowInsetsAnimation(@InsetsType int types, long durationMillis, 168 @Nullable Interpolator interpolator, 169 @Nullable CancellationSignal cancellationSignal, 170 @NonNull WindowInsetsAnimationControlListener listener); 171 172 /** 173 * Controls the appearance of system bars. 174 * <p> 175 * For example, the following statement adds {@link #APPEARANCE_LIGHT_STATUS_BARS}: 176 * <pre> 177 * setSystemBarsAppearance(APPEARANCE_LIGHT_STATUS_BARS, APPEARANCE_LIGHT_STATUS_BARS) 178 * </pre> 179 * And the following statement clears it: 180 * <pre> 181 * setSystemBarsAppearance(0, APPEARANCE_LIGHT_STATUS_BARS) 182 * </pre> 183 * 184 * @param appearance Bitmask of {@link Appearance} flags. 185 * @param mask Specifies which flags of appearance should be changed. 186 * @see #getSystemBarsAppearance 187 */ setSystemBarsAppearance(@ppearance int appearance, @Appearance int mask)188 void setSystemBarsAppearance(@Appearance int appearance, @Appearance int mask); 189 190 /** 191 * Retrieves the requested appearance of system bars. 192 * 193 * @return The requested bitmask of system bar appearance controlled by this window. 194 * @see #setSystemBarsAppearance(int, int) 195 */ getSystemBarsAppearance()196 @Appearance int getSystemBarsAppearance(); 197 198 /** 199 * Notify the caption insets height change. The information will be used on the client side to, 200 * make sure the InsetsState has the correct caption insets. 201 * 202 * @param height the height of caption bar insets. 203 * @hide 204 */ setCaptionInsetsHeight(int height)205 void setCaptionInsetsHeight(int height); 206 207 /** 208 * Controls the behavior of system bars. 209 * 210 * @param behavior Determines how the bars behave when being hidden by the application. 211 * @see #getSystemBarsBehavior 212 */ setSystemBarsBehavior(@ehavior int behavior)213 void setSystemBarsBehavior(@Behavior int behavior); 214 215 /** 216 * Retrieves the requested behavior of system bars. 217 * 218 * @return the system bar behavior controlled by this window. 219 * @see #setSystemBarsBehavior(int) 220 */ getSystemBarsBehavior()221 @Behavior int getSystemBarsBehavior(); 222 223 /** 224 * Disables or enables the animations. 225 * 226 * @hide 227 */ setAnimationsDisabled(boolean disable)228 void setAnimationsDisabled(boolean disable); 229 230 /** 231 * @hide 232 */ getState()233 InsetsState getState(); 234 235 /** 236 * @return Whether the specified insets source is currently requested to be visible by the 237 * application. 238 * @hide 239 */ isRequestedVisible(@nternalInsetsType int type)240 boolean isRequestedVisible(@InternalInsetsType int type); 241 242 /** 243 * Adds a {@link OnControllableInsetsChangedListener} to the window insets controller. 244 * 245 * @param listener The listener to add. 246 * 247 * @see OnControllableInsetsChangedListener 248 * @see #removeOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 249 */ addOnControllableInsetsChangedListener( @onNull OnControllableInsetsChangedListener listener)250 void addOnControllableInsetsChangedListener( 251 @NonNull OnControllableInsetsChangedListener listener); 252 253 /** 254 * Removes a {@link OnControllableInsetsChangedListener} from the window insets controller. 255 * 256 * @param listener The listener to remove. 257 * 258 * @see OnControllableInsetsChangedListener 259 * @see #addOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 260 */ removeOnControllableInsetsChangedListener( @onNull OnControllableInsetsChangedListener listener)261 void removeOnControllableInsetsChangedListener( 262 @NonNull OnControllableInsetsChangedListener listener); 263 264 /** 265 * Listener to be notified when the set of controllable {@link InsetsType} controlled by a 266 * {@link WindowInsetsController} changes. 267 * <p> 268 * Once a {@link InsetsType} becomes controllable, the app will be able to control the window 269 * that is causing this type of insets by calling {@link #controlWindowInsetsAnimation}. 270 * <p> 271 * Note: When listening to controllability of the {@link Type#ime}, 272 * {@link #controlWindowInsetsAnimation} may still fail in case the {@link InputMethodService} 273 * decides to cancel the show request. This could happen when there is a hardware keyboard 274 * attached. 275 * 276 * @see #addOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 277 * @see #removeOnControllableInsetsChangedListener(OnControllableInsetsChangedListener) 278 */ 279 interface OnControllableInsetsChangedListener { 280 281 /** 282 * Called when the set of controllable {@link InsetsType} changes. 283 * 284 * @param controller The controller for which the set of controllable {@link InsetsType}s 285 * are changing. 286 * @param typeMask Bitwise type-mask of the {@link InsetsType}s the controller is currently 287 * able to control. 288 */ onControllableInsetsChanged(@onNull WindowInsetsController controller, @InsetsType int typeMask)289 void onControllableInsetsChanged(@NonNull WindowInsetsController controller, 290 @InsetsType int typeMask); 291 } 292 } 293