// Copyright 2020 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 present graphical views.
///
/// The `GraphicalPresenter` protocol is typically implemented by a session component or
/// its child that presents element views.
///
/// The presented views can be annotated with `fuchsia.element.Annotations` to communicate
/// presentation properties to the `GraphicalPresenter`.
@discoverable
protocol GraphicalPresenter {
    /// Presents the view described by `view_spec`.
    ///
    /// ## ViewController
    ///
    /// `view_controller` allows clients to receive a `ViewController` for the
    /// presented view. The client can use the `ViewController` to control the view's
    /// presentation and receive events.
    ///
    /// If `view_controller` is closed, the client can assume that the view is
    /// no longer being presented, and will not be presented in the future.
    ///
    /// If the client closes the `view_controller`, or does not provide a request
    /// to `PresentView`, the view may be dismissed at any time with no signal to the client.
    ///
    /// ## Errors
    ///
    /// `PresentView` errors are signaled by closing `view_controller`
    /// with an epitaph, `ViewControllerEpitaph`. See [`ViewController`].
    ///
    /// + `view_spec` describes the view to present
    /// + `annotation_controller` a handle to make changes to the respective element'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 thrown.
    /// * error `PresentViewError.INVALID_ARGS` if `spec.view_holder_token` or
    ///   `spec.view_ref` are missing or invalid
    /// * error `PresentViewError` if the view could not be presented
    PresentView(resource struct {
        view_spec ViewSpec;
        annotation_controller client_end:<AnnotationController, optional>;
        view_controller_request server_end:<ViewController, optional>;
    }) -> (struct {}) error PresentViewError;
};

/// An error returned when `GraphicalPresenter` fails to present a view.
type PresentViewError = strict enum {
    /// The provided `ViewSpec` is malformed.
    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.
    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.
    4: viewport_creation_token fuchsia.ui.views.ViewportCreationToken;

    /// The annotations associated with the presented view.
    ///
    /// The presenter must observe incoming annotations and update the presentation
    /// accordingly.
    ///
    /// For views that come from elements, the annotations are expected to be the same
    /// as the annotations for the element. For example, if the `GraphicalPresenter`
    /// component uses `ElementManager` to add an element to the session, and gives it
    /// an annotation, the presenter can expect that annotation to be passed back in
    /// `ViewSpec.annotations` for the associated view.
    ///
    /// Optional.
    3: annotations Annotations;
};

/// An interface that gives clients of `GraphicalPresenter` control over a view
/// that was presented.
///
/// ## Lifecycle
///
/// The client must keep `ViewController` connected to ensure the view is
/// presented. Once `ViewController` is closed, the view will be
/// permanently dismissed.
///
/// For example, if the view originates from an element, the component
/// that manages the element's lifecycle may choose to stop the element's
/// component once the `ViewController` is closed.
///
/// ## Epitaph
///
/// This protocol is closed with an epitaph:
///
/// * `ZX_OK` when the view is dismissed
protocol ViewController {
    /// Instructs the presenter to dismiss the associated view.
    ///
    /// This call results in the `ViewController` being closed with a
    /// `ZX_OK` epitaph once any exit animation has been performed, the
    /// view/view holder connection has been severed, and the component
    /// instance serving the view can be terminated.
    Dismiss();

    /// Informs the view controller that the view was presented successfully.
    -> OnPresented();
};