View.cs 21 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552
  1. #nullable enable
  2. using System.ComponentModel;
  3. using System.Diagnostics;
  4. namespace Terminal.Gui;
  5. #region API Docs
  6. /// <summary>
  7. /// View is the base class all visible elements. View can render itself and
  8. /// contains zero or more nested views, called SubViews. View provides basic functionality for layout, positioning, and
  9. /// drawing. In addition, View provides keyboard and mouse event handling.
  10. /// </summary>
  11. /// <remarks>
  12. /// <list type="table">
  13. /// <listheader>
  14. /// <term>Term</term><description>Definition</description>
  15. /// </listheader>
  16. /// <item>
  17. /// <term>SubView</term>
  18. /// <description>
  19. /// A View that is contained in another view and will be rendered as part of the containing view's
  20. /// ContentArea. SubViews are added to another view via the <see cref="View.Add(View)"/>` method. A View
  21. /// may only be a SubView of a single View.
  22. /// </description>
  23. /// </item>
  24. /// <item>
  25. /// <term>SuperView</term><description>The View that is a container for SubViews.</description>
  26. /// </item>
  27. /// </list>
  28. /// <para>
  29. /// Focus is a concept that is used to describe which View is currently receiving user input. Only Views that are
  30. /// <see cref="Enabled"/>, <see cref="Visible"/>, and <see cref="CanFocus"/> will receive focus.
  31. /// </para>
  32. /// <para>
  33. /// Views that are focusable should override <see cref="PositionCursor"/> to make sure that the cursor is
  34. /// placed in a location that makes sense. Some terminals do not have a way of hiding the cursor, so it can be
  35. /// distracting to have the cursor left at the last focused view. So views should make sure that they place the
  36. /// cursor in a visually sensible place. The default implementation of <see cref="PositionCursor"/> will place the
  37. /// cursor at either the hotkey (if defined) or <c>0,0</c>.
  38. /// </para>
  39. /// <para>
  40. /// The View defines the base functionality for user interface elements in Terminal.Gui. Views can contain one or
  41. /// more subviews, can respond to user input and render themselves on the screen.
  42. /// </para>
  43. /// <para>
  44. /// To create a View using Absolute layout, call a constructor that takes a Rect parameter to specify the
  45. /// absolute position and size or simply set <see cref="View.Frame "/>). To create a View using Computed layout use
  46. /// a constructor that does not take a Rect parameter and set the X, Y, Width and Height properties on the view to
  47. /// non-absolute values. Both approaches use coordinates that are relative to the <see cref="Viewport"/> of the
  48. /// <see cref="SuperView"/> the View is added to.
  49. /// </para>
  50. /// <para>
  51. /// Computed layout is more flexible and supports dynamic console apps where controls adjust layout as the
  52. /// terminal resizes or other Views change size or position. The <see cref="X"/>, <see cref="Y"/>,
  53. /// <see cref="Width"/>, and <see cref="Height"/> properties are <see cref="Dim"/> and <see cref="Pos"/> objects
  54. /// that dynamically update the position of a view. The X and Y properties are of type <see cref="Pos"/> and you
  55. /// can use either absolute positions, percentages, or anchor points. The Width and Height properties are of type
  56. /// <see cref="Dim"/> and can use absolute position, percentages, and anchors. These are useful as they will take
  57. /// care of repositioning views when view's adornments are resized or if the terminal size changes.
  58. /// </para>
  59. /// <para>
  60. /// Absolute layout requires specifying coordinates and sizes of Views explicitly, and the View will typically
  61. /// stay in a fixed position and size. To change the position and size use the <see cref="Frame"/> property.
  62. /// </para>
  63. /// <para>
  64. /// Subviews (child views) can be added to a View by calling the <see cref="Add(View)"/> method. The container of
  65. /// a View can be accessed with the <see cref="SuperView"/> property.
  66. /// </para>
  67. /// <para>
  68. /// To flag a region of the View's <see cref="Viewport"/> to be redrawn call
  69. /// <see cref="SetNeedsDisplay(Rectangle)"/>
  70. /// .
  71. /// To flag the entire view for redraw call <see cref="SetNeedsDisplay()"/>.
  72. /// </para>
  73. /// <para>
  74. /// The <see cref="LayoutSubviews"/> method is invoked when the size or layout of a view has changed.
  75. /// </para>
  76. /// <para>
  77. /// Views have a <see cref="ColorScheme"/> property that defines the default colors that subviews should use for
  78. /// rendering. This ensures that the views fit in the context where they are being used, and allows for themes to
  79. /// be plugged in. For example, the default colors for windows and Toplevels uses a blue background, while it uses
  80. /// a white background for dialog boxes and a red background for errors.
  81. /// </para>
  82. /// <para>
  83. /// Subclasses should not rely on <see cref="ColorScheme"/> being set at construction time. If a
  84. /// <see cref="ColorScheme"/> is not set on a view, the view will inherit the value from its
  85. /// <see cref="SuperView"/> and the value might only be valid once a view has been added to a SuperView.
  86. /// </para>
  87. /// <para>By using <see cref="ColorScheme"/> applications will work both in color as well as black and white displays.</para>
  88. /// <para>
  89. /// Views can also opt-in to more sophisticated initialization by implementing overrides to
  90. /// <see cref="ISupportInitialize.BeginInit"/> and <see cref="ISupportInitialize.EndInit"/> which will be called
  91. /// when the view is added to a <see cref="SuperView"/>.
  92. /// </para>
  93. /// <para>
  94. /// If first-run-only initialization is preferred, overrides to <see cref="ISupportInitializeNotification"/> can
  95. /// be implemented, in which case the <see cref="ISupportInitialize"/> methods will only be called if
  96. /// <see cref="ISupportInitializeNotification.IsInitialized"/> is <see langword="false"/>. This allows proper
  97. /// <see cref="View"/> inheritance hierarchies to override base class layout code optimally by doing so only on
  98. /// first run, instead of on every run.
  99. /// </para>
  100. /// <para>See <see href="../docs/keyboard.md"> for an overview of View keyboard handling.</see></para>
  101. /// </remarks>
  102. #endregion API Docs
  103. public partial class View : Responder, ISupportInitializeNotification
  104. {
  105. #region Constructors and Initialization
  106. /// <summary>Gets or sets arbitrary data for the view.</summary>
  107. /// <remarks>This property is not used internally.</remarks>
  108. public object? Data { get; set; }
  109. /// <summary>Gets or sets an identifier for the view;</summary>
  110. /// <value>The identifier.</value>
  111. /// <remarks>The id should be unique across all Views that share a SuperView.</remarks>
  112. public string Id { get; set; } = "";
  113. /// <summary>
  114. /// Points to the current driver in use by the view, it is a convenience property for simplifying the development
  115. /// of new views.
  116. /// </summary>
  117. public static ConsoleDriver? Driver => Application.Driver;
  118. /// <summary>Initializes a new instance of <see cref="View"/>.</summary>
  119. /// <remarks>
  120. /// <para>
  121. /// Use <see cref="X"/>, <see cref="Y"/>, <see cref="Width"/>, and <see cref="Height"/> properties to dynamically
  122. /// control the size and location of the view.
  123. /// </para>
  124. /// </remarks>
  125. public View ()
  126. {
  127. SetupAdornments ();
  128. SetupCommands ();
  129. SetupKeyboard ();
  130. //SetupMouse ();
  131. SetupText ();
  132. }
  133. /// <summary>
  134. /// Raised once when the <see cref="View"/> is being initialized for the first time. Allows
  135. /// configurations and assignments to be performed before the <see cref="View"/> being shown.
  136. /// View implements <see cref="ISupportInitializeNotification"/> to allow for more sophisticated initialization.
  137. /// </summary>
  138. public event EventHandler? Initialized;
  139. /// <summary>
  140. /// Get or sets if the <see cref="View"/> has been initialized (via <see cref="ISupportInitialize.BeginInit"/>
  141. /// and <see cref="ISupportInitialize.EndInit"/>).
  142. /// </summary>
  143. /// <para>
  144. /// If first-run-only initialization is preferred, overrides to
  145. /// <see cref="ISupportInitializeNotification.IsInitialized"/> can be implemented, in which case the
  146. /// <see cref="ISupportInitialize"/> methods will only be called if
  147. /// <see cref="ISupportInitializeNotification.IsInitialized"/> is <see langword="false"/>. This allows proper
  148. /// <see cref="View"/> inheritance hierarchies to override base class layout code optimally by doing so only on first
  149. /// run, instead of on every run.
  150. /// </para>
  151. public virtual bool IsInitialized { get; set; }
  152. /// <summary>Signals the View that initialization is starting. See <see cref="ISupportInitialize"/>.</summary>
  153. /// <remarks>
  154. /// <para>
  155. /// Views can opt-in to more sophisticated initialization by implementing overrides to
  156. /// <see cref="ISupportInitialize.BeginInit"/> and <see cref="ISupportInitialize.EndInit"/> which will be called
  157. /// when the <see cref="SuperView"/> is initialized.
  158. /// </para>
  159. /// <para>
  160. /// If first-run-only initialization is preferred, overrides to <see cref="ISupportInitializeNotification"/> can
  161. /// be implemented too, in which case the <see cref="ISupportInitialize"/> methods will only be called if
  162. /// <see cref="ISupportInitializeNotification.IsInitialized"/> is <see langword="false"/>. This allows proper
  163. /// <see cref="View"/> inheritance hierarchies to override base class layout code optimally by doing so only on
  164. /// first run, instead of on every run.
  165. /// </para>
  166. /// </remarks>
  167. public virtual void BeginInit ()
  168. {
  169. if (IsInitialized)
  170. {
  171. throw new InvalidOperationException ("The view is already initialized.");
  172. }
  173. #if AUTO_CANFOCUS
  174. _oldCanFocus = CanFocus;
  175. _oldTabIndex = _tabIndex;
  176. #endif
  177. BeginInitAdornments ();
  178. if (_subviews?.Count > 0)
  179. {
  180. foreach (View view in _subviews)
  181. {
  182. if (!view.IsInitialized)
  183. {
  184. view.BeginInit ();
  185. }
  186. }
  187. }
  188. }
  189. // TODO: Implement logic that allows EndInit to throw if BeginInit has not been called
  190. // TODO: See EndInit_Called_Without_BeginInit_Throws test.
  191. /// <summary>Signals the View that initialization is ending. See <see cref="ISupportInitialize"/>.</summary>
  192. /// <remarks>
  193. /// <para>Initializes all Subviews and Invokes the <see cref="Initialized"/> event.</para>
  194. /// </remarks>
  195. public virtual void EndInit ()
  196. {
  197. if (IsInitialized)
  198. {
  199. throw new InvalidOperationException ("The view is already initialized.");
  200. }
  201. IsInitialized = true;
  202. EndInitAdornments ();
  203. // TODO: Move these into ViewText.cs as EndInit_Text() to consolidate.
  204. // TODO: Verify UpdateTextDirection really needs to be called here.
  205. // These calls were moved from BeginInit as they access Viewport which is indeterminate until EndInit is called.
  206. UpdateTextDirection (TextDirection);
  207. UpdateTextFormatterText ();
  208. SetLayoutNeeded ();
  209. if (_subviews is { })
  210. {
  211. foreach (View view in _subviews)
  212. {
  213. if (!view.IsInitialized)
  214. {
  215. view.EndInit ();
  216. }
  217. }
  218. }
  219. // TOOD: Figure out how to move this out of here and just depend on IsLayoutNeeded in Mainloop
  220. LayoutSubviews();
  221. Initialized?.Invoke (this, EventArgs.Empty);
  222. }
  223. #endregion Constructors and Initialization
  224. #region Visibility
  225. private bool _enabled = true;
  226. // This is a cache of the Enabled property so that we can restore it when the superview is re-enabled.
  227. private bool _oldEnabled;
  228. /// <summary>Gets or sets a value indicating whether this <see cref="Responder"/> can respond to user interaction.</summary>
  229. public bool Enabled
  230. {
  231. get => _enabled;
  232. set
  233. {
  234. if (_enabled == value)
  235. {
  236. return;
  237. }
  238. _enabled = value;
  239. if (!_enabled && HasFocus)
  240. {
  241. HasFocus = false;
  242. }
  243. if (_enabled
  244. && CanFocus
  245. && Visible
  246. && !HasFocus
  247. && SuperView is null or { HasFocus: true, Visible: true, Enabled: true, Focused: null })
  248. {
  249. SetFocus ();
  250. }
  251. OnEnabledChanged ();
  252. SetNeedsDisplay ();
  253. if (_subviews is null)
  254. {
  255. return;
  256. }
  257. foreach (View view in _subviews)
  258. {
  259. if (!_enabled)
  260. {
  261. view._oldEnabled = view.Enabled;
  262. view.Enabled = _enabled;
  263. }
  264. else
  265. {
  266. view.Enabled = view._oldEnabled;
  267. #if AUTO_CANFOCUS
  268. view._addingViewSoCanFocusAlsoUpdatesSuperView = _enabled;
  269. #endif
  270. }
  271. }
  272. }
  273. }
  274. /// <summary>Raised when the <see cref="Enabled"/> value is being changed.</summary>
  275. public event EventHandler? EnabledChanged;
  276. // TODO: Change this event to match the standard TG event model.
  277. /// <summary>Invoked when the <see cref="Enabled"/> property from a view is changed.</summary>
  278. public virtual void OnEnabledChanged () { EnabledChanged?.Invoke (this, EventArgs.Empty); }
  279. private bool _visible = true;
  280. // TODO: Remove virtual once Menu/MenuBar are removed. MenuBar is the only override.
  281. /// <summary>Gets or sets a value indicating whether this <see cref="View"/> is visible.</summary>
  282. public virtual bool Visible
  283. {
  284. get => _visible;
  285. set
  286. {
  287. if (_visible == value)
  288. {
  289. return;
  290. }
  291. if (OnVisibleChanging ())
  292. {
  293. return;
  294. }
  295. CancelEventArgs<bool> args = new (in _visible, ref value);
  296. VisibleChanging?.Invoke (this, args);
  297. if (args.Cancel)
  298. {
  299. return;
  300. }
  301. _visible = value;
  302. if (!_visible)
  303. {
  304. if (HasFocus)
  305. {
  306. HasFocus = false;
  307. }
  308. }
  309. if (_visible
  310. && CanFocus
  311. && Enabled
  312. && !HasFocus
  313. && SuperView is null or { HasFocus: true, Visible: true, Enabled: true, Focused: null })
  314. {
  315. SetFocus ();
  316. }
  317. OnVisibleChanged ();
  318. VisibleChanged?.Invoke (this, EventArgs.Empty);
  319. SetLayoutNeeded ();
  320. SuperView?.SetLayoutNeeded();
  321. SetNeedsDisplay ();
  322. SuperView?.SetNeedsDisplay();
  323. }
  324. }
  325. /// <summary>Called when <see cref="Visible"/> is changing. Can be cancelled by returning <see langword="true"/>.</summary>
  326. protected virtual bool OnVisibleChanging () { return false; }
  327. /// <summary>
  328. /// Raised when the <see cref="Visible"/> value is being changed. Can be cancelled by setting Cancel to
  329. /// <see langword="true"/>.
  330. /// </summary>
  331. public event EventHandler<CancelEventArgs<bool>>? VisibleChanging;
  332. /// <summary>Called when <see cref="Visible"/> has changed.</summary>
  333. protected virtual void OnVisibleChanged () { }
  334. /// <summary>Raised when <see cref="Visible"/> has changed.</summary>
  335. public event EventHandler? VisibleChanged;
  336. /// <summary>
  337. /// INTERNAL Indicates whether all views up the Superview hierarchy are visible.
  338. /// </summary>
  339. /// <param name="view">The view to test.</param>
  340. /// <returns>
  341. /// <see langword="false"/> if `view.Visible` is <see langword="false"/> or any Superview is not visible,
  342. /// <see langword="true"/> otherwise.
  343. /// </returns>
  344. internal static bool CanBeVisible (View view)
  345. {
  346. if (!view.Visible)
  347. {
  348. return false;
  349. }
  350. for (View? c = view.SuperView; c != null; c = c.SuperView)
  351. {
  352. if (!c.Visible)
  353. {
  354. return false;
  355. }
  356. }
  357. return true;
  358. }
  359. #endregion Visibility
  360. #region Title
  361. private string _title = string.Empty;
  362. /// <summary>Gets the <see cref="Gui.TextFormatter"/> used to format <see cref="Title"/>.</summary>
  363. internal TextFormatter TitleTextFormatter { get; init; } = new ();
  364. /// <summary>
  365. /// The title to be displayed for this <see cref="View"/>. The title will be displayed if <see cref="Border"/>.
  366. /// <see cref="Thickness.Top"/> is greater than 0. The title can be used to set the <see cref="HotKey"/>
  367. /// for the view by prefixing character with <see cref="HotKeySpecifier"/> (e.g. <c>"T_itle"</c>).
  368. /// </summary>
  369. /// <remarks>
  370. /// <para>
  371. /// Set the <see cref="HotKeySpecifier"/> to enable hotkey support. To disable Title-based hotkey support set
  372. /// <see cref="HotKeySpecifier"/> to <c>(Rune)0xffff</c>.
  373. /// </para>
  374. /// <para>
  375. /// Only the first HotKey specifier found in <see cref="Title"/> is supported.
  376. /// </para>
  377. /// <para>
  378. /// To cause the hotkey to be rendered with <see cref="Text"/>,
  379. /// set <c>View.</c><see cref="TextFormatter.HotKeySpecifier"/> to the desired character.
  380. /// </para>
  381. /// </remarks>
  382. /// <value>The title.</value>
  383. public string Title
  384. {
  385. get
  386. {
  387. #if DEBUG_IDISPOSABLE
  388. if (WasDisposed)
  389. {
  390. throw new ObjectDisposedException (GetType ().FullName);
  391. }
  392. #endif
  393. return _title;
  394. }
  395. set
  396. {
  397. #if DEBUG_IDISPOSABLE
  398. if (WasDisposed)
  399. {
  400. throw new ObjectDisposedException (GetType ().FullName);
  401. }
  402. #endif
  403. if (value == _title)
  404. {
  405. return;
  406. }
  407. if (!OnTitleChanging (ref value))
  408. {
  409. string old = _title;
  410. _title = value;
  411. TitleTextFormatter.Text = _title;
  412. SetTitleTextFormatterSize ();
  413. SetHotKeyFromTitle ();
  414. SetNeedsDisplay ();
  415. #if DEBUG
  416. if (string.IsNullOrEmpty (Id))
  417. {
  418. Id = _title;
  419. }
  420. #endif // DEBUG
  421. OnTitleChanged ();
  422. }
  423. }
  424. }
  425. private void SetTitleTextFormatterSize ()
  426. {
  427. TitleTextFormatter.ConstrainToSize = new (
  428. TextFormatter.GetWidestLineLength (TitleTextFormatter.Text)
  429. - (TitleTextFormatter.Text?.Contains ((char)HotKeySpecifier.Value) == true
  430. ? Math.Max (HotKeySpecifier.GetColumns (), 0)
  431. : 0),
  432. 1);
  433. }
  434. // TODO: Change this event to match the standard TG event model.
  435. /// <summary>Called when the <see cref="View.Title"/> has been changed. Invokes the <see cref="TitleChanged"/> event.</summary>
  436. protected void OnTitleChanged () { TitleChanged?.Invoke (this, new (in _title)); }
  437. /// <summary>
  438. /// Called before the <see cref="View.Title"/> changes. Invokes the <see cref="TitleChanging"/> event, which can
  439. /// be cancelled.
  440. /// </summary>
  441. /// <param name="newTitle">The new <see cref="View.Title"/> to be replaced.</param>
  442. /// <returns>`true` if an event handler canceled the Title change.</returns>
  443. protected bool OnTitleChanging (ref string newTitle)
  444. {
  445. CancelEventArgs<string> args = new (ref _title, ref newTitle);
  446. TitleChanging?.Invoke (this, args);
  447. return args.Cancel;
  448. }
  449. /// <summary>Raised after the <see cref="View.Title"/> has been changed.</summary>
  450. public event EventHandler<EventArgs<string>>? TitleChanged;
  451. /// <summary>
  452. /// Raised when the <see cref="View.Title"/> is changing. Set <see cref="CancelEventArgs.Cancel"/> to `true`
  453. /// to cancel the Title change.
  454. /// </summary>
  455. public event EventHandler<CancelEventArgs<string>>? TitleChanging;
  456. #endregion
  457. /// <summary>Pretty prints the View</summary>
  458. /// <returns></returns>
  459. public override string ToString () { return $"{GetType ().Name}({Id}){Frame}"; }
  460. /// <inheritdoc/>
  461. protected override void Dispose (bool disposing)
  462. {
  463. LineCanvas.Dispose ();
  464. DisposeKeyboard ();
  465. DisposeAdornments ();
  466. for (int i = InternalSubviews.Count - 1; i >= 0; i--)
  467. {
  468. View subview = InternalSubviews [i];
  469. Remove (subview);
  470. subview.Dispose ();
  471. }
  472. base.Dispose (disposing);
  473. Debug.Assert (InternalSubviews.Count == 0);
  474. }
  475. }