| // 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(); |
| }; |