diff --git a/Terminal.Gui/Drivers/ConsoleDriver.cs b/Terminal.Gui/Drivers/ConsoleDriver.cs index 534adefb7..503cc7286 100644 --- a/Terminal.Gui/Drivers/ConsoleDriver.cs +++ b/Terminal.Gui/Drivers/ConsoleDriver.cs @@ -57,7 +57,24 @@ public abstract class ConsoleDriver : IConsoleDriver internal bool []? _dirtyLines; // QUESTION: When non-full screen apps are supported, will this represent the app size, or will that be in Application? - /// Gets the location and size of the terminal screen. + /// + /// Gets the location and size of the terminal screen. This is the single source of truth for + /// the available drawing area. + /// + /// + /// + /// The screen rectangle always has origin (0,0) and size determined by and . + /// When the terminal is resized, and are updated, and the + /// event is fired. + /// + /// + /// In production drivers (WindowsDriver, UnixDriver, DotNetDriver), this reflects the actual terminal size. + /// In , this can be controlled programmatically via SetBufferSize for testing. + /// + /// + /// + /// + /// public Rectangle Screen => new (0, 0, Cols, Rows); private Region? _clip; @@ -93,7 +110,25 @@ public abstract class ConsoleDriver : IConsoleDriver /// public int Col { get; private set; } - /// The number of columns visible in the terminal. + /// + /// Gets or sets the number of columns visible in the terminal. This property, along with , + /// defines the dimensions of the rectangle. + /// + /// + /// + /// In production drivers, this value reflects the actual terminal width and is updated when + /// the terminal is resized. In , this can be set programmatically + /// via SetBufferSize or SetWindowSize for testing. + /// + /// + /// Warning: Setting this property directly clears the contents buffer. + /// Prefer using resize methods (SetBufferSize in FakeDriver) that properly handle + /// the resize sequence including firing events. + /// + /// + /// + /// + /// public virtual int Cols { get => _cols; @@ -157,7 +192,25 @@ public abstract class ConsoleDriver : IConsoleDriver /// public int Row { get; private set; } - /// The number of rows visible in the terminal. + /// + /// Gets or sets the number of rows visible in the terminal. This property, along with , + /// defines the dimensions of the rectangle. + /// + /// + /// + /// In production drivers, this value reflects the actual terminal height and is updated when + /// the terminal is resized. In , this can be set programmatically + /// via SetBufferSize or SetWindowSize for testing. + /// + /// + /// Warning: Setting this property directly clears the contents buffer. + /// Prefer using resize methods (SetBufferSize in FakeDriver) that properly handle + /// the resize sequence including firing events. + /// + /// + /// + /// + /// public virtual int Rows { get => _rows; @@ -508,8 +561,27 @@ public abstract class ConsoleDriver : IConsoleDriver } } - /// Called when the terminal size changes. Fires the event. - /// + /// + /// Called when the terminal screen size changes. This method fires the event, + /// notifying subscribers that , , and have changed. + /// + /// + /// + /// This method is typically called internally by the driver when it detects a terminal resize. + /// For , it is called by SetBufferSize and SetWindowSize methods. + /// + /// + /// For driver implementations: Call this method after updating and + /// to notify the application that the screen dimensions have changed. + /// + /// + /// For application code: Subscribe to the event to respond + /// to screen size changes rather than calling this method directly. + /// + /// + /// Event arguments containing the new screen size. + /// + /// public void OnSizeChanged (SizeChangedEventArgs args) { SizeChanged?.Invoke (this, args); } /// Updates the screen to reflect all the changes that have been done to the display buffer @@ -531,7 +603,32 @@ public abstract class ConsoleDriver : IConsoleDriver /// upon success public abstract bool SetCursorVisibility (CursorVisibility visibility); - /// The event fired when the terminal is resized. + /// + /// Event fired when the terminal screen is resized. Provides the new screen dimensions via + /// . + /// + /// + /// + /// This event is raised by when the driver detects or is notified + /// of a terminal size change. At the time this event fires, , , + /// and have already been updated to reflect the new dimensions. + /// + /// + /// In production drivers: This event fires when the OS notifies the driver of a + /// terminal window resize (e.g., SIGWINCH on Unix, WINDOW_BUFFER_SIZE_EVENT on Windows). + /// + /// + /// In FakeDriver: This event fires when test code calls SetBufferSize or + /// SetWindowSize, allowing tests to simulate and verify resize behavior. + /// + /// + /// Usage in Application: subscribes to this event + /// during initialization and propagates resize notifications to top-level views, triggering layout + /// and redraw operations. + /// + /// + /// + /// public event EventHandler? SizeChanged; #endregion Cursor Handling diff --git a/Terminal.Gui/Drivers/FakeDriver/FakeDriver.cs b/Terminal.Gui/Drivers/FakeDriver/FakeDriver.cs index 916760c97..34f463a8f 100644 --- a/Terminal.Gui/Drivers/FakeDriver/FakeDriver.cs +++ b/Terminal.Gui/Drivers/FakeDriver/FakeDriver.cs @@ -378,6 +378,46 @@ public class FakeDriver : ConsoleDriver /// internal override IAnsiResponseParser GetParser () => _parser; + /// + /// Sets the size of the fake console screen/buffer for testing purposes. This method updates + /// the driver's dimensions ( and ), + /// clears the contents, and fires the event. + /// + /// + /// + /// This method is intended for use in unit tests to simulate terminal resize events. + /// For FakeDriver, the buffer size and window size are always the same (there is no scrollback). + /// + /// + /// When called, this method: + /// + /// Updates the buffer size + /// Sets and to the new dimensions + /// Updates the window size to match + /// Clears the screen contents + /// Fires the event + /// + /// + /// + /// Thread Safety: This method is not thread-safe. Tests using this method + /// should ensure they are not accessing the driver concurrently. + /// + /// + /// Relationship to Screen property: After calling this method, + /// will return a rectangle with origin (0,0) and size (width, height). + /// + /// + /// The new width in columns. + /// The new height in rows. + /// + /// + /// // Simulate a terminal resize to 120x30 + /// var driver = new FakeDriver(); + /// driver.SetBufferSize(120, 30); + /// Assert.Equal(120, driver.Cols); + /// Assert.Equal(30, driver.Rows); + /// + /// public void SetBufferSize (int width, int height) { FakeConsole.SetBufferSize (width, height); @@ -387,6 +427,24 @@ public class FakeDriver : ConsoleDriver ProcessResize (); } + /// + /// Sets the window size of the fake console. For FakeDriver, this is functionally equivalent to + /// as the fake console does not support scrollback (window size == buffer size). + /// + /// + /// + /// This method exists for API compatibility with real console drivers, but in FakeDriver, + /// the window size and buffer size are always kept in sync. Calling this method will update + /// both the window and buffer to the specified size. + /// + /// + /// Prefer using for clarity in test code, as it more accurately + /// describes what's happening (setting the entire screen size for the fake driver). + /// + /// + /// The new width in columns. + /// The new height in rows. + /// public void SetWindowSize (int width, int height) { FakeConsole.SetWindowSize (width, height); diff --git a/Tests/UnitTests/AutoInitShutdownAttribute.cs b/Tests/UnitTests/AutoInitShutdownAttribute.cs index b5e11ccbc..361fadde1 100644 --- a/Tests/UnitTests/AutoInitShutdownAttribute.cs +++ b/Tests/UnitTests/AutoInitShutdownAttribute.cs @@ -155,9 +155,55 @@ public class AutoInitShutdownAttribute : BeforeAfterTestAttribute private bool AutoInit { get; } /// - /// 'Resizes' the application and forces layout. Only works if your test uses + /// Simulates a terminal resize in tests that use . + /// This method updates the driver's output buffer size, triggers size change events, + /// and forces a layout/draw cycle. /// - /// + /// + /// + /// This method is designed for use in unit tests to simulate terminal resize events. + /// It works with both the fluent testing infrastructure () and + /// the library's built-in . + /// + /// + /// The method performs the following operations: + /// + /// Updates the output buffer size via + /// Raises the size changing event through the appropriate size monitor + /// Forces a layout and draw cycle via + /// + /// + /// + /// Thread Safety: This method is not thread-safe. Tests using FakeResize + /// should not run in parallel if they share driver state. + /// + /// + /// Requirements: Your test must use + /// with autoInit=true for this method to work correctly. + /// + /// + /// The new terminal size (width, height). + /// + /// Thrown if is null or not initialized. + /// + /// + /// + /// [Fact] + /// [AutoInitShutdown] + /// public void TestResize() + /// { + /// // Initial size is 80x25 + /// Assert.Equal(80, Application.Driver.Cols); + /// + /// // Simulate resize to 120x30 + /// AutoInitShutdownAttribute.FakeResize(new Size(120, 30)); + /// + /// // Verify new size + /// Assert.Equal(120, Application.Driver.Cols); + /// Assert.Equal(30, Application.Driver.Rows); + /// } + /// + /// public static void FakeResize (Size size) { var d = (IConsoleDriverFacade)Application.Driver!;