blob: a5da14303d53caa7b96ca372ec0f95433bc676b4 [file] [log] [blame]
// Copyright 2019 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.
@available(added=7)
library fuchsia.ui.focus;
using fuchsia.ui.views;
using zx;
/// A FocusChain tracks the status of the View hierarchy as View focus changes.
///
/// Reception. Only certain components may receive a FocusChain, as it
/// captures global information about the scene graph.
type FocusChain = resource table {
/// The `focus_chain` is reported in order of dominance in the View
/// hierarchy; each adjacent pair of elements represents a
/// parent-child relationship.
///
/// The `focus_chain` MAY be unset when `FocusChain` message is received, if
/// the message is sent very early in the scene setup, before the first
/// view is available.
///
/// When `focus_chain` is set, however, the root View is always present
/// and occupies slot 0 in the `focus_chain`. The newly-focused View
/// receives a `fuchsia.ui.input.FocusEvent` and occupies the final slot
/// in the vector.
///
/// If a View gets destroyed, a `FocusChain` holder that listens will
/// receive a `ZX_EVENTPAIR_PEER_CLOSED` signal on the corresponding
/// `ViewRef`.
///
/// ## Invalidation.
///
/// A FocusChain is invalid if any one if its ViewRefs is
/// invalid.
1: focus_chain vector<fuchsia.ui.views.ViewRef>;
};
/// A FocusChainListener receives an updated FocusChain when focus changes.
protocol FocusChainListener {
/// Sent when a focus change occurs. Since `focus_chain` may contain an
/// empty update, every handler MUST respond to the message even
/// if its contents are not immediately useful.
OnFocusChange(resource struct {
focus_chain FocusChain;
}) -> ();
};
/// A FocusChainListenerRegistry allows listening to FocusChain updates.
@discoverable
protocol FocusChainListenerRegistry {
Register(resource struct {
listener client_end:FocusChainListener;
});
};
/// A `FocusKoidChain` serves almost the same purpose as a `FocusChain`, but is
/// intended for applications that merely need to identify views in the chain
/// and do not need to watch their state.
type FocusKoidChain = table {
1: focus_chain vector<zx.koid>:MAX;
};
/// The `FocusChainProvider` protocol allows privileged clients to watch for
/// focus chain updates.
///
/// It is intended as an experimental solution for providing focus information
/// to the clipboard.
@discoverable
protocol FocusChainProvider {
/// Subscribe to changes in the focus chain (koids only) with a hanging-get
/// pattern.
///
/// The server responds immediately with the initial state, and afterwards
/// whenever a change occurs. Updates are not queued up for slow clients;
/// only the latest state is sent.
///
/// It is invalid to call this method while a previous call is pending.
/// Doing so will cause the server end of the protocol to be closed.
WatchFocusKoidChain(table {}) -> (FocusKoidChain);
};