public abstract class InputFilter
extends IInputFilter.Stub
At most one input filter can be installed by calling
WindowManagerService#setInputFilter
. When an input filter is installed, the
system's behavior changes as follows:
WindowManagerPolicy
interception methods before queuing as usual. This critical step takes care of managing
the power state of the device and handling wake keys.#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.#sendInputEvent(InputEvent)
and passing appropriate policy flags for the
input event.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
MotionEvent.ACTION_DOWN
or MotionEvent.ACTION_POINTER_DOWN
and then
individually go up with MotionEvent.ACTION_POINTER_UP
or 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 KeyEvent.FLAG_CANCELED
or 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 InputEvent.getDeviceId()
and 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.
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
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 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
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 WindowManagerPolicy.FLAG_DISABLE_KEY_REPEAT
policy flag.
Constructor and Description |
---|
InputFilter(Looper looper)
Creates the input filter.
|
Modifier and Type | Method and Description |
---|---|
void |
filterInputEvent(InputEvent event,
int policyFlags)
Called to enqueue the input event for filtering.
|
void |
install(IInputFilterHost host)
Called when the input filter is installed.
|
void |
onInputEvent(InputEvent event,
int policyFlags)
Called when an input event has been received from the dispatcher.
|
void |
onInstalled()
Called when the filter is installed into the dispatch pipeline.
|
void |
onUninstalled()
Called when the filter is uninstalled from the dispatch pipeline.
|
void |
sendInputEvent(InputEvent event,
int policyFlags)
Sends an input event to the dispatcher.
|
void |
uninstall()
Called when the input filter is uninstalled.
|
public InputFilter(Looper looper)
looper
- The looper to run callbacks on.public final void install(IInputFilterHost host)
host
- The input filter host environment.public final void uninstall()
public final void filterInputEvent(InputEvent event, int policyFlags)
event
- The input event to enqueue.public void sendInputEvent(InputEvent event, int policyFlags)
event
- The input event to publish.policyFlags
- The input event policy flags.public void onInputEvent(InputEvent event, int policyFlags)
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!
event
- The input event that was received.policyFlags
- The input event policy flags.public void onInstalled()
This method is called before the input filter receives any input events. The input filter should take this opportunity to prepare itself.
public void onUninstalled()
This method is called after the input filter receives its last input event. The input filter should take this opportunity to clean up.