// 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.ui.views;
using zx;

/// 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
closed 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.
    ///
    /// `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.
    @available(deprecated=13)
    strict CreateViewWithViewRef(resource struct {
        token zx.Handle:EVENTPAIR;
        view_ref_control fuchsia.ui.views.ViewRefControl;
        view_ref fuchsia.ui.views.ViewRef;
    });

    /// Creates a new View under the control of the ViewProvider.
    ///
    /// The args are provided as a table, for forward compatibility.  See documentation on the
    /// individual table fields.
    // TODO(https://fxbug.dev/42162471): Rename this to `CreateView()`.
    strict CreateView2(resource struct {
        args CreateView2Args;
    });
};

// Args for ViewProvider.CreateView2(), see above.
type CreateView2Args = resource table {
    /// Non-optional.  This token can be provided to Flatland to attach the client's child view
    /// to the parent's viewport.
    1: view_creation_token fuchsia.ui.views.ViewCreationToken;
};