// Copyright 2018 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 fuchsia.sys;
using fuchsia.ui.views;

/// ViewProvider is the standard mechanism for two modules to each obtain half
/// of a shared eventpair token.  The shared token is a capability allowing the
/// modules to ask Scenic to create a ViewHolder/View pair.  The resulting
/// View and ViewHolder are linked together until either one is destroyed.
///
/// Modules are free to use any other mechanism to agree upon the shared
/// eventpair token, and use this to create the linked ViewHolder/View.
/// ViewProvider is given for the convenience of clients that don't require
/// a more complex implementation.
[Discoverable]
protocol ViewProvider {
    /// Creates a new View under the control of the ViewProvider.
    ///
    /// `token` is one half of the shared eventpair which will bind the new View
    /// to its associated ViewHolder.  The ViewProvider will use `token` to
    /// create its internal View representation.  The caller is expected to use
    /// its half to create corresponding ViewHolder object.
    ///
    /// `incoming_services` allows clients to request services from the
    /// ViewProvider implementation.  `outgoing_services` allows clients to
    /// provide services of their own to the ViewProvider implementation.
    ///
    /// Clients can embed a ViewHolder (and by proxy the paired View) into their
    /// scene graph by using `Node.AddChild()`.  The ViewHolder cannot itself
    /// have any children. A ViewProvider implementation can nest scene objects
    /// within its View by using `View.AddChild()`.  The View itself
    /// cannot be a child of anything.
    ///
    /// Modules can use these mechanisms to establish a distributed,
    /// inter-process scene graph.
    CreateView(handle<eventpair> token,
               request<fuchsia.sys.ServiceProvider>? incoming_services,
               fuchsia.sys.ServiceProvider? outgoing_services);

    /// Creates a new View under the control of the ViewProvider.
    ///
    /// `token` is one half of the shared eventpair which will bind the new View
    /// to its associated ViewHolder.  The ViewProvider will use `token` to
    /// create its internal View representation.  The caller is expected to use
    /// its half to create corresponding ViewHolder object.
    ///
    /// `view_ref_control` and `view_ref` are two typed handles to each half of the
    /// same event pair. The `view_ref` can be cloned before passing it to this method,
    /// which will allow clients to track the view (e.g., in a focus chain update).
    ///
    /// `view_ref_control` must not have the ZX_RIGHT_DUPLICATE set, or view creation
    /// will fail.
    [Transitional]
    CreateViewWithViewRef(handle<eventpair> token,
                          fuchsia.ui.views.ViewRefControl view_ref_control,
                          fuchsia.ui.views.ViewRef view_ref);
};