blob: 4faed02eac2110a0019f54ff80d63828a9ad3c4b [file] [log] [blame]
// Copyright 2020 The Fuchsia Authors. All rights reserved.
// Use of this source code is governed by a BSD-style license that can be
// found in the LICENSE file.
library fuchsia.ui.input3;
using fuchsia.ui.views;
/// Components may request this service from their namespace to be notified of
/// physical key events.
protocol Keyboard {
/// Add a key event listener for the specified View.
/// If multiple listeners are added, each will receive key events independently and
/// should respond with a `Status`.
/// The client calling `AddListener` should keep the connection to `Keyboard` alive
/// for as long as the events from `KeyboardListener` need to be received. Dropping the
/// connection to the `Keyboard` protocol will terminate `KeyboardListener` as well.
AddListener(resource struct {
view_ref fuchsia.ui.views.ViewRef;
listener client_end:KeyboardListener;
}) -> ();
/// Client should implement this protocol to get notified of key events.
protocol KeyboardListener {
/// Called when a key event takes place, such as key press or release.
/// Protocol implementers must respond to acknowledge the event by returning Status
/// in a timely manner, i.e. not introducing significant delays to the
/// input pipeline (typically 10s of milliseconds).
/// Returning `NOT_HANDLED` means the event will propagate to another client or listener.
/// Clients that do not acknowledge their events will eventually be disconnected.
/// Notification is only dispatched when the View is focused (ViewRef is on FocusChain).
/// Parent Views receive the notification first, child Views last.
/// Returning `HANDLED` will stop event propagation to other clients and listeners.
OnKeyEvent(struct {
event KeyEvent;
}) -> (struct {
status KeyEventStatus;
/// Provides the ability to inject `KeyEvent`s into the keyboard subsystem.
/// # Roles
/// This protocol will typically be:
/// * Implemented by platform components which process and deliver keyboard
/// events.
/// * Consumed by components which originiate keyboard events. E.g.
/// an on-screen keyboard, or the Session Framework Input Pipeline.
/// # Related protocols
/// This protocol should be using in preference to legacy protocols which provide
/// similar functionality. Specifically, this means this protocol should be preferred
/// over
/// * `fuchsia.ui.input.ImeService` which provides `InjectInput()`, `DispatchKey()`,
/// and `DispatchKey3()`
/// * `fuchsia.ui.input.InputMethodEditor`, which provides `InjectInput()` and
/// `DispatchKey3()`
/// # Notes
/// Products should take care to limit access to this protocol, as events injected
/// with this protocol are indistinguishable from those coming from physical devices.
protocol KeyEventInjector {
/// Inject an event into the keyboard subsystem.
/// # Returns
/// * `HANDLED` if the keyboard subsystem delivered the event to a consumer,
/// and the consumer reported that it `HANDLED` the event
/// * `NOT_HANDLED` if the keyboard subsystem did not deliever the event to
/// any consumers, or no consumer reported that it `HANDLED` the event.
Inject(struct {
key_event KeyEvent;
}) -> (struct {
status KeyEventStatus;
/// Return type for clients key events listener.
/// We do not expect new values to be added to this enum.
type KeyEventStatus = strict enum {
/// The key event was handled and its further propagation should be stopped.
/// The key event wasn't handled and should be delivered to other clients or listeners.