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