Improved API docs

docfx/docs/arrangement.md

@@ -0,0 +1,22 @@
+# View Layout Arrangement
+
+Terminal.Gui provides a feature of Layout known as **Arrangement**, which controls how the user can use the mouse and keyboard to arrange views and enables either **Tiled** or **Overlapped** layouts. Arrangement is a sub-topic of [Layout](layout.md).
+
+
+* **Arrangement** - Describes the feature of [Layout](layout.md) which controls how the user can use the mouse and keyboard to arrange views and enables either **Tiled** or **Overlapped** layouts.
+
+* **Arrange Mode** - When a user presses `Ctrl+F5` (configurable via the [Application.ArrangeKey](~/api/Terminal.Gui.Application.ArrangeKey)) the application goes into **Arrange Mode**. In this mode, indicators are displayed on an arrangeable view indicating which aspect of the View can be arranged. If [Movable](~/api/Terminal.Gui.ViewArrangement.Movable.yml), a `◊` will be displayed in the top-left corner of the [Border](~/api/Terminal.Gui.View.Border). If [Sizable](~/api/Terminal.Gui.ViewArrangement.Sizable.yml), pressing `Tab` (or `Shift+Tab`) will cycle to an an indictor in the bottom-right corner of the Border. The up/down/left/right cursor keys will act appropriately. `Esc`, `Ctrl+F5` or clicking outside of the Border will exit Arrange Mode.
+
+* **Modal** - A modal view is one that is run as an "application" via `Application.Run(Toplevel)` where `Modal == true`. `Dialog`, `Messagebox`, and `Wizard` are the prototypical examples. When run this way, there IS a `z-order` but it is highly-constrained: the modal view has a z-order of 1 and everything else is at 0. 
+
+* **Movable** - Describes a View that can be moved by the user using the keyboard or mouse. **Movable** is enabled on a per-View basis by setting the [ViewArrangement.Movable](~/api/Terminal.Gui.ViewArrangement.Movable.yml) flag on [View.Arrangement](~/api/Terminal.Gui.View.Arrangement.yml). Dragging on the top [Border](~/api/Terminal.Gui.View.Border) of a View will move such a view. Pressing `Ctrl+F5` will activate **Arrange Mode** letting the user move the view with the up/down/left/right cursor keys.
+
+* **Overlapped** - A form of layout where SubViews of a View are visually arranged such that their Frames overlap. In Overlap view arrangements there is a Z-axis (Z-order) in addition to the X and Y dimension. The Z-order indicates which Views are shown above other views. **Overlapped** is enabled on a per-View basis by setting the [ViewArrangement.Overlapped](~/api/Terminal.Gui.ViewArrangement.Overlapped.yml) flag on [View.Arrangement](~/api/Terminal.Gui.View.Arrangement.yml). 
+
+* **Sizable** - Describes a View that can be sized by the user using the keyboard or mouse. **Sizable** is enabled on a per-View basis by setting the [ViewArrangement.Sizable](~/api/Terminal.Gui.ViewArrangement.Sizable.yml) flag on [View.Arrangement](~/api/Terminal.Gui.View.Arrangement.yml). Dragging on the left, right, or bottom [Border](~/api/Terminal.Gui.View.Border) of a View will size that side of such a view. Pressing `Ctrl+F5` will activate **Arrange Mode** letting the user size the view with the up/down/left/right cursor keys.
+
+* **Tiled** - A form of layout where SubViews of a View are visually arranged such that their Frames do not typically overlap. With **Tiled** views, there is no 'z-order` to the Subviews of a View. In most use-cases, subviews do not overlap with each other (the exception being when it's done intentionally to create some visual effect). As a result, the default layout for most TUI apps is "tiled", and by default [View.Arrangement](~/api/Terminal.Gui.View.Arrangement.yml) is set to [ViewArrangement.Fixed](~/api/Terminal.Gui.ViewArrangement.Fixed.yml).
+
+* **Runnable** - Today, Overlapped and Runnable are intrinsically linked. A runnable view is one where `Application.Run(Toplevel)` is called.  Each *Runnable* view where (`Modal == false`) has it's own `RunState` and is, effectively, a self-contained "application". `Application.Run()` non-preemptively dispatches events (screen, keyboard, mouse , Timers, and Idle handlers) to the associated `Toplevel`. It is possible for such a `Toplevel` to create a thread and call `Application.Run(someotherToplevel)` on that thread, enabling pre-emptive user-interface multitasking (`BackgroundWorkerCollection` does this). 
+
+

docfx/docs/index.md

@@ -26,6 +26,7 @@ See [What's New in V2 For more](newinv2.md).
 * [Navigation](navigation.md)
 * [Keyboard API](keyboard.md)
 * [Mouse API](mouse.md)
+* [Arrangement API](arrangement.md)
 * [Configuration and Theme Manager](config.md)
 * [Multi-tasking and the Application Main Loop](mainloop.md)
 * [Cross-platform Driver Model](drivers.md)

docfx/docs/layout.md

@@ -2,6 +2,8 @@
 
 Terminal.Gui provides a rich system for how `View` objects are laid out relative to each other. The layout system also defines how coordinates are specified.
 
+In addition to the Layout system described here, Terminal.Gui provides a feature of Layout known as **Arrangement**, which controls how the user can use the mouse and keyboard to arrange views and enables either **Tiled** or **Overlapped** layouts. See the [Arrangement Deep Dive](arrangement.md) for more. 
+
 ## 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.
@@ -34,6 +36,8 @@ The default `ViewportSettings` also constrains the Viewport to the size of the c
 
 Terminal.Gui provides a rich system for how views are laid out relative to each other. The position of a view is set by setting the `X` and `Y` properties, which are of time [Pos](~/api/Terminal.Gui.Pos.yml). The size is set via `Width` and `Height`, which are of type [Dim](~/api/Terminal.Gui.Dim.yml).
 
+See also [Arrangement API](arrangement.md).
+
 ```cs
 var label1 = new Label () { X = 1, Y = 2, Width = 3, Height = 4, Title = "Absolute")
 

docfx/docs/migratingfromv1.md

@@ -452,3 +452,25 @@ In v2, these methods have been named correctly.
 - `SendSubViewBackward` -> `MoveSubviewTowardsStart` - Moves the specified subview one position towards the start of the list.
 - `SendSubViewToFront` -> `MoveSubviewToEnd` - Moves the specified subview to the end of the list.
 - `SendSubViewForward` -> `MoveSubviewTowardsEnd` - Moves the specified subview one position towards the end of the list.
+
+## `Mdi` Replaced by `ViewArrangement.Overlapped`
+
+In v1, it apps with multiple overlapping views could be created using a set of APIs spread across `Application` (e.g. `Application.MdiTop`) and `Toplevel` (e.g. `IsMdiContainer`). This functionality has been replaced in v2 with [View.Arrangement](~/api/Terminal.Gui.View.Arrangement.yml). Specifically, overlapped views with [View.Arrangement](~/api/Terminal.Gui.View.Arrangement.yml) having the [ViewArrangement.Overlapped](~/api/Terminal.Gui.ViewArrangement.Overlapped.yml) flag set will be arranged in an overlapped fashion using the order in their SuperView's subview list as the Z-order. 
+
+Setting the [ViewArrangement.Movable](~/api/Terminal.Gui.ViewArrangement.Movable.yml) flag will enable the overlapped views to be movable with the mouse or keyboard (`Ctrl+F5` to activate).
+
+Setting the [ViewArrangement.Sizable](~/api/Terminal.Gui.ViewArrangement.Sizable.yml) flag will enable the overlapped views to be resized with the mouse or keyboard (`Ctrl+F5` to activate).
+
+In v1, only Views derived from `Toplevel` could be overlapped. In v2, any view can be.
+
+v1 conflated the concepts of 
+
+## Others...
+
+* `View` and all subclasses support `IDisposable` and must be disposed (by calling `view.Dispose ()`) by whatever code owns the instance when the instance is longer needed. 
+
+* To simplify programming, any `View` added as a Subview another `View` will have it's lifecycle owned by the Superview; when a `View` is disposed, it will call `Dispose` on all the items in the `Subviews` property. Note this behavior is the same as it was in v1, just clarified.
+
+* In v1, [Application.End](~/api/Terminal.Gui.Application.Run.yml) called `Dispose ()` on [Application.Top](~/api/Terminal.Gui.Application.Top.yml) (via `Runstate.Toplevel`). This was incorrect as it meant that after `Application.Run` returned, `Application.Top` had been disposed, and any code that wanted to interrogate the results of `Run` by accessing `Application.Top` only worked by accident. This is because GC had not actually happened; if it had the application would have crashed. In v2 `Application.End` does NOT call `Dispose`, and it is the caller to `Application.Run` who is responsible for disposing the `Toplevel` that was either passed to `Application.Run (View)` or created by `Application.Run<T> ()`.
+
+* Any code that creates a `Toplevel`, either by using `top = new()` or by calling either `top = Application.Run ()` or `top = ApplicationRun<T>()` must call `top.Dispose` when complete. The exception to this is if `top` is passed to `myView.Add(top)` making it a subview of `myView`. This is because the semantics of `Add` are that the `myView` takes over responsibility for the subviews lifetimes. Of course, if someone calls `myView.Remove(top)` to remove said subview, they then re-take responsbility for `top`'s lifetime and they must call `top.Dispose`.

docfx/docs/newinv2.md

@@ -12,25 +12,21 @@ Apps built with Terminal.Gui now feel modern thanks to these improvements:
 * *Enhanced Borders and Padding* - Terminal.Gui now supports a `Border`, `Margin`, and `Padding` property on all views. This simplifies View development and enables a sophisticated look and feel. See [Adornments](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#adornments) for details.
 * *User Configurable Color Themes* - See [Color Themes](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#color-themes) for details.
 * *Enhanced Unicode/Wide Character support* - Terminal.Gui now supports the full range of Unicode/wide characters. See [Unicode](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#unicode) for details.
-* *[LineCanvas](~/api/Terminal.Gui.Line Canvas.yml)* - Terminal.Gui now supports a line canvas enabling high-performance drawing of lines and shapes using box-drawing glyphs. `LineCanvas` provides *auto join*, a smart TUI drawing system that automatically selects the correct line/box drawing glyphs for intersections making drawing complex shapes easy. See [Line Canvas](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#line-canvas) for details.
+* [LineCanvas](~/api/Terminal.Gui.LineCanvas.yml) - Terminal.Gui now supports a line canvas enabling high-performance drawing of lines and shapes using box-drawing glyphs. `LineCanvas` provides *auto join*, a smart TUI drawing system that automatically selects the correct line/box drawing glyphs for intersections making drawing complex shapes easy. See [Line Canvas](https://gui-cs.github.io/Terminal.GuiV2Docs/docs/overview.html#line-canvas) for details.
 
 ## Simplified API
 
 The entire library has been reviewed and simplified. As a result, the API is more consistent and uses modern .NET API standards (e.g. for events). This refactoring resulted in the removal of thousands of lines of code, better unit tests, and higher performance than v1. See [Simplified API](overview.md#simplified-api) for details.
 
-## `View` Improvements
-* *View Lifetime Management is Now Deterministic* - In v1 the rules ofr lifetime management of `View` objects was unclear and led to non-dterministic behavior and hard to diagnose bugs. This was particularly acute in the behavior of `Application.Run`. In v2, the rules are clear and the code and unit test infrastructure tries to enforce them. 
-  * `View` and all subclasses support `IDisposable` and must be disposed (by calling `view.Dispose ()`) by whatever code owns the instance when the instance is longer needed. 
-  * To simplify programming, any `View` added as a Subview another `View` will have it's lifecycle owned by the Superview; when a `View` is disposed, it will call `Dispose` on all the items in the `Subviews` property. Note this behavior is the same as it was in v1, just clarified.
-  * In v1, `Application.End` called `Dispose ()` on `Application.Top` (via `Runstate.Toplevel`). This was incorrect as it meant that after `Application.Run` returned, `Application.Top` had been disposed, and any code that wanted to interogate the results of `Run` by accessing `Application.Top` only worked by accident. This is because GC had not actually happened; if it had the application would have crashed. In v2 `Application.End` does NOT call `Dispose`, and it is the caller to `Application.Run` who is responsible for disposing the `Toplevel` that was either passed to `Application.Run (View)` or created by `Application.Run<T> ()`.
-	* Any code that creates a `Toplevel`, either by using `top = new()` or by calling either `top = Application.Run ()` or `top = ApplicationRun<T>()` must call `top.Dispose` when complete.
-  	*  The exception to this is if `top` is passed to `myView.Add(top)` making it a subview of `myView`. This is because the semantics of `Add` are that the `myView` takes over responsibility for the subviews lifetimes. Of course, if someone calls `myView.Remove(top)` to remove said subview, they then re-take responsbility for `top`'s lifetime and they must call `top.Dispose`.
-* New! *Adornments* -  Adornments are a special form of View that appear outside the `Viewport`: `Margin`, `Border`, and `Padding`.
-* New! *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.GetContentSize()`. See [Layout](layout.md) for details.
-* New! *`Dim.Auto`* - Automatically sizes the view to fitthe view's Text, SubViews, or ContentArea.
-* Improved! *`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. 
-* New! *`Pos.Align ()`* - Aligns a set of views horizontally or vertically (left, rigth, center, etc...).
-* Keyboard [Navigation](navigation.md) has been revamped to be more reliability and ensure TUI apps built with Terminal.Gui are accessible. 
+## [View](~/api/Terminal.Gui.View.yml) Improvements
+* *Improved!* View Lifetime Management is Now Deterministic - In v1 the rules ofr lifetime management of `View` objects was unclear and led to non-dterministic behavior and hard to diagnose bugs. This was particularly acute in the behavior of [Application.Run](~/api/Terminal.Gui.Application.Run.yml). In v2, the rules are clear and the code and unit test infrastructure tries to enforce them. See [Migrating From v1 To v2](migratingfromv1.md) for more details.
+* *New!* Adornments - Adornments are a special form of View that appear outside the `Viewport`: [Margin](~/api/Terminal.Gui.View.Margin.yml), [Border](~/api/Terminal.Gui.View.Border.yml), and [Padding](~/api/Terminal.Gui.View.Padding.yml).
+* *New!* 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.GetContentSize()`. See [Layout](layout.md) for details.
+* *New!* [Dim.Auto](~/api/Terminal.Gui.Dim.Auto.yml) - Automatically sizes the view to fitthe view's Text, SubViews, or ContentArea.
+* *Improved!* [Pos.AnchorEnd](~/api/Terminal.Gui.Pos.AnchorEnd.yml) - New to v2 is `Pos.AnchorEnd ()` (with no parameters) which allows a view to be anchored to the right or bottom of the Superview. 
+* *New!* [Pos.Align](~/api/Terminal.Gui.Pos.Align.yml) - Aligns a set of views horizontally or vertically (left, rigth, center, etc...).
+* *New!* [View.Arrangement](~/api/Terminal.Gui.View.Arrangement.yml) enables tiled and overlapped view arrangement and moving/resizing Views with the keyboard and mouse. See [Arrangement](arrangement.md).
+* *Improved!* Keyboard [Navigation](navigation.md) has been revamped to be more reliability and ensure TUI apps built with Terminal.Gui are accessible. 
 
 ## New and Improved Built-in Views
 

docfx/docs/toc.yml

@@ -6,10 +6,14 @@
   href: newinv2.md
 - name: v1 To v2 Migration
   href: migratingfromv1.md  
+- name: View Deep Dive
+  href: View.md  
 - name: List of Views
   href: views.md
 - name: Layout Engine
   href: layout.md
+- name: Arrangement
+  href: arrangement.md
 - name: Navigation
   href: navigation.md
 - name: Keyboard