1 /*
2  ** Copyright 2012, 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.server.accessibility;
18 
19 import android.view.KeyEvent;
20 import android.view.MotionEvent;
21 import android.view.accessibility.AccessibilityEvent;
22 
23 /**
24  * Interface for classes that can handle and potentially transform a stream of
25  * motion and accessibility events. Instances implementing this interface are
26  * ordered in a sequence to implement a transformation chain. An instance may
27  * consume, modify, and generate events. It is responsible to deliver the
28  * output events to the next transformation in the sequence set via
29  * {@link #setNext(EventStreamTransformation)}.
30  *
31  * Note that since instances implementing this interface are transformations
32  * of the event stream, an instance should work against the event stream
33  * potentially modified by previous ones. Hence, the order of transformations
34  * is important.
35  *
36  * It is a responsibility of each handler that decides to react to an event
37  * sequence and prevent any subsequent ones from performing an action to send
38  * the appropriate cancel event given it has delegated a part of the events
39  * that belong to the current gesture. This will ensure that subsequent
40  * transformations will not be left in an inconsistent state and the applications
41  * see a consistent event stream.
42  *
43  * For example, to cancel a {@link KeyEvent} the handler has to emit an event
44  * with action {@link KeyEvent#ACTION_UP} with the additional flag
45  * {@link KeyEvent#FLAG_CANCELED}. To cancel a {@link MotionEvent} the handler
46  * has to send an event with action {@link MotionEvent#ACTION_CANCEL}.
47  *
48  * It is a responsibility of each handler that received a cancel event to clear its
49  * internal state and to propagate the event to the next one to enable subsequent
50  * transformations to clear their internal state.
51  *
52  * It is a responsibility for each transformation to start handling events only
53  * after an event that designates the start of a well-formed event sequence.
54  * For example, if it received a down motion event followed by a cancel motion
55  * event, it should not handle subsequent move and up events until it gets a down.
56  */
57 interface EventStreamTransformation {
58 
59     /**
60      * Receives a motion event. Passed are the event transformed by previous
61      * transformations and the raw event to which no transformations have
62      * been applied.
63      *
64      * @param event The transformed motion event.
65      * @param rawEvent The raw motion event.
66      * @param policyFlags Policy flags for the event.
67      */
onMotionEvent(MotionEvent event, MotionEvent rawEvent, int policyFlags)68     default void onMotionEvent(MotionEvent event, MotionEvent rawEvent, int policyFlags) {
69         EventStreamTransformation next = getNext();
70         if (next != null) {
71             next.onMotionEvent(event, rawEvent, policyFlags);
72         }
73     }
74 
75     /**
76      * Receives a key event.
77      *
78      * @param event The key event.
79      * @param policyFlags Policy flags for the event.
80      */
onKeyEvent(KeyEvent event, int policyFlags)81     default void onKeyEvent(KeyEvent event, int policyFlags) {
82         EventStreamTransformation next = getNext();
83         if (next != null) {
84             next.onKeyEvent(event, policyFlags);
85         }
86     }
87 
88     /**
89      * Receives an accessibility event.
90      *
91      * @param event The accessibility event.
92      */
onAccessibilityEvent(AccessibilityEvent event)93     default void onAccessibilityEvent(AccessibilityEvent event) {
94         EventStreamTransformation next = getNext();
95         if (next != null) {
96             next.onAccessibilityEvent(event);
97         }
98     };
99 
100     /**
101      * Sets the next transformation.
102      *
103      * @param next The next transformation.
104      */
setNext(EventStreamTransformation next)105     public void setNext(EventStreamTransformation next);
106 
107     /**
108      * Gets the next transformation.
109      *
110      * @return The next transformation.
111      */
getNext()112     public EventStreamTransformation getNext();
113 
114     /**
115      * Clears internal state associated with events from specific input source.
116      *
117      * @param inputSource The input source class for which transformation state should be cleared.
118      */
clearEvents(int inputSource)119     default void clearEvents(int inputSource) {
120         EventStreamTransformation next = getNext();
121         if (next != null) {
122             next.clearEvents(inputSource);
123         }
124     }
125 
126     /**
127      * Destroys this transformation.
128      */
onDestroy()129     default void onDestroy() {}
130 }
131