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.FloatRange; 20 import android.annotation.NonNull; 21 import android.annotation.Nullable; 22 import android.annotation.SuppressLint; 23 import android.graphics.Insets; 24 import android.view.WindowInsets.Type.InsetsType; 25 import android.view.WindowInsetsAnimation.Bounds; 26 import android.view.animation.Interpolator; 27 28 /** 29 * Controller for app-driven animation of system windows. 30 * <p> 31 * {@code WindowInsetsAnimationController} lets apps animate system windows such as 32 * the {@link android.inputmethodservice.InputMethodService IME}. The animation is 33 * synchronized, such that changes the system windows and the app's current frame 34 * are rendered at the same time. 35 * <p> 36 * Control is obtained through {@link WindowInsetsController#controlWindowInsetsAnimation}. 37 */ 38 @SuppressLint("NotCloseable") 39 public interface WindowInsetsAnimationController { 40 41 /** 42 * Retrieves the {@link Insets} when the windows this animation is controlling are fully hidden. 43 * <p> 44 * Note that these insets are always relative to the window, which is the same as being relative 45 * to {@link View#getRootView} 46 * <p> 47 * If there are any animation listeners registered, this value is the same as 48 * {@link Bounds#getLowerBound()} that is being be passed into the root view of the 49 * hierarchy. 50 * 51 * @return Insets when the windows this animation is controlling are fully hidden. 52 * 53 * @see Bounds#getLowerBound() 54 */ getHiddenStateInsets()55 @NonNull Insets getHiddenStateInsets(); 56 57 /** 58 * Retrieves the {@link Insets} when the windows this animation is controlling are fully shown. 59 * <p> 60 * Note that these insets are always relative to the window, which is the same as being relative 61 * to {@link View#getRootView} 62 * <p> 63 * If there are any animation listeners registered, this value is the same as 64 * {@link Bounds#getUpperBound()} that is being passed into the root view of hierarchy. 65 * 66 * @return Insets when the windows this animation is controlling are fully shown. 67 * 68 * @see Bounds#getUpperBound() 69 */ getShownStateInsets()70 @NonNull Insets getShownStateInsets(); 71 72 /** 73 * Retrieves the current insets. 74 * <p> 75 * Note that these insets are always relative to the window, which is the same as 76 * being relative 77 * to {@link View#getRootView} 78 * @return The current insets on the currently showing frame. These insets will change as the 79 * animation progresses to reflect the current insets provided by the controlled window. 80 */ getCurrentInsets()81 @NonNull Insets getCurrentInsets(); 82 83 /** 84 * Returns the progress as previously set by {@code fraction} in {@link #setInsetsAndAlpha} 85 * 86 * @return the progress of the animation, where {@code 0} is fully hidden and {@code 1} is 87 * fully shown. 88 * <p> 89 * Note: this value represents raw overall progress of the animation 90 * i.e. the combined progress of insets and alpha. 91 * <p> 92 */ 93 @FloatRange(from = 0f, to = 1f) getCurrentFraction()94 float getCurrentFraction(); 95 96 /** 97 * Current alpha value of the window. 98 * @return float value between 0 and 1. 99 */ getCurrentAlpha()100 float getCurrentAlpha(); 101 102 /** 103 * @return The {@link WindowInsets.Type}s this object is currently controlling. 104 */ getTypes()105 @InsetsType int getTypes(); 106 107 /** 108 * Modifies the insets for the frame being drawn by indirectly moving the windows around in the 109 * system that are causing window insets. 110 * <p> 111 * Note that these insets are always relative to the window, which is the same as being relative 112 * to {@link View#getRootView} 113 * <p> 114 * Also note that this will <b>not</b> inform the view system of a full inset change via 115 * {@link View#dispatchApplyWindowInsets} in order to avoid a full layout pass during the 116 * animation. If you'd like to animate views during a window inset animation, register a 117 * {@link WindowInsetsAnimation.Callback} by calling 118 * {@link View#setWindowInsetsAnimationCallback(WindowInsetsAnimation.Callback)} that will be 119 * notified about any insets change via {@link WindowInsetsAnimation.Callback#onProgress} during 120 * the animation. 121 * <p> 122 * {@link View#dispatchApplyWindowInsets} will instead be called once the animation has 123 * finished, i.e. once {@link #finish} has been called. 124 * Note: If there are no insets, alpha animation is still applied. 125 * 126 * @param insets The new insets to apply. Based on the requested insets, the system will 127 * calculate the positions of the windows in the system causing insets such that 128 * the resulting insets of that configuration will match the passed in parameter. 129 * Note that these insets are being clamped to the range from 130 * {@link #getHiddenStateInsets} to {@link #getShownStateInsets}. 131 * If you intend on changing alpha only, pass null or {@link #getCurrentInsets()}. 132 * @param alpha The new alpha to apply to the inset side. 133 * @param fraction instantaneous animation progress. This value is dispatched to 134 * {@link WindowInsetsAnimation.Callback}. 135 * 136 * @see WindowInsetsAnimation.Callback 137 * @see View#setWindowInsetsAnimationCallback(WindowInsetsAnimation.Callback) 138 */ setInsetsAndAlpha(@ullable Insets insets, @FloatRange(from = 0f, to = 1f) float alpha, @FloatRange(from = 0f, to = 1f) float fraction)139 void setInsetsAndAlpha(@Nullable Insets insets, @FloatRange(from = 0f, to = 1f) float alpha, 140 @FloatRange(from = 0f, to = 1f) float fraction); 141 142 /** 143 * Finishes the animation, and leaves the windows shown or hidden. 144 * <p> 145 * After invoking {@link #finish}, this instance is no longer {@link #isReady ready}. 146 * <p> 147 * Note: Finishing an animation implicitly {@link #setInsetsAndAlpha sets insets and alpha} 148 * according to the requested end state without any further animation. 149 * 150 * @param shown if {@code true}, the windows will be shown after finishing the 151 * animation. Otherwise they will be hidden. 152 */ finish(boolean shown)153 void finish(boolean shown); 154 155 /** 156 * Returns whether this instance is ready to be used to control window insets. 157 * <p> 158 * Instances are ready when passed in {@link WindowInsetsAnimationControlListener#onReady} 159 * and stop being ready when it is either {@link #isFinished() finished} or 160 * {@link #isCancelled() cancelled}. 161 * 162 * @return {@code true} if the instance is ready, {@code false} otherwise. 163 */ isReady()164 default boolean isReady() { 165 return !isFinished() && !isCancelled(); 166 } 167 168 /** 169 * Returns whether this instance has been finished by a call to {@link #finish}. 170 * 171 * @see WindowInsetsAnimationControlListener#onFinished 172 * @return {@code true} if the instance is finished, {@code false} otherwise. 173 */ isFinished()174 boolean isFinished(); 175 176 /** 177 * Returns whether this instance has been cancelled by the system, or by invoking the 178 * {@link android.os.CancellationSignal} passed into 179 * {@link WindowInsetsController#controlWindowInsetsAnimation}. 180 * 181 * @see WindowInsetsAnimationControlListener#onCancelled 182 * @return {@code true} if the instance is cancelled, {@code false} otherwise. 183 */ isCancelled()184 boolean isCancelled(); 185 186 /** 187 * @hide 188 * @return {@code true} when controller controls IME and IME has no insets (floating, 189 * fullscreen or non-overlapping). 190 */ hasZeroInsetsIme()191 boolean hasZeroInsetsIme(); 192 193 /** 194 * @hide 195 * @return The duration of the animation in {@link java.util.concurrent.TimeUnit#MILLISECONDS}. 196 */ getDurationMs()197 long getDurationMs(); 198 199 /** 200 * @hide 201 * @return The interpolator of the animation. 202 */ getInsetsInterpolator()203 Interpolator getInsetsInterpolator(); 204 } 205