Updated developer docs

docfx/docs/dimauto.md

@@ -7,15 +7,15 @@ Like all `Dim` types, `Dim.Auto` is used to set the `Width` or `Height` of a vie
 The `DimAutoStyle` enum defines the different ways that `Dim.Auto` can be used to size a view. The `DimAutoStyle` enum has the following values:
 
 * `Text` - The view is sized based on the `Text` property and `TextFormatter` settings.
-* `Content` - The view is sized based on either the `ContentSize` or the `Subviews` property. If `ContentSize` is null, the view is sized based on the size of the subviews (the Subview with the largest relvant dimension plus location will dictate the size). If `ContentSize` is not null, the view is sized based on the `ContentSize` property.
-* `Auto` -  The view is sized based on both `Text` and `Content`, whichever is larger.
+* `Content` - The view is sized based on either the `ContentSize` or the `Subviews` property. If `ContentSize` is not explicitly set (via `View.SetContentSize()`), the view is sized based on the Subview with the largest relvant dimension plus location. If `ContentSize` is explicitly set, the view is sized based on the `ContentSize`.
+* `Auto` -  The view is sized based on both the text and content, whichever is larger.
 
 ## Using Dim.Auto
 
 `Dim.Auto` is defined as:
 
 ```cs
-public static Dim Auto (DimAutoStyle style = DimAutoStyle.Auto, Dim min = null, Dim max = null)
+public static Dim Auto (DimAutoStyle style = DimAutoStyle.Auto, Dim minimumContentDim = null, Dim max = null)
 ```
 
 To use `Dim.Auto`, set the `Width` or `Height` property of a view to `Dim.Auto (DimAutoStyle.Text)` or `Dim.Auto (DimAutoStyle.Content)`.
@@ -49,17 +49,32 @@ In this example, the `View` will be sized based on the size of the `Label` that
 
 ### Specifying a miniumum size
 
-You can specify a minimum size by passing a `Dim` object to the `min` parameter. For example, to create a `View` that is sized based on the `Text` property, but has a minimum width of 10 columns, you can do this:
+You can specify a minimum size by passing a `Dim` object to the `minimumContentDim` parameter. For example, to create a `View` that is sized based on the `Text` property, but has a minimum width of 10 columns, you can do this:
 
 ```cs
 View view = new ()
 {
     Text = "Hello, World!",
-    Width = Dim.Auto (DimAutoStyle.Text, min: Dim.Absolute (10)),
+    Width = Dim.Auto (DimAutoStyle.Text, minimumContentDim: Dim.Absolute (10)), // Same as `minimumContentDim: 10`
     Height = Dim.Auto (DimAutoStyle.Text),
 };
 ```
 
+Sometimes it's useful to have the minimum size be dynamic. Use `Dim.Func` as follows:
+
+```cs
+View view = new ()
+{
+    Width = Dim.Auto (DimAutoStyle.Content, minimumContentDim: Dim.Func (GetDynamicMinSize)),
+    Height = Dim.Auto (DimAutoStyle.Text),
+};
+
+int GetDynamicMinSize () 
+{
+    return someDynamicInt;
+}
+```
+
 ### Specifying a maximum size
 
 > NOT YET IMPLEMENTED
@@ -76,14 +91,15 @@ Some `Pos` and `Dim` types are not compatible with `Dim.Auto`. For example, you
 
 `Pos` types that are relative to the size of the view, such as `Pos.Percent (n)` are not compatible with `Dim.Auto` because the size of the view is not known until the layout is computed. However, `Pos.Center ()` and `Pos.AnchorEnd ()` are compatible with `Dim.Auto` because they are relative to the size of the view's Superview.
 
-
 ## Building Dim.Auto friendly View
 
-It is common to build View classes that have a natrual size based on their content. For example, the `Label` class is a view that is sized based on the `Text` property. Another example is `Slider` which is size based on the number of options it has, it's orientation, etc... 
+It is common to build View classes that have a natrual size based on their content. For example, the `Label` class is a view that is sized based on the `Text` property. 
+
+`Slider` is a good example of sophsticated Dim.Auto friendly view.
 
 Developers using these views shouldn't need to know the details of how the view is sized, they should just be able to use the view and have it size itself correctly.
 
-For example, a vertical `Slider` with 3 options may be created like this:
+For example, a vertical `Slider` with 3 options may be created like this: which is size based on the number of options it has, it's orientation, etc... 
 
 ```cs
 List<object> options = new () { "Option 1", "Option 2", "Option 3" };
@@ -97,7 +113,6 @@ view.Add (slider);
 
 Note the developer does not need to specify the size of the `Slider`, it will size itself based on the number of options and the orientation. 
 
-Views like `Slider` do this by setting `Width` and `Height` to `Dim.Auto (DimAutoStyle.Content)` in the constructor and and setting the `ContentSize` property to the size that the view should be in the `LayoutStarted` event handler.
-
-Views that use `Text` for their content can just set `Width` and `Height` to `Dim.Auto (DimAutoStyle.Text)`.
+Views like `Slider` do this by setting `Width` and `Height` to `Dim.Auto (DimAutoStyle.Content)` in the constructor and calling `SetContentSize ()` whenever the desired content size changes. The View will then be sized to be big enough to fit the content.
 
+Views that use `Text` for their content can just set `Width` and `Height` to `Dim.Auto (DimAutoStyle.Text)`. It is recommended to use `Height = Dim.Auto (DimAutoStyle.Text, minimumContentDim: 1)` to ensure the View can show at least one line of text.

docfx/docs/layout.md

@@ -4,7 +4,6 @@ Terminal.Gui provides a rich system for how `View` objects are laid out relative
 
 ## Coordinates
 
-
 * **Screen-Relative** - Describes the dimensions and characteristics of the underlying terminal. Currently Terminal.Gui only supports applications that run "full-screen", meaning they fill the entire terminal when running. As the user resizes their terminal, the `Screen` changes size and the applicaiton will be resized to fit. *Screen-Relative* means an origin (`0, 0`) at the top-left corner of the terminal. `ConsoleDriver`s operate exclusively on *Screen-Relative* coordinates.
 * **Application.Relative** - The dimensions and characteristics of the application. Because only full-screen apps are currently supported, `Application` is effectively the same as `Screen` from a layout perspective. *Application-Relative* currently means an origin (`0, 0`) at the top-left corner of the terminal. `Applicaiton.Top` is a `View` with a top-left corner fixed at the *Application.Relative* coordinate of (`0, 0`) and is the size of `Screen`.
 * **Frame-Relative**  - The `Frame` property of a `View` is a rectangle that describes the current location and size of the view relative to the `Superview`'s content area. *Frame-Relative* means a coordinate is relative to the top-left corner of the View in question. `View.FrameToScreen ()` and `View.ScreenToFrame ()` are helper methods for translating a *Frame-Relative* coordinate to a *Screen-Relative* coordinate and vice-versa.
@@ -17,15 +16,15 @@ The `Frame` property of a `View` is a rectangle that describes the current locat
 
 ## The Content Area
 
- The content area is the area where the view's content is drawn. Content can be any combination of the `View.Text` property, `Subviews`, and other content drawn by the View. The `View.ContentSize` property defines the size of the content area of the view. *Content Area* refers to the rectangle with a location of `0,0` with a size of `ContentSize`.
+ The content area is the area where the view's content is drawn. Content can be any combination of the `View.Text` property, `Subviews`, and other content drawn by the View. The `View.ContentSize` property gets the size of the content area of the view. *Content Area* refers to the rectangle with a location of `0,0` with a size of `ContentSize`.
 
- `ContentSize` is `null` by default. If `ContentSize` is `null`, the content area is the size of the `Viewport`. If `ContentSize` is set, the content area is the size of `ContentSize`. If `ContentSize` is larger than the `Viewport`, scrolling is enabled. 
+ `ContentSize` tracks the size of the `Viewport` by default. If `ContentSize` is set via `SetContentSize()`, the content area is the provided size. If `ContentSize` is larger than the `Viewport`, scrolling is enabled. 
 
 ## The Viewport
 
 The Viewport (`View.Viewport`) is a rectangle describing the portion of the *Content Area* that is currently visible to the user. It is a "portal" into the content. The `Viewport.Location` is relative to the top-left corner of the inner rectangle of `View.Padding`. If `Viewport.Size` is the same as `View.ContentSize`, `Viewport.Location` will be `0,0`. 
 
-To enable scrolling set `View.ContentSize` and then set `Viewport.Location` to positive values. Making `Viewport.Location` positive moves the Viewport down and to the right in the content. 
+To enable scrolling call `View.SetContentSize()` and then set `Viewport.Location` to positive values. Making `Viewport.Location` positive moves the Viewport down and to the right in the content. 
 
 The `View.ViewportSettings` property controls how the Viewport is constrained. By default, the `ViewportSettings` is set to `ViewportSettings.None`. To enable the viewport to be moved up-and-to-the-left of the content, use `ViewportSettings.AllowNegativeX` and or `ViewportSettings.AllowNegativeY`. 
 
@@ -74,7 +73,6 @@ All `Pos` coordinates are relative to the Superview's content area.
 ```cs
 // Set the X coordinate to 10 characters left from the center
 view.X = Pos.Center () - 10;
-
 view.Y = Pos.Percent (20);
 
 anotherView.X = AnchorEnd (10);

docfx/docs/migratingfromv1.md

@@ -120,7 +120,7 @@ In v1, `View.AutoSize` was used to size a view to its `Text`. In v2, `View.AutoS
 
 ### How to Fix
 
-* Replace `View.AutoSize = true` with `View.Width = Dim.Auto` or `View.Height = Dim.Auto` as needed.
+* Replace `View.AutoSize = true` with `View.Width = Dim.Auto` or `View.Height = Dim.Auto` as needed. See the [DimAuto Deep Dive](dimauto.md) for more information.
 
 ## Adornments
 

docfx/docs/newinv2.md

@@ -27,7 +27,7 @@ The entire library has been reviewed and simplified. As a result, the API is mor
 * *Built-in Scrolling/Virtual Content Area* - In v1, to have a view a user could scroll required either a bespoke scrolling implementation, inheriting from `ScrollView`, or managing the complexity of `ScrollBarView` directly. In v2, the base-View class supports scrolling inherently. The area of a view visible to the user at a given moment was previously a rectangle called `Bounds`. `Bounds.Location` was always `Point.Empty`. In v2 the visible area is a rectangle called `Viewport` which is a protal into the Views content, which can be bigger (or smaller) than the area visible to the user. Causing a view to scroll is as simple as changing `View.Viewport.Location`. The View's content described by `View.ContentSize`. See [Layout](layout.md) for details.
 * *Computed Layout Improvements* - 
 * *`Pos.AnchorEnd ()`* - New to v2 is `Pos.AnchorEnd ()` (with no parameters) which allows a view to be anchored to the right or bottom of the Superview. 
-* *`Dim.Auto`* - 
+* *`Dim.Auto`* - Automatic size based on the View's content (either Subviews or Text) - `Dim.Auto()` - See the [DimAuto Deep Dive](dimauto.md) for more information.
 * ...	
 
 ## New and Improved Built-in Views