blob: ba0a5b0b4fae51c9db63eb92596cffc8f75ae63d [file] [log] [blame]
// 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
/// + `view_controller` an optional request for a controller for the view
/// * 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(ViewSpec view_spec, request<ViewController>? view_controller)
-> () error PresentViewError;
};
/// An error returned when `GraphicalPresenter` fails to present a view.
enum PresentViewError {
/// The provided `ViewSpec` is malformed.
INVALID_ARGS = 1;
};
/// A description of a view that can be presented by a `GraphicalPresenter`.
resource table ViewSpec {
/// The view holder token for the presented view. Required.
1: fuchsia.ui.views.ViewHolderToken view_holder_token;
/// The `ViewRef` of the presented view. Required.
2: fuchsia.ui.views.ViewRef view_ref;
/// 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 {
// Provides control over the view's `annotations`.
//
// The presenter must observe incoming annotation requests and update
// the presentation accordingly.
//
// When calls to methods that update annotations return, clients can assume
// that the annotations have been incorporated into the presentation.
compose AnnotationController;
/// 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();
};