1 /*
2  * Copyright (C) 2022 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.window;
18 
19 import android.annotation.FloatRange;
20 import android.annotation.IntDef;
21 
22 import java.lang.annotation.Retention;
23 import java.lang.annotation.RetentionPolicy;
24 
25 /**
26  * Object used to report back gesture progress.
27  * Holds information about the touch event, swipe direction and the animation progress that
28  * predictive back animations should seek to.
29  */
30 public final class BackEvent {
31     /** Indicates that the edge swipe starts from the left edge of the screen */
32     public static final int EDGE_LEFT = 0;
33     /** Indicates that the edge swipe starts from the right edge of the screen */
34     public static final int EDGE_RIGHT = 1;
35 
36     /** @hide */
37     @IntDef({
38             EDGE_LEFT,
39             EDGE_RIGHT,
40     })
41     @Retention(RetentionPolicy.SOURCE)
42     public @interface SwipeEdge{}
43 
44     private final float mTouchX;
45     private final float mTouchY;
46     private final float mProgress;
47 
48     @SwipeEdge
49     private final int mSwipeEdge;
50 
51     /**
52      * Creates a new {@link BackMotionEvent} instance.
53      *
54      * @param touchX Absolute X location of the touch point of this event.
55      * @param touchY Absolute Y location of the touch point of this event.
56      * @param progress Value between 0 and 1 on how far along the back gesture is.
57      * @param swipeEdge Indicates which edge the swipe starts from.
58      */
BackEvent(float touchX, float touchY, float progress, @SwipeEdge int swipeEdge)59     public BackEvent(float touchX, float touchY, float progress, @SwipeEdge int swipeEdge) {
60         mTouchX = touchX;
61         mTouchY = touchY;
62         mProgress = progress;
63         mSwipeEdge = swipeEdge;
64     }
65 
66     /**
67      * Returns a value between 0 and 1 on how far along the back gesture is. This value is
68      * driven by the horizontal location of the touch point, and should be used as the fraction to
69      * seek the predictive back animation with. Specifically,
70      * <ol>
71      * <li>The progress is 0 when the touch is at the starting edge of the screen (left or right),
72      * and animation should seek to its start state.
73      * <li>The progress is approximately 1 when the touch is at the opposite side of the screen,
74      * and animation should seek to its end state. Exact end value may vary depending on
75      * screen size.
76      * </ol>
77      * <li> After the gesture finishes in cancel state, this method keeps getting invoked until the
78      * progress value animates back to 0.
79      * </ol>
80      * In-between locations are linearly interpolated based on horizontal distance from the starting
81      * edge and smooth clamped to 1 when the distance exceeds a system-wide threshold.
82      */
83     @FloatRange(from = 0, to = 1)
getProgress()84     public float getProgress() {
85         return mProgress;
86     }
87 
88     /**
89      * Returns the absolute X location of the touch point, or NaN if the event is from
90      * a button press.
91      */
getTouchX()92     public float getTouchX() {
93         return mTouchX;
94     }
95 
96     /**
97      * Returns the absolute Y location of the touch point, or NaN if the event is from
98      * a button press.
99      */
getTouchY()100     public float getTouchY() {
101         return mTouchY;
102     }
103 
104     /**
105      * Returns the screen edge that the swipe starts from.
106      */
107     @SwipeEdge
getSwipeEdge()108     public int getSwipeEdge() {
109         return mSwipeEdge;
110     }
111 
112     @Override
toString()113     public String toString() {
114         return "BackEvent{"
115                 + "mTouchX=" + mTouchX
116                 + ", mTouchY=" + mTouchY
117                 + ", mProgress=" + mProgress
118                 + ", mSwipeEdge" + mSwipeEdge
119                 + "}";
120     }
121 }
122