sdk/fidl/fuchsia.ui.app/view_provider.fidl

// 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;
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
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(resource struct {
        token zx.handle:EVENTPAIR;
        incoming_services server_end:<fuchsia.sys.ServiceProvider, optional>;
        outgoing_services client_end:<fuchsia.sys.ServiceProvider, optional>;
    });

    /// 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(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(fxbug.dev/81959): use "resource table" syntax when it becomes available, thus getting
    // rid of the need for CreateView2Args.  Hopefully this will be done by the time we want to
    // rename CreateView2() to CreateView(), once the latter is deleted.
    @transitional
    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;
};