// Copyright 2022 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.

/// # Physical keyboard events
///
/// Fuchsia's Keyboard service provides a mechanism for delivering physical keyboard
/// events to all interested clients.
///
/// ## Rendered Docs
///
/// * [FIDL](https://fuchsia.dev/reference/fidl/fuchsia.ui.input3)
/// * [Rust](https://fuchsia-docs.firebaseapp.com/rust/fidl_fuchsia_ui_input3/index.html)
///
/// ## Overview
///
/// Key events are delivered only to the components subscribed via `Keyboard` FIDL
/// protocol. Components interested in the service, should list FIDL service in the
/// components manifest, and it will be injected when the component is started.
///
/// Typical use-cases:
///
/// * TAB navigation between form fields.
/// * Arrow keys navigation in menus, lists.
/// * Pressing “f” to open a **F**ile from a menu.
/// * Closing popups on ESC.
/// * WASD navigation in games.
///
/// Media buttons, shortcuts, and text entry (IME) related events are delivered
/// separately via specialized interfaces.
///
/// Key events are only delivered to components in the Scenic focus chain.
/// Only focused components receive key events.
///
/// Key events are delivered in root to leaf order - i.e. parent components first.
///
/// Parent components have the ability to block further event propagation via
/// `KeyboardListener.OnKeyEvent` by returning `KeyEventStatus.Handled` to prevent
/// event’s propagation.
///
/// Clients are notified of keys being pressed or released via `Pressed` and
/// `Released` event types.
///
/// Clients are notified of keys pressed or released while client wasn't available
/// (e.g. not focused, or not started) via `Sync` and `Cancel` event types. Those
/// events will delivered for relevant events only, e.g. keys pressed and held while
/// client was not available.
///
/// ## Example
///
/// ```rust
/// use fidl_fuchsia_ui_input3 as ui_input;
///
/// let keyboard = connect_to_protocol::<ui_input::KeyboardMarker>()
///     .context("Failed to connect to Keyboard service")?;
///
/// let (listener_client_end, mut listener_stream) =
///     create_request_stream::<ui_input::KeyboardListenerMarker>()?;
///
/// keyboard.add_listener(view_ref, listener_client_end).await.expect("add_listener");
///
/// match listener_stream.next().await {
///     Some(Ok(ui_input::KeyboardListenerRequest::OnKeyEvent { event, responder, .. })) => {
///         assert_eq!(event.key, Some(fuchsia_input::Key::A));
///         responder.send(ui_input::Status::Handled).expect("response from key listener")
///     },
/// }
/// ```
@available(added=7)
library fuchsia.ui.input3;