1 /*
2  * Copyright (C) 2024 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.ambient.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 TouchHandler} 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 TouchHandler}
32  * stopping interception of gestures. If no gesture is intercepted, the session continues
33  * indefinitely. {@link TouchHandler} 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 TouchHandler {
37     /**
38      * A touch session captures the interaction surface of a {@link TouchHandler}. Clients
39      * register listeners as desired to participate in motion/gesture callbacks.
40      */
41     interface TouchSession {
42         interface Callback {
43             /**
44              * Invoked when the session has been removed.
45              */
onRemoved()46             void onRemoved();
47         }
48 
49         /**
50          * Registers a callback to be notified when there are updates to the {@link TouchSession}.
51          */
registerCallback(Callback callback)52         void registerCallback(Callback callback);
53 
54         /**
55          * Adds a input event listener for the given session.
56          * @param inputEventListener
57          */
registerInputListener(InputChannelCompat.InputEventListener inputEventListener)58         boolean registerInputListener(InputChannelCompat.InputEventListener inputEventListener);
59 
60         /**
61          * Adds a gesture listener for the given session.
62          * @param gestureListener
63          */
registerGestureListener(GestureDetector.OnGestureListener gestureListener)64         boolean registerGestureListener(GestureDetector.OnGestureListener gestureListener);
65 
66         /**
67          * Creates a new {@link TouchSession} that will receive any updates that would have been
68          * directed to this {@link TouchSession}.
69          * @return The future which will return a new {@link TouchSession} that will receive
70          * subsequent events. If the operation fails, {@code null} will be returned.
71          */
push()72         ListenableFuture<TouchSession> push();
73 
74         /**
75          * Explicitly releases this {@link TouchSession}. The registered listeners will no longer
76          * receive any further updates.
77          * @return The future containing the {@link TouchSession} that will receive subsequent
78          * events. This session will be the direct predecessor of the popped session. {@code null}
79          * if the popped {@link TouchSession} was the initial session or has already been popped.
80          */
pop()81         ListenableFuture<TouchSession> pop();
82 
83         /**
84          * Returns the number of currently active sessions.
85          */
getActiveSessionCount()86         int getActiveSessionCount();
87 
88         /**
89          * Returns the bounds of the display the touch region.
90          */
getBounds()91         Rect getBounds();
92     }
93 
94     /**
95      * Returns whether the handler is enabled to handle touch on dream.
96      * @return isEnabled state. By default it's true.
97      */
isEnabled()98     default Boolean isEnabled() {
99         return true;
100     }
101 
102     /**
103      * Sets whether to enable the handler to handle touch on dream.
104      * @param enabled new value to be set whether to enable the handler.
105      */
setIsEnabled(Boolean enabled)106     default void setIsEnabled(Boolean enabled){}
107 
108     /**
109      * Returns the region the touch handler is interested in. By default, no region is specified,
110      * indicating the entire screen should be considered.
111      * @param region A {@link Region} that is passed in to the target entry touch region.
112      */
getTouchInitiationRegion(Rect bounds, Region region, Rect exclusionRect)113     default void getTouchInitiationRegion(Rect bounds, Region region, Rect exclusionRect) {
114     }
115 
116     /**
117      * Informed a new touch session has begun. The first touch event will be delivered to any
118      * listener registered through
119      * {@link TouchSession#registerInputListener(InputChannelCompat.InputEventListener)} during this
120      * call. If there are no interactions with this touch session after this method returns, it will
121      * be dropped.
122      * @param session
123      */
onSessionStart(TouchSession session)124     void onSessionStart(TouchSession session);
125 }
126