mozart: Introduce new view manager interfaces.

mojo/services/ui/views/interfaces/layouts.mojom

Index: mojo/services/ui/views/interfaces/layouts.mojom
diff --git a/mojo/services/ui/views/interfaces/layouts.mojom b/mojo/services/ui/views/interfaces/layouts.mojom
new file mode 100644
index 0000000000000000000000000000000000000000..75be093e3a87ea4f7302104667a089f2250a2a20
--- /dev/null
+++ b/mojo/services/ui/views/interfaces/layouts.mojom
@@ -0,0 +1,75 @@
+// 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 pixels.
+  // Must be >= 0.

[jamesr, 2015/10/26 19:35:38]

we could express this constraint in the type system - 'uint32'

[jeffbrown, 2015/10/27 01:49:07]

We could.  I was debating whether to use uint32 or int32.  I ultimately settled
on int32 to follow the pattern of mojo.Point and mojo.Rect which are likely to
be used in tandem with these box constraints.

In general I would like to avoid situations where clients might inadvertently
compare signed and unsigned values, especially given that some languages don't
even support unsigned types.

What do you think?

+  int32 min_width;
+
+  // The maximum width of the view in pixels.
+  // Must be >= |min_width|.

[jamesr, 2015/10/26 19:35:38]

we don't have a way to validate on this automatically, though

[jeffbrown, 2015/10/27 01:49:07]

True, which is why it's documented.  The implementation will close the
connection on any client that passes an invalid value here.

+  int32 max_width;
+
+  // The minimum height of the view in pixels.
+  // Must be >= 0.
+  int32 min_height;
+
+  // The maximum height of the view in 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.

[abarth-chromium, 2015/10/24 05:09:30]

The way we handle this issue in Flutter is that we have multiple traversals of
the tree.  For example, it's usually possible to change theme colors without
needing to trigger a layout.  Instead, the various views just need to repaint.

[jeffbrown, 2015/10/27 01:49:07]

Hmm.  This bears further consideration.  We may need other ways to propagate
contextual information.  I think a lot of this design pivots on how we will
synchronize rendering across the view tree.

+struct ViewLayoutParams {
+  // The size constraints for the child in pixels.

[jamesr, 2015/10/26 19:35:38]

"in pixels" is ambiguous - what sort of pixels?

[jeffbrown, 2015/10/27 01:49:07]

Logical pixels.  I'll clarify the docs.

+  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

[jamesr, 2015/10/26 19:35:38]

what uses logical pixels and what uses device pixels in this scheme?

[jeffbrown, 2015/10/27 01:49:06]

Everything here uses integer device pixels.  The assumption is that the view's
framebuffer will be rendered at that resolution (but the general case is more
complicated).

That said, I might not be using the terminology properly. It can get a bit muddy
especially when output is composed or redirected.  It would be good to settle on
consistent definitions for our coordinate systems.

+  // in relation to display density and zoom level.
+  // Must be > 0.
+  float device_pixel_ratio = 1.0;

[jamesr, 2015/10/26 19:35:38]

seems a bit odd to have this be a constraint on a particular view

[jeffbrown, 2015/10/27 01:49:07]

It's not a constraint.  It's a parameter that's needed to interpret the
dimensions of the layout.

+};

[abarth-chromium, 2015/10/24 05:09:30]

We'll probably need a bunch more metrics about the display here eventually.  For
example, the layout of a view will probably depend on the overall screen size.

[jeffbrown, 2015/10/27 01:49:07]

I don't think views should care about the overall screen size.  They should do
the best they can with the real-estate they are given.  Apps using display size
for measurement has caused significant compatibility issues for Android and made
it difficult to support multi-window use-cases and the like.

If we want apps to lay out differently on phones vs. tablets vs. watches vs.
laptops then we should find ways of expressing the essential underlying
qualities.  (Here there be dragons.)

+
+// 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 pixels, or null if not provided.
+  // This information must always be returned by a view during OnLayout()
+  // but will only be provided to the parent upon request.
+  mojo.Size? size;
+};