mozart: Introduce new view manager interfaces. This change adds mojom interfaces for the new Mozart view manager. Mozart is different from the old view manager in several ways: - It does not require a C++ client library to use it. - The overall design is more centralized. The view manager keeps track of the state of all views and mediates interactions between them. This significantly reduces the complexity of using these interfaces safely. - The view manager supports basic layout negotiations between views. - Only view management concerns are addressed by the core view interfaces. Other concerns, such as input, will be addressed by services which are associated with views but managed separately. R=abarth@chromium.org, jamesr@chromium.org Review URL: https://codereview.chromium.org/1410693003 .
diff --git a/mojo/services/mojo_services.gni b/mojo/services/mojo_services.gni index f2bdddc..e55533d 100644 --- a/mojo/services/mojo_services.gni +++ b/mojo/services/mojo_services.gni
@@ -40,6 +40,7 @@ "//mojo/services/surfaces/interfaces", "//mojo/services/terminal/interfaces", "//mojo/services/tracing/interfaces", + "//mojo/services/ui/views/interfaces", "//mojo/services/url_response_disk_cache/interfaces", "//mojo/services/vanadium/security/interfaces", "//mojo/services/view_manager/interfaces",
diff --git a/mojo/services/ui/views/interfaces/BUILD.gn b/mojo/services/ui/views/interfaces/BUILD.gn new file mode 100644 index 0000000..07ac010 --- /dev/null +++ b/mojo/services/ui/views/interfaces/BUILD.gn
@@ -0,0 +1,21 @@ +# Copyright 2015 The Chromium Authors. All rights reserved. +# Use of this source code is governed by a BSD-style license that can be +# found in the LICENSE file. + +import("//build/module_args/mojo.gni") +import("$mojo_sdk_root/mojo/public/tools/bindings/mojom.gni") + +mojom("interfaces") { + sources = [ + "layouts.mojom", + "view_manager.mojom", + "view_provider.mojom", + "view_trees.mojom", + "views.mojom", + ] + + deps = [ + "../../../geometry/interfaces", + "../../../surfaces/interfaces:surface_id", + ] +}
diff --git a/mojo/services/ui/views/interfaces/layouts.mojom b/mojo/services/ui/views/interfaces/layouts.mojom new file mode 100644 index 0000000..7a6a177 --- /dev/null +++ b/mojo/services/ui/views/interfaces/layouts.mojom
@@ -0,0 +1,73 @@ +// Copyright 2015 The Chromium Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +[DartPackage="mojo_services"] +module mojo.ui; + +import "mojo/services/geometry/interfaces/geometry.mojom"; +import "mojo/services/surfaces/interfaces/surface_id.mojom"; + +// Box constraints for layout. +// +// A box constraint allows a parent view to determine the size of its child +// by constraining its width and height. Each dimension is considered +// independently. If a constraint only admits a single value in one or both +// dimensions (because the minimum and maximum values are equal) then it is +// said to be "tight" in those dimension. +// +// A |Size| respects this constraint if, and only if, all of the following +// relations hold: +// +// size.width >= constraints.min_width +// size.width <= constraints.max_width +// size.height >= constraints.min_height +// size.height <= constraints.max_height +// +// The view manager validates all constraints before delivering them to a +// child view; it will close its connection if the parent view supplies +// constraints which are ill-formed. +struct BoxConstraints { + // The minimum width of the view in device pixels. + // Must be >= 0. + int32 min_width; + + // The maximum width of the view in device pixels. + // Must be >= |min_width|. + int32 max_width; + + // The minimum height of the view in device pixels. + // Must be >= 0. + int32 min_height; + + // The maximum height of the view in device pixels. + // Must be >= |min_height|. + int32 max_height; +}; + +// Layout parameters provided by a parent view to one of its children. +// +// TODO(jeffbrown): We will eventually need to pass a bunch more information +// such as theme colors, virtual light sources for shadows, elevation, and +// more. It is unclear whether we'll want to put that information here +// or somewhere else but it may be convenient to stash it here because we +// will already have an invalidation mechanism in place. +struct ViewLayoutParams { + // The size constraints for the child. + mojo.ui.BoxConstraints constraints; + + // The ratio between the size of one display device pixel to the size + // of one logical pixel, assuming pixels are square. This value changes + // in relation to display density and zoom level. + // Must be > 0. + float device_pixel_ratio = 1.0; +}; + +// Layout information for a view. +struct ViewLayoutInfo { + // The view's surface id for composition by the parent. + mojo.SurfaceId surface_id; + + // The actual size of the view in device pixels. + mojo.Size size; +};
diff --git a/mojo/services/ui/views/interfaces/view_manager.mojom b/mojo/services/ui/views/interfaces/view_manager.mojom new file mode 100644 index 0000000..0e45fe6 --- /dev/null +++ b/mojo/services/ui/views/interfaces/view_manager.mojom
@@ -0,0 +1,49 @@ +// Copyright 2015 The Chromium Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +[DartPackage="mojo_services"] +module mojo.ui; + +import "mojo/services/ui/views/interfaces/views.mojom"; +import "mojo/services/ui/views/interfaces/view_trees.mojom"; + +// The view manager is a service which manages trees of views. +// +// Before a view can be added to the view tree, it must first be registered +// with the view manager. Once registered, the view receives a token as a +// transferable reference to be provided to the view's intended container. +interface ViewManager { + // Registers a view with the view manager. + // + // When a view is registered, it receives its own host and a token + // to identify it. + // + // The |view_host| is used to configure the view and interact with its + // local environment. The view host is private to the view and should + // not be shared with anyone else. + // + // The |view_token| is used as a transferable reference which can + // be passed to the view's intended container as part of a request to + // add the view as a child. The view manager itself does not describe + // how this interaction should take place, only that the token should + // eventually be passed back through the container's view host interface + // as an argument to AddChild(). + // + // To unregister the view and cause it to be removed from the view tree, + // simply close the |view| and/or |view_host| message pipes. + RegisterView(mojo.ui.View view, + mojo.ui.ViewHost& view_host) => + (mojo.ui.ViewToken view_token); + + // Registers a view tree with the view manager. + // + // The |view_tree_host| is used to configure the view tree and interact + // with the views it contains. The view tree host is private to the view + // and should not be shared with anyone else. + // + // To unregister the view tree simply close the |view_tree| and/or + // |view_tree_host| message pipes. + RegisterViewTree(mojo.ui.ViewTree view_tree, + mojo.ui.ViewTreeHost& view_tree_host) => (); +};
diff --git a/mojo/services/ui/views/interfaces/view_provider.mojom b/mojo/services/ui/views/interfaces/view_provider.mojom new file mode 100644 index 0000000..b09ec92 --- /dev/null +++ b/mojo/services/ui/views/interfaces/view_provider.mojom
@@ -0,0 +1,30 @@ +// Copyright 2015 The Chromium Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +[DartPackage="mojo_services"] +module mojo.ui; + +import "mojo/public/interfaces/application/service_provider.mojom"; +import "mojo/services/ui/views/interfaces/views.mojom"; + +// Provides a View upon request. +// +// Applications should implement and expose this service so that they can +// expose views to be embedded into other applications. +interface ViewProvider { + // Creates and registers a view with the view manager and returns its + // view token (as provided by |ViewManager.RegisterView()|). + // + // Having received the view token, the caller should attach the view to + // a view tree and lay it out. + // + // The caller may provide services to the view via the |services| + // service provider. + // + // The caller may receive services from the view via the |exposed_services| + // service provider. + CreateView(mojo.ServiceProvider&? services, + mojo.ServiceProvider? exposed_services) => + (ViewToken view_token); +};
diff --git a/mojo/services/ui/views/interfaces/view_trees.mojom b/mojo/services/ui/views/interfaces/view_trees.mojom new file mode 100644 index 0000000..ac3439c --- /dev/null +++ b/mojo/services/ui/views/interfaces/view_trees.mojom
@@ -0,0 +1,92 @@ +// Copyright 2015 The Chromium Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +[DartPackage="mojo_services"] +module mojo.ui; + +import "mojo/services/ui/views/interfaces/layouts.mojom"; +import "mojo/services/ui/views/interfaces/views.mojom"; + +// A view tree is a top-level container for a hierarchy of views. +// +// A view tree must registered with the view manager before it can be shown. +interface ViewTree { + // Called when the tree needs to update its layout. + // + // This method may be called for one or more of the following reasons: + // + // 1. The root was just set. + // 2. The root produced different layout information during its last + // layout pass causing a recursive layout to occur. + // + // Layout requests are coalesced for efficiency. Certain intermediate + // updates may be dropped if the view tree is unable to keep up with them + // in a timely manner. Do nothing updates are always dropped. + // + // The implementation should invoke the callback once the event has + // been handled and the view tree is ready to be shown in its new aspect. + OnLayout() => (); + + // Called when the root view has become unavailable. + // + // The root may become unavailable for many reasons such being unregistered + // by its application, abnormal termination of its application, or + // being reparented into a different view tree. + // + // The implementation should invoke the callback once the event has + // been handled. + OnRootUnavailable(uint32 root_key) => (); +}; + +// The view tree host provides an interface for a view tree to configure itself +// and interact with its views. +// +// Each view tree obtains its own view tree host when registered with the +// ViewManager. To unregister the view tree, close its view tree +// and/or view tree host message pipes. +interface ViewTreeHost { + // Requests that the view tree's OnLayout() method be called to compute a + // new layout due to a change in the view tree's layout information. + RequestLayout(); + + // Sets the root of the view tree and assigns it the provided |root_key| + // to distinguish it from any other roots this view tree has had. + // + // It is a good idea to provide a distinct |root_key| each time a new root + // is set so that callbacks related to the root can be clearly distinguished + // across these changes. + // + // If |root_view_token| refers to a view which is already unavailable + // then the call proceeds as if it succeeded but an OnChildUnavailable() + // message will be sent. + // + // If |root_view_token| refers to a view which already has a parent or is + // the root of a view tree then an OnChildUnavailable() or OnRootUnavailable() + // message will be sent to its old parent or root and the the view will be + // used as the root of the new view tree as usual. This special case also + // applies when the specified view is already the root of this view tree, in + // which case the behavior is similar to the view having been transferred to + // some other view tree and then back again. + SetRoot(uint32 root_key, mojo.ui.ViewToken root_view_token); + + // Removes the root of the view tree. + // + // Does nothing if the view tree currently does not have a root. + ResetRoot(); + + // Sets the layout parameters of the root of the view tree and retrieves + // its layout information. + // + // The returned |info| is null if this layout request was canceled either + // because it has been superceded by a subsequently issued layout request + // or because the root has become unavailable. + // + // It is an error to call this function if the view tree does not currently + // have a root; the connection will be closed. + // + // It is an error to specify malformed |root_layout_params| such + // as invalid size constraints; the connection will be closed. + LayoutRoot(mojo.ui.ViewLayoutParams root_layout_params) => + (mojo.ui.ViewLayoutInfo? info); +};
diff --git a/mojo/services/ui/views/interfaces/views.mojom b/mojo/services/ui/views/interfaces/views.mojom new file mode 100644 index 0000000..49ca841 --- /dev/null +++ b/mojo/services/ui/views/interfaces/views.mojom
@@ -0,0 +1,167 @@ +// Copyright 2015 The Chromium Authors. All rights reserved. +// Use of this source code is governed by a BSD-style license that can be +// found in the LICENSE file. + +[DartPackage="mojo_services"] +module mojo.ui; + +import "mojo/public/interfaces/application/service_provider.mojom"; +import "mojo/services/ui/views/interfaces/layouts.mojom"; + +// A view token is an opaque transferable reference to a view. +// +// The ViewManager provides each view with a unique view token when +// it is registered. The token can subsequently be passed to other +// applications and may be used to add the view as a child of some +// other view or to set it as the root of a view tree. +// +// View tokens should be kept secret and should only be shared with +// the view's intended container. +// +// TODO(jeffbrown): This implementation is a temporary placeholder until +// we extend Mojo to provide a way to create tokens which cannot be forged. +struct ViewToken { + uint32 value; +}; + +// A view is a graphical user interface component which is responsible +// for drawing and supporting user interactions in the area of the screen +// that it occupies. +// +// A view may also act as a container for other views (known as the +// view's children) which it may freely layout and position anywhere +// within its bounds to form a composite user interface. The hierarchy +// of views thus formed is called a view tree. +// +// A view must registered with the view manager before it can be shown. +interface View { + // Called when the view needs to update its layout and provide its size. + // + // This method may be called for one or more of the following reasons: + // + // 1. The view called RequestLayout() to mark itself as needing layout. + // 2. The view's parent called LayoutChild() for the first time to + // provide layout parameters to this view. + // 3. The view's parent called LayoutChild() and provided a + // set of layout parameters which differ from its prior call to + // OnLayout(). + // 4. One or more of the view's children were just added to the view + // tree using AddChild() or removed from the tree using RemoveChild(). + // 5. One or more of the view's children produced different layout + // information during their last layout pass causing a recursive + // layout to occur. + // + // The |children_needing_layout| array includes the keys of all children + // which require a layout. The view is responsible for calling LayoutChild() + // at least once for each child in the array in addition to any other + // children which might also need to be updated. + // + // Layout requests are coalesced for efficiency. Certain intermediate + // updates may be dropped if the view is unable to keep up with them + // in a timely manner. Do nothing updates are always dropped. + // + // The implementation should invoke the callback once the event has + // been handled and the view is ready to be shown in its new aspect. + // + // The result of the layout may cause the parent's layout to be invalidated. + // When this happens, the parent's own OnLayout() method will be called + // and will be informed that this child needs layout. + // + // Recursive layout happens in any of the following circumstances: + // + // 1. If the resulting surface has changed since the last layout. + // 2. If the resulting size has changed since the last layout. + // + // It is an error to return a malformed |info| which does not satisfy + // the requested |layout_params|, such as by returning a size which + // exceeds the requested constraints; the view's connection will be closed. + OnLayout(mojo.ui.ViewLayoutParams layout_params, + array<uint32> children_needing_layout) => (mojo.ui.ViewLayoutInfo 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 host with |child_key|. + // + // The implementation should invoke the callback once the event has + // been handled. + OnChildUnavailable(uint32 child_key) => (); +}; + +// The view host provides an interface for a view to configure itself and +// interact with its local environment, such as adding and removing +// children and specifying layout constraints. +// +// Each view obtains its own view host when registered with the ViewManager. +// To unregister the view, close its view host message pipe. +interface ViewHost { + // Gets a service provider to access services which are associated with + // the view such as input, accessibility and editing capabilities. + // The view service provider is private to the view and should not be + // shared with anyone else. + GetServiceProvider(mojo.ServiceProvider& service_provider); + + // Requests that the view's OnLayout() method be called to compute a + // new layout due to a change in the view's layout information. + RequestLayout(); + + // Adds the view referenced by |child_view_token| as a child and assigns + // it the provided |child_key| to identify it among its children. + // The parent may remove the child later by passing the same |child_key| + // to RemoveChild(). + // + // It is important for the parent 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_token| 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_token| refers to a view which already has a parent or is + // the root of a view tree then an OnChildUnavailable() or OnRootUnavailable() + // message will be sent to its old parent or root and the the view will be + // (re-)added to its new parent 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 parent and then back again. + // + // Note that an unavailable child will remain in its parent's list of + // children until its parent explicitly calls RemoveChild() to remove + // it. + // + // 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. + AddChild(uint32 child_key, mojo.ui.ViewToken child_view_token); + + // Removes the view referenced by |child_key| from the view's + // list of children. + // + // It is an error to remove a view whose |child_key| does not appear + // in the parent's list of children; the connection will be closed. + RemoveChild(uint32 child_key); + + // Sets the layout parameters of the child view referenced by |child_key| + // and retrieves its layout information. + // + // The returned |info| is null if this layout request was canceled either + // because it has been superceded by a subsequently issued layout request + // or because the child has become unavailable. + // + // It is an error to specify a |child_key| that does not appear in + // the parent's list of children; the connection will be closed. + // + // It is an error to specify malformed |child_layout_params| such + // as invalid size constraints; the connection will be closed. + LayoutChild(uint32 child_key, mojo.ui.ViewLayoutParams child_layout_params) + => (mojo.ui.ViewLayoutInfo? info); +};