diff --git a/Terminal.Gui/App/IApplication.cs b/Terminal.Gui/App/IApplication.cs index 16d4dc063c..93a2f6171f 100644 --- a/Terminal.Gui/App/IApplication.cs +++ b/Terminal.Gui/App/IApplication.cs @@ -135,12 +135,31 @@ public interface IApplication : IDisposable ConcurrentStack? SessionStack { get; } /// - /// Raised when has been called and has created a new . + /// Raised by after the new has been pushed onto + /// and has been set, but before + /// and fire. This event + /// reports a token-lifecycle moment, not a state transition on the . /// /// - /// If is , callers to - /// must also subscribe to and manually dispose of the token - /// when the application is done. + /// + /// To observe the runnable transitioning to the running state, subscribe to + /// . is not a substitute: at the moment + /// it fires, the cached value is still because + /// has not yet been called. Subscribers that need post-state-change + /// semantics must use . + /// + /// + /// and are intentionally NOT a symmetric + /// before/after pair. fires early — after the token has been pushed onto + /// but before the runnable's running/modal state has been published. + /// fires late — after all state has unwound. This asymmetry is deliberate: + /// the events mark token-lifecycle boundaries, not runnable-state transitions. + /// + /// + /// If is , callers to + /// must also subscribe to and call + /// themselves to complete the session. + /// /// public event EventHandler? SessionBegun; @@ -422,7 +441,8 @@ public interface IApplication : IDisposable /// /// /// This method removes the from the , - /// raises the lifecycle events, and disposes the . + /// raises the lifecycle events, and clears on + /// . /// /// /// Raises , , @@ -432,14 +452,37 @@ public interface IApplication : IDisposable void End (SessionToken sessionToken); /// - /// Raised when was called and the session is stopping. The event args contain a - /// reference to the - /// that was active during the session. This can be used to ensure the Runnable is disposed of properly. + /// Raised by after the runnable's state has fully unwound — including + /// firing with false — and after + /// has finished its state-unwinding work. The reference is + /// at this point. This event reports a token-lifecycle moment, not a state transition + /// on the . /// /// - /// If is , callers to - /// must also subscribe to and manually dispose of the token - /// when the application is done. + /// + /// At the moment fires, all state has already unwound: + /// is and + /// has already fired with false. To observe the runnable + /// transitioning out of the running state, subscribe to instead. + /// + /// + /// The token's property is at this point — it + /// is cleared immediately before the event is raised. Subscribers that need the session result must read + /// from the token; they must not attempt to access + /// . + /// + /// + /// and are intentionally NOT a symmetric + /// before/after pair. fires early — after the token has been pushed onto + /// but before the runnable's running/modal state has been published. + /// fires late — after all state has unwound. This asymmetry is deliberate: + /// the events mark token-lifecycle boundaries, not runnable-state transitions. + /// + /// + /// If is , callers to + /// must also subscribe to and call + /// themselves to complete the session. + /// /// public event EventHandler? SessionEnded;