From 7c6cdbcd7b172a354669c0d2cb64bd1fbe1ca75f Mon Sep 17 00:00:00 2001
From: outfoxxed <outfoxxed@outfoxxed.me>
Date: Mon, 15 Apr 2024 03:59:17 -0700
Subject: [PATCH] guide: add positioning overview

---
 content/docs/configuration/intro.md       |  27 ++----
 content/docs/configuration/positioning.md | 103 ++++++++++++++++++++++
 2 files changed, 111 insertions(+), 19 deletions(-)
 create mode 100644 content/docs/configuration/positioning.md

diff --git a/content/docs/configuration/intro.md b/content/docs/configuration/intro.md
index b177aed..23a10d9 100644
--- a/content/docs/configuration/intro.md
+++ b/content/docs/configuration/intro.md
@@ -599,19 +599,13 @@ single `Text` object but the same concepts apply regardless of complexity.
 ```qml {filename="ClockWidget.qml"}
 import QtQuick
 
-// Item is a common base type for visual components
-Item {
-  // make a property the creator of this type is required to set
+Text {
+  // A property the creator of this type is required to set.
+  // Note that we could just set `text` instead, but don't because your
+  // clock probably will not be this simple.
   required property string time
 
-  // size the item to its children
-  width: childrenRect.width
-  height: childrenRect.height
-
-  // use the default property to contain the clock
-  Text {
-    text: time
-  }
+  text: time
 }
 ```
 
@@ -774,16 +768,11 @@ Singleton {
 ```qml {filename="ClockWidget.qml"}
 import QtQuick
 
-Item {
+Text {
   // we no longer need time as an input
 
-  width: childrenRect.width
-  height: childrenRect.height
-
-  Text {
-    // directly access the time property from the Time singleton
-    text: Time.time
-  }
+  // directly access the time property from the Time singleton
+  text: Time.time
 }
 ```
 
diff --git a/content/docs/configuration/positioning.md b/content/docs/configuration/positioning.md
new file mode 100644
index 0000000..91ecd3f
--- /dev/null
+++ b/content/docs/configuration/positioning.md
@@ -0,0 +1,103 @@
++++
+title = "Positioning"
++++
+
+QtQuick has multiple ways to position components. This page has instructions for where and how
+to use them.
+
+## Anchors
+Anchors can be used to position components relative to another neighboring component.
+It is faster than [manual positioning](#manual-positioning) and covers a lot of simple
+use cases.
+
+The [Qt Documentation: Positioning with Anchors](https://doc.qt.io/qt-6/qtquick-positioning-anchors.html)
+page has comprehensive documentation of anchors.
+
+## Layouts
+Layouts are useful when you have many components that need to be positioned relative to
+eachother such as a list.
+
+The [Qt Documentation: Layouts Overview](https://doc.qt.io/qt-6/qtquicklayouts-overview.html)
+page has good documentation of the basic layout types and how to use them.
+
+Note: layouts by default have a nonzero spacing.
+
+## Manual Positioning
+If layouts and anchors can't easily fulfill your usecase, you can also manually position and size
+components by setting their `x`, `y`, `width` and `height` properties, which are relative to
+the parent component.
+
+This example puts a 100x100px blue rectangle at x=20,y=40 in the parent item. Ensure the size
+of the parent is large enough for its content or positioning based on them will break.
+```qml
+Item {
+  // make sure the component is large enough to fit its children
+  implicitWidth: childrenRect.width
+  implicitHeight: childrenRect.height
+  
+  Rectangle {
+    color: "blue"
+    x: 20
+    y: 40
+    width: 100
+    height: 100
+  }
+}
+```
+
+## Notes
+### Component Size
+The [Item.implicitHeight] and [Item.implicitWidth] properties control the *base size* of a
+component, before layouts are applied. These properties are *not* the same as
+[Item.height] and [Item.width] which are the final size of the component.
+You should nearly always use the implicit size properties when creating a component,
+however using the normal width and height properties is fine if you know an
+item will never go in a layout.
+
+[Item.height]: https://doc.qt.io/qt-6/qml-qtquick-item.html#height-prop
+[Item.width]: https://doc.qt.io/qt-6/qml-qtquick-item.html#width-prop
+[Item.implicitHeight]: https://doc.qt.io/qt-6/qml-qtquick-item.html#implicitHeight-prop
+[Item.implicitWidth]: https://doc.qt.io/qt-6/qml-qtquick-item.html#implicitWidth-prop
+
+This example component puts a colored rectangle behind some text, and will act the same
+way in a layout as the text by itself.
+```qml {filename="TextWithBkgColor.qml"}
+Rectangle {
+  implicitWidth: text.implicitWidth
+  implicitHeight: text.implicitHeight
+  
+  Text {
+    id: text
+    text: "hello!"
+  }
+}
+```
+
+If you want to size your component based on multiple others or use any other math you can.
+```qml {filename="PaddedTexts.qml"}
+Item {
+  // width of both texts plus 5
+  implicitWidth: text1.implicitWidth + text2.implicitWidth + 5
+  // max height of both texts plus 5
+  implicitHeight: Math.min(text1.implicitHeight, text2.implicitHeight) + 5
+
+  Text {
+    id: text1
+    text: "text1"
+  }
+  
+  Text {
+    id: text2
+    anchors.left: text1.left
+    text: "text2"
+  }
+}
+```
+
+### Coordinate space
+You should always position or size components relative to the closest possible
+parent. Often this is just the `parent` property.
+
+Refrain from using things like the size of your screen to size a component,
+as this will break as soon as anything up the component hierarchy changes, such
+as adding padding to a bar.