View.Hierarchy.cs 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324
  1. #nullable enable
  2. using System.Diagnostics;
  3. namespace Terminal.Gui;
  4. public partial class View // SuperView/SubView hierarchy management (SuperView, SubViews, Add, Remove, etc.)
  5. {
  6. private static readonly IList<View> _empty = new List<View> (0).AsReadOnly ();
  7. private List<View>? _subviews; // This is null, and allocated on demand.
  8. private View? _superView;
  9. /// <summary>Indicates whether the view was added to <see cref="SuperView"/>.</summary>
  10. public bool IsAdded { get; private set; }
  11. /// <summary>This returns a list of the subviews contained by this view.</summary>
  12. /// <value>The subviews.</value>
  13. public IList<View> Subviews => _subviews?.AsReadOnly () ?? _empty;
  14. /// <summary>Returns the container for this view, or null if this view has not been added to a container.</summary>
  15. /// <value>The super view.</value>
  16. public virtual View? SuperView
  17. {
  18. get => _superView!;
  19. set => throw new NotImplementedException ();
  20. }
  21. // Internally, we use InternalSubviews rather than subviews, as we do not expect us
  22. // to make the same mistakes our users make when they poke at the Subviews.
  23. internal IList<View> InternalSubviews => _subviews ?? _empty;
  24. /// <summary>Adds a subview (child) to this view.</summary>
  25. /// <remarks>
  26. /// <para>
  27. /// The Views that have been added to this view can be retrieved via the <see cref="Subviews"/> property. See also
  28. /// <seealso cref="Remove(View)"/> <seealso cref="RemoveAll"/>
  29. /// </para>
  30. /// <para>
  31. /// Subviews will be disposed when this View is disposed. In other-words, calling this method causes
  32. /// the lifecycle of the subviews to be transferred to this View.
  33. /// </para>
  34. /// </remarks>
  35. /// <param name="view">The view to add.</param>
  36. /// <returns>The view that was added.</returns>
  37. public virtual View Add (View view)
  38. {
  39. if (_subviews is null)
  40. {
  41. _subviews = [];
  42. }
  43. Debug.WriteLineIf (_subviews.Contains (view), $"WARNING: {view} has already been added to {this}.");
  44. // TileView likes to add views that were previously added and have HasFocus = true. No bueno.
  45. view.HasFocus = false;
  46. _subviews.Add (view);
  47. view._superView = this;
  48. if (view is { Enabled: true, Visible: true, CanFocus: true })
  49. {
  50. // Add will cause the newly added subview to gain focus if it's focusable
  51. if (HasFocus)
  52. {
  53. view.SetFocus ();
  54. }
  55. }
  56. if (view.Enabled && !Enabled)
  57. {
  58. view._oldEnabled = true;
  59. view.Enabled = false;
  60. }
  61. OnAdded (new (this, view));
  62. if (IsInitialized && !view.IsInitialized)
  63. {
  64. view.BeginInit ();
  65. view.EndInit ();
  66. }
  67. CheckDimAuto ();
  68. SetNeedsLayout ();
  69. SetNeedsDisplay ();
  70. return view;
  71. }
  72. /// <summary>Adds the specified views (children) to the view.</summary>
  73. /// <param name="views">Array of one or more views (can be optional parameter).</param>
  74. /// <remarks>
  75. /// <para>
  76. /// The Views that have been added to this view can be retrieved via the <see cref="Subviews"/> property. See also
  77. /// <seealso cref="Remove(View)"/> and <seealso cref="RemoveAll"/>.
  78. /// </para>
  79. /// <para>
  80. /// Subviews will be disposed when this View is disposed. In other-words, calling this method causes
  81. /// the lifecycle of the subviews to be transferred to this View.
  82. /// </para>
  83. /// </remarks>
  84. public void Add (params View []? views)
  85. {
  86. if (views is null)
  87. {
  88. return;
  89. }
  90. foreach (View view in views)
  91. {
  92. Add (view);
  93. }
  94. }
  95. /// <summary>Event fired when this view is added to another.</summary>
  96. public event EventHandler<SuperViewChangedEventArgs>? Added;
  97. /// <summary>Get the top superview of a given <see cref="View"/>.</summary>
  98. /// <returns>The superview view.</returns>
  99. public View? GetTopSuperView (View? view = null, View? superview = null)
  100. {
  101. View? top = superview ?? Application.Top;
  102. for (View? v = view?.SuperView ?? this?.SuperView; v != null; v = v.SuperView)
  103. {
  104. top = v;
  105. if (top == superview)
  106. {
  107. break;
  108. }
  109. }
  110. return top;
  111. }
  112. /// <summary>Method invoked when a subview is being added to this view.</summary>
  113. /// <param name="e">Event where <see cref="ViewEventArgs.View"/> is the subview being added.</param>
  114. public virtual void OnAdded (SuperViewChangedEventArgs e)
  115. {
  116. View view = e.Child;
  117. view.IsAdded = true;
  118. view.OnResizeNeeded ();
  119. view.Added?.Invoke (this, e);
  120. }
  121. /// <summary>Method invoked when a subview is being removed from this view.</summary>
  122. /// <param name="e">Event args describing the subview being removed.</param>
  123. public virtual void OnRemoved (SuperViewChangedEventArgs e)
  124. {
  125. View view = e.Child;
  126. view.IsAdded = false;
  127. view.Removed?.Invoke (this, e);
  128. }
  129. /// <summary>Removes a subview added via <see cref="Add(View)"/> or <see cref="Add(View[])"/> from this View.</summary>
  130. /// <remarks>
  131. /// <para>
  132. /// Normally Subviews will be disposed when this View is disposed. Removing a Subview causes ownership of the
  133. /// Subview's
  134. /// lifecycle to be transferred to the caller; the caller muse call <see cref="Dispose"/>.
  135. /// </para>
  136. /// </remarks>
  137. /// <returns>
  138. /// The removed View. <see langword="null"/> if the View could not be removed.
  139. /// </returns>
  140. public virtual View? Remove (View view)
  141. {
  142. if (_subviews is null)
  143. {
  144. return view;
  145. }
  146. Rectangle touched = view.Frame;
  147. // If a view being removed is focused, it should lose focus.
  148. if (view.HasFocus)
  149. {
  150. view.HasFocus = false;
  151. }
  152. _subviews.Remove (view);
  153. view._superView = null; // Null this AFTER removing focus
  154. SetNeedsLayout ();
  155. SetNeedsDisplay ();
  156. foreach (View v in _subviews)
  157. {
  158. if (v.Frame.IntersectsWith (touched))
  159. {
  160. view.SetNeedsDisplay ();
  161. }
  162. }
  163. if (HasFocus)
  164. {
  165. FocusDeepest (NavigationDirection.Forward, TabStop);
  166. }
  167. OnRemoved (new (this, view));
  168. return view;
  169. }
  170. /// <summary>
  171. /// Removes all subviews (children) added via <see cref="Add(View)"/> or <see cref="Add(View[])"/> from this View.
  172. /// </summary>
  173. /// <remarks>
  174. /// <para>
  175. /// Normally Subviews will be disposed when this View is disposed. Removing a Subview causes ownership of the
  176. /// Subview's
  177. /// lifecycle to be transferred to the caller; the caller must call <see cref="Dispose"/> on any Views that were
  178. /// added.
  179. /// </para>
  180. /// </remarks>
  181. public virtual void RemoveAll ()
  182. {
  183. if (_subviews is null)
  184. {
  185. return;
  186. }
  187. while (_subviews.Count > 0)
  188. {
  189. Remove (_subviews [0]);
  190. }
  191. }
  192. /// <summary>Event fired when this view is removed from another.</summary>
  193. public event EventHandler<SuperViewChangedEventArgs>? Removed;
  194. /// <summary>
  195. /// Moves <paramref name="subview"/> one position towards the end of the <see cref="Subviews"/> list.
  196. /// </summary>
  197. /// <param name="subview">The subview to move.</param>
  198. public void MoveSubviewTowardsEnd (View subview)
  199. {
  200. PerformActionForSubview (
  201. subview,
  202. x =>
  203. {
  204. int idx = _subviews!.IndexOf (x);
  205. if (idx + 1 < _subviews.Count)
  206. {
  207. _subviews.Remove (x);
  208. _subviews.Insert (idx + 1, x);
  209. }
  210. }
  211. );
  212. }
  213. /// <summary>
  214. /// Moves <paramref name="subview"/> to the end of the <see cref="Subviews"/> list.
  215. /// </summary>
  216. /// <param name="subview">The subview to move.</param>
  217. public void MoveSubviewToEnd (View subview)
  218. {
  219. PerformActionForSubview (
  220. subview,
  221. x =>
  222. {
  223. _subviews!.Remove (x);
  224. _subviews.Add (x);
  225. }
  226. );
  227. }
  228. /// <summary>
  229. /// Moves <paramref name="subview"/> one position towards the start of the <see cref="Subviews"/> list.
  230. /// </summary>
  231. /// <param name="subview">The subview to move.</param>
  232. public void MoveSubviewTowardsStart (View subview)
  233. {
  234. PerformActionForSubview (
  235. subview,
  236. x =>
  237. {
  238. int idx = _subviews!.IndexOf (x);
  239. if (idx > 0)
  240. {
  241. _subviews.Remove (x);
  242. _subviews.Insert (idx - 1, x);
  243. }
  244. }
  245. );
  246. }
  247. /// <summary>
  248. /// Moves <paramref name="subview"/> to the start of the <see cref="Subviews"/> list.
  249. /// </summary>
  250. /// <param name="subview">The subview to move.</param>
  251. public void MoveSubviewToStart (View subview)
  252. {
  253. PerformActionForSubview (
  254. subview,
  255. x =>
  256. {
  257. _subviews!.Remove (x);
  258. _subviews.Insert (0, subview);
  259. }
  260. );
  261. }
  262. /// <summary>
  263. /// Internal API that runs <paramref name="action"/> on a subview if it is part of the <see cref="Subviews"/> list.
  264. /// </summary>
  265. /// <param name="subview"></param>
  266. /// <param name="action"></param>
  267. private void PerformActionForSubview (View subview, Action<View> action)
  268. {
  269. if (_subviews!.Contains (subview))
  270. {
  271. action (subview);
  272. }
  273. // BUGBUG: this is odd. Why is this needed?
  274. SetNeedsDisplay ();
  275. subview.SetNeedsDisplay ();
  276. }
  277. }