Merge branch 'gui-cs:v2_develop' into v2_develop

tig · web-flow · commit 82bab3957d57 · 2024-11-19T14:12:44.000-07:00
diff --git a/README.md b/README.md
@@ -49,91 +49,7 @@ The team is looking forward to seeing new amazing projects made by the community
 
 The following example shows a basic Terminal.Gui application in C#:
 
-```csharp
-// This is a simple example application.  For the full range of functionality
-// see the UICatalog project
-
-// A simple Terminal.Gui example in C# - using C# 9.0 Top-level statements
-
-using System;
-using Terminal.Gui;
-
-Application.Run<ExampleWindow> ().Dispose ();
-
-// Before the application exits, reset Terminal.Gui for clean shutdown
-Application.Shutdown ();
-
-// To see this output on the screen it must be done after shutdown,
-// which restores the previous screen.
-Console.WriteLine ($@"Username: {ExampleWindow.UserName}");
-
-// Defines a top-level window with border and title
-public class ExampleWindow : Window
-{
-    public static string UserName;
-
-    public ExampleWindow ()
-    {
-        Title = $"Example App ({Application.QuitKey} to quit)";
-
-        // Create input components and labels
-        var usernameLabel = new Label { Text = "Username:" };
-
-        var userNameText = new TextField
-        {
-            // Position text field adjacent to the label
-            X = Pos.Right (usernameLabel) + 1,
-
-            // Fill remaining horizontal space
-            Width = Dim.Fill ()
-        };
-
-        var passwordLabel = new Label
-        {
-            Text = "Password:", X = Pos.Left (usernameLabel), Y = Pos.Bottom (usernameLabel) + 1
-        };
-
-        var passwordText = new TextField
-        {
-            Secret = true,
-
-            // align with the text box above
-            X = Pos.Left (userNameText),
-            Y = Pos.Top (passwordLabel),
-            Width = Dim.Fill ()
-        };
-
-        // Create login button
-        var btnLogin = new Button
-        {
-            Text = "Login",
-            Y = Pos.Bottom (passwordLabel) + 1,
-
-            // center the login button horizontally
-            X = Pos.Center (),
-            IsDefault = true
-        };
-
-        // When login button is clicked display a message popup
-        btnLogin.Accept += (s, e) =>
-                           {
-                               if (userNameText.Text == "admin" && passwordText.Text == "password")
-                               {
-                                   MessageBox.Query ("Logging In", "Login Successful", "Ok");
-                                   UserName = userNameText.Text;
-                                   Application.RequestStop ();
-                               }
-                               else
-                               {
-                                   MessageBox.ErrorQuery ("Logging In", "Incorrect username or password", "Ok");
-                               }
-                           };
-
-        // Add the views to the Window
-        Add (usernameLabel, userNameText, passwordLabel, passwordText, btnLogin);
-    }
-}
-```
+[!code-csharp[](./Example/Example.cs)]
 
 When run the application looks as follows:
 
diff --git a/docfx/docs/arrangement.md b/docfx/docs/arrangement.md
@@ -5,7 +5,7 @@ Terminal.Gui provides a feature of Layout known as **Arrangement**, which contro
 
 * **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 @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 @Terminal.Gui.ViewArrangement.Movable, a `◊` will be displayed in the top-left corner of the @Terminal.Gui.View.Border. If @Terminal.Gui.ViewArrangement.Resizable , 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.
+* **Arrange Mode** - The Arrange Modes are set via @Terminal.Gui.View.ViewArrangement. When a user presses `Ctrl+F5` (configurable via the @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 @Terminal.Gui.ViewArrangement.Movable, a `◊` will be displayed in the top-left corner of the @Terminal.Gui.View.Border. If @Terminal.Gui.ViewArrangement.Resizable , 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 @Terminal.Gui.Application.Run(System.Func{System.Exception,System.Boolean},Terminal.Gui.ConsoleDriver) 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. 
 
diff --git a/docfx/docs/index.md b/docfx/docs/index.md
@@ -91,7 +91,7 @@ var button = new Button () {
     Width = Dim.Fill (),
     Height = Dim.Fill () - 1
 };
-button.Clicked += () => {
+button.Accepting += () => {
     MessageBox.Query (50, 5, "Hi", "Hello World! This is a message box", "Ok");
 };
 
@@ -143,26 +143,7 @@ Views can either be Modal or Non-modal. Modal views take over all user input unt
 To run any View (but especially Dialogs, Windows, or Toplevels) modally, invoke the `Application.Run` method on a Toplevel. Use the `Application.RequestStop()` method to terminate the modal execution.
 
 ```csharp
-bool okpressed = false;
-var ok = new Button(3, 14, "Ok") { 
-    Clicked = () => { Application.RequestStop (); okpressed = true; }
-};
-var cancel = new Button(10, 14, "Cancel") {
-    Clicked = () => Application.RequestStop () 
-};
-var dialog = new Dialog ("Login", 60, 18, ok, cancel);
 
-var entry = new TextField () {
-    X = 1, 
-    Y = 1,
-    Width = Dim.Fill (),
-    Height = 1
-};
-dialog.Add (entry);
-Application.Run (dialog);
-if (okpressed)
-    Console.WriteLine ("The user entered: " + entry.Text);
-dialog.Dispose ();
 ```
 
 There is no return value from running modally, so the modal view must have a mechanism to indicate the reason the modal was closed. In the case above, the `okpressed` value is set to true if the user pressed or selected the `Ok` button.
diff --git a/docfx/docs/layout.md b/docfx/docs/layout.md
@@ -82,7 +82,7 @@ To enable scrolling call `View.SetContentSize()` and then set `Viewport.Location
 
 See the [Scrolling Deep Dive](scrolling.md) for details on how to enable scrolling.
 
-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`. 
+The @Terminal.Gui.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`. 
 
 The default `ViewportSettings` also constrains the Viewport to the size of the content, ensuring the right-most column or bottom-most row of the content will always be visible (in v1 the equivalent concept was `ScrollBarView.AlwaysKeepContentInViewport`). To allow the Viewport to be smaller than the content, set `ViewportSettings.AllowXGreaterThanContentWidth` and/or `ViewportSettings.AllowXGreaterThanContentHeight`.
 
diff --git a/docfx/docs/scrolling.md b/docfx/docs/scrolling.md
@@ -40,15 +40,13 @@ These Scenarios illustrate Terminal.Gui scrolling:
 
 ## [Viewport Settings](~/api/Terminal.Gui.ViewportSettings.yml)
 
-Use [View.ViewportSettings](~/api/Terminal.Gui.View.ViewportSettings.yml) to adjust the behavior of scrolling. 
+Use  @Terminal.Gui.ViewporSettings to adjust the behavior of scrolling. 
 
-* [AllowNegativeX/Y](~/api/Terminal.Gui.ViewportSettings.AllowNegativeXyml) - If set, Viewport.Size can be set to negative coordinates enabling scrolling beyond the top-left of the content area.
+* `AllowNegativeX/Y` - If set, Viewport.Size can be set to negative coordinates enabling scrolling beyond the top-left of the content area.
 
-* [AllowX/YGreaterThanContentWidth](~/api/Terminal.Gui.ViewportSettings.AllowXGreaterThanContentWidth) - If set, Viewport.Size can be set values greater than GetContentSize() enabling scrolling beyond the bottom-right of the Content Area. When not set, `Viewport.X/Y` are constrained to the dimension of the content area - 1. This means the last column of the content will remain visible even if there is an attempt to scroll the Viewport past the last column. The practical effect of this is that the last column/row of the content will always be visible.
+* `AllowX/YGreaterThanContentWidth` - If set, Viewport.Size can be set values greater than GetContentSize() enabling scrolling beyond the bottom-right of the Content Area. When not set, `Viewport.X/Y` are constrained to the dimension of the content area - 1. This means the last column of the content will remain visible even if there is an attempt to scroll the Viewport past the last column. The practical effect of this is that the last column/row of the content will always be visible.
 
-* [ClipContentOnly](~/api/Terminal.Gui.ViewportSettings.ClipContentOnly) - By default, clipping is applied to [Viewport](~/api/Terminal.Gui.View.Viewport.yml). Setting this flag will cause clipping to be applied to the visible content area.
+* `ClipContentOnly` - By default, clipping is applied to [Viewport](~/api/Terminal.Gui.View.Viewport.yml). Setting this flag will cause clipping to be applied to the visible content area.
 
-* [ClearContentOnly](~/api/Terminal.Gui.ViewportSettings.ClearContentOnly) - If set [View.Clear()](~/api/Terminal.Gui.View.Clear.yml) will clear only the portion of the content area that is visible within the Viewport. This is useful for views that have a content area larger than the Viewport and want the area outside the content to be visually distinct.
-
-* [EnableHorizontal/VerticalScrollBar](~/api/Terminal.Gui.ViewportSettings.EnableHorizontalScrollBar) - If set, the scroll bar will be enabled and automatically made visible when the corresponding dimension of [View.Viewport](~/api/Terminal.Gui.View.Viewport.yml) is smaller than the dimension of [View.GetContentSize()](~/api/Terminal.Gui.View.GetContentSize.yml).
+* `ClearContentOnly`- If set [View.Clear()](~/api/Terminal.Gui.View.Clear.yml) will clear only the portion of the content area that is visible within the Viewport. This is useful for views that have a content area larger than the Viewport and want the area outside the content to be visually distinct.
 
diff --git a/docfx/docs/toc.yml b/docfx/docs/toc.yml
@@ -16,6 +16,8 @@
   href: arrangement.md
 - name: Navigation
   href: navigation.md
+- name: Scrolling
+  href: scrolling.md
 - name: Keyboard
   href: keyboard.md
 - name: Mouse
