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 public void onMotionEvent(MotionEvent event, MotionEvent rawEvent, int policyFlags); 69 70 /** 71 * Receives an accessibility event. 72 * 73 * @param event The accessibility event. 74 */ onAccessibilityEvent(AccessibilityEvent event)75 public void onAccessibilityEvent(AccessibilityEvent event); 76 77 /** 78 * Sets the next transformation. 79 * 80 * @param next The next transformation. 81 */ setNext(EventStreamTransformation next)82 public void setNext(EventStreamTransformation next); 83 84 /** 85 * Clears the internal state of this transformation. 86 */ clear()87 public void clear(); 88 89 /** 90 * Destroys this transformation. 91 */ onDestroy()92 public void onDestroy(); 93 } 94