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 com.android.systemui.dreams.touch;
18 
19 import android.graphics.Rect;
20 import android.graphics.Region;
21 import android.view.GestureDetector;
22 
23 import com.android.systemui.shared.system.InputChannelCompat;
24 
25 import com.google.common.util.concurrent.ListenableFuture;
26 
27 /**
28  * The {@link DreamTouchHandler} interface provides a way for dream overlay components to observe
29  * touch events and gestures with the ability to intercept the latter. Touch interaction sequences
30  * are abstracted as sessions. A session represents the time of first
31  * {@code android.view.MotionEvent.ACTION_DOWN} event to the last {@link DreamTouchHandler}
32  * stopping interception of gestures. If no gesture is intercepted, the session continues
33  * indefinitely. {@link DreamTouchHandler} have the ability to create a stack of sessions, which
34  * allows for motion logic to be captured in modal states.
35  */
36 public interface DreamTouchHandler {
37     /**
38      * A touch session captures the interaction surface of a {@link DreamTouchHandler}. Clients
39      * register listeners as desired to participate in motion/gesture callbacks.
40      */
41     interface TouchSession {
42         interface Callback {
onRemoved()43             void onRemoved();
44         }
45 
registerCallback(Callback callback)46         void registerCallback(Callback callback);
47 
48         /**
49          * Adds a input event listener for the given session.
50          * @param inputEventListener
51          */
registerInputListener(InputChannelCompat.InputEventListener inputEventListener)52         boolean registerInputListener(InputChannelCompat.InputEventListener inputEventListener);
53 
54         /**
55          * Adds a gesture listener for the given session.
56          * @param gestureListener
57          */
registerGestureListener(GestureDetector.OnGestureListener gestureListener)58         boolean registerGestureListener(GestureDetector.OnGestureListener gestureListener);
59 
60         /**
61          * Creates a new {@link TouchSession} that will receive any updates that would have been
62          * directed to this {@link TouchSession}.
63          * @return The future which will return a new {@link TouchSession} that will receive
64          * subsequent events. If the operation fails, {@code null} will be returned.
65          */
push()66         ListenableFuture<TouchSession> push();
67 
68         /**
69          * Explicitly releases this {@link TouchSession}. The registered listeners will no longer
70          * receive any further updates.
71          * @return The future containing the {@link TouchSession} that will receive subsequent
72          * events. This session will be the direct predecessor of the popped session. {@code null}
73          * if the popped {@link TouchSession} was the initial session or has already been popped.
74          */
pop()75         ListenableFuture<TouchSession> pop();
76 
77         /**
78          * Returns the number of currently active sessions.
79          */
getActiveSessionCount()80         int getActiveSessionCount();
81 
82         /**
83          * Returns the bounds of the display the touch region.
84          */
getBounds()85         Rect getBounds();
86     }
87 
88     /**
89      * Returns the region the touch handler is interested in. By default, no region is specified,
90      * indicating the entire screen should be considered.
91      * @param region A {@link Region} that is passed in to the target entry touch region.
92      */
getTouchInitiationRegion(Rect bounds, Region region)93     default void getTouchInitiationRegion(Rect bounds, Region region) {
94     }
95 
96     /**
97      * Informed a new touch session has begun. The first touch event will be delivered to any
98      * listener registered through
99      * {@link TouchSession#registerInputListener(InputChannelCompat.InputEventListener)} during this
100      * call. If there are no interactions with this touch session after this method returns, it will
101      * be dropped.
102      * @param session
103      */
onSessionStart(TouchSession session)104     void onSessionStart(TouchSession session);
105 }
106