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