// Copyright 2022 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.test.scene;

using fuchsia.ui.app;
using fuchsia.ui.observation.geometry;
using fuchsia.ui.views;
using zx;

/// Controls a UI test scene. Allows a test to attach test Views to the scene
/// and add View-related instrumentation.
@discoverable
closed protocol Controller {
    /// *** NOTE: `ViewProvider` is no longer the preferred way for a parent
    /// and child view to agree on a ViewportCreationToken / ViewCreationToken
    /// pair. Flatland-based clients are encouraged to use `PresentView` (below)
    /// instead of `AttachClientView`.
    ///
    /// Elicits the server to request a view using the
    /// `fuchsia.ui.app.ViewProvider` handle provided, and attach it to the
    /// scene.
    ///
    /// RETURN VALUE
    ///
    /// This method returns the KOID for the client view's `ViewRef`.
    ///
    /// SYNCHRONIZATION
    ///
    /// This call returns as soon as the client `ViewRef` is available. Note
    /// that this signal does NOT necessarily indicate that the view has been
    /// attached to the scene.
    ///
    /// LIFE CYCLE
    ///
    /// Clients may drop the `Controller` connection once `AttachClientView` has
    /// returned.
    strict AttachClientView(resource table {
        1: view_provider client_end:fuchsia.ui.app.ViewProvider;
    }) -> (struct {
        view_ref_koid zx.Koid;
    });

    /// Elicits the server to create a viewport using `viewport_creation_token`.
    ///
    /// LIFE CYCLE
    ///
    /// Clients may drop the `Controller` connection once `PresentClientView` has
    /// returned.
    @available(added=10)
    strict PresentClientView(resource table {
        @available(added=10)
        1: viewport_creation_token fuchsia.ui.views.ViewportCreationToken;
    });

    /// Registers a `ViewTreeWatcher` on the client's behalf.
    ///
    /// The `ViewTreeWatcher` registered on behalf of the client will currently
    /// be scoped globally; we intend to restrict the scope to the client view's
    /// subtree as soon as it's feasible to do so.
    ///
    /// For more information on geometry observation, see the documentation
    /// in //sdk/fidl/fuchsia.ui.observation.geometry/watcher.fidl.
    strict RegisterViewTreeWatcher(resource struct {
        watcher server_end:fuchsia.ui.observation.geometry.ViewTreeWatcher;
    }) -> ();

    /// A hanging get to watch for updates to view presentation.
    ///
    /// Callers can use this method to wait until a `ClientView` has
    /// `Present()`-ed through any of the following view presentation methods:
    ///   * `fuchsia.ui.test.scene.Controller/AttachClientView()`
    ///   * `fuchsia.ui.test.scene.Controller/PresentClientView()`
    ///   * `fuchsia.element.GraphicalPresenter/PresentView()`
    ///
    /// Callers should expect to call this method once for each view they
    /// expect to wait for.
    ///
    /// Note that callers must take care when interleaving calls, since
    /// this method has no way to
    ///   a) associate a `Present()` with a specific `ClientView`, or
    ///   b) associate a `Present()` with an `AttachClientView()` call, rather
    ///    than a `PresentClientView()` or `PresentView` call.
    ///
    /// It is invalid to call `WatchViewPresentation` while a previous call is
    /// still pending; subsequent requests will be ignored.
    @available(added=19)
    strict WatchViewPresentation() -> ();
};