FileDocCategorySizeDatePackage
InputFilter.javaAPI DocAndroid 5.1 API10844Thu Mar 12 22:22:10 GMT 2015android.view

InputFilter

public abstract class InputFilter extends IInputFilter.Stub
Filters input events before they are dispatched to the system.

At most one input filter can be installed by calling {@link WindowManagerService#setInputFilter}. When an input filter is installed, the system's behavior changes as follows:

  • Input events are first delivered to the {@link WindowManagerPolicy} interception methods before queuing as usual. This critical step takes care of managing the power state of the device and handling wake keys.
  • Input events are then asynchronously delivered to the input filter's {@link #onInputEvent(InputEvent)} method instead of being enqueued for dispatch to applications as usual. The input filter only receives input events that were generated by an input device; the input filter will not receive input events that were injected into the system by other means, such as by instrumentation.
  • The input filter processes and optionally transforms the stream of events. For example, it may transform a sequence of motion events representing an accessibility gesture into a different sequence of motion events, key presses or other system-level interactions. The input filter can send events to be dispatched by calling {@link #sendInputEvent(InputEvent)} and passing appropriate policy flags for the input event.

The importance of input event consistency

The input filter mechanism is very low-level. At a minimum, it needs to ensure that it sends an internally consistent stream of input events to the dispatcher. There are very important invariants to be maintained.

For example, if a key down is sent, a corresponding key up should also be sent eventually. Likewise, for touch events, each pointer must individually go down with {@link MotionEvent#ACTION_DOWN} or {@link MotionEvent#ACTION_POINTER_DOWN} and then individually go up with {@link MotionEvent#ACTION_POINTER_UP} or {@link MotionEvent#ACTION_UP} and the sequence of pointer ids used must be consistent throughout the gesture.

Sometimes a filter may wish to cancel a previously dispatched key or motion. It should use {@link KeyEvent#FLAG_CANCELED} or {@link MotionEvent#ACTION_CANCEL} accordingly.

The input filter must take into account the fact that the input events coming from different devices or even different sources all consist of distinct streams of input. Use {@link InputEvent#getDeviceId()} and {@link InputEvent#getSource()} to identify the source of the event and its semantics. There may be multiple sources of keys, touches and other input: they must be kept separate.

Policy flags

Input events received from the dispatcher and sent to the dispatcher have policy flags associated with them. Policy flags control some functions of the dispatcher.

The early policy interception decides whether an input event should be delivered to applications or dropped. The policy indicates its decision by setting the {@link WindowManagerPolicy#FLAG_PASS_TO_USER} policy flag. The input filter may sometimes receive events that do not have this flag set. It should take note of the fact that the policy intends to drop the event, clean up its state, and then send appropriate cancellation events to the dispatcher if needed.

For example, suppose the input filter is processing a gesture and one of the touch events it receives does not have the {@link WindowManagerPolicy#FLAG_PASS_TO_USER} flag set. The input filter should clear its internal state about the gesture and then send key or motion events to the dispatcher to cancel any keys or pointers that are down.

Corollary: Events that get sent to the dispatcher should usually include the {@link WindowManagerPolicy#FLAG_PASS_TO_USER} flag. Otherwise, they will be dropped!

It may be prudent to disable automatic key repeating for synthetic key events by setting the {@link WindowManagerPolicy#FLAG_DISABLE_KEY_REPEAT} policy flag.

hide

Fields Summary
private static final int
MSG_INSTALL
private static final int
MSG_UNINSTALL
private static final int
MSG_INPUT_EVENT
private final android.view.InputEventConsistencyVerifier
mInboundInputEventConsistencyVerifier
private final android.view.InputEventConsistencyVerifier
mOutboundInputEventConsistencyVerifier
private final H
mH
private IInputFilterHost
mHost
Constructors Summary
public InputFilter(android.os.Looper looper)
Creates the input filter.

param
looper The looper to run callbacks on.


                     
       
        mH = new H(looper);
Methods Summary
public final voidfilterInputEvent(android.view.InputEvent event, int policyFlags)
Called to enqueue the input event for filtering. The event will be recycled after the input filter processes it. This method is guaranteed to be non-reentrant.

param
event The input event to enqueue.

        mH.obtainMessage(MSG_INPUT_EVENT, policyFlags, 0, event).sendToTarget();
public final voidinstall(IInputFilterHost host)
Called when the input filter is installed. This method is guaranteed to be non-reentrant.

param
host The input filter host environment.

        mH.obtainMessage(MSG_INSTALL, host).sendToTarget();
public voidonInputEvent(android.view.InputEvent event, int policyFlags)
Called when an input event has been received from the dispatcher.

The default implementation sends the input event back to the dispatcher, unchanged.

The event will be recycled when this method returns. If you want to keep it around, make a copy!

param
event The input event that was received.
param
policyFlags The input event policy flags.

        sendInputEvent(event, policyFlags);
public voidonInstalled()
Called when the filter is installed into the dispatch pipeline.

This method is called before the input filter receives any input events. The input filter should take this opportunity to prepare itself.
public voidonUninstalled()
Called when the filter is uninstalled from the dispatch pipeline.

This method is called after the input filter receives its last input event. The input filter should take this opportunity to clean up.
public voidsendInputEvent(android.view.InputEvent event, int policyFlags)
Sends an input event to the dispatcher.

param
event The input event to publish.
param
policyFlags The input event policy flags.

        if (event == null) {
            throw new IllegalArgumentException("event must not be null");
        }
        if (mHost == null) {
            throw new IllegalStateException("Cannot send input event because the input filter " +
                    "is not installed.");
        }
        if (mOutboundInputEventConsistencyVerifier != null) {
            mOutboundInputEventConsistencyVerifier.onInputEvent(event, 0);
        }
        try {
            mHost.sendInputEvent(event, policyFlags);
        } catch (RemoteException re) {
            /* ignore */
        }
public final voiduninstall()
Called when the input filter is uninstalled. This method is guaranteed to be non-reentrant.

        mH.obtainMessage(MSG_UNINSTALL).sendToTarget();