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

library fuchsia.ui.app;

using zx;

/// A View is an interface that a component implements to offer a Scenic
/// view to its clients.  A Scenic view is container of Scenic graph nodes,
/// which, when rendered, might display a graphical user interface, such
/// as a module, shell, or on-screen keyboard.
///
/// A client of the `View` interface will:
///
/// 1. Launch (or bind to) the component that provides the interface.
/// 2. Connect to the component's `View` interface.
/// 3. Call `SetConfig()` at least once to configure the view's presentation
///    parameters.
/// 4. Call `AttachView()` to ask the `View` to attach its graphical
///    content to the Scenic scene graph using the provided `view_token`.
/// 5. Optionally, while the View is attached, call `SetConfig()` again to
///    modify any presentation parameters as needed.
///
/// When the client no longer needs the View, it should disconnect from
/// the interface and terminate (or unbind) from the component.
///
/// NOTE: Unlike with `ViewProvider`, the client owns the `View` instance and
/// must retain it for the lifetime of the UI that it displays. If the `View`
/// instance is destroyed, the connection will be dropped.
///
/// On the implementation side, a component that exposes the
/// `View` interface has the following responsibilities:
///
/// * Initialize and attach the View's content to the Scenic scene graph
///   using the `fuchsia.ui.view.CreateViewCmd` and passing the provided
///   `view_token`.
/// * Adjust the appearance and/or contents of the view's content whenever
///   its `ViewConfig` changes.
/// * Provide graphical content for the view and handle user interface
///   events such as touches, key presses, and `fuchsia.ui.view.ViewProperty`
///   changes using other Scenic interfaces such as `fuchsia.ui.Scenic`
///   and `fuchsia.ui.SessionListener`.
///
///  TODO(fxbug.dev/24402): Migrate all implementations of `ViewProvider` to use `View`.
[Discoverable]
protocol View {
    /// Updates the View's configuration.
    ///
    /// To prevent triggering UI changes shortly after a client starts up, the
    /// View's client should set the configuration prior to calling
    /// `AttachView()` unless the default is adequate.
    ///
    /// May be called again at any time to modify the view's configuration.
    SetConfig(ViewConfig config);

    /// Attaches the View to Scenic's scene graph. Must only be called once per
    /// `View` lifetime.
    ///
    /// The View's implementation should pass the `view_token` to Scenic
    /// using a `fuchsia.ui.view.CreateViewCmd`.
    Attach(zx.handle:EVENTPAIR view_token);
};