| // 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 `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 view. Required. |
| 1: view_holder_token fuchsia.ui.views.ViewHolderToken; |
| |
| /// The `ViewRef` of the presented view. Required. |
| 2: view_ref fuchsia.ui.views.ViewRef; |
| |
| /// 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(); |
| }; |