Base: Add manpages for new layout system

This is far from explaining all implications of the new layout system,
but it covers the basics.

5 files changed, 85 insertions, 38 deletions

diff --git a/Base/usr/share/man/man5/GML-Introduction.md b/Base/usr/share/man/man5/GML-Introduction.md
index 6bdfbf0e2d..e41d85c16c 100644
--- a/Base/usr/share/man/man5/GML-Introduction.md
+++ b/Base/usr/share/man/man5/GML-Introduction.md
@@ -30,6 +30,7 @@ Or right clicking on a folder in the TreeView and using
     -   [Define widgets](help://man/5/GML-Define-widget)
 -   GML object and property reference
     -   [Core::Object](help://man/5/GML-CoreObject)
+    -   [UI Dimensions](help://man/5/GML-UI-Dimensions)
     -   Layouts
         -   [HorizontalBoxLayout](help://man/5/GML-Layout-HorizontalBoxLayout)
         -   [VerticalBoxLayout](help://man/5/GML-Layout-VerticalBoxLayout)
@@ -76,3 +77,4 @@ Or right clicking on a folder in the TreeView and using
         -   [VerticalSlider](help://man/5/GML-Widget-VerticalSlider)
         -   [VerticalSplitter](help://man/5/GML-Widget-VerticalSplitter)
         -   [Widget](help://man/5/GML-Widget)
+
diff --git a/Base/usr/share/man/man5/GML-Syntax.md b/Base/usr/share/man/man5/GML-Syntax.md
index b236c595ae..e1241f5fad 100644
--- a/Base/usr/share/man/man5/GML-Syntax.md
+++ b/Base/usr/share/man/man5/GML-Syntax.md
@@ -90,6 +90,7 @@ A property's `value` is required to be either a JSON value or another object. Ob
 Among the supported JSON values, these types can be further distinguished:
 
 -   `int`: Regular JSON integer, note that JSON floats are not currently used.
+-   `ui_dimension`: either positive integers, that work just like `int`, or special meaning values as JSON strings; see [UI Dimensions](help://man/5/GML-UI-Dimensions)
 -   `bool`: Regular JSON boolean, may be enclosed in quotes but this is discouraged.
 -   `string`: JSON string, also used as a basis for other types.
 -   `readonly_string`: String-valued property that cannot be changed from C++ later.
@@ -99,6 +100,7 @@ Among the supported JSON values, these types can be further distinguished:
     -   `text_wrapping`: Special case of `enum` for `Gfx::TextWrapping`. One of `Wrap` or `DontWrap`.
 -   `rect`: A JSON object of four `int`s specifying a rectangle. The keys are `x`, `y`, `width`, `height`.
 -   `size`: A JSON array of two `int`s specifying two sizes in the format `[width, height]`.
+-   `ui_size`: A JSON array of two `ui_dimension`s specifying two sizes in the format `[width, height]`
 -   `margins`: A JSON array or object specifying four-directional margins as `int`s. If this is a JSON object, the four keys `top`, `right`, `bottom`, `left` are used. If this is a JSON array, there can be one to four integers. These have the following meaning (see also `GUI::Margins`):
     -   `[ all_four_margins ]`
     -   `[ top_and_bottom, right_and_left ]`
@@ -232,3 +234,4 @@ GML files can be found in the SerenityOS source tree with the `*.gml` extension.
     }
 }
 ```
+
diff --git a/Base/usr/share/man/man5/GML-UI-Dimensions.md b/Base/usr/share/man/man5/GML-UI-Dimensions.md
new file mode 100644
index 0000000000..b89921f55e
--- /dev/null
+++ b/Base/usr/share/man/man5/GML-UI-Dimensions.md
@@ -0,0 +1,29 @@
+## Name
+
+UI Dimensions
+
+# Description
+
+UI Dimension (or [GUI::UIDimension](file:///usr/src/serenity/Userland/Libraries/LibGUI/UIDimensions.h) in c++) is a special, union — of positive integer and enum — like, type that is used to represent dimensions in a user interface context.
+
+It can either store positive integers ≥0 or special meaning values from a pre determined set.
+
+## Basic Syntax
+
+In GML UI Dimensions that are "regular" values (integer ≥0) are represented by JSON's int type,
+while "special" values are represented by their name as a JSON string type.
+
+# Special Values
+
+Special Values carry size information that would otherwise not be intuitively possible to be transported by an integer (positive or negative) alone.
+
+Importantly, while any "regular" (i.e. int ≥0) UI Dimension values might (by convention) be assigned to any UI Dimension property, many properties only allow a subset of the "special" values to be assigned to them.
+
+| Name              | c++ name                                   | GML/JSON representation | General meaning                                 |
+|-------------------|--------------------------------------------|-------------------------|-------------------------------------------------|
+| Regular           | `GUI::SpecialDimension::Regular` (mock)    | int ≥0                  | This is a regular integer value specifying a specific size |
+| Grow              | `GUI::SpecialDimension::Grow`              | `"grow"`                | Grow to the maximum size the surrounding allows |
+| OpportunisticGrow | `GUI::SpecialDimension::OpportunisticGrow` | `"opportunistic_grow"`  | Grow when the opportunity arises, meaning — only when all other widgets have already grown to their maximum size, and only opportunistically growing widgets are left |
+| Fit               | `GUI::SpecialDimension::Fit`               | `"fit"`                 | Grow exactly to the size of the surrounding as determined by other factors, but do not call for e.g. expansion of the parent container itself |
+| Shrink            | `GUI::SpecialDimension::Shrink`            | `"shrink"`              | Shrink to the smallest size possible |
+
diff --git a/Base/usr/share/man/man5/GML-Widget-ScrollableContainerWidget.md b/Base/usr/share/man/man5/GML-Widget-ScrollableContainerWidget.md
index 50047c6b51..38bcd53c7b 100644
--- a/Base/usr/share/man/man5/GML-Widget-ScrollableContainerWidget.md
+++ b/Base/usr/share/man/man5/GML-Widget-ScrollableContainerWidget.md
@@ -6,21 +6,29 @@ GML Scrollable Container Widget
 
 Defines a GUI scrollable container widget.
 
+Unlike other container widgets, this one does not allow multiple child widgets to be added, and thus also does not support setting a layout.
+
 ## Synopsis
 
 `@GUI::ScrollableContainerWidget`
 
+Content declared as `content_widget` property.
+
 ## Examples
 
 ```gml
 @GUI::ScrollableContainerWidget {
-
+	content_widget: @GUI::Widget {
+		[...]
+	}
 }
 ```
 
 ## Registered Properties
 
-| Property                           | Type | Possible values | Description                                 |
-|------------------------------------|------|-----------------|---------------------------------------------|
-| scrollbars_enabled                 | bool | true or false   | Status of scrollbar                         |
-| should_hide_unnecessary_scrollbars | bool | true or false   | Whether to hide scrollbars when unnecessary |
+| Property                           | Type          | Possible values        | Description                                 |
+|------------------------------------|---------------|------------------------|---------------------------------------------|
+| ~~layout~~                         |               | none                   | Does not take layout                        |
+| scrollbars_enabled                 | bool          | true or false          | Status of scrollbar                         |
+| should_hide_unnecessary_scrollbars | bool          | true or false          | Whether to hide scrollbars when unnecessary |
+| content_widget                     | widget object | Any Subclass of Widget | The Widget to be displayed in the Container |
diff --git a/Base/usr/share/man/man5/GML-Widget.md b/Base/usr/share/man/man5/GML-Widget.md
index 4b90e2bfa8..4aa4eef78c 100644
--- a/Base/usr/share/man/man5/GML-Widget.md
+++ b/Base/usr/share/man/man5/GML-Widget.md
@@ -4,7 +4,8 @@ Defines a GUI widget.
 
 ```gml
 @GUI::Widget {
-  fixed_width: 250
+  min_width: 200
+  preferred_width: "opportunistic_grow"
   fixed_height: 215
   fill_with_background_color: true
   layout: @GUI::VerticalBoxLayout {
@@ -15,35 +16,39 @@ Defines a GUI widget.
 
 ## Registered Properties
 
-| Property                    | Type          | Possible values                                       | Description                                                                                       |
-| --------------------------- | ------------- | ----------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
-| x                           | int           |                                                       | x offset relative to parent                                                                       |
-| y                           | int           |                                                       | y offset relative to parent                                                                       |
-| visible                     | bool          |                                                       | Whether widget and children are drawn                                                             |
-| focused                     | bool          |                                                       | Whether widget should be tab-focused on start                                                     |
-| focus_policy                | enum          | ClickFocus, NoFocus, TabFocus, StrongFocus            | How the widget can receive focus                                                                  |
-| enabled                     | bool          |                                                       | Whether this widget is enabled for interactive purposes, e.g. can be clicked                      |
-| tooltip                     | string        |                                                       | Mouse tooltip to show when hovering over this widget                                              |
-| min_size                    | size          |                                                       | Minimum size this widget wants to occupy                                                          |
-| max_size                    | size          |                                                       | Maximum size this widget wants to occupy                                                          |
-| width                       | int           |                                                       | Width of the widget, independent of its layout size calculation                                   |
-| height                      | int           |                                                       | Height of the widget, independent of its layout size calculation                                  |
-| min_width                   | int           | smaller than max_width                                | Minimum width this widget wants to occupy                                                         |
-| min_height                  | int           | smaller than max_height                               | Minimum height this widget wants to occupy                                                        |
-| max_width                   | int           | greater than min_width                                | Maximum width this widget wants to occupy                                                         |
-| max_height                  | int           | greater than min_height                               | Maximum height this widget wants to occupy                                                        |
-| fixed_width                 | int           |                                                       | Both maximum and minimum width; widget is fixed-width                                             |
-| fixed_height                | int           |                                                       | Both maximum and minimum height; widget is fixed-height                                           |
-| fixed_size                  | size          |                                                       | Both maximum and minimum size; widget is fixed-size                                               |
-| shrink_to_fit               | bool          |                                                       | Whether the widget shrinks as much as possible while still respecting its childrens minimum sizes |
-| font                        | string        | Any system-known font                                 | Font family                                                                                       |
-| font_size                   | int           | Font size that is available on this family            | Font size                                                                                         |
-| font_weight                 | font_weight   | Font weight that is available on this family and size | Font weight                                                                                       |
-| font_type                   | enum          | FixedWidth, Normal                                    | Font type                                                                                         |
-| foreground_color            | color         |                                                       | Color of foreground elements such as text                                                         |
-| foreground_role             | string        | Any theme palette color role name                     | Palette color role (depends on system theme) for the foreground elements                          |
-| background_color            | color         |                                                       | Color of the widget background                                                                    |
-| background_role             | string        | Any theme palette color role name                     | Palette color role (depends on system theme) for the widget background                            |
-| fill_width_background_color | bool          |                                                       | Whether to fill the widget's background with the background color                                 |
-| layout                      | layout object |                                                       | Layout object for layouting this widget's children                                                |
-| relative_rect               | rect          |                                                       | Rectangle for relatively positioning the widget to the parent                                     |
+| Property                    | Type          | Possible values                                       | Description                                                                                        |
+| --------------------------- | ------------- | ----------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| x                           | int           |                                                       | x offset relative to parent                                                                        |
+| y                           | int           |                                                       | y offset relative to parent                                                                        |
+| visible                     | bool          |                                                       | Whether widget and children are drawn                                                              |
+| focused                     | bool          |                                                       | Whether widget should be tab-focused on start                                                      |
+| focus_policy                | enum          | ClickFocus, NoFocus, TabFocus, StrongFocus            | How the widget can receive focus                                                                   |
+| enabled                     | bool          |                                                       | Whether this widget is enabled for interactive purposes, e.g. can be clicked                       |
+| tooltip                     | string        |                                                       | Mouse tooltip to show when hovering over this widget                                               |
+| min_size                    | ui_size       | {Regular, Shrink}²                                    | Minimum size this widget wants to occupy (Shrink is equivalent to 0)                               |
+| max_size                    | ui_size       | {Regular, Grow}²                                      | Maximum size this widget wants to occupy                                                           |
+| preferred_size              | ui_size       | {Regular, Shrink, Fit, OpportunisticGrow, Grow}²      | Preferred size this widget wants to occupy, if not otherwise constrained (Shrink means min_size)   |
+| width                       | int           |                                                       | Width of the widget, independent of its layout size calculation                                    |
+| height                      | int           |                                                       | Height of the widget, independent of its layout size calculation                                   |
+| min_width                   | ui_dimension  | Regular, Shrink                                       | Minimum width this widget wants to occupy (Shrink is equivalent to 0)                              |
+| min_height                  | ui_dimension  | Regular, Shrink                                       | Minimum height this widget wants to occupy (Shrink is equivalent to 0                              |
+| max_width                   | ui_dimension  | Regular, Grow                                         | Maximum width this widget wants to occupy                                                          |
+| max_height                  | ui_dimension  | Regular, Grow                                         | Maximum height this widget wants to occupy                                                         |
+| preferred_width             | ui_dimension  | Regular, Shrink, Fit, OpportunisticGrow, Grow         | Preferred width this widget wants to occupy, if not otherwise constrained (Shrink means min_size)  |
+| preferred_height            | ui_dimension  | Regular, Shrink, Fit, OpportunisticGrow, Grow         | Preferred height this widget wants to occupy, if not otherwise constrained (Shrink means min_size) |
+| fixed_width                 | ui_dimension  | Regular (currently only integer values ≥0 allowed)    | Both maximum and minimum width; widget is fixed-width                                              |
+| fixed_height                | ui_dimension  | Regular (currently only integer values ≥0 allowed)    | Both maximum and minimum height; widget is fixed-height                                            |
+| fixed_size                  | ui_size       | {Regular}²                                            | Both maximum and minimum size; widget is fixed-size                                                |
+| shrink_to_fit               | bool          |                                                       | Whether the widget shrinks as much as possible while still respecting its childrens minimum sizes  |
+| font                        | string        | Any system-known font                                 | Font family                                                                                        |
+| font_size                   | int           | Font size that is available on this family            | Font size                                                                                          |
+| font_weight                 | font_weight   | Font weight that is available on this family and size | Font weight                                                                                        |
+| font_type                   | enum          | FixedWidth, Normal                                    | Font type                                                                                          |
+| foreground_color            | color         |                                                       | Color of foreground elements such as text                                                          |
+| foreground_role             | string        | Any theme palette color role name                     | Palette color role (depends on system theme) for the foreground elements                           |
+| background_color            | color         |                                                       | Color of the widget background                                                                     |
+| background_role             | string        | Any theme palette color role name                     | Palette color role (depends on system theme) for the widget background                             |
+| fill_width_background_color | bool          |                                                       | Whether to fill the widget's background with the background color                                  |
+| layout                      | layout object |                                                       | Layout object for layouting this widget's children                                                 |
+| relative_rect               | rect          |                                                       | Rectangle for relatively positioning the widget to the parent                                      |
+