Home | History | Annotate | Download | only in accessibility 
      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      */
     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      */
     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      */
     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      */
    105     public void setNext(EventStreamTransformation next);
    106 
    107     /**
    108      * Gets the next transformation.
    109      *
    110      * @return The next transformation.
    111      */
    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      */
    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      */
    129     default void onDestroy() {}
    130 }
    131