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     /** @hide */
fromBackMotionEvent(BackMotionEvent backMotionEvent)52     public static BackEvent fromBackMotionEvent(BackMotionEvent backMotionEvent) {
53         return new BackEvent(backMotionEvent.getTouchX(), backMotionEvent.getTouchY(),
54                 backMotionEvent.getProgress(), backMotionEvent.getSwipeEdge());
55     }
56 
57     /**
58      * Creates a new {@link BackEvent} instance.
59      *
60      * @param touchX Absolute X location of the touch point of this event.
61      * @param touchY Absolute Y location of the touch point of this event.
62      * @param progress Value between 0 and 1 on how far along the back gesture is.
63      * @param swipeEdge Indicates which edge the swipe starts from.
64      */
BackEvent(float touchX, float touchY, float progress, @SwipeEdge int swipeEdge)65     public BackEvent(float touchX, float touchY, float progress, @SwipeEdge int swipeEdge) {
66         mTouchX = touchX;
67         mTouchY = touchY;
68         mProgress = progress;
69         mSwipeEdge = swipeEdge;
70     }
71 
72     /**
73      * Returns a value between 0 and 1 on how far along the back gesture is. This value is
74      * driven by the horizontal location of the touch point, and should be used as the fraction to
75      * seek the predictive back animation with. Specifically,
76      * <ol>
77      * <li>The progress is 0 when the touch is at the starting edge of the screen (left or right),
78      * and animation should seek to its start state.
79      * <li>The progress is approximately 1 when the touch is at the opposite side of the screen,
80      * and animation should seek to its end state. Exact end value may vary depending on
81      * screen size.
82      * </ol>
83      * <li> After the gesture finishes in cancel state, this method keeps getting invoked until the
84      * progress value animates back to 0.
85      * </ol>
86      * In-between locations are linearly interpolated based on horizontal distance from the starting
87      * edge and smooth clamped to 1 when the distance exceeds a system-wide threshold.
88      */
89     @FloatRange(from = 0, to = 1)
getProgress()90     public float getProgress() {
91         return mProgress;
92     }
93 
94     /**
95      * Returns the absolute X location of the touch point, or NaN if the event is from
96      * a button press.
97      */
getTouchX()98     public float getTouchX() {
99         return mTouchX;
100     }
101 
102     /**
103      * Returns the absolute Y location of the touch point, or NaN if the event is from
104      * a button press.
105      */
getTouchY()106     public float getTouchY() {
107         return mTouchY;
108     }
109 
110     /**
111      * Returns the screen edge that the swipe starts from.
112      */
113     @SwipeEdge
getSwipeEdge()114     public int getSwipeEdge() {
115         return mSwipeEdge;
116     }
117 
118     @Override
toString()119     public String toString() {
120         return "BackEvent{"
121                 + "mTouchX=" + mTouchX
122                 + ", mTouchY=" + mTouchY
123                 + ", mProgress=" + mProgress
124                 + ", mSwipeEdge" + mSwipeEdge
125                 + "}";
126     }
127 }
128