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

/// 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(SCN-1198): 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(handle<eventpair> view_token);
};