| // Copyright 2019 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.ui.app; |
| |
| using zx; |
| |
| /// A View is an interface that a component implements to offer a Scenic |
| /// view to its clients. A Scenic view is container of Scenic graph nodes, |
| /// which, when rendered, might display a graphical user interface, such |
| /// as a module, shell, or on-screen keyboard. |
| /// |
| /// A client of the `View` interface will: |
| /// |
| /// 1. Launch (or bind to) the component that provides the interface. |
| /// 2. Connect to the component's `View` interface. |
| /// 3. Call `SetConfig()` at least once to configure the view's presentation |
| /// parameters. |
| /// 4. Call `AttachView()` to ask the `View` to attach its graphical |
| /// content to the Scenic scene graph using the provided `view_token`. |
| /// 5. Optionally, while the View is attached, call `SetConfig()` again to |
| /// modify any presentation parameters as needed. |
| /// |
| /// When the client no longer needs the View, it should disconnect from |
| /// the interface and terminate (or unbind) from the component. |
| /// |
| /// NOTE: Unlike with `ViewProvider`, the client owns the `View` instance and |
| /// must retain it for the lifetime of the UI that it displays. If the `View` |
| /// instance is destroyed, the connection will be dropped. |
| /// |
| /// On the implementation side, a component that exposes the |
| /// `View` interface has the following responsibilities: |
| /// |
| /// * Initialize and attach the View's content to the Scenic scene graph |
| /// using the `fuchsia.ui.view.CreateViewCmd` and passing the provided |
| /// `view_token`. |
| /// * Adjust the appearance and/or contents of the view's content whenever |
| /// its `ViewConfig` changes. |
| /// * Provide graphical content for the view and handle user interface |
| /// events such as touches, key presses, and `fuchsia.ui.view.ViewProperty` |
| /// changes using other Scenic interfaces such as `fuchsia.ui.Scenic` |
| /// and `fuchsia.ui.SessionListener`. |
| /// |
| /// TODO(fxbug.dev/24402): Migrate all implementations of `ViewProvider` to use `View`. |
| @discoverable |
| protocol View { |
| /// Updates the View's configuration. |
| /// |
| /// To prevent triggering UI changes shortly after a client starts up, the |
| /// View's client should set the configuration prior to calling |
| /// `AttachView()` unless the default is adequate. |
| /// |
| /// May be called again at any time to modify the view's configuration. |
| SetConfig(struct { |
| config ViewConfig; |
| }); |
| |
| /// Attaches the View to Scenic's scene graph. Must only be called once per |
| /// `View` lifetime. |
| /// |
| /// The View's implementation should pass the `view_token` to Scenic |
| /// using a `fuchsia.ui.view.CreateViewCmd`. |
| Attach(resource struct { |
| view_token zx.handle:EVENTPAIR; |
| }); |
| }; |