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
17package com.android.server.accessibility;
18
19import android.view.KeyEvent;
20import android.view.MotionEvent;
21import 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 */
57interface EventStreamTransformation {
58
59    /**
60     * Receives 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     */
68    public void onMotionEvent(MotionEvent event, MotionEvent rawEvent, int policyFlags);
69
70    /**
71     * Receives an accessibility event.
72     *
73     * @param event The accessibility event.
74     */
75    public void onAccessibilityEvent(AccessibilityEvent event);
76
77    /**
78     * Sets the next transformation.
79     *
80     * @param next The next transformation.
81     */
82    public void setNext(EventStreamTransformation next);
83
84    /**
85     * Clears the internal state of this transformation.
86     */
87    public void clear();
88
89    /**
90     * Destroys this transformation.
91     */
92    public void onDestroy();
93}
94