Adornment.cs 8.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256
  1. #nullable enable
  2. using Terminal.Gui;
  3. using Attribute = Terminal.Gui.Attribute;
  4. /// <summary>
  5. /// Adornments are a special form of <see cref="View"/> that appear outside the <see cref="View.Viewport"/>:
  6. /// <see cref="Margin"/>, <see cref="Border"/>, and <see cref="Padding"/>. They are defined using the
  7. /// <see cref="Thickness"/> class, which specifies the thickness of the sides of a rectangle.
  8. /// </summary>
  9. /// <remarsk>
  10. /// <para>
  11. /// Each of <see cref="Margin"/>, <see cref="Border"/>, and <see cref="Padding"/> has slightly different
  12. /// behavior relative to <see cref="ColorScheme"/>, <see cref="View.SetFocus()"/>, keyboard input, and
  13. /// mouse input. Each can be customized by manipulating their Subviews.
  14. /// </para>
  15. /// </remarsk>
  16. public class Adornment : View, IDesignable
  17. {
  18. /// <inheritdoc/>
  19. public Adornment ()
  20. {
  21. /* Do nothing; A parameter-less constructor is required to support all views unit tests. */
  22. }
  23. /// <summary>Constructs a new adornment for the view specified by <paramref name="parent"/>.</summary>
  24. /// <param name="parent"></param>
  25. public Adornment (View parent)
  26. {
  27. // By default, Adornments can't get focus; has to be enabled specifically.
  28. CanFocus = false;
  29. TabStop = TabBehavior.NoStop;
  30. Parent = parent;
  31. }
  32. /// <summary>The Parent of this Adornment (the View this Adornment surrounds).</summary>
  33. /// <remarks>
  34. /// Adornments are distinguished from typical View classes in that they are not sub-views, but have a parent/child
  35. /// relationship with their containing View.
  36. /// </remarks>
  37. public View? Parent { get; set; }
  38. #region Thickness
  39. /// <summary>
  40. /// Gets or sets whether the Adornment will draw diagnostic information. This is a bit-field of <see cref="ViewDiagnosticFlags"/>.
  41. /// </summary>
  42. /// <remarks>
  43. /// The <see cref="View.Diagnostics"/> static property is used as the default value for this property.
  44. /// </remarks>
  45. public new ViewDiagnosticFlags Diagnostics { get; set; } = View.Diagnostics;
  46. private Thickness _thickness = Thickness.Empty;
  47. /// <summary>Defines the rectangle that the <see cref="Adornment"/> will use to draw its content.</summary>
  48. public Thickness Thickness
  49. {
  50. get => _thickness;
  51. set
  52. {
  53. Thickness current = _thickness;
  54. _thickness = value;
  55. if (current != _thickness)
  56. {
  57. Parent?.SetAdornmentFrames ();
  58. SetNeedsLayout ();
  59. SetNeedsDisplay ();
  60. OnThicknessChanged ();
  61. }
  62. }
  63. }
  64. /// <summary>Fired whenever the <see cref="Thickness"/> property changes.</summary>
  65. public event EventHandler? ThicknessChanged;
  66. /// <summary>Called whenever the <see cref="Thickness"/> property changes.</summary>
  67. public void OnThicknessChanged () { ThicknessChanged?.Invoke (this, EventArgs.Empty); }
  68. #endregion Thickness
  69. #region View Overrides
  70. /// <summary>
  71. /// Adornments cannot be used as sub-views (see <see cref="Parent"/>); setting this property will throw
  72. /// <see cref="InvalidOperationException"/>.
  73. /// </summary>
  74. /// <remarks>
  75. /// While there are no real use cases for an Adornment being a subview, it is not explicitly dis-allowed to support
  76. /// testing. E.g. in AllViewsTester.
  77. /// </remarks>
  78. public override View? SuperView
  79. {
  80. get => base.SuperView!;
  81. set => throw new InvalidOperationException (@"Adornments can not be Subviews or have SuperViews. Use Parent instead.");
  82. }
  83. /// <summary>
  84. /// Gets the rectangle that describes the area of the Adornment. The Location is always (0,0).
  85. /// The size is the size of the <see cref="View.Frame"/>.
  86. /// </summary>
  87. /// <remarks>
  88. /// The Viewport of an Adornment cannot be modified. Attempting to set this property will throw an
  89. /// <see cref="InvalidOperationException"/>.
  90. /// </remarks>
  91. public override Rectangle Viewport
  92. {
  93. get => base.Viewport;
  94. set => throw new InvalidOperationException (@"The Viewport of an Adornment cannot be modified.");
  95. }
  96. /// <inheritdoc/>
  97. public override Rectangle FrameToScreen ()
  98. {
  99. if (Parent is null)
  100. {
  101. // While there are no real use cases for an Adornment being a subview, we support it for
  102. // testing. E.g. in AllViewsTester.
  103. if (SuperView is { })
  104. {
  105. Point super = SuperView.ViewportToScreen (Frame.Location);
  106. return new (super, Frame.Size);
  107. }
  108. return Frame;
  109. }
  110. // Adornments are *Children* of a View, not SubViews. Thus View.FrameToScreen will not work.
  111. // To get the screen-relative coordinates of an Adornment, we need get the parent's Frame
  112. // in screen coords, ...
  113. Rectangle parentScreen = Parent.FrameToScreen ();
  114. // ...and add our Frame location to it.
  115. return new (new (parentScreen.X + Frame.X, parentScreen.Y + Frame.Y), Frame.Size);
  116. }
  117. /// <inheritdoc/>
  118. public override Point ScreenToFrame (in Point location)
  119. {
  120. View? parentOrSuperView = Parent;
  121. if (parentOrSuperView is null)
  122. {
  123. // While there are no real use cases for an Adornment being a subview, we support it for
  124. // testing. E.g. in AllViewsTester.
  125. parentOrSuperView = SuperView;
  126. if (parentOrSuperView is null)
  127. {
  128. return Point.Empty;
  129. }
  130. }
  131. return parentOrSuperView.ScreenToFrame (new (location.X - Frame.X, location.Y - Frame.Y));
  132. }
  133. /// <summary>Does nothing for Adornment</summary>
  134. /// <returns></returns>
  135. protected override bool OnDrawingAdornments () { return false; }
  136. /// <inheritdoc/>
  137. protected override bool OnClearingViewport (Rectangle viewport)
  138. {
  139. if (Thickness == Thickness.Empty)
  140. {
  141. return true;
  142. }
  143. Attribute normalAttr = GetNormalColor ();
  144. Driver?.SetAttribute (normalAttr);
  145. // This just draws/clears the thickness, not the insides.
  146. Thickness.Draw (ViewportToScreen (viewport), Diagnostics, ToString ());
  147. return true;
  148. }
  149. /// <inheritdoc />
  150. protected override bool OnDrawingText (Rectangle viewport)
  151. {
  152. return Thickness == Thickness.Empty;
  153. }
  154. /// <inheritdoc />
  155. protected override bool OnDrawingSubviews (Rectangle viewport)
  156. {
  157. return Thickness == Thickness.Empty;
  158. }
  159. /// <summary>Does nothing for Adornment</summary>
  160. /// <returns></returns>
  161. protected override bool OnRenderingLineCanvas () { return true; }
  162. /// <summary>
  163. /// Adornments only render to their <see cref="Parent"/>'s or Parent's SuperView's LineCanvas, so setting this
  164. /// property throws an <see cref="InvalidOperationException"/>.
  165. /// </summary>
  166. public override bool SuperViewRendersLineCanvas
  167. {
  168. get => false;
  169. set => throw new InvalidOperationException (@"Adornment can only render to their Parent or Parent's Superview.");
  170. }
  171. /// <inheritdoc />
  172. protected override bool OnDrawComplete (Rectangle viewport)
  173. {
  174. return Thickness == Thickness.Empty;
  175. }
  176. /// <summary>
  177. /// Indicates whether the specified Parent's SuperView-relative coordinates are within the Adornment's Thickness.
  178. /// </summary>
  179. /// <remarks>
  180. /// The <paramref name="location"/> is relative to the PARENT's SuperView.
  181. /// </remarks>
  182. /// <param name="location"></param>
  183. /// <returns>
  184. /// <see langword="true"/> if the specified Parent's SuperView-relative coordinates are within the Adornment's
  185. /// Thickness.
  186. /// </returns>
  187. public override bool Contains (in Point location)
  188. {
  189. View? parentOrSuperView = Parent;
  190. if (parentOrSuperView is null)
  191. {
  192. // While there are no real use cases for an Adornment being a subview, we support it for
  193. // testing. E.g. in AllViewsTester.
  194. parentOrSuperView = SuperView;
  195. if (parentOrSuperView is null)
  196. {
  197. return false;
  198. }
  199. }
  200. Rectangle outside = Frame;
  201. outside.Offset (parentOrSuperView.Frame.Location);
  202. return Thickness.Contains (outside, location);
  203. }
  204. #endregion View Overrides
  205. /// <inheritdoc/>
  206. bool IDesignable.EnableForDesign ()
  207. {
  208. // This enables AllViewsTester to show something useful.
  209. Thickness = new (3);
  210. Frame = new (0, 0, 10, 10);
  211. Diagnostics = ViewDiagnosticFlags.Thickness;
  212. return true;
  213. }
  214. }