| // 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. |
| @discoverable |
| 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. |
| @discoverable |
| 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. |
| type KeyEventStatus = strict enum { |
| /// The key event was handled and its further propagation should be stopped. |
| HANDLED = 1; |
| |
| /// The key event wasn't handled and should be delivered to other clients or listeners. |
| NOT_HANDLED = 2; |
| }; |