Improve layout related documentation
Bug: 142543823
Bug: 142543825
Bug: 142543541
Bug: 142543542
Bug: 142544575
Bug: 142543829
Bug: 141917238
Test: ran samples and tests
Change-Id: I55c53ec70e9d3b3c39b9a1436789ca193f4041f5
diff --git a/ui/ui-framework/integration-tests/samples/src/main/java/androidx/ui/framework/samples/OnPositionedSample.kt b/ui/ui-framework/integration-tests/samples/src/main/java/androidx/ui/framework/samples/OnPositionedSample.kt
new file mode 100644
index 0000000..b66bc6b
--- /dev/null
+++ b/ui/ui-framework/integration-tests/samples/src/main/java/androidx/ui/framework/samples/OnPositionedSample.kt
@@ -0,0 +1,138 @@
+/*
+ * Copyright 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package androidx.ui.framework.samples
+
+import androidx.annotation.Sampled
+import androidx.compose.Composable
+import androidx.ui.core.Constraints
+import androidx.ui.core.Dp
+import androidx.ui.core.Layout
+import androidx.ui.core.Modifier
+import androidx.ui.core.OnChildPositioned
+import androidx.ui.core.OnPositioned
+import androidx.ui.core.coerceAtLeast
+import androidx.ui.core.coerceIn
+import androidx.ui.core.dp
+import androidx.ui.core.globalPosition
+import androidx.ui.core.ipx
+import androidx.ui.core.max
+import androidx.ui.core.positionInRoot
+import androidx.ui.foundation.shape.DrawShape
+import androidx.ui.foundation.shape.RectangleShape
+import androidx.ui.graphics.Color
+
+@Sampled
+@Composable
+fun OnPositionedSample() {
+ Column {
+ SizedRectangle(color = Color.Green, width = 20.dp, height = 20.dp)
+ SizedRectangle(color = Color.Blue, width = 20.dp, height = 20.dp)
+ OnPositioned( coordinates ->
+ // This will be the size of the Column.
+ coordinates.size
+ // This will be the position of Column inside its parent.
+ coordinates.position
+ // The position of the Column relative to the application window.
+ coordinates.globalPosition
+ // The position of the Column relative to the Compose root.
+ coordinates.positionInRoot
+ // These will be the alignment lines provided to the layout (empty here for Column).
+ coordinates.providedAlignmentLines
+ // This will a LayoutCoordinates instance corresponding to the parent of Column.
+ coordinates.parentCoordinates
+ })
+ }
+}
+
+@Sampled
+@Composable
+fun OnChildPositionedSample() {
+ Column {
+ SizedRectangle(color = Color.Green, width = 20.dp, height = 20.dp)
+ OnChildPositioned( coordinates ->
+ // This will be the size of the child SizedRectangle.
+ coordinates.size
+ // This will be the position of SizedRectangle inside its Column parent.
+ coordinates.position
+ // The position of the SizedRectangle relative to the application window.
+ coordinates.globalPosition
+ // The position of the SizedRectangle relative to the Compose root.
+ coordinates.positionInRoot
+ // These will be the alignment lines provided to the layout (empty for SizedRectangle)
+ coordinates.providedAlignmentLines
+ // This will a LayoutCoordinates instance corresponding to the Column.
+ coordinates.parentCoordinates
+ }) {
+ SizedRectangle(color = Color.Blue, width = 20.dp, height = 20.dp)
+ }
+ }
+}
+
+/**
+ * Simple Column implementation.
+ */
+@Composable
+fun Column(children: @Composable() () -> Unit) {
+ Layout(children) { measurables, constraints ->
+ val placeables = measurables.map { measurable ->
+ measurable.measure(
+ Constraints(minWidth = constraints.minWidth, maxWidth = constraints.maxWidth)
+ )
+ }
+ val columnWidth = (placeables.maxBy { it.width.value }?.width ?: 0.ipx)
+ .coerceAtLeast(constraints.minWidth)
+ val columnHeight = placeables.sumBy { it.height.value }.ipx.coerceIn(
+ constraints.minHeight,
+ constraints.maxHeight
+ )
+ layout(columnWidth, columnHeight) {
+ var top = 0.ipx
+ placeables.forEach { placeable ->
+ placeable.place(0.ipx, top)
+ top += placeable.height
+ }
+ }
+ }
+}
+
+/**
+ * A rectangle layout that tries to size itself to specified width and height, subject to
+ * the incoming constraints. The composable also draws a color in the space of the rectangle
+ * layout. If the width and/or height of the rectangle are not specified, the rectangle will
+ * be sized to the incoming max constraints.
+ */
+@Composable
+fun SizedRectangle(
+ modifier: Modifier = Modifier.None,
+ color: Color,
+ width: Dp? = null,
+ height: Dp? = null
+) {
+ Layout(children = { DrawRectangle(color = color) }, modifier = modifier) { _, constraints ->
+ val widthPx = max(width?.toIntPx() ?: constraints.maxWidth, constraints.minWidth)
+ val heightPx = max(height?.toIntPx() ?: constraints.maxHeight, constraints.minHeight)
+ layout(widthPx, heightPx) {}
+ }
+}
+
+/**
+ * Draws a rectangle of a given color in the space of the parent layout.
+ */
+@Composable
+fun DrawRectangle(color: Color) {
+ DrawShape(shape = RectangleShape, color = color)
+}
diff --git a/ui/ui-framework/integration-tests/samples/src/main/java/androidx/ui/framework/samples/ParentDataSample.kt b/ui/ui-framework/integration-tests/samples/src/main/java/androidx/ui/framework/samples/ParentDataSample.kt
new file mode 100644
index 0000000..5aa5f47
--- /dev/null
+++ b/ui/ui-framework/integration-tests/samples/src/main/java/androidx/ui/framework/samples/ParentDataSample.kt
@@ -0,0 +1,39 @@
+/*
+ * Copyright 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package androidx.ui.framework.samples
+
+import androidx.annotation.Sampled
+import androidx.compose.Composable
+import androidx.ui.core.Layout
+import androidx.ui.core.ParentData
+import androidx.ui.core.dp
+import androidx.ui.graphics.Color
+
+@Sampled
+@Composable
+fun ParentDataSample() {
+ val parentDataComposable = @Composable {
+ ParentData(data = 5) {
+ SizedRectangle(color = Color.Blue, width = 50.dp, height = 50.dp)
+ }
+ }
+ Layout(parentDataComposable) { measurables, constraints ->
+ // The parentData will be 5.
+ measurables[0].parentData as Int
+ layout(constraints.maxWidth, constraints.maxHeight) {}
+ }
+}
diff --git a/ui/ui-framework/integration-tests/samples/src/main/java/androidx/ui/framework/samples/WithConstraintsSample.kt b/ui/ui-framework/integration-tests/samples/src/main/java/androidx/ui/framework/samples/WithConstraintsSample.kt
new file mode 100644
index 0000000..cc30781
--- /dev/null
+++ b/ui/ui-framework/integration-tests/samples/src/main/java/androidx/ui/framework/samples/WithConstraintsSample.kt
@@ -0,0 +1,43 @@
+/*
+ * Copyright 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package androidx.ui.framework.samples
+
+import androidx.annotation.Sampled
+import androidx.compose.Composable
+import androidx.compose.unaryPlus
+import androidx.ui.core.WithConstraints
+import androidx.ui.core.ambientDensity
+import androidx.ui.core.dp
+import androidx.ui.core.withDensity
+import androidx.ui.graphics.Color
+
+@Sampled
+@Composable
+fun WithConstraintsSample() {
+ WithConstraints { constraints ->
+ val rectangleHeight = 100.dp
+ val threshold = withDensity(+ambientDensity()) { (rectangleHeight * 2).toIntPx() }
+ if (constraints.maxHeight < threshold) {
+ SizedRectangle(color = Color.Blue, width = 50.dp, height = rectangleHeight)
+ } else {
+ Column {
+ SizedRectangle(color = Color.Blue, width = 50.dp, height = rectangleHeight)
+ SizedRectangle(color = Color.Gray, width = 50.dp, height = rectangleHeight)
+ }
+ }
+ }
+}
diff --git a/ui/ui-framework/src/main/java/androidx/ui/core/Layout.kt b/ui/ui-framework/src/main/java/androidx/ui/core/Layout.kt
index 4a68bed..e912690 100644
--- a/ui/ui-framework/src/main/java/androidx/ui/core/Layout.kt
+++ b/ui/ui-framework/src/main/java/androidx/ui/core/Layout.kt
@@ -439,17 +439,7 @@
/**
* A widget that defines its own content according to the available space, based on the incoming
* constraints. Example usage:
- *
- * WithConstraints { constraints ->
- * if (constraints.maxWidth < 100.ipx) {
- * Icon()
- * } else {
- * Row {
- * Icon()
- * IconDescription()
- * }
- * }
- * }
+ * @sample androidx.ui.framework.samples.WithConstraintsSample
*
* The widget will compose the given children, and will position the resulting layout widgets
* in a parent [Layout]. The widget will be as small as possible such that it can fit its
@@ -540,14 +530,7 @@
* Note that it will be called after a composition when the coordinates are finalized.
*
* Usage example:
- * Column {
- * Item1()
- * Item2()
- * OnPositioned ( coordinates ->
- * // This coordinates contain bounds of the Column within it's parent Layout.
- * // Store it if you want to use it later f.e. when a touch happens.
- * })
- * }
+ * @sample androidx.ui.framework.samples.OnPositionedSample
*/
@Composable
@Suppress("NOTHING_TO_INLINE")
@@ -563,13 +546,7 @@
* Note that it will be called after a composition when the coordinates are finalized.
*
* Usage example:
- * OnChildPositioned ( coordinates ->
- * // This coordinates contain bounds of the Item within it's parent Layout.
- * // Store it if you want to use it later f.e. when a touch happens.
- * }) {
- * Item()
- * }
- * }
+ * @sample androidx.ui.framework.samples.OnChildPositionedSample
*/
@Composable
inline fun OnChildPositioned(
diff --git a/ui/ui-framework/src/main/java/androidx/ui/core/ParentData.kt b/ui/ui-framework/src/main/java/androidx/ui/core/ParentData.kt
index eb8db87..4a4085e 100644
--- a/ui/ui-framework/src/main/java/androidx/ui/core/ParentData.kt
+++ b/ui/ui-framework/src/main/java/androidx/ui/core/ParentData.kt
@@ -18,37 +18,19 @@
import androidx.compose.Composable
/**
- * Provide data that can be read from the [Measurable] children.
+ * Provide data for the parent of a [Layout], which can then be read from the
+ * corresponding [Measurable].
*
* A containing [Layout] sometimes needs to mark children with attributes that can later
* be read during layout. [data] is assigned to the [Measurable.parentData] to be read.
* Normally [ParentData] is completely controlled by the containing Layout. For example,
- * [Flex] is used like this:
+ * Row and Column layout models use parent data to access the flex value of their children
+ * during measurement (though that is achieved using the Inflexible and Flexible modifiers,
+ * rather than using this widget).
*
- * Flex(...) {
- * expanded(2f) {
- * Text(...)
- * }
- * inflexible {
- * Center {Text(...)}
- * }
- * }
+ * Example usage:
+ * @sample androidx.ui.framework.samples.ParentDataSample
*
- * The Flex component internally adds a ParentData to mark the expanded and inflexible
- * children so that they can later be read during layout. Conceptually, Flex will treat it
- * like this:
- *
- * Flex(...) {
- * ParentData(value = FlexInfo(FlexFit.Tight, 2f)) {
- * Text(...)
- * }
- * ParentData(value = FlexInfo(FlexFit.Loose, 0f)) {
- * Center {Text(...)}
- * }
- * }
- *
- * Flex then reads the [Measurable.parentData] and can determine which elements are
- * expanded, which are inflexible and which are flexible.
*/
@Composable
inline fun ParentData(data: Any, crossinline children: @Composable() () -> Unit) {
diff --git a/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/AlignSample.kt b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/AlignSample.kt
new file mode 100644
index 0000000..683da48
--- /dev/null
+++ b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/AlignSample.kt
@@ -0,0 +1,41 @@
+/*
+ * Copyright 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package androidx.ui.layout.samples
+
+import androidx.annotation.Sampled
+import androidx.compose.Composable
+import androidx.ui.core.Alignment
+import androidx.ui.core.dp
+import androidx.ui.graphics.Color
+import androidx.ui.layout.Align
+import androidx.ui.layout.Center
+
+@Sampled
+@Composable
+fun SimpleAlign() {
+ Align(Alignment.BottomRight) {
+ SizedRectangle(color = Color.Blue, width = 20.dp, height = 20.dp)
+ }
+}
+
+@Sampled
+@Composable
+fun SimpleCenter() {
+ Center {
+ SizedRectangle(color = Color.Blue, width = 20.dp, height = 20.dp)
+ }
+}
diff --git a/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/AspectRatioSamples.kt b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/AspectRatioSample.kt
similarity index 100%
rename from ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/AspectRatioSamples.kt
rename to ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/AspectRatioSample.kt
diff --git a/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/ExpandedModifierSamples.kt b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/ExpandedModifierSample.kt
similarity index 100%
rename from ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/ExpandedModifierSamples.kt
rename to ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/ExpandedModifierSample.kt
diff --git a/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/FlexSamples.kt b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/FlexSample.kt
similarity index 100%
rename from ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/FlexSamples.kt
rename to ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/FlexSample.kt
diff --git a/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/FlowSamples.kt b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/FlowSample.kt
similarity index 100%
rename from ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/FlowSamples.kt
rename to ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/FlowSample.kt
diff --git a/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/IntrinsicSamples.kt b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/IntrinsicSample.kt
similarity index 100%
rename from ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/IntrinsicSamples.kt
rename to ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/IntrinsicSample.kt
diff --git a/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/LayoutSample.kt b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/LayoutSample.kt
new file mode 100644
index 0000000..9267b9e
--- /dev/null
+++ b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/LayoutSample.kt
@@ -0,0 +1,55 @@
+/*
+ * Copyright 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package androidx.ui.layout.samples
+
+import androidx.compose.Composable
+import androidx.compose.composer
+import androidx.ui.core.Dp
+import androidx.ui.core.Layout
+import androidx.ui.core.Modifier
+import androidx.ui.core.max
+import androidx.ui.foundation.shape.DrawShape
+import androidx.ui.foundation.shape.RectangleShape
+import androidx.ui.graphics.Color
+
+/**
+ * A rectangle layout that tries to size itself to specified width and height, subject to
+ * the incoming constraints. The composable also draws a color in the space of the rectangle
+ * layout. If the width and/or height of the rectangle are not specified, the rectangle will
+ * be sized to the incoming max constraints.
+ */
+@Composable
+fun SizedRectangle(
+ modifier: Modifier = Modifier.None,
+ color: Color,
+ width: Dp? = null,
+ height: Dp? = null
+) {
+ Layout(children = { DrawRectangle(color = color) }, modifier = modifier) { _, constraints ->
+ val widthPx = max(width?.toIntPx() ?: constraints.maxWidth, constraints.minWidth)
+ val heightPx = max(height?.toIntPx() ?: constraints.maxHeight, constraints.minHeight)
+ layout(widthPx, heightPx) {}
+ }
+}
+
+/**
+ * Draws a rectangle of a given color in the space of the parent layout.
+ */
+@Composable
+fun DrawRectangle(color: Color) {
+ DrawShape(shape = RectangleShape, color = color)
+}
diff --git a/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/PaddingSample.kt b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/PaddingSample.kt
new file mode 100644
index 0000000..079c707
--- /dev/null
+++ b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/PaddingSample.kt
@@ -0,0 +1,118 @@
+/*
+ * Copyright 2019 The Android Open Source Project
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ * http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+package androidx.ui.layout.samples
+
+import androidx.annotation.Sampled
+import androidx.compose.Composable
+import androidx.ui.core.Alignment
+import androidx.ui.core.dp
+import androidx.ui.graphics.Color
+import androidx.ui.layout.Align
+import androidx.ui.layout.Container
+import androidx.ui.layout.EdgeInsets
+import androidx.ui.layout.Padding
+import androidx.ui.layout.absolutePadding
+import androidx.ui.layout.padding
+
+@Sampled
+@Composable
+fun AbsolutePaddingModifier() {
+ Align(Alignment.TopLeft) {
+ Container {
+ DrawRectangle(Color.Gray)
+ SizedRectangle(
+ modifier = absolutePadding(
+ left = 20.dp, top = 30.dp, right = 20.dp, bottom = 30.dp
+ ),
+ color = Color.Blue,
+ width = 50.dp,
+ height = 50.dp
+ )
+ }
+ }
+}
+
+@Sampled
+@Composable
+fun PaddingModifier() {
+ Align(Alignment.TopLeft) {
+ Container {
+ DrawRectangle(Color.Gray)
+ SizedRectangle(
+ modifier = padding(all = 20.dp),
+ color = Color.Blue,
+ width = 50.dp,
+ height = 50.dp
+ )
+ }
+ }
+}
+
+@Sampled
+@Composable
+fun SymmetricalPaddingModifier() {
+ Align(Alignment.TopLeft) {
+ Container {
+ DrawRectangle(Color.Gray)
+ SizedRectangle(
+ modifier = padding(horizontal = 20.dp, vertical = 30.dp),
+ color = Color.Blue,
+ width = 50.dp,
+ height = 50.dp
+ )
+ }
+ }
+}
+
+@Sampled
+@Composable
+fun PaddingWidgetEdgeInsets() {
+ Align(Alignment.TopLeft) {
+ Container {
+ DrawRectangle(Color.Gray)
+ Padding(EdgeInsets(left = 20.dp, top = 30.dp, right = 20.dp, bottom = 30.dp)) {
+ SizedRectangle(color = Color.Blue, width = 50.dp, height = 50.dp)
+ }
+ }
+ }
+}
+
+@Sampled
+@Composable
+fun PaddingWidget() {
+ Align(Alignment.TopLeft) {
+ Container {
+ DrawRectangle(Color.Gray)
+ Padding(left = 20.dp, top = 30.dp, right = 20.dp, bottom = 30.dp) {
+ SizedRectangle(color = Color.Blue, width = 50.dp, height = 50.dp)
+ }
+ }
+ }
+}
+
+@Sampled
+@Composable
+fun PaddingWidgetSameInset() {
+ Align(Alignment.TopLeft) {
+ Container {
+ DrawRectangle(Color.Gray)
+ Padding(padding = 20.dp) {
+ SizedRectangle(color = Color.Blue, width = 50.dp, height = 50.dp)
+ }
+ }
+ }
+}
diff --git a/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/StackSamples.kt b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/StackSample.kt
similarity index 63%
rename from ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/StackSamples.kt
rename to ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/StackSample.kt
index b27167e..6e2e7c1 100644
--- a/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/StackSamples.kt
+++ b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/StackSample.kt
@@ -19,42 +19,9 @@
import androidx.annotation.Sampled
import androidx.compose.Composable
import androidx.ui.core.Alignment
-import androidx.ui.core.Dp
-import androidx.ui.core.Draw
-import androidx.ui.core.Layout
-import androidx.ui.core.Modifier
import androidx.ui.core.dp
-import androidx.ui.core.toRect
import androidx.ui.graphics.Color
import androidx.ui.layout.Stack
-import androidx.ui.graphics.Paint
-
-/**
- * Draws a rectangle of a specified dimension, or to its max incoming constraints if dimensions are
- * not specified.
- */
-@Composable
-fun SizedRectangle(
- modifier: Modifier = Modifier.None,
- color: Color,
- width: Dp? = null,
- height: Dp? = null
-) {
- Layout(children = { DrawRectangle(color = color) }, modifier = modifier) { _, constraints ->
- val widthPx = width?.toIntPx() ?: constraints.maxWidth
- val heightPx = height?.toIntPx() ?: constraints.maxHeight
- layout(widthPx, heightPx) {}
- }
-}
-
-@Composable
-fun DrawRectangle(color: Color) {
- val paint = Paint()
- paint.color = color
- Draw { canvas, parentSize ->
- canvas.drawRect(parentSize.toRect(), paint)
- }
-}
@Sampled
@Composable
diff --git a/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/TableSamples.kt b/ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/TableSample.kt
similarity index 100%
rename from ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/TableSamples.kt
rename to ui/ui-layout/integration-tests/samples/src/main/java/androidx/ui/layout/samples/TableSample.kt
diff --git a/ui/ui-layout/src/main/java/androidx/ui/layout/Align.kt b/ui/ui-layout/src/main/java/androidx/ui/layout/Align.kt
index 8f4d93a..6d4583e 100644
--- a/ui/ui-layout/src/main/java/androidx/ui/layout/Align.kt
+++ b/ui/ui-layout/src/main/java/androidx/ui/layout/Align.kt
@@ -16,22 +16,25 @@
package androidx.ui.layout
-import androidx.ui.core.IntPxPosition
import androidx.ui.core.IntPxSize
import androidx.ui.core.Layout
import androidx.ui.core.isFinite
import androidx.ui.core.looseMin
import androidx.compose.Composable
import androidx.ui.core.Alignment
-import androidx.ui.core.round
-import androidx.ui.core.toPx
/**
* A layout that takes a child and aligns it within itself, according to the alignment parameter.
* The layout will be as large as possible for finite incoming constraints,
* or wrap content otherwise.
*
+ * Example usage:
+ * @sample androidx.ui.layout.samples.SimpleAlign
+ *
+ * For a widget that just does center alignment, see [Center].
* For a widget that does alignment and tries to be the same size as its child, see [Wrap].
+ * @see Center
+ * @see Wrap
*/
@Composable
fun Align(alignment: Alignment, children: @Composable() () -> Unit) {
@@ -69,12 +72,13 @@
* The layout will be as large as possible for finite incoming
* constraints, or wrap content otherwise.
*
- * For a widget that does alignment and tries to be the same size as its child, see [Wrap].
- *
* Example usage:
- * Center {
- * SizedRectangle(color = Color(0xFF0000FF), width = 40.dp, height = 40.dp)
- * }
+ * @sample androidx.ui.layout.samples.SimpleCenter
+ *
+ * For a widget that supports other alignments than just center, see [Align].
+ * For a widget that does alignment and tries to be the same size as its child, see [Wrap].
+ * @see Align
+ * @see Wrap
*/
@Composable
fun Center(children: @Composable() () -> Unit) {
diff --git a/ui/ui-layout/src/main/java/androidx/ui/layout/Flex.kt b/ui/ui-layout/src/main/java/androidx/ui/layout/Flex.kt
index f442759..68ca3f6 100644
--- a/ui/ui-layout/src/main/java/androidx/ui/layout/Flex.kt
+++ b/ui/ui-layout/src/main/java/androidx/ui/layout/Flex.kt
@@ -121,7 +121,7 @@
* A widget that places its children in a vertical sequence, assigning children heights
* according to their flex weights.
*
- * [FlexRow] children can be:
+ * [FlexColumn] children can be:
* - [inflexible] meaning that the child is not flex, and it should be measured with
* loose constraints to determine its preferred height
* - [expanded] meaning that the child is flexible, and it should be assigned a
diff --git a/ui/ui-layout/src/main/java/androidx/ui/layout/Padding.kt b/ui/ui-layout/src/main/java/androidx/ui/layout/Padding.kt
index db49eb7..a7c3324 100644
--- a/ui/ui-layout/src/main/java/androidx/ui/layout/Padding.kt
+++ b/ui/ui-layout/src/main/java/androidx/ui/layout/Padding.kt
@@ -36,6 +36,9 @@
/**
* Padding on all sides.
+ *
+ * Example usage:
+ * @sample androidx.ui.layout.samples.AbsolutePaddingModifier
*/
fun absolutePadding(
left: Dp = 0.dp,
@@ -46,12 +49,18 @@
/**
* Padding with [all] dp on each side.
+ *
+ * Example usage:
+ * @sample androidx.ui.layout.samples.PaddingModifier
*/
fun padding(all: Dp = 0.dp) = AbsolutePadding(left = all, top = all, right = all, bottom = all)
/**
* Padding with [horizontal] dp of padding on the left and right and [vertical] dp of padding
* on the top and bottom.
+ *
+ * Example usage:
+ * @sample androidx.ui.layout.samples.SymmetricalPaddingModifier
*/
fun padding(
horizontal: Dp = 0.dp,
@@ -133,11 +142,7 @@
* requested padding, causing the child to layout at a smaller size.
*
* Example usage:
- * Row {
- * Padding(padding=EdgeInsets(right=20.dp)) {
- * SizedRectangle(color=Color(0xFFFF0000), width=20.dp, height= 20.dp)
- * }
- * }
+ * @sample androidx.ui.layout.samples.PaddingWidgetEdgeInsets
*/
@Composable
fun Padding(
@@ -177,9 +182,7 @@
* requested padding, causing the child to layout at a smaller size.
*
* Example usage:
- * Padding(left=20.dp, right=20.dp) {
- * SizedRectangle(color=Color(0xFFFF0000), width=20.dp, height= 20.dp)
- * }
+ * @sample androidx.ui.layout.samples.PaddingWidget
*/
@Composable
fun Padding(
@@ -203,9 +206,7 @@
* requested padding, causing the child to layout at a smaller size.
*
* Example usage:
- * Padding(padding=20.dp) {
- * SizedRectangle(color=Color(0xFFFF0000), width=20.dp, height= 20.dp)
- * }
+ * @sample androidx.ui.layout.samples.PaddingWidgetSameInset
*/
@Composable
fun Padding(