// Copyright 2023 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.element;

using fuchsia.ui.views;

/// An interface used to instruct a server to present graphical views, and observe
/// and control the view's lifecycle.
@discoverable
closed protocol GraphicalPresenter {
    /// Presents the view described by `view_spec`.
    ///
    /// If `view_controller_request` is provided, it will be connected to a `ViewController`
    /// implemented by the `GraphicalPresenter` server. When the view is dismissed,
    /// the `ViewController` channel is closed with a `ZX_OK`, at which point it is safe
    /// to clean up resources backing the view. To dismiss the view, the client should
    /// call `ViewController.Dismiss()` and wait for the `ZX_OK` epitaph.
    /// Not providing a `view_controller_request` handle will make it impossible for the
    /// client to observe the view's lifecycle.
    ///
    /// + `view_spec` describes the view to present
    /// + `annotation_controller` a handle to an `AnnotationController`, allowing the
    ///    `GraphicalPresenter` server to observe and update the view's annotations.
    /// + `view_controller_request` an optional request for a controller for the view
    /// * error `view_spec`  must contain `view_holder_token` and `view_ref` for Gfx views,
    ///   OR `viewport_creation_token` for Flatland views, but never both. If both are
    ///   set, error `PresentViewError.INVALID_ARGS` is returned.
    /// * error `PresentViewError.INVALID_ARGS` if `spec.view_holder_token` or
    ///   `spec.view_ref` are missing or invalid.
    strict PresentView(resource struct {
        view_spec ViewSpec;
        annotation_controller client_end:<AnnotationController, optional>;
        view_controller_request server_end:<ViewController, optional>;
    }) -> () error PresentViewError;
};

/// An error returned when `GraphicalPresenter` fails to present a view.
type PresentViewError = strict enum {
    /// The provided `ViewSpec` is invalid.
    INVALID_ARGS = 1;
};

/// A description of a view that can be presented by a `GraphicalPresenter`.
type ViewSpec = resource table {
    /// The view holder token for the presented Gfx view. Must be unset for
    /// Flatland views. One of `view_holder_token` or `viewport_creation_token`
    /// must be set.
    1: view_holder_token fuchsia.ui.views.ViewHolderToken;

    /// The `ViewRef` of the presented Gfx view. Must be unset for Flatland
    /// views.
    2: view_ref fuchsia.ui.views.ViewRef;

    /// The viewport creation token for the presented Flatland view. Must be
    /// unset for Gfx views. One of `view_holder_token` or `viewport_creation_token`
    /// must be set.
    4: viewport_creation_token fuchsia.ui.views.ViewportCreationToken;

    /// The initial annotations associated with the presented view. Updates to
    /// annotations are observed through the `AnnotationController` passed
    /// to `PresentView()`.
    ///
    /// Optional.
    3: annotations Annotations;
};

/// Gives clients of `GraphicalPresenter` control over an individual view
/// presented through `PresentView()`.
closed protocol ViewController {
    /// Instructs the presenter to dismiss the associated view. Once dismissed,
    /// the `ViewController` channel is closed with a `ZX_OK` epitaph. At this
    /// point, it is safe to clean up any resources (such as terminating
    /// a component) backing the view.
    ///
    /// Clients should call `Dismiss()` prior to closing the `ViewController`
    /// channel themselves.
    strict Dismiss();

    /// An event that signals that the view is now being presented.
    strict -> OnPresented();
};