| // Copyright 2016 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.viewsv1; |
| |
| using fuchsia.mem; |
| |
| using fuchsia.ui.viewsv1token; |
| |
| // A view container is an interface exposed by |View| and |ViewTree| to |
| // manage their child views. Although |View| may have any number of children, |
| // a |ViewTree| can have at most one (its root view). |
| // |
| // EMBEDDING |
| // |
| // The following steps are required to embed another view as a child: |
| // |
| // 1. Obtain the |ViewOwner| belonging to the view you would like to embed. |
| // The means for doing this is not specified by the view system. |
| // You might create another view of your own to embed or connect to |
| // another application using a mechanism such as |ViewProvider| (or |
| // any suitable agreed-upon protocol) to create the view to embed. |
| // |
| // 2. Call |AddChild()| to add the view you would like to embed and assign |
| // it a unique key. |
| // |
| // 3. Call |SetChildProperties()| to provide layout parameters and other |
| // properties for the new child using the same key that was provided |
| // to |AddChild()|. |
| // |
| // 4. Watch for the child becoming unavailable, as reported by |
| // |OnChildUnavailable()|, which indicates that the child is no longer |
| // in a usable state (perhaps the application which provided it has |
| // stopped). When this happens, you are still responsible for calling |
| // |RemoveChild()| to remove the child and discard any state that your |
| // view has associated with it. |
| // |
| // VIEW PROPERTIES AND LAYOUT |
| // |
| // The container controls the presentation of its children by setting |
| // |ViewProperties| for each of them. View properties include layout |
| // information and other parameters the child needs to know to participate |
| // in the view hierarchy. |
| // |
| // The container must set properties for each of its children after adding |
| // them, as otherwise the children cannot be rendered (since they lack enough |
| // context to know what to draw). |
| protocol ViewContainer { |
| // Sets the view container listener, or null to remove. |
| SetListener(ViewContainerListener? listener); |
| |
| // Adds the view referenced by |child_view_owner| as a child and assigns |
| // it the provided |child_key| to identify it among its children. |
| // The container may remove the child later by passing the same |child_key| |
| // to |RemoveChild()|. |
| // |
| // This method takes ownership of the view. |
| // |
| // It is important for the container to choose locally unique values for |
| // |child_key| to ensure that each child can be distinguished even as |
| // more children are added or removed. We recommend using a simple |
| // counter which is incremented on each (re-)addition. |
| // |
| // If the child becomes unavailable at any time prior to being removed |
| // then an |OnChildUnavailable()| message will be sent. |
| // |
| // If |child_view_owner| refers to a view which is already unavailable or |
| // if adding the view would create a cycle in the view tree then the |
| // call proceeds as if it succeeded but an |OnChildUnavailable()| message |
| // will be sent. |
| // |
| // If |child_view_owner| refers to a view which already has a container or is |
| // the root of a view tree then an |OnChildUnavailable()| message will |
| // be sent to its old container or root and the view will be |
| // (re-)added to its new container as usual. This special case also |
| // applies when the specified view is already a child of this view, in which |
| // case the behavior is similar to the view having been transferred to |
| // some other container and then back again. |
| // |
| // Note that an unavailable child will remain in its container's list of |
| // children until its container explicitly calls |RemoveChild()| to remove |
| // it. |
| // |
| // |host_import_token| is an import token which the view manager will |
| // use to import the node to which the child view's content should |
| // be attached. |
| // |
| // To establish the graphical embedding relation, the container view |
| // must create an event pair, bind one endpoint to an |ExportResourceOp| |
| // associated with the node to which the child's content nodes will be |
| // attached as descendants, and pass the other endpoint to this method as |
| // |host_import_token|. |
| // |
| // It is an error to add a view whose |child_key| already appears |
| // in the view's list of children; the connection will be closed. |
| // |
| // It is an error to add more than one child to a |ViewTree|'s container; |
| // it can only have at most one child (its root). |
| // |
| // This method is deprecated in favor of the eventpair-based one below. |
| // TODO(SCN-1018): Remove this. |
| AddChild(uint32 child_key, |
| fuchsia.ui.viewsv1token.ViewOwner child_view_owner, |
| handle<eventpair> host_import_token); |
| |
| AddChild2(uint32 child_key, |
| handle<eventpair> view_holder_token, |
| handle<eventpair> host_import_token); |
| |
| // Removes the view referenced by |child_key| from the view's |
| // list of children. |
| // |
| // If |transferred_view_owner| is not null, associates it with the |
| // previously added child to allow it to be transferred elsewhere or |
| // closes the |transferred_view_owner| channel if there was none. |
| // |
| // It is an error to remove a view whose |child_key| does not appear |
| // in the container's list of children; the connection will be closed. |
| // |
| // This method is deprecated in favor of the eventpair-based one below. |
| // TODO(SCN-1018): Remove this. |
| RemoveChild(uint32 child_key, |
| request<fuchsia.ui.viewsv1token.ViewOwner>? transferred_view_owner); |
| |
| RemoveChild2(uint32 child_key, |
| handle<eventpair>? transferred_view_holder_token); |
| |
| // Sets view properties for the child, such as layout constraints. |
| // |
| // This method must be called at least once after a child is added to |
| // set the view's properties before it can be rendered. Rendering for |
| // children without properties is blocked until properties are set. |
| // |
| // The |child_view_properties| specifies the properties for the child, or |
| // null to remove the properties from the child which will cause rendering |
| // of the child's scene to be blocked until new properties are set. |
| // |
| // It is an error to specify a |child_key| that does not appear in |
| // the container's list of children; the connection will be closed. |
| // |
| // It is an error to specify malformed |child_view_properties| such |
| // as invalid layout properties; the connection will be closed. |
| SetChildProperties(uint32 child_key, ViewProperties? child_view_properties); |
| |
| // WIP API |
| // Sends a hint about a pending size change to the given node and all nodes |
| // below. This is generally sent before an animation. |
| // |
| // |width_change_factor| and |height_change_factor| is how much bigger or smaller |
| // the item is expected to be in the near future. This one number encapsulate |
| // both changes in scale, as well as changes to layout width and height. |
| // |
| // It is an error to specify a |child_key| that does not appear in |
| // the container's list of children; the connection will be closed. |
| // |
| SendSizeChangeHintHACK(uint32 child_key, float32 width_change_factor, |
| float32 height_change_factor); |
| |
| // Request the snapshot of the child view. |
| RequestSnapshotHACK(uint32 child_key)-> (fuchsia.mem.Buffer data); |
| }; |
| |
| // An interface clients may implement to receive events from a view container. |
| protocol ViewContainerListener { |
| // Called when a child view is attached along with embedding information. |
| // |
| // This method will be called at most once after the child is added. |
| // |
| // The implementation should invoke the callback once the event has |
| // been handled. |
| OnChildAttached(uint32 child_key, ViewInfo child_view_info) -> (); |
| |
| // Called when a child view has become unavailable. |
| // |
| // A child may become unavailable for many reasons such being unregistered |
| // by its application, abnormal termination of its application, or |
| // cycles being introduced in the view tree. |
| // |
| // To complete removal of an unavailable child, this view component must |
| // call RemoveChild() on its view with |child_key|. |
| // |
| // The implementation should invoke the callback once the event has |
| // been handled. |
| OnChildUnavailable(uint32 child_key) -> (); |
| |
| // TODO(jeffbrown): Once we figure out measurement, add a |OnChildResized| |
| // event or similar to allow the container to get the size along with the |
| // scene version. |
| }; |
| |
| // Provides embedding information about a view for use by its container. |
| // |
| // This information is valid until the container removes the view. |
| struct ViewInfo { |
| }; |