Fixes #4004 & #4445 - Merge of Application.ForceDriver and Driver.Force16Colors and windows" broken in conhost and cmd (#4448)

* Fixes #4004. Driver "windows" broken in conhost and cmd * Fix unit tests * Remove IsVirtualTerminal from IApplication. Add IDriverInternal and IOutputInternal interfaces * Fix result.IsSupported * Remove internal interfaces and add them in the implementations classes * Move Sixel from IApplication to IDriver interface it's a characteristic of the driver * Only if IOutput is OutputBase then set the internal properties * Prevents driver windows error on Unix system * Fix scenario sixel error * Comment some tests because is keyboard layout dependent and shifted key is needed to produce them (Pt) * Add 🇵🇹 regional indicators test proving they ca be joined as only one grapheme * SetConsoleActiveScreenBuffer is already called by the constructor and is only needed once * Finally fixed non virtual terminal in windows driver * Add more Sixel unit tests * Add unit tests for OutputBase class * Avoid emit escape sequence * Fix assertion failure in UICatalog * Let each driver to deal with the Sixel write * When Shutdown is called by the static Application then the ApplicationImpl.ResetStateStatic should be also called * Add more OutputBase with Sixel unit tests * Fix some issues with IsVirtualTerminal and Force16Colors with unit tests improvement * Add Sixel Detect method unit test * Make Sixel IsSupported and SupportsTransparency consistent with more unit tests * Fix namespaces and unit test * Covering more ApplicationImpl Sixel unit test * Remove DriverImplProxy because sometimes fails in parallel unit tests * Fix Init_KeyBindings_Are_Not_Reset unit test failing * Revert "Fix Init_KeyBindings_Are_Not_Reset unit test failing" This reverts commit 0ab298bc56. * Fix Force16Colors but still use Application.Force16Colors because of CM * Enforce conditional * Revert change * Moving to a new file * Add the same workaround as the All_Scenarios_Benchmark unit test * Fixes #4440. TextView with ReadOnly as true, MoveRight doesn't select text up to the end of the line * Fixes #4442. TextField PositionCursor doesn't treat zero width as one column * Each character must return at least one column, with the exception of Tab. * Add unit test for the ScrollOffset * Each character must return at least one column, with the exception of Tab. * Add unit test for the LeftColumn * WIP * Refactor DriverImpl and OutputBase for maintainability Refactored `DriverImpl` to remove `IDisposable` and streamline event handling, including replacing `OnSizeMonitorOnSizeChanged` with an inline lambda. Reintroduced `SizeChanged` and updated `SetScreenSize` to invoke it. Moved `SupportsTrueColor` from `OutputBase` to `DriverImpl` and reintroduced `Force16Colors` with updated logic. Reintroduced and updated several `OutputBuffer`-related properties and methods in `DriverImpl`, including `Screen`, `Clip`, `Cols`, and `Contents`. Moved `Clipboard` from `OutputBase` to `DriverImpl` and initialized it with `FakeClipboard`. Simplified `Refresh` and `ToAnsi` methods in `DriverImpl`. Removed `Force16Colors` from `OutputBase` and simplified method signatures, including `ToAnsi` and `BuildAnsiForRegion`. Fixed a parameter name typo in `AppendOrWriteAttribute`. Made minor code formatting adjustments. These changes improve code maintainability, reduce redundancy, and align the implementation with updated design requirements. * Refactor Force16Colors handling and improve UICatalog Refactored the `Force16Colors` property: - Moved it from `DriverImpl` to `IOutput` and `OutputBase`. - Simplified its management by removing redundant logic. - Added `OnDriverOnForce16ColorsChanged` to handle updates. Updated `UICatalogRunnable`: - Replaced `Driver.Force16Colors` with `Application.Driver.Force16Colors`. - Added an `F7` shortcut to toggle `Force16Colors`. - Removed redundant event handlers and improved formatting. Updated `config.json`: - Replaced `Application.Force16Colors` with `Driver.Force16Colors`. - Improved theme configuration formatting for readability. Other changes: - Removed the `force16Colors` parameter from `IOutput.ToAnsi`. - Improved diagnostics handling in `UICatalogRunnable`. - General code cleanup for readability and maintainability. * Refactor `Force16Colors` access and improve null safety Refactored `Force16Colors` property access to use `Application.Driver!` for null safety and consistency. Updated event handlers to align with this pattern. Replaced nullable `DrawContext?` parameters with non-nullable `DrawContext` in `OnDrawingContent` overrides across multiple classes to enforce stricter nullability checks. Removed unused `_cachedCursorVisibility` field in `OutputBase.cs` and cleaned up commented-out legacy code in `UICatalogRunnable.cs`. Updated XML documentation to reflect method signature changes and property references. Refactored `Shortcut` example in documentation for consistency. Replaced `Application.LayoutAndDraw` with `SetNeedsDraw` for marking views as needing redraw. Performed general code cleanup to remove redundant code and improve consistency. * Refactor ForceDriver and Force16Colors properties Removed `[Obsolete]` from `Application.ForceDriver`, making it a stable API. Added comments to clarify its role as a configuration property and its synchronization with `IApplication.ForceDriver`. Introduced `_forceDriver` as a private backing field. Removed `Force16Colors` from `ApplicationImpl` and eliminated reset logic for `ForceDriver` and `Force16Colors` during shutdown, shifting state management responsibility to the library user. Updated comments in `Driver.cs` to document `Force16Colors` as a configuration property and its synchronization with `IDriver.Force16Colors`. Retained `_force16Colors` as a private backing field for configuration overrides. * Updated docs * There is no way to detect Sixel transparency and so relying in VTS or Xterm with transparency * Fix detect Sixel unit tests with the adjusting code * Refactored Output. * MErging * - Added `OnDriverOnForce16ColorsChanged` method to handle `Driver.Force16ColorsChanged` events and update the `Force16Colors` property. - Implemented `IDisposable` to ensure proper cleanup of resources, including unsubscribing from `SizeMonitor.SizeChanged` and `Driver.Force16ColorsChanged` events, and disposing of `_output`. - Replaced inline `SizeMonitor.SizeChanged` event handler with a dedicated method, `OnSizeMonitorOnSizeChanged`, for better readability and maintainability. - Simplified the `Screen` property by removing commented-out code and directly returning a `Rectangle` based on `OutputBuffer` dimensions. - Updated the `Force16Colors` property to use `_output` for both getting and setting its value. - Performed general cleanup, including removing unused code and improving code structure. * merged * Refactor Sixel handling with ConcurrentQueue Replaced `List<SixelToRender>` with `ConcurrentQueue<SixelToRender>` to improve thread safety and performance in sixel management. Updated the `Images` class to avoid unnecessary removal and re-creation of sixel objects by updating existing ones in place. Refactored `Application.Sixel` to return a `ConcurrentQueue` and introduced `GetSixels` in `IDriver` and `IOutput` for consistent access. Updated `OutputBase` to use a private `ConcurrentQueue` and adjusted rendering logic accordingly. Removed legacy and redundant code, including `Application.Driver?.Sixel.Clear()` and unused properties in `DriverImpl` and `ApplicationImpl`. Updated tests in `OutputBaseTests` to align with the new implementation. Added `using System.Collections.Concurrent` where necessary and improved documentation to reflect the changes. These updates enhance thread safety, simplify the codebase, and align with modern concurrent programming practices. * Tweak * Refactor DriverImpl to use Dispose and improve modularity Replaced `Driver.End()` with `Driver.Dispose()` across the codebase, aligning with the `IDisposable` pattern for proper resource cleanup. Updated `DriverImpl` to implement `Dispose`, ensuring event unsubscriptions and resource disposal. Enhanced `DriverImpl` structure by organizing code into logical regions, improving modularity and readability. Refactored and reintroduced methods and properties like `Clipboard`, `Screen`, `SetScreenSize`, `Cols`, `Rows`, and others for better encapsulation. Updated the `IDriver` interface to include `IDisposable` and reorganized it into regions. Added new methods and properties such as `Init`, `Refresh`, `Suspend`, `QueueAnsiRequest`, and `ToAnsi`. Refactored unit tests to replace `driver.End()` with `driver.Dispose()` and ensured proper resource cleanup. Improved code comments and documentation for better clarity. Aligned with modern C# practices, adopting features like null-coalescing operators and pattern matching. Removed redundant code, addressed some TODOs, and modularized the codebase for maintainability and extensibility. * Refactor driver docs and update View.Driver usage Updated `application.md` to clarify the purpose of the `View.Driver` property, replacing the obsolete `Application.Driver`. Added a reference to the "Drivers Deep Dive" documentation for further details. Refactored the `OnDrawContent` method to use the `Driver` property, ensuring compatibility with the new driver architecture. Added a new section, "Testing with the New Architecture," to `application.md`, highlighting the improved testability of the instance-based architecture. Expanded and reorganized `drivers.md` to provide a detailed breakdown of the `IDriver` interface, including lifecycle, components, screen and display, color support, content buffer, drawing, cursor, input events, and ANSI escape sequences. Introduced new subsections for clarity and emphasized the modular design for maintainability. Added a note in `drivers.md` discouraging direct access to the `Driver` and recommending higher-level abstractions like `Terminal.Gui.App.Application.Screen` and `Terminal.Gui.ViewBase.View` methods for positioning and drawing. * Refactor IsVirtualTerminal to IsLegacyConsole Replaced the `IsVirtualTerminal` property with `IsLegacyConsole` across the codebase to better represent legacy versus modern terminal environments. Updated logic in `SixelSupportDetector`, `DriverImpl`, and `OutputBase` to use the new property. Refactored tests to align with the updated property, including renaming test methods, adjusting mock setups, and replacing `VirtualTerminalTests` with `LegacyConsoleTests`. Simplified `WindowsOutput` implementation to handle console modes and sixel rendering based on `IsLegacyConsole`. Removed redundant code related to `IsVirtualTerminal`. Improved code readability and maintainability by using more descriptive property names and ensuring consistency across the codebase. Updated `.DotSettings` with new entries. * Update Examples/UICatalog/Scenarios/LineDrawing.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update Examples/UICatalog/Scenarios/Images.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update Examples/UICatalog/Scenarios/Images.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update Terminal.Gui/App/IApplication.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update Terminal.Gui/App/ApplicationImpl.Lifecycle.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update Examples/UICatalog/Scenarios/ColorPicker.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Update Examples/UICatalog/Scenarios/ColorPicker.cs Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> * Fix formatting and typo in code and documentation Improved code readability in `LineDrawing.cs` by fixing spacing around the ternary operator in `Width` and `Y` property assignments. Corrected a typo in `drivers.md` by changing "Configuraiton Manager" to "Configuration Manager" for accurate documentation. * Test failure casued by assert left in by accident. * Added a workaround in `OutputBase.cs` to address dirty cell handling in legacy console mode by marking all buffer cells as dirty. Refactored `_disableMouseCb` event handling in `UICatalogRunnable.cs` to use the `Selecting` event for toggling `Application.IsMouseDisabled`. Simplified `MouseImpl.cs` by converting `App` to an auto-implemented property and removing redundant namespace usage. Streamlined logging in `WindowsOutput.cs` by replacing verbose `Logging.Logger` calls with shorter alternatives (`Logging.Information`, `Logging.Error`, etc.). * Update theme and remove unused ListView component The application's default theme configuration was updated from "Light" to "Amber Phosphor" by modifying the `ConfigurationManager.RuntimeConfig` value. Additionally, the `ListView` component in the `ExampleWindow` class was removed. This included its initialization, layout properties (`Y`, `Height`, `Width`), and its data source (["One", "Two", "Three", "Four"]). * Increase safety timeout in NestedRunTimeoutTests to 10s The timeout duration for the safety mechanism in the `NestedRunTimeoutTests` class was increased from 5000ms (5s) to 10000ms (10s). This change allows the app more time to complete before triggering the safety timeout, reducing the likelihood of premature termination during long-running tests. Refactor and enhance test coverage Refactored `Load_WithInvalidJson_AddsJsonError` test in `SourcesManagerTests.cs` to improve organization and added a note about its impact on parallel execution. Increased the safety timeout in `NestedRunTimeoutTests.cs` from 5 seconds to 10 seconds to address potential premature test timeouts. * Handle null Driver gracefully in event subscription Replaced `ArgumentNullException.ThrowIfNull(Driver)` with a null-check conditional in `SubscribeDriverEvents` and `UnsubscribeDriverEvents`. If `Driver` is `null`, the methods now log an error using `Logging.Error` and return early. This prevents potential exceptions and improves error handling. --------- Co-authored-by: BDisp <bd.bdisp@gmail.com> Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
2025-12-26 07:47:54 +01:00 · 2025-12-05 17:40:48 -07:00
parent f0343e4c3c
commit d303943809
58 changed files with 2048 additions and 876 deletions
--- a/docfx/docs/application.md
+++ b/docfx/docs/application.md
@@ -81,14 +81,6 @@ sequenceDiagram
 **Terminal.Gui v2** supports both static and instance-based patterns. The static `Application` class is marked obsolete but still functional for backward compatibility. The recommended pattern is to use `Application.Create()` to get an `IApplication` instance:

 ```csharp
-// OLD (v1 / early v2 - still works but obsolete):
-Application.Init ();
-Window top = new ();
-top.Add (myView);
-Application.Run (top);
-top.Dispose ();
-Application.Shutdown (); // Obsolete - use Dispose() instead
-
 // RECOMMENDED (v2 - instance-based with using statement):
 using (IApplication app = Application.Create ().Init ())
 {
@@ -105,11 +97,19 @@ using (IApplication app = Application.Create ().Init ())
    Color? result = app.GetResult<Color> ();
 }

-// SIMPLEST (manual disposal):
+// ALTERNATIVE (manual disposal):
 IApplication app = Application.Create ().Init ();
 app.Run<ColorPickerDialog> ();
 Color? result = app.GetResult<Color> ();
 app.Dispose ();
+
+// OLD (v1 / early v2 - obsolete, avoid in new code):
+Application.Init ();
+Window top = new ();
+top.Add (myView);
+Application.Run (top);
+top.Dispose ();
+Application.Shutdown (); // Obsolete - use Dispose() instead
 ```

 **Note:** The static `Application` class delegates to a singleton instance accessible via `Application.Instance`. `Application.Create()` creates a **new** application instance, enabling multiple application contexts and better testability.
@@ -149,11 +149,12 @@ public class MyView : View
 {
    public override void OnEnter (View view)
    {
-        // Use View.App instead of static Application
-        App?.TopRunnable?.SetNeedsDraw ();
+        // Use View.App instead of obsolete static Application
+        IApplication? app = App;
+        app?.TopRunnable?.SetNeedsDraw ();
        
        // Access SessionStack
-        if (App?.SessionStack.Count > 0)
+        if (app?.SessionStack?.Count > 0)
        {
            // Work with sessions
        }
@@ -171,7 +172,7 @@ public class MyView : View
    public MyView (IApplication app)
    {
        _app = app;
-        // Now completely decoupled from static Application
+        // Completely decoupled from obsolete static Application
    }
    
    public void DoWork ()
@@ -275,7 +276,7 @@ public class FileDialog : Runnable<string?>
        okButton.Accepting += (s, e) =>
        {
            Result = _pathField.Text;
-            Application.RequestStop ();
+            App?.RequestStop ();
        };
        
        Add (_pathField, okButton);
@@ -321,11 +322,13 @@ protected override bool OnIsRunningChanging (bool oldValue, bool newValue)
        // Optionally cancel stop (e.g., unsaved changes)
        if (HasUnsavedChanges ())
        {
-            var response = MessageBox.Query ("Save?", "Save changes?", "Yes", "No", "Cancel");
+            int response = MessageBox.Query ("Save?", "Save changes?", "Yes", "No", "Cancel");
+            
            if (response == 2)
            {
                return true;  // Cancel stop
            }
+            
            if (response == 0)
            {
                Save ();
@@ -691,37 +694,77 @@ app.End (token1);
 // app.TopRunnable == null, SessionStack.Count == 0
 ```

-## View.Driver Property
+## Driver Management

-Similar to `View.App`, views now have a `Driver` property:
+### ForceDriver Configuration Property
+
+The `ForceDriver` property is a configuration property that allows you to specify which driver to use. It can be set via code or through the configuration system (e.g., `config.json`):

 ```csharp
-public class View
+// RECOMMENDED: Set on instance
+using (IApplication app = Application.Create ())
 {
-    /// <summary>
-    /// Gets the driver for this view.
-    /// </summary>
-    public IDriver? Driver => GetDriver ();
-    
-    /// <summary>
-    /// Gets the driver, checking application context if needed.
-    /// Override to customize driver resolution.
-    /// </summary>
-    public virtual IDriver? GetDriver () => App?.Driver;
+    app.ForceDriver = "fake";
+    app.Init ();
 }
+
+// ALTERNATIVE: Set on legacy static Application (obsolete)
+Application.ForceDriver = "dotnet";
+Application.Init ();
 ```

-**Usage:**
+**Valid driver names**: `"dotnet"`, `"windows"`, `"unix"`, `"fake"`
+
+### ForceDriverChanged Event
+
+The static `Application.ForceDriverChanged` event is raised when the `ForceDriver` property changes:
+
+```csharp
+// ForceDriverChanged event (on legacy static Application)
+Application.ForceDriverChanged += (sender, e) =>
+{
+    Debug.WriteLine ($"Driver changed from '{e.OldValue}' to '{e.NewValue}'");
+};
+
+Application.ForceDriver = "fake";
+```
+
+### Getting Available Drivers
+
+You can query which driver types are available using `GetDriverTypes()`:
+
+```csharp
+// Get available driver types and names
+(List<Type?> types, List<string?> names) = Application.GetDriverTypes();
+
+foreach (string? name in names)
+{
+    Debug.WriteLine($"Available driver: {name}");
+}
+// Output:
+// Available driver: dotnet
+// Available driver: windows
+// Available driver: unix
+// Available driver: fake
+```
+
+**Note**: This method uses reflection and is marked with `[RequiresUnreferencedCode]` for AOT compatibility considerations.
+
+## View.Driver Property
+
+Similar to `View.App`, views now have a `Driver` property for accessing driver functionality.

 ```csharp
 public override void OnDrawContent (Rectangle viewport)
 {
-    // Use view's driver instead of Application.Driver
+    // Use view's driver instead of obsolete Application.Driver
    Driver?.Move (0, 0);
    Driver?.AddStr ("Hello");
 }
 ```

+**Note**: See [Drivers Deep Dive](drivers.md) for complete driver architecture details, including the organized interface structure with lifecycle, components, display, rendering, cursor, and input regions.
+
 ## Testing with the New Architecture

 The instance-based architecture dramatically improves testability:
@@ -734,7 +777,8 @@ public void MyView_DisplaysCorrectly ()
 {
    // Create mock application
    Mock<IApplication> mockApp = new ();
-    mockApp.Setup (a => a.TopRunnable).Returns (new Runnable ());
+    Runnable runnable = new ();
+    mockApp.Setup (a => a.TopRunnable).Returns (runnable);
    
    // Create view with mock app
    MyView view = new () { App = mockApp.Object };
@@ -743,7 +787,7 @@ public void MyView_DisplaysCorrectly ()
    view.SetNeedsDraw ();
    Assert.True (view.NeedsDraw);
    
-    // No Application.Shutdown() needed!
+    // No disposal needed for mock!
 }
 ```

@@ -753,21 +797,28 @@ public void MyView_DisplaysCorrectly ()
 [Fact]
 public void MyView_WorksWithRealApplication ()
 {
-    using IApplication app = Application.Create ();
-    app.Init ("fake");
-    
-    MyView view = new ();
-    Window top = new ();
-    top.Add (view);
-    
-    app.Begin (top);
-    
-    // View.App automatically set
-    Assert.NotNull (view.App);
-    Assert.Same (app, view.App);
-    
-    // Test view behavior
-    view.DoSomething ();
+    using (IApplication app = Application.Create ())
+    {
+        app.Init ("fake");
+        
+        MyView view = new ();
+        Window top = new ();
+        top.Add (view);
+        
+        SessionToken? token = app.Begin (top);
+        
+        // View.App automatically set
+        Assert.NotNull (view.App);
+        Assert.Same (app, view.App);
+        
+        // Test view behavior
+        view.DoSomething ();
+        
+        if (token is { })
+        {
+            app.End (token);
+        }
+    }
 }
 ```

@@ -776,7 +827,7 @@ public void MyView_WorksWithRealApplication ()
 ### DO: Use View.App

 ```csharp
-✅ GOOD:
+// ✅ GOOD - Use View.App (modern instance-based pattern):
 public void Refresh ()
 {
    App?.TopRunnableView?.SetNeedsDraw ();
@@ -786,7 +837,7 @@ public void Refresh ()
 ### DON'T: Use Static Application

 ```csharp
-❌ AVOID:
+// ❌ AVOID - Obsolete static Application:
 public void Refresh ()
 {
    Application.TopRunnableView?.SetNeedsDraw (); // Obsolete!
@@ -796,33 +847,38 @@ public void Refresh ()
 ### DO: Pass IApplication as Dependency

 ```csharp
-✅ GOOD:
+// ✅ GOOD - Dependency injection:
 public class Service
 {
-    public Service (IApplication app) { }
+    private readonly IApplication _app;
+    
+    public Service (IApplication app)
+    {
+        _app = app;
+    }
 }
 ```

 ### DON'T: Use Static Application in New Code

 ```csharp
-❌ AVOID (obsolete pattern):
+// ❌ AVOID - Obsolete static Application in new code:
 public void Refresh ()
 {
-    Application.TopRunnableView?.SetNeedsDraw (); // Obsolete static access
+    Application.TopRunnableView?.SetNeedsDraw (); // Obsolete!
 }

-✅ PREFERRED:
+// ✅ PREFERRED - Use View.App property:
 public void Refresh ()
 {
-    App?.TopRunnableView?.SetNeedsDraw (); // Use View.App property
+    App?.TopRunnableView?.SetNeedsDraw ();
 }
 ```

 ### DO: Override GetApp() for Custom Resolution

 ```csharp
-✅ GOOD:
+// ✅ GOOD - Custom application resolution:
 public class SpecialView : View
 {
    private IApplication? _customApp;
@@ -842,41 +898,25 @@ The instance-based architecture enables multiple applications:

 ```csharp
 // Application 1
-using IApplication app1 = Application.Create ();
-app1.Init ("windows");
-Window top1 = new () { Title = "App 1" };
-// ... configure top1
+using (IApplication app1 = Application.Create ())
+{
+    app1.Init ("fake");
+    Window top1 = new () { Title = "App 1" };
+    // ... configure and run top1
+}

 // Application 2 (different driver!)
-using IApplication app2 = Application.Create ();
-app2.Init ("unix");
-Window top2 = new () { Title = "App 2" };
-// ... configure top2
+using (IApplication app2 = Application.Create ())
+{
+    app2.Init ("fake");
+    Window top2 = new () { Title = "App 2" };
+    // ... configure and run top2
+}

 // Views in top1 use app1
 // Views in top2 use app2
 ```

-### Application-Agnostic Views
-
-Create views that work with any application:
-
-```csharp
-public class UniversalView : View
-{
-    public void ShowMessage (string message)
-    {
-        // Works regardless of which application context
-        IApplication? app = GetApp ();
-        if (app != null)
-        {
-            MessageBox msg = new (message);
-            app.Begin (msg);
-        }
-    }
-}
-```
-
 ## See Also

 - [Navigation](navigation.md) - Navigation with the instance-based architecture
--- a/docfx/docs/drivers.md
+++ b/docfx/docs/drivers.md
@@ -24,22 +24,75 @@ The appropriate driver is automatically selected based on the platform when you

 ### Explicit Driver Selection

-You can explicitly specify a driver in three ways:
+You can explicitly specify a driver in several ways:

-```csharp
-// Method 1: Set ForceDriver property before Init
-Application.ForceDriver = "dotnet";
-Application.Init();
+Method 1: Set ForceDriver using Configuration Manager

-// Method 2: Pass driver name to Init
-Application.Init(driverName: "unix");
-
-// Method 3: Pass a custom IDriver instance
-var customDriver = new MyCustomDriver();
-Application.Init(driver: customDriver);
+```json
+{
+  "ForceDriver": "fake"
+}
 ```

-Valid driver names: `"dotnet"`, `"windows"`, `"unix"`, `"fake"`
+Method 2: Pass driver name to Init
+
+```csharp
+Application.Init(driverName: "unix");
+```
+
+Method 3: Set ForceDriver on instance
+
+```csharp
+using (IApplication app = Application.Create())
+{
+    app.ForceDriver = "fake";
+    app.Init();
+}
+```
+
+**Valid driver names**: `"dotnet"`, `"windows"`, `"unix"`, `"fake"`
+
+### ForceDriver as Configuration Property
+
+The `ForceDriver` property is a configuration property marked with `[ConfigurationProperty]`, which means:
+
+- It can be set through the configuration system (e.g., `config.json`)
+- Changes raise the `ForceDriverChanged` event
+- It persists across application instances when using the static `Application` class
+
+```csharp
+// Subscribe to driver changes
+Application.ForceDriverChanged += (sender, e) =>
+{
+    Console.WriteLine($"Driver changed: {e.OldValue} → {e.NewValue}");
+};
+
+// Change driver
+Application.ForceDriver = "fake";
+```
+
+### Discovering Available Drivers
+
+Use `GetDriverTypes()` to discover which drivers are available at runtime:
+
+```csharp
+(List<Type?> driverTypes, List<string?> driverNames) = Application.GetDriverTypes();
+
+Console.WriteLine("Available drivers:");
+foreach (string? name in driverNames)
+{
+    Console.WriteLine($"  - {name}");
+}
+
+// Output:
+// Available drivers:
+//   - dotnet
+//   - windows
+//   - unix
+//   - fake
+```
+
+**Note**: `GetDriverTypes()` uses reflection to discover driver implementations and is marked with `[RequiresUnreferencedCode("AOT")]` and `[Obsolete]` as part of the legacy static API.

 ## Architecture

@@ -151,15 +204,49 @@ When `IApplication.Shutdown()` is called:

 ### IDriver

-The main driver interface that the framework uses internally. Provides:
+The main driver interface that the framework uses internally. `IDriver` is organized into logical regions:

- **Screen Management**: `Screen`, `Cols`, `Rows`, `Contents`
- **Drawing Operations**: `AddRune()`, `AddStr()`, `Move()`, `FillRect()`
- **Cursor Management**: `SetCursorVisibility()`, `UpdateCursor()`
- **Attribute Management**: `CurrentAttribute`, `SetAttribute()`, `MakeColor()`
- **Clipping**: `Clip` property
- **Events**: `KeyDown`, `KeyUp`, `MouseEvent`, `SizeChanged`
- **Platform Features**: `SupportsTrueColor`, `Force16Colors`, `Clipboard`
+#### Driver Lifecycle
+- `Init()`, `Refresh()`, `End()` - Core lifecycle methods
+- `GetName()`, `GetVersionInfo()` - Driver identification
+- `Suspend()` - Platform-specific suspend support
+
+#### Driver Components
+- `InputProcessor` - Processes input into Terminal.Gui events
+- `OutputBuffer` - Manages screen buffer state
+- `SizeMonitor` - Detects terminal size changes
+- `Clipboard` - OS clipboard integration
+
+#### Screen and Display
+- `Screen`, `Cols`, `Rows`, `Left`, `Top` - Screen dimensions
+- `SetScreenSize()`, `SizeChanged` - Size management
+
+#### Color Support
+- `SupportsTrueColor` - 24-bit color capability
+- `Force16Colors` - Force 16-color mode
+
+#### Content Buffer
+- `Contents` - Screen buffer array
+- `Clip` - Clipping region
+- `ClearContents()`, `ClearedContents` - Buffer management
+
+#### Drawing and Rendering
+- `Col`, `Row`, `CurrentAttribute` - Drawing state
+- `Move()`, `AddRune()`, `AddStr()`, `FillRect()` - Drawing operations
+- `SetAttribute()`, `GetAttribute()` - Attribute management
+- `WriteRaw()`, `GetSixels()` - Raw output and graphics
+- `Refresh()`, `ToString()`, `ToAnsi()` - Output rendering
+
+#### Cursor
+- `UpdateCursor()` - Position cursor
+- `GetCursorVisibility()`, `SetCursorVisibility()` - Visibility management
+
+#### Input Events
+- `KeyDown`, `KeyUp`, `MouseEvent` - Input events
+- `EnqueueKeyEvent()` - Test support
+
+#### ANSI Escape Sequences
+- `QueueAnsiRequest()` - ANSI request handling

 **Note:** The driver is internal to Terminal.Gui. View classes should not access `Driver` directly. Instead:
 - Use @Terminal.Gui.App.Application.Screen to get screen dimensions
@@ -167,6 +254,20 @@ The main driver interface that the framework uses internally. Provides:
 - Use @Terminal.Gui.ViewBase.View.AddRune and @Terminal.Gui.ViewBase.View.AddStr for drawing
 - ViewBase infrastructure classes (in `Terminal.Gui/ViewBase/`) can access Driver when needed for framework implementation

+### Driver Creation and Selection
+
+The driver selection logic in `ApplicationImpl.Driver.cs` prioritizes component factory type over the driver name parameter:
+
+1. **Component Factory Type**: If an `IComponentFactory` is already set, it determines the driver
+2. **Driver Name Parameter**: The `driverName` parameter to `Init()` is checked next
+3. **ForceDriver Property**: The `ForceDriver` configuration property is evaluated
+4. **Platform Detection**: If none of the above specify a driver, the platform is detected:
+   - Windows (Win32NT, Win32S, Win32Windows) → `WindowsDriver`
+   - Unix/Linux/macOS → `UnixDriver`
+   - Other platforms → `DotNetDriver` (fallback)
+
+This prioritization ensures flexibility while maintaining deterministic behavior.
+
 ## Platform-Specific Details

 ### DotNetDriver (NetComponentFactory)