Application.Initialization.cs 9.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236
  1. #nullable enable
  2. using System.Diagnostics;
  3. using System.Diagnostics.CodeAnalysis;
  4. using System.Reflection;
  5. namespace Terminal.Gui;
  6. public static partial class Application // Initialization (Init/Shutdown)
  7. {
  8. /// <summary>Initializes a new instance of <see cref="Terminal.Gui"/> Application.</summary>
  9. /// <para>Call this method once per instance (or after <see cref="Shutdown"/> has been called).</para>
  10. /// <para>
  11. /// This function loads the right <see cref="ConsoleDriver"/> for the platform, Creates a <see cref="Toplevel"/>. and
  12. /// assigns it to <see cref="Top"/>
  13. /// </para>
  14. /// <para>
  15. /// <see cref="Shutdown"/> must be called when the application is closing (typically after
  16. /// <see cref="Run{T}"/> has returned) to ensure resources are cleaned up and
  17. /// terminal settings
  18. /// restored.
  19. /// </para>
  20. /// <para>
  21. /// The <see cref="Run{T}"/> function combines
  22. /// <see cref="Init(Terminal.Gui.ConsoleDriver,string)"/> and <see cref="Run(Toplevel, Func{Exception, bool})"/>
  23. /// into a single
  24. /// call. An application cam use <see cref="Run{T}"/> without explicitly calling
  25. /// <see cref="Init(Terminal.Gui.ConsoleDriver,string)"/>.
  26. /// </para>
  27. /// <param name="driver">
  28. /// The <see cref="ConsoleDriver"/> to use. If neither <paramref name="driver"/> or
  29. /// <paramref name="driverName"/> are specified the default driver for the platform will be used.
  30. /// </param>
  31. /// <param name="driverName">
  32. /// The short name (e.g. "net", "windows", "ansi", "fake", or "curses") of the
  33. /// <see cref="ConsoleDriver"/> to use. If neither <paramref name="driver"/> or <paramref name="driverName"/> are
  34. /// specified the default driver for the platform will be used.
  35. /// </param>
  36. [RequiresUnreferencedCode ("AOT")]
  37. [RequiresDynamicCode ("AOT")]
  38. public static void Init (ConsoleDriver? driver = null, string? driverName = null) { InternalInit (driver, driverName); }
  39. internal static bool IsInitialized { get; set; }
  40. internal static int MainThreadId { get; set; } = -1;
  41. // INTERNAL function for initializing an app with a Toplevel factory object, driver, and mainloop.
  42. //
  43. // Called from:
  44. //
  45. // Init() - When the user wants to use the default Toplevel. calledViaRunT will be false, causing all state to be reset.
  46. // Run<T>() - When the user wants to use a custom Toplevel. calledViaRunT will be true, enabling Run<T>() to be called without calling Init first.
  47. // Unit Tests - To initialize the app with a custom Toplevel, using the FakeDriver. calledViaRunT will be false, causing all state to be reset.
  48. //
  49. // calledViaRunT: If false (default) all state will be reset. If true the state will not be reset.
  50. [RequiresUnreferencedCode ("AOT")]
  51. [RequiresDynamicCode ("AOT")]
  52. internal static void InternalInit (
  53. ConsoleDriver? driver = null,
  54. string? driverName = null,
  55. bool calledViaRunT = false
  56. )
  57. {
  58. if (IsInitialized && driver is null)
  59. {
  60. return;
  61. }
  62. if (IsInitialized)
  63. {
  64. throw new InvalidOperationException ("Init has already been called and must be bracketed by Shutdown.");
  65. }
  66. if (!calledViaRunT)
  67. {
  68. // Reset all class variables (Application is a singleton).
  69. ResetState (ignoreDisposed: true);
  70. }
  71. Navigation = new ();
  72. // For UnitTests
  73. if (driver is { })
  74. {
  75. Driver = driver;
  76. if (driver is FakeDriver)
  77. {
  78. // We're running unit tests. Disable loading config files other than default
  79. if (Locations == ConfigLocations.All)
  80. {
  81. Locations = ConfigLocations.DefaultOnly;
  82. Reset ();
  83. }
  84. }
  85. }
  86. // Start the process of configuration management.
  87. // Note that we end up calling LoadConfigurationFromAllSources
  88. // multiple times. We need to do this because some settings are only
  89. // valid after a Driver is loaded. In this case we need just
  90. // `Settings` so we can determine which driver to use.
  91. // Don't reset, so we can inherit the theme from the previous run.
  92. string previousTheme = Themes?.Theme ?? string.Empty;
  93. Load ();
  94. if (Themes is { } && !string.IsNullOrEmpty (previousTheme) && previousTheme != "Default")
  95. {
  96. ThemeManager.SelectedTheme = previousTheme;
  97. }
  98. Apply ();
  99. AddApplicationKeyBindings ();
  100. // Ignore Configuration for ForceDriver if driverName is specified
  101. if (!string.IsNullOrEmpty (driverName))
  102. {
  103. ForceDriver = driverName;
  104. }
  105. if (Driver is null)
  106. {
  107. PlatformID p = Environment.OSVersion.Platform;
  108. if (string.IsNullOrEmpty (ForceDriver))
  109. {
  110. if (p == PlatformID.Win32NT || p == PlatformID.Win32S || p == PlatformID.Win32Windows)
  111. {
  112. Driver = new WindowsDriver ();
  113. }
  114. else
  115. {
  116. Driver = new CursesDriver ();
  117. }
  118. }
  119. else
  120. {
  121. List<Type?> drivers = GetDriverTypes ();
  122. Type? driverType = drivers.FirstOrDefault (t => t!.Name.Equals (ForceDriver, StringComparison.InvariantCultureIgnoreCase));
  123. if (driverType is { })
  124. {
  125. Driver = (ConsoleDriver)Activator.CreateInstance (driverType)!;
  126. }
  127. else
  128. {
  129. throw new ArgumentException (
  130. $"Invalid driver name: {ForceDriver}. Valid names are {string.Join (", ", drivers.Select (t => t!.Name))}"
  131. );
  132. }
  133. }
  134. }
  135. try
  136. {
  137. MainLoop = Driver!.Init ();
  138. }
  139. catch (InvalidOperationException ex)
  140. {
  141. // This is a case where the driver is unable to initialize the console.
  142. // This can happen if the console is already in use by another process or
  143. // if running in unit tests.
  144. // In this case, we want to throw a more specific exception.
  145. throw new InvalidOperationException (
  146. "Unable to initialize the console. This can happen if the console is already in use by another process or in unit tests.",
  147. ex
  148. );
  149. }
  150. Driver.SizeChanged += Driver_SizeChanged;
  151. Driver.KeyDown += Driver_KeyDown;
  152. Driver.KeyUp += Driver_KeyUp;
  153. Driver.MouseEvent += Driver_MouseEvent;
  154. SynchronizationContext.SetSynchronizationContext (new MainLoopSyncContext ());
  155. SupportedCultures = GetSupportedCultures ();
  156. MainThreadId = Thread.CurrentThread.ManagedThreadId;
  157. bool init = IsInitialized = true;
  158. InitializedChanged?.Invoke (null, new (init));
  159. }
  160. private static void Driver_SizeChanged (object? sender, SizeChangedEventArgs e) { OnSizeChanging (e); }
  161. private static void Driver_KeyDown (object? sender, Key e) { OnKeyDown (e); }
  162. private static void Driver_KeyUp (object? sender, Key e) { OnKeyUp (e); }
  163. private static void Driver_MouseEvent (object? sender, MouseEvent e) { OnMouseEvent (e); }
  164. /// <summary>Gets of list of <see cref="ConsoleDriver"/> types that are available.</summary>
  165. /// <returns></returns>
  166. [RequiresUnreferencedCode ("AOT")]
  167. public static List<Type?> GetDriverTypes ()
  168. {
  169. // use reflection to get the list of drivers
  170. List<Type?> driverTypes = new ();
  171. foreach (Assembly asm in AppDomain.CurrentDomain.GetAssemblies ())
  172. {
  173. foreach (Type? type in asm.GetTypes ())
  174. {
  175. if (type.IsSubclassOf (typeof (ConsoleDriver)) && !type.IsAbstract)
  176. {
  177. driverTypes.Add (type);
  178. }
  179. }
  180. }
  181. return driverTypes;
  182. }
  183. /// <summary>Shutdown an application initialized with <see cref="Init"/>.</summary>
  184. /// <remarks>
  185. /// Shutdown must be called for every call to <see cref="Init"/> or
  186. /// <see cref="Application.Run(Toplevel, Func{Exception, bool})"/> to ensure all resources are cleaned
  187. /// up (Disposed)
  188. /// and terminal settings are restored.
  189. /// </remarks>
  190. public static void Shutdown ()
  191. {
  192. // TODO: Throw an exception if Init hasn't been called.
  193. bool wasInitialized = IsInitialized;
  194. ResetState ();
  195. PrintJsonErrors ();
  196. if (wasInitialized)
  197. {
  198. bool init = IsInitialized;
  199. InitializedChanged?.Invoke (null, new (in init));
  200. }
  201. }
  202. /// <summary>
  203. /// This event is raised after the <see cref="Init"/> and <see cref="Shutdown"/> methods have been called.
  204. /// </summary>
  205. /// <remarks>
  206. /// Intended to support unit tests that need to know when the application has been initialized.
  207. /// </remarks>
  208. public static event EventHandler<EventArgs<bool>>? InitializedChanged;
  209. }