ConsoleDriver.cs 36 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978
  1. #nullable enable
  2. //
  3. // ConsoleDriver.cs: Base class for Terminal.Gui ConsoleDriver implementations.
  4. //
  5. using System.Diagnostics;
  6. namespace Terminal.Gui;
  7. /// <summary>Base class for Terminal.Gui ConsoleDriver implementations.</summary>
  8. /// <remarks>
  9. /// There are currently four implementations: - <see cref="CursesDriver"/> (for Unix and Mac) -
  10. /// <see cref="WindowsDriver"/> - <see cref="NetDriver"/> that uses the .NET Console API - <see cref="FakeConsole"/>
  11. /// for unit testing.
  12. /// </remarks>
  13. public abstract class ConsoleDriver
  14. {
  15. // As performance is a concern, we keep track of the dirty lines and only refresh those.
  16. // This is in addition to the dirty flag on each cell.
  17. internal bool []? _dirtyLines;
  18. // QUESTION: When non-full screen apps are supported, will this represent the app size, or will that be in Application?
  19. /// <summary>Gets the location and size of the terminal screen.</summary>
  20. internal Rectangle Screen => new (0, 0, Cols, Rows);
  21. private Region? _clip = null;
  22. /// <summary>
  23. /// Gets or sets the clip rectangle that <see cref="AddRune(Rune)"/> and <see cref="AddStr(string)"/> are subject
  24. /// to.
  25. /// </summary>
  26. /// <value>The rectangle describing the of <see cref="Clip"/> region.</value>
  27. public Region? Clip
  28. {
  29. get => _clip;
  30. set
  31. {
  32. if (_clip == value)
  33. {
  34. return;
  35. }
  36. _clip = value;
  37. // Don't ever let Clip be bigger than Screen
  38. if (_clip is { })
  39. {
  40. _clip.Intersect (Screen);
  41. }
  42. }
  43. }
  44. /// <summary>Get the operating system clipboard.</summary>
  45. public IClipboard? Clipboard { get; internal set; }
  46. /// <summary>
  47. /// Gets the column last set by <see cref="Move"/>. <see cref="Col"/> and <see cref="Row"/> are used by
  48. /// <see cref="AddRune(Rune)"/> and <see cref="AddStr"/> to determine where to add content.
  49. /// </summary>
  50. internal int Col { get; private set; }
  51. /// <summary>The number of columns visible in the terminal.</summary>
  52. internal virtual int Cols
  53. {
  54. get => _cols;
  55. set
  56. {
  57. _cols = value;
  58. ClearContents ();
  59. }
  60. }
  61. /// <summary>
  62. /// The contents of the application output. The driver outputs this buffer to the terminal when
  63. /// <see cref="UpdateScreen"/> is called.
  64. /// <remarks>The format of the array is rows, columns. The first index is the row, the second index is the column.</remarks>
  65. /// </summary>
  66. internal Cell [,]? Contents { get; set; }
  67. /// <summary>The leftmost column in the terminal.</summary>
  68. internal virtual int Left { get; set; } = 0;
  69. /// <summary>
  70. /// Gets the row last set by <see cref="Move"/>. <see cref="Col"/> and <see cref="Row"/> are used by
  71. /// <see cref="AddRune(Rune)"/> and <see cref="AddStr"/> to determine where to add content.
  72. /// </summary>
  73. internal int Row { get; private set; }
  74. /// <summary>The number of rows visible in the terminal.</summary>
  75. internal virtual int Rows
  76. {
  77. get => _rows;
  78. set
  79. {
  80. _rows = value;
  81. ClearContents ();
  82. }
  83. }
  84. /// <summary>The topmost row in the terminal.</summary>
  85. internal virtual int Top { get; set; } = 0;
  86. /// <summary>
  87. /// Set this to true in any unit tests that attempt to test drivers other than FakeDriver.
  88. /// <code>
  89. /// public ColorTests ()
  90. /// {
  91. /// ConsoleDriver.RunningUnitTests = true;
  92. /// }
  93. /// </code>
  94. /// </summary>
  95. internal static bool RunningUnitTests { get; set; }
  96. /// <summary>Adds the specified rune to the display at the current cursor position.</summary>
  97. /// <remarks>
  98. /// <para>
  99. /// When the method returns, <see cref="Col"/> will be incremented by the number of columns
  100. /// <paramref name="rune"/> required, even if the new column value is outside of the <see cref="Clip"/> or screen
  101. /// dimensions defined by <see cref="Cols"/>.
  102. /// </para>
  103. /// <para>
  104. /// If <paramref name="rune"/> requires more than one column, and <see cref="Col"/> plus the number of columns
  105. /// needed exceeds the <see cref="Clip"/> or screen dimensions, the default Unicode replacement character (U+FFFD)
  106. /// will be added instead.
  107. /// </para>
  108. /// </remarks>
  109. /// <param name="rune">Rune to add.</param>
  110. internal void AddRune (Rune rune)
  111. {
  112. int runeWidth = -1;
  113. bool validLocation = IsValidLocation (rune, Col, Row);
  114. if (Contents is null)
  115. {
  116. return;
  117. }
  118. Rectangle clipRect = Clip!.GetBounds ();
  119. if (validLocation)
  120. {
  121. rune = rune.MakePrintable ();
  122. runeWidth = rune.GetColumns ();
  123. lock (Contents)
  124. {
  125. if (runeWidth == 0 && rune.IsCombiningMark ())
  126. {
  127. // AtlasEngine does not support NON-NORMALIZED combining marks in a way
  128. // compatible with the driver architecture. Any CMs (except in the first col)
  129. // are correctly combined with the base char, but are ALSO treated as 1 column
  130. // width codepoints E.g. `echo "[e`u{0301}`u{0301}]"` will output `[é ]`.
  131. //
  132. // Until this is addressed (see Issue #), we do our best by
  133. // a) Attempting to normalize any CM with the base char to it's left
  134. // b) Ignoring any CMs that don't normalize
  135. if (Col > 0)
  136. {
  137. if (Contents [Row, Col - 1].CombiningMarks.Count > 0)
  138. {
  139. // Just add this mark to the list
  140. Contents [Row, Col - 1].CombiningMarks.Add (rune);
  141. // Ignore. Don't move to next column (let the driver figure out what to do).
  142. }
  143. else
  144. {
  145. // Attempt to normalize the cell to our left combined with this mark
  146. string combined = Contents [Row, Col - 1].Rune + rune.ToString ();
  147. // Normalize to Form C (Canonical Composition)
  148. string normalized = combined.Normalize (NormalizationForm.FormC);
  149. if (normalized.Length == 1)
  150. {
  151. // It normalized! We can just set the Cell to the left with the
  152. // normalized codepoint
  153. Contents [Row, Col - 1].Rune = (Rune)normalized [0];
  154. // Ignore. Don't move to next column because we're already there
  155. }
  156. else
  157. {
  158. // It didn't normalize. Add it to the Cell to left's CM list
  159. Contents [Row, Col - 1].CombiningMarks.Add (rune);
  160. // Ignore. Don't move to next column (let the driver figure out what to do).
  161. }
  162. }
  163. Contents [Row, Col - 1].Attribute = CurrentAttribute;
  164. Contents [Row, Col - 1].IsDirty = true;
  165. }
  166. else
  167. {
  168. // Most drivers will render a combining mark at col 0 as the mark
  169. Contents [Row, Col].Rune = rune;
  170. Contents [Row, Col].Attribute = CurrentAttribute;
  171. Contents [Row, Col].IsDirty = true;
  172. Col++;
  173. }
  174. }
  175. else
  176. {
  177. Contents [Row, Col].Attribute = CurrentAttribute;
  178. Contents [Row, Col].IsDirty = true;
  179. if (Col > 0)
  180. {
  181. // Check if cell to left has a wide glyph
  182. if (Contents [Row, Col - 1].Rune.GetColumns () > 1)
  183. {
  184. // Invalidate cell to left
  185. Contents [Row, Col - 1].Rune = Rune.ReplacementChar;
  186. Contents [Row, Col - 1].IsDirty = true;
  187. }
  188. }
  189. if (runeWidth < 1)
  190. {
  191. Contents [Row, Col].Rune = Rune.ReplacementChar;
  192. }
  193. else if (runeWidth == 1)
  194. {
  195. Contents [Row, Col].Rune = rune;
  196. if (Col < clipRect.Right - 1)
  197. {
  198. Contents [Row, Col + 1].IsDirty = true;
  199. }
  200. }
  201. else if (runeWidth == 2)
  202. {
  203. if (!Clip.Contains (Col + 1, Row))
  204. {
  205. // We're at the right edge of the clip, so we can't display a wide character.
  206. // TODO: Figure out if it is better to show a replacement character or ' '
  207. Contents [Row, Col].Rune = Rune.ReplacementChar;
  208. }
  209. else if (!Clip.Contains (Col, Row))
  210. {
  211. // Our 1st column is outside the clip, so we can't display a wide character.
  212. Contents [Row, Col+1].Rune = Rune.ReplacementChar;
  213. }
  214. else
  215. {
  216. Contents [Row, Col].Rune = rune;
  217. if (Col < clipRect.Right - 1)
  218. {
  219. // Invalidate cell to right so that it doesn't get drawn
  220. // TODO: Figure out if it is better to show a replacement character or ' '
  221. Contents [Row, Col + 1].Rune = Rune.ReplacementChar;
  222. Contents [Row, Col + 1].IsDirty = true;
  223. }
  224. }
  225. }
  226. else
  227. {
  228. // This is a non-spacing character, so we don't need to do anything
  229. Contents [Row, Col].Rune = (Rune)' ';
  230. Contents [Row, Col].IsDirty = false;
  231. }
  232. _dirtyLines! [Row] = true;
  233. }
  234. }
  235. }
  236. if (runeWidth is < 0 or > 0)
  237. {
  238. Col++;
  239. }
  240. if (runeWidth > 1)
  241. {
  242. Debug.Assert (runeWidth <= 2);
  243. if (validLocation && Col < clipRect.Right)
  244. {
  245. lock (Contents!)
  246. {
  247. // This is a double-width character, and we are not at the end of the line.
  248. // Col now points to the second column of the character. Ensure it doesn't
  249. // Get rendered.
  250. Contents [Row, Col].IsDirty = false;
  251. Contents [Row, Col].Attribute = CurrentAttribute;
  252. // TODO: Determine if we should wipe this out (for now now)
  253. //Contents [Row, Col].Rune = (Rune)' ';
  254. }
  255. }
  256. Col++;
  257. }
  258. }
  259. /// <summary>
  260. /// Adds the specified <see langword="char"/> to the display at the current cursor position. This method is a
  261. /// convenience method that calls <see cref="AddRune(Rune)"/> with the <see cref="Rune"/> constructor.
  262. /// </summary>
  263. /// <param name="c">Character to add.</param>
  264. internal void AddRune (char c) { AddRune (new Rune (c)); }
  265. /// <summary>Adds the <paramref name="str"/> to the display at the cursor position.</summary>
  266. /// <remarks>
  267. /// <para>
  268. /// When the method returns, <see cref="Col"/> will be incremented by the number of columns
  269. /// <paramref name="str"/> required, unless the new column value is outside of the <see cref="Clip"/> or screen
  270. /// dimensions defined by <see cref="Cols"/>.
  271. /// </para>
  272. /// <para>If <paramref name="str"/> requires more columns than are available, the output will be clipped.</para>
  273. /// </remarks>
  274. /// <param name="str">String.</param>
  275. public void AddStr (string str)
  276. {
  277. List<Rune> runes = str.EnumerateRunes ().ToList ();
  278. for (var i = 0; i < runes.Count; i++)
  279. {
  280. AddRune (runes [i]);
  281. }
  282. }
  283. /// <summary>Clears the <see cref="Contents"/> of the driver.</summary>
  284. public void ClearContents ()
  285. {
  286. Contents = new Cell [Rows, Cols];
  287. //CONCURRENCY: Unsynchronized access to Clip isn't safe.
  288. // TODO: ClearContents should not clear the clip; it should only clear the contents. Move clearing it elsewhere.
  289. Clip = new (Screen);
  290. _dirtyLines = new bool [Rows];
  291. lock (Contents)
  292. {
  293. for (var row = 0; row < Rows; row++)
  294. {
  295. for (var c = 0; c < Cols; c++)
  296. {
  297. Contents [row, c] = new Cell
  298. {
  299. Rune = (Rune)' ',
  300. Attribute = new Attribute (Color.White, Color.Black),
  301. IsDirty = true
  302. };
  303. }
  304. _dirtyLines [row] = true;
  305. }
  306. }
  307. ClearedContents?.Invoke (this, EventArgs.Empty);
  308. }
  309. /// <summary>
  310. /// Raised each time <see cref="ClearContents"/> is called. For benchmarking.
  311. /// </summary>
  312. public event EventHandler<EventArgs>? ClearedContents;
  313. /// <summary>
  314. /// Sets <see cref="Contents"/> as dirty for situations where views
  315. /// don't need layout and redrawing, but just refresh the screen.
  316. /// </summary>
  317. public void SetContentsAsDirty ()
  318. {
  319. lock (Contents!)
  320. {
  321. for (var row = 0; row < Rows; row++)
  322. {
  323. for (var c = 0; c < Cols; c++)
  324. {
  325. Contents [row, c].IsDirty = true;
  326. }
  327. _dirtyLines! [row] = true;
  328. }
  329. }
  330. }
  331. /// <summary>Determines if the terminal cursor should be visible or not and sets it accordingly.</summary>
  332. /// <returns><see langword="true"/> upon success</returns>
  333. public abstract bool EnsureCursorVisibility ();
  334. /// <summary>Fills the specified rectangle with the specified rune, using <see cref="CurrentAttribute"/></summary>
  335. /// <remarks>
  336. /// The value of <see cref="Clip"/> is honored. Any parts of the rectangle not in the clip will not be drawn.
  337. /// </remarks>
  338. /// <param name="rect">The Screen-relative rectangle.</param>
  339. /// <param name="rune">The Rune used to fill the rectangle</param>
  340. public void FillRect (Rectangle rect, Rune rune = default)
  341. {
  342. // BUGBUG: This should be a method on Region
  343. rect = Rectangle.Intersect (rect, Clip?.GetBounds () ?? Screen);
  344. lock (Contents!)
  345. {
  346. for (int r = rect.Y; r < rect.Y + rect.Height; r++)
  347. {
  348. for (int c = rect.X; c < rect.X + rect.Width; c++)
  349. {
  350. if (!IsValidLocation (rune, c, r))
  351. {
  352. continue;
  353. }
  354. Contents [r, c] = new Cell
  355. {
  356. Rune = (rune != default ? rune : (Rune)' '),
  357. Attribute = CurrentAttribute, IsDirty = true
  358. };
  359. _dirtyLines! [r] = true;
  360. }
  361. }
  362. }
  363. }
  364. /// <summary>
  365. /// Fills the specified rectangle with the specified <see langword="char"/>. This method is a convenience method
  366. /// that calls <see cref="FillRect(Rectangle, Rune)"/>.
  367. /// </summary>
  368. /// <param name="rect"></param>
  369. /// <param name="c"></param>
  370. public void FillRect (Rectangle rect, char c) { FillRect (rect, new Rune (c)); }
  371. /// <summary>Gets the terminal cursor visibility.</summary>
  372. /// <param name="visibility">The current <see cref="CursorVisibility"/></param>
  373. /// <returns><see langword="true"/> upon success</returns>
  374. public abstract bool GetCursorVisibility (out CursorVisibility visibility);
  375. /// <summary>Returns the name of the driver and relevant library version information.</summary>
  376. /// <returns></returns>
  377. public virtual string GetVersionInfo () { return GetType ().Name; }
  378. /// <summary>Tests if the specified rune is supported by the driver.</summary>
  379. /// <param name="rune"></param>
  380. /// <returns>
  381. /// <see langword="true"/> if the rune can be properly presented; <see langword="false"/> if the driver does not
  382. /// support displaying this rune.
  383. /// </returns>
  384. public virtual bool IsRuneSupported (Rune rune) { return Rune.IsValid (rune.Value); }
  385. /// <summary>Tests whether the specified coordinate are valid for drawing the specified Rune.</summary>
  386. /// <param name="rune">Used to determine if one or two columns are required.</param>
  387. /// <param name="col">The column.</param>
  388. /// <param name="row">The row.</param>
  389. /// <returns>
  390. /// <see langword="false"/> if the coordinate is outside the screen bounds or outside of <see cref="Clip"/>.
  391. /// <see langword="true"/> otherwise.
  392. /// </returns>
  393. public bool IsValidLocation (Rune rune, int col, int row)
  394. {
  395. if (rune.GetColumns () < 2)
  396. {
  397. return col >= 0 && row >= 0 && col < Cols && row < Rows && Clip!.Contains (col, row);
  398. }
  399. else
  400. {
  401. return Clip!.Contains (col, row) || Clip!.Contains (col + 1, row);
  402. }
  403. }
  404. /// <summary>
  405. /// Updates <see cref="Col"/> and <see cref="Row"/> to the specified column and row in <see cref="Contents"/>.
  406. /// Used by <see cref="AddRune(Rune)"/> and <see cref="AddStr"/> to determine where to add content.
  407. /// </summary>
  408. /// <remarks>
  409. /// <para>This does not move the cursor on the screen, it only updates the internal state of the driver.</para>
  410. /// <para>
  411. /// If <paramref name="col"/> or <paramref name="row"/> are negative or beyond <see cref="Cols"/> and
  412. /// <see cref="Rows"/>, the method still sets those properties.
  413. /// </para>
  414. /// </remarks>
  415. /// <param name="col">Column to move to.</param>
  416. /// <param name="row">Row to move to.</param>
  417. public virtual void Move (int col, int row)
  418. {
  419. //Debug.Assert (col >= 0 && row >= 0 && col < Contents.GetLength(1) && row < Contents.GetLength(0));
  420. Col = col;
  421. Row = row;
  422. }
  423. /// <summary>Called when the terminal size changes. Fires the <see cref="SizeChanged"/> event.</summary>
  424. /// <param name="args"></param>
  425. public void OnSizeChanged (SizeChangedEventArgs args) { SizeChanged?.Invoke (this, args); }
  426. /// <summary>Updates the screen to reflect all the changes that have been done to the display buffer</summary>
  427. public void Refresh ()
  428. {
  429. bool updated = UpdateScreen ();
  430. UpdateCursor ();
  431. Refreshed?.Invoke (this, new EventArgs<bool> (in updated));
  432. }
  433. /// <summary>
  434. /// Raised each time <see cref="Refresh"/> is called. For benchmarking.
  435. /// </summary>
  436. public event EventHandler<EventArgs<bool>>? Refreshed;
  437. /// <summary>Sets the terminal cursor visibility.</summary>
  438. /// <param name="visibility">The wished <see cref="CursorVisibility"/></param>
  439. /// <returns><see langword="true"/> upon success</returns>
  440. public abstract bool SetCursorVisibility (CursorVisibility visibility);
  441. /// <summary>The event fired when the terminal is resized.</summary>
  442. public event EventHandler<SizeChangedEventArgs>? SizeChanged;
  443. /// <summary>Suspends the application (e.g. on Linux via SIGTSTP) and upon resume, resets the console driver.</summary>
  444. /// <remarks>This is only implemented in <see cref="CursesDriver"/>.</remarks>
  445. public abstract void Suspend ();
  446. /// <summary>Sets the position of the terminal cursor to <see cref="Col"/> and <see cref="Row"/>.</summary>
  447. public abstract void UpdateCursor ();
  448. /// <summary>Redraws the physical screen with the contents that have been queued up via any of the printing commands.</summary>
  449. /// <returns><see langword="true"/> if any updates to the screen were made.</returns>
  450. public abstract bool UpdateScreen ();
  451. #region Setup & Teardown
  452. /// <summary>Initializes the driver</summary>
  453. /// <returns>Returns an instance of <see cref="MainLoop"/> using the <see cref="IMainLoopDriver"/> for the driver.</returns>
  454. internal abstract MainLoop Init ();
  455. /// <summary>Ends the execution of the console driver.</summary>
  456. internal abstract void End ();
  457. #endregion
  458. #region Color Handling
  459. /// <summary>Gets whether the <see cref="ConsoleDriver"/> supports TrueColor output.</summary>
  460. public virtual bool SupportsTrueColor => true;
  461. // TODO: This makes ConsoleDriver dependent on Application, which is not ideal. This should be moved to Application.
  462. // BUGBUG: Application.Force16Colors should be bool? so if SupportsTrueColor and Application.Force16Colors == false, this doesn't override
  463. /// <summary>
  464. /// Gets or sets whether the <see cref="ConsoleDriver"/> should use 16 colors instead of the default TrueColors.
  465. /// See <see cref="Application.Force16Colors"/> to change this setting via <see cref="ConfigurationManager"/>.
  466. /// </summary>
  467. /// <remarks>
  468. /// <para>
  469. /// Will be forced to <see langword="true"/> if <see cref="ConsoleDriver.SupportsTrueColor"/> is
  470. /// <see langword="false"/>, indicating that the <see cref="ConsoleDriver"/> cannot support TrueColor.
  471. /// </para>
  472. /// </remarks>
  473. internal virtual bool Force16Colors
  474. {
  475. get => Application.Force16Colors || !SupportsTrueColor;
  476. set => Application.Force16Colors = value || !SupportsTrueColor;
  477. }
  478. private Attribute _currentAttribute;
  479. private int _cols;
  480. private int _rows;
  481. /// <summary>
  482. /// The <see cref="Attribute"/> that will be used for the next <see cref="AddRune(Rune)"/> or <see cref="AddStr"/>
  483. /// call.
  484. /// </summary>
  485. public Attribute CurrentAttribute
  486. {
  487. get => _currentAttribute;
  488. set
  489. {
  490. // TODO: This makes ConsoleDriver dependent on Application, which is not ideal. Once Attribute.PlatformColor is removed, this can be fixed.
  491. if (Application.Driver is { })
  492. {
  493. _currentAttribute = new Attribute (value.Foreground, value.Background);
  494. return;
  495. }
  496. _currentAttribute = value;
  497. }
  498. }
  499. /// <summary>Selects the specified attribute as the attribute to use for future calls to AddRune and AddString.</summary>
  500. /// <remarks>Implementations should call <c>base.SetAttribute(c)</c>.</remarks>
  501. /// <param name="c">C.</param>
  502. internal Attribute SetAttribute (Attribute c)
  503. {
  504. Attribute prevAttribute = CurrentAttribute;
  505. CurrentAttribute = c;
  506. return prevAttribute;
  507. }
  508. /// <summary>Gets the current <see cref="Attribute"/>.</summary>
  509. /// <returns>The current attribute.</returns>
  510. internal Attribute GetAttribute () { return CurrentAttribute; }
  511. // TODO: This is only overridden by CursesDriver. Once CursesDriver supports 24-bit color, this virtual method can be
  512. // removed (and Attribute can lose the platformColor property).
  513. /// <summary>Makes an <see cref="Attribute"/>.</summary>
  514. /// <param name="foreground">The foreground color.</param>
  515. /// <param name="background">The background color.</param>
  516. /// <returns>The attribute for the foreground and background colors.</returns>
  517. public virtual Attribute MakeColor (in Color foreground, in Color background)
  518. {
  519. // Encode the colors into the int value.
  520. return new Attribute (
  521. -1, // only used by cursesdriver!
  522. foreground,
  523. background
  524. );
  525. }
  526. #endregion
  527. #region Mouse and Keyboard
  528. /// <summary>Event fired when a key is pressed down. This is a precursor to <see cref="KeyUp"/>.</summary>
  529. public event EventHandler<Key>? KeyDown;
  530. /// <summary>
  531. /// Called when a key is pressed down. Fires the <see cref="KeyDown"/> event. This is a precursor to
  532. /// <see cref="OnKeyUp"/>.
  533. /// </summary>
  534. /// <param name="a"></param>
  535. public void OnKeyDown (Key a) { KeyDown?.Invoke (this, a); }
  536. /// <summary>Event fired when a key is released.</summary>
  537. /// <remarks>
  538. /// Drivers that do not support key release events will fire this event after <see cref="KeyDown"/> processing is
  539. /// complete.
  540. /// </remarks>
  541. public event EventHandler<Key>? KeyUp;
  542. /// <summary>Called when a key is released. Fires the <see cref="KeyUp"/> event.</summary>
  543. /// <remarks>
  544. /// Drivers that do not support key release events will call this method after <see cref="OnKeyDown"/> processing
  545. /// is complete.
  546. /// </remarks>
  547. /// <param name="a"></param>
  548. public void OnKeyUp (Key a) { KeyUp?.Invoke (this, a); }
  549. /// <summary>Event fired when a mouse event occurs.</summary>
  550. public event EventHandler<MouseEventArgs>? MouseEvent;
  551. /// <summary>Called when a mouse event occurs. Fires the <see cref="MouseEvent"/> event.</summary>
  552. /// <param name="a"></param>
  553. public void OnMouseEvent (MouseEventArgs a)
  554. {
  555. // Ensure ScreenPosition is set
  556. a.ScreenPosition = a.Position;
  557. MouseEvent?.Invoke (this, a);
  558. }
  559. /// <summary>Simulates a key press.</summary>
  560. /// <param name="keyChar">The key character.</param>
  561. /// <param name="key">The key.</param>
  562. /// <param name="shift">If <see langword="true"/> simulates the Shift key being pressed.</param>
  563. /// <param name="alt">If <see langword="true"/> simulates the Alt key being pressed.</param>
  564. /// <param name="ctrl">If <see langword="true"/> simulates the Ctrl key being pressed.</param>
  565. public abstract void SendKeys (char keyChar, ConsoleKey key, bool shift, bool alt, bool ctrl);
  566. #endregion
  567. }
  568. /// <summary>
  569. /// The <see cref="KeyCode"/> enumeration encodes key information from <see cref="ConsoleDriver"/>s and provides a
  570. /// consistent way for application code to specify keys and receive key events.
  571. /// <para>
  572. /// The <see cref="Key"/> class provides a higher-level abstraction, with helper methods and properties for
  573. /// common operations. For example, <see cref="Key.IsAlt"/> and <see cref="Key.IsCtrl"/> provide a convenient way
  574. /// to check whether the Alt or Ctrl modifier keys were pressed when a key was pressed.
  575. /// </para>
  576. /// </summary>
  577. /// <remarks>
  578. /// <para>
  579. /// Lowercase alpha keys are encoded as values between 65 and 90 corresponding to the un-shifted A to Z keys on a
  580. /// keyboard. Enum values are provided for these (e.g. <see cref="KeyCode.A"/>, <see cref="KeyCode.B"/>, etc.).
  581. /// Even though the values are the same as the ASCII values for uppercase characters, these enum values represent
  582. /// *lowercase*, un-shifted characters.
  583. /// </para>
  584. /// <para>
  585. /// Numeric keys are the values between 48 and 57 corresponding to 0 to 9 (e.g. <see cref="KeyCode.D0"/>,
  586. /// <see cref="KeyCode.D1"/>, etc.).
  587. /// </para>
  588. /// <para>
  589. /// The shift modifiers (<see cref="KeyCode.ShiftMask"/>, <see cref="KeyCode.CtrlMask"/>, and
  590. /// <see cref="KeyCode.AltMask"/>) can be combined (with logical or) with the other key codes to represent shifted
  591. /// keys. For example, the <see cref="KeyCode.A"/> enum value represents the un-shifted 'a' key, while
  592. /// <see cref="KeyCode.ShiftMask"/> | <see cref="KeyCode.A"/> represents the 'A' key (shifted 'a' key). Likewise,
  593. /// <see cref="KeyCode.AltMask"/> | <see cref="KeyCode.A"/> represents the 'Alt+A' key combination.
  594. /// </para>
  595. /// <para>
  596. /// All other keys that produce a printable character are encoded as the Unicode value of the character. For
  597. /// example, the <see cref="KeyCode"/> for the '!' character is 33, which is the Unicode value for '!'. Likewise,
  598. /// `â` is 226, `Â` is 194, etc.
  599. /// </para>
  600. /// <para>
  601. /// If the <see cref="SpecialMask"/> is set, then the value is that of the special mask, otherwise, the value is
  602. /// the one of the lower bits (as extracted by <see cref="CharMask"/>).
  603. /// </para>
  604. /// </remarks>
  605. [Flags]
  606. public enum KeyCode : uint
  607. {
  608. /// <summary>
  609. /// Mask that indicates that the key is a unicode codepoint. Values outside this range indicate the key has shift
  610. /// modifiers or is a special key like function keys, arrows keys and so on.
  611. /// </summary>
  612. CharMask = 0x_f_ffff,
  613. /// <summary>
  614. /// If the <see cref="SpecialMask"/> is set, then the value is that of the special mask, otherwise, the value is
  615. /// in the lower bits (as extracted by <see cref="CharMask"/>).
  616. /// </summary>
  617. SpecialMask = 0x_fff0_0000,
  618. /// <summary>
  619. /// When this value is set, the Key encodes the sequence Shift-KeyValue. The actual value must be extracted by
  620. /// removing the ShiftMask.
  621. /// </summary>
  622. ShiftMask = 0x_1000_0000,
  623. /// <summary>
  624. /// When this value is set, the Key encodes the sequence Alt-KeyValue. The actual value must be extracted by
  625. /// removing the AltMask.
  626. /// </summary>
  627. AltMask = 0x_8000_0000,
  628. /// <summary>
  629. /// When this value is set, the Key encodes the sequence Ctrl-KeyValue. The actual value must be extracted by
  630. /// removing the CtrlMask.
  631. /// </summary>
  632. CtrlMask = 0x_4000_0000,
  633. /// <summary>The key code representing an invalid or empty key.</summary>
  634. Null = 0,
  635. /// <summary>Backspace key.</summary>
  636. Backspace = 8,
  637. /// <summary>The key code for the tab key (forwards tab key).</summary>
  638. Tab = 9,
  639. /// <summary>The key code for the return key.</summary>
  640. Enter = ConsoleKey.Enter,
  641. /// <summary>The key code for the clear key.</summary>
  642. Clear = 12,
  643. /// <summary>The key code for the escape key.</summary>
  644. Esc = 27,
  645. /// <summary>The key code for the space bar key.</summary>
  646. Space = 32,
  647. /// <summary>Digit 0.</summary>
  648. D0 = 48,
  649. /// <summary>Digit 1.</summary>
  650. D1,
  651. /// <summary>Digit 2.</summary>
  652. D2,
  653. /// <summary>Digit 3.</summary>
  654. D3,
  655. /// <summary>Digit 4.</summary>
  656. D4,
  657. /// <summary>Digit 5.</summary>
  658. D5,
  659. /// <summary>Digit 6.</summary>
  660. D6,
  661. /// <summary>Digit 7.</summary>
  662. D7,
  663. /// <summary>Digit 8.</summary>
  664. D8,
  665. /// <summary>Digit 9.</summary>
  666. D9,
  667. /// <summary>The key code for the A key</summary>
  668. A = 65,
  669. /// <summary>The key code for the B key</summary>
  670. B,
  671. /// <summary>The key code for the C key</summary>
  672. C,
  673. /// <summary>The key code for the D key</summary>
  674. D,
  675. /// <summary>The key code for the E key</summary>
  676. E,
  677. /// <summary>The key code for the F key</summary>
  678. F,
  679. /// <summary>The key code for the G key</summary>
  680. G,
  681. /// <summary>The key code for the H key</summary>
  682. H,
  683. /// <summary>The key code for the I key</summary>
  684. I,
  685. /// <summary>The key code for the J key</summary>
  686. J,
  687. /// <summary>The key code for the K key</summary>
  688. K,
  689. /// <summary>The key code for the L key</summary>
  690. L,
  691. /// <summary>The key code for the M key</summary>
  692. M,
  693. /// <summary>The key code for the N key</summary>
  694. N,
  695. /// <summary>The key code for the O key</summary>
  696. O,
  697. /// <summary>The key code for the P key</summary>
  698. P,
  699. /// <summary>The key code for the Q key</summary>
  700. Q,
  701. /// <summary>The key code for the R key</summary>
  702. R,
  703. /// <summary>The key code for the S key</summary>
  704. S,
  705. /// <summary>The key code for the T key</summary>
  706. T,
  707. /// <summary>The key code for the U key</summary>
  708. U,
  709. /// <summary>The key code for the V key</summary>
  710. V,
  711. /// <summary>The key code for the W key</summary>
  712. W,
  713. /// <summary>The key code for the X key</summary>
  714. X,
  715. /// <summary>The key code for the Y key</summary>
  716. Y,
  717. /// <summary>The key code for the Z key</summary>
  718. Z,
  719. ///// <summary>
  720. ///// The key code for the Delete key.
  721. ///// </summary>
  722. //Delete = 127,
  723. // --- Special keys ---
  724. // The values below are common non-alphanum keys. Their values are
  725. // based on the .NET ConsoleKey values, which, in-turn are based on the
  726. // VK_ values from the Windows API.
  727. // We add MaxCodePoint to avoid conflicts with the Unicode values.
  728. /// <summary>The maximum Unicode codepoint value. Used to encode the non-alphanumeric control keys.</summary>
  729. MaxCodePoint = 0x10FFFF,
  730. /// <summary>Cursor up key</summary>
  731. CursorUp = MaxCodePoint + ConsoleKey.UpArrow,
  732. /// <summary>Cursor down key.</summary>
  733. CursorDown = MaxCodePoint + ConsoleKey.DownArrow,
  734. /// <summary>Cursor left key.</summary>
  735. CursorLeft = MaxCodePoint + ConsoleKey.LeftArrow,
  736. /// <summary>Cursor right key.</summary>
  737. CursorRight = MaxCodePoint + ConsoleKey.RightArrow,
  738. /// <summary>Page Up key.</summary>
  739. PageUp = MaxCodePoint + ConsoleKey.PageUp,
  740. /// <summary>Page Down key.</summary>
  741. PageDown = MaxCodePoint + ConsoleKey.PageDown,
  742. /// <summary>Home key.</summary>
  743. Home = MaxCodePoint + ConsoleKey.Home,
  744. /// <summary>End key.</summary>
  745. End = MaxCodePoint + ConsoleKey.End,
  746. /// <summary>Insert (INS) key.</summary>
  747. Insert = MaxCodePoint + ConsoleKey.Insert,
  748. /// <summary>Delete (DEL) key.</summary>
  749. Delete = MaxCodePoint + ConsoleKey.Delete,
  750. /// <summary>Print screen character key.</summary>
  751. PrintScreen = MaxCodePoint + ConsoleKey.PrintScreen,
  752. /// <summary>F1 key.</summary>
  753. F1 = MaxCodePoint + ConsoleKey.F1,
  754. /// <summary>F2 key.</summary>
  755. F2 = MaxCodePoint + ConsoleKey.F2,
  756. /// <summary>F3 key.</summary>
  757. F3 = MaxCodePoint + ConsoleKey.F3,
  758. /// <summary>F4 key.</summary>
  759. F4 = MaxCodePoint + ConsoleKey.F4,
  760. /// <summary>F5 key.</summary>
  761. F5 = MaxCodePoint + ConsoleKey.F5,
  762. /// <summary>F6 key.</summary>
  763. F6 = MaxCodePoint + ConsoleKey.F6,
  764. /// <summary>F7 key.</summary>
  765. F7 = MaxCodePoint + ConsoleKey.F7,
  766. /// <summary>F8 key.</summary>
  767. F8 = MaxCodePoint + ConsoleKey.F8,
  768. /// <summary>F9 key.</summary>
  769. F9 = MaxCodePoint + ConsoleKey.F9,
  770. /// <summary>F10 key.</summary>
  771. F10 = MaxCodePoint + ConsoleKey.F10,
  772. /// <summary>F11 key.</summary>
  773. F11 = MaxCodePoint + ConsoleKey.F11,
  774. /// <summary>F12 key.</summary>
  775. F12 = MaxCodePoint + ConsoleKey.F12,
  776. /// <summary>F13 key.</summary>
  777. F13 = MaxCodePoint + ConsoleKey.F13,
  778. /// <summary>F14 key.</summary>
  779. F14 = MaxCodePoint + ConsoleKey.F14,
  780. /// <summary>F15 key.</summary>
  781. F15 = MaxCodePoint + ConsoleKey.F15,
  782. /// <summary>F16 key.</summary>
  783. F16 = MaxCodePoint + ConsoleKey.F16,
  784. /// <summary>F17 key.</summary>
  785. F17 = MaxCodePoint + ConsoleKey.F17,
  786. /// <summary>F18 key.</summary>
  787. F18 = MaxCodePoint + ConsoleKey.F18,
  788. /// <summary>F19 key.</summary>
  789. F19 = MaxCodePoint + ConsoleKey.F19,
  790. /// <summary>F20 key.</summary>
  791. F20 = MaxCodePoint + ConsoleKey.F20,
  792. /// <summary>F21 key.</summary>
  793. F21 = MaxCodePoint + ConsoleKey.F21,
  794. /// <summary>F22 key.</summary>
  795. F22 = MaxCodePoint + ConsoleKey.F22,
  796. /// <summary>F23 key.</summary>
  797. F23 = MaxCodePoint + ConsoleKey.F23,
  798. /// <summary>F24 key.</summary>
  799. F24 = MaxCodePoint + ConsoleKey.F24
  800. }