Key.cs 41 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044
  1. using System.Diagnostics.CodeAnalysis;
  2. using System.Globalization;
  3. namespace Terminal.Gui;
  4. /// <summary>
  5. /// Provides an abstraction for common keyboard operations and state. Used for processing keyboard input and
  6. /// raising keyboard events.
  7. /// </summary>
  8. /// <remarks>
  9. /// <para>
  10. /// This class provides a high-level abstraction with helper methods and properties for common keyboard
  11. /// operations. Use this class instead of the <see cref="Terminal.Gui.KeyCode"/> enumeration for keyboard input
  12. /// whenever possible.
  13. /// </para>
  14. /// <para></para>
  15. /// <para>
  16. /// The default value for <see cref="Key"/> is <see cref="KeyCode.Null"/> and can be tested using
  17. /// <see cref="Key.Empty"/>.
  18. /// </para>
  19. /// <para>
  20. /// <list type="table">
  21. /// <listheader>
  22. /// <term>Concept</term><description>Definition</description>
  23. /// </listheader>
  24. /// <item>
  25. /// <term>Testing Shift State</term>
  26. /// <description>
  27. /// The <c>Is</c> properties (<see cref="IsShift"/>,<see cref="IsCtrl"/>, <see cref="IsAlt"/>)
  28. /// test for shift state; whether the key press was modified by a shift key.
  29. /// </description>
  30. /// </item>
  31. /// <item>
  32. /// <term>Adding Shift State</term>
  33. /// <description>
  34. /// The <c>With</c> properties (<see cref="WithShift"/>,<see cref="WithCtrl"/>,
  35. /// <see cref="WithAlt"/>) return a copy of the Key with the shift modifier applied. This is useful for
  36. /// specifying a key that requires a shift modifier (e.g.
  37. /// <c>var ControlAltDelete = new Key(Key.Delete).WithAlt.WithDel;</c>.
  38. /// </description>
  39. /// </item>
  40. /// <item>
  41. /// <term>Removing Shift State</term>
  42. /// <description>
  43. /// The <c>No</c> properties (<see cref="NoShift"/>,<see cref="NoCtrl"/>, <see cref="NoAlt"/>)
  44. /// return a copy of the Key with the shift modifier removed. This is useful for specifying a key that
  45. /// does not require a shift modifier (e.g. <c>var ControlDelete = ControlAltDelete.NoCtrl;</c>.
  46. /// </description>
  47. /// </item>
  48. /// <item>
  49. /// <term>Encoding of A..Z</term>
  50. /// <description>
  51. /// Lowercase alpha keys are encoded (in <see cref="Key.KeyCode"/>) as values between 65 and
  52. /// 90 corresponding to the un-shifted A to Z keys on a keyboard. Properties are provided for these
  53. /// (e.g. <see cref="Key.A"/>, <see cref="Key.B"/>, etc.). Even though the encoded values are the same
  54. /// as the ASCII values for uppercase characters, these enum values represent *lowercase*, un-shifted
  55. /// characters.
  56. /// </description>
  57. /// </item>
  58. /// <item>
  59. /// <term>Persistence as strings</term>
  60. /// <description>
  61. /// Keys are persisted as <c>"[Modifiers]+[Key]</c>. For example
  62. /// <c>new Key(Key.Delete).WithAlt.WithDel</c> is persisted as <c>"Ctrl+Alt+Delete"</c>. See
  63. /// <see cref="ToString()"/> and <see cref="TryParse(string, out Terminal.Gui.Key)"/> for more
  64. /// information.
  65. /// </description>
  66. /// </item>
  67. /// </list>
  68. /// </para>
  69. /// </remarks>
  70. public class Key : EventArgs, IEquatable<Key>
  71. {
  72. /// <summary>Constructs a new <see cref="Key"/></summary>
  73. public Key () : this (KeyCode.Null) { }
  74. /// <summary>Constructs a new <see cref="Key"/> from the provided Key value</summary>
  75. /// <param name="k">The key</param>
  76. public Key (KeyCode k) { KeyCode = k; }
  77. /// <summary>
  78. /// Copy constructor.
  79. /// </summary>
  80. /// <param name="key">The Key to copy</param>
  81. public Key (Key key)
  82. {
  83. KeyCode = key.KeyCode;
  84. Handled = key.Handled;
  85. }
  86. /// <summary>Constructs a new <see cref="Key"/> from a char.</summary>
  87. /// <remarks>
  88. /// <para>
  89. /// The key codes for the A..Z keys are encoded as values between 65 and 90 (<see cref="KeyCode.A"/> through
  90. /// <see cref="KeyCode.Z"/>). While these are the same as the ASCII values for uppercase characters, they represent
  91. /// *keys*, not characters. Therefore, this constructor will store 'A'..'Z' as <see cref="KeyCode.A"/>..
  92. /// <see cref="KeyCode.Z"/> with the <see cref="KeyCode.ShiftMask"/> set and will store `a`..`z` as
  93. /// <see cref="KeyCode.A"/>..<see cref="KeyCode.Z"/>.
  94. /// </para>
  95. /// </remarks>
  96. /// <param name="ch"></param>
  97. public Key (char ch)
  98. {
  99. switch (ch)
  100. {
  101. case >= 'A' and <= 'Z':
  102. // Upper case A..Z mean "Shift-char" so we need to add Shift
  103. KeyCode = (KeyCode)ch | KeyCode.ShiftMask;
  104. break;
  105. case >= 'a' and <= 'z':
  106. // Lower case a..z mean no shift, so we need to store as Key.A...Key.Z
  107. KeyCode = (KeyCode)(ch - 32);
  108. return;
  109. default:
  110. KeyCode = (KeyCode)ch;
  111. break;
  112. }
  113. }
  114. /// <summary>
  115. /// Constructs a new Key from a string describing the key. See
  116. /// <see cref="TryParse(string, out Terminal.Gui.Key)"/> for information on the format of the string.
  117. /// </summary>
  118. /// <param name="str">The string describing the key.</param>
  119. public Key (string str)
  120. {
  121. bool result = TryParse (str, out Key key);
  122. if (!result)
  123. {
  124. throw new ArgumentException (@$"Invalid key string: {str}", nameof (str));
  125. }
  126. KeyCode = key.KeyCode;
  127. }
  128. /// <summary>
  129. /// The key value as a Rune. This is the actual value of the key pressed, and is independent of the modifiers.
  130. /// Useful for determining if a key represents is a printable character.
  131. /// </summary>
  132. /// <remarks>
  133. /// <para>Keys with Ctrl or Alt modifiers will return <see langword="default"/>.</para>
  134. /// <para>
  135. /// If the key is a letter key (A-Z), the Rune will be the upper or lower case letter depending on whether
  136. /// <see cref="KeyCode.ShiftMask"/> is set.
  137. /// </para>
  138. /// <para>
  139. /// If the key is outside of the <see cref="KeyCode.CharMask"/> range, the returned Rune will be
  140. /// <see langword="default"/>.
  141. /// </para>
  142. /// </remarks>
  143. public Rune AsRune => ToRune (KeyCode);
  144. /// <summary>
  145. /// Indicates if the current Key event has already been processed and the driver should stop notifying any other
  146. /// event subscriber. It's important to set this value to true specially when updating any View's layout from inside
  147. /// the
  148. /// subscriber method.
  149. /// </summary>
  150. public bool Handled { get; set; }
  151. /// <summary>Gets a value indicating whether the Alt key was pressed (real or synthesized)</summary>
  152. /// <value><see langword="true"/> if is alternate; otherwise, <see langword="false"/>.</value>
  153. public bool IsAlt => (KeyCode & KeyCode.AltMask) != 0;
  154. /// <summary>Gets a value indicating whether the Ctrl key was pressed.</summary>
  155. /// <value><see langword="true"/> if is ctrl; otherwise, <see langword="false"/>.</value>
  156. public bool IsCtrl => (KeyCode & KeyCode.CtrlMask) != 0;
  157. /// <summary>
  158. /// Gets a value indicating whether the key represents a key in the range of <see cref="KeyCode.A"/> to
  159. /// <see cref="KeyCode.Z"/>, regardless of the <see cref="KeyCode.ShiftMask"/>. This is useful for testing if a key is
  160. /// based on these keys which are special cased.
  161. /// </summary>
  162. /// <remarks>
  163. /// IMPORTANT: Lowercase alpha keys are encoded in <see cref="Key.KeyCode"/> as values between 65 and 90
  164. /// corresponding to the un-shifted A to Z keys on a keyboard. Helper properties are provided these (e.g.
  165. /// <see cref="Key.A"/>, <see cref="Key.B"/>, etc.). Even though the values are the same as the ASCII values for
  166. /// uppercase characters, these enum values represent *lowercase*, un-shifted characters.
  167. /// </remarks>
  168. public bool IsKeyCodeAtoZ => GetIsKeyCodeAtoZ (KeyCode);
  169. /// <summary>Gets a value indicating whether the Shift key was pressed.</summary>
  170. /// <value><see langword="true"/> if is shift; otherwise, <see langword="false"/>.</value>
  171. public bool IsShift => (KeyCode & KeyCode.ShiftMask) != 0;
  172. /// <summary>
  173. /// Indicates whether the <see cref="Key"/> is valid or not. Invalid keys are <see cref="Key.Empty"/>, and keys
  174. /// with only shift modifiers.
  175. /// </summary>
  176. public bool IsValid => this != Empty && NoAlt.NoShift.NoCtrl != Empty;
  177. private readonly KeyCode _keyCode;
  178. /// <summary>The encoded key value.</summary>
  179. /// <para>
  180. /// IMPORTANT: Lowercase alpha keys are encoded (in <see cref="Gui.KeyCode"/>) as values between 65 and 90
  181. /// corresponding to the un-shifted A to Z keys on a keyboard. Enum values are provided for these (e.g.
  182. /// <see cref="KeyCode.A"/>, <see cref="KeyCode.B"/>, etc.). Even though the values are the same as the ASCII values
  183. /// for uppercase characters, these enum values represent *lowercase*, un-shifted characters.
  184. /// </para>
  185. /// <remarks>This property is the backing data for the <see cref="Key"/>. It is a <see cref="KeyCode"/> enum value.</remarks>
  186. public KeyCode KeyCode
  187. {
  188. get => _keyCode;
  189. init
  190. {
  191. #if DEBUG
  192. if (GetIsKeyCodeAtoZ (value) && (value & KeyCode.Space) != 0)
  193. {
  194. throw new ArgumentException ($"Invalid KeyCode: {value} is invalid.", nameof (value));
  195. }
  196. #endif
  197. _keyCode = value;
  198. }
  199. }
  200. /// <summary>
  201. /// Helper for removing a shift modifier from a <see cref="Key"/>.
  202. /// <code>
  203. /// var ControlAltDelete = new Key(Key.Delete).WithAlt.WithDel;
  204. /// var AltDelete = ControlAltDelete.NoCtrl;
  205. /// </code>
  206. /// </summary>
  207. public Key NoAlt => new (this) { KeyCode = KeyCode & ~KeyCode.AltMask };
  208. /// <summary>
  209. /// Helper for removing a shift modifier from a <see cref="Key"/>.
  210. /// <code>
  211. /// var ControlAltDelete = new Key(Key.Delete).WithAlt.WithDel;
  212. /// var AltDelete = ControlAltDelete.NoCtrl;
  213. /// </code>
  214. /// </summary>
  215. public Key NoCtrl => new (this) { KeyCode = KeyCode & ~KeyCode.CtrlMask };
  216. /// <summary>
  217. /// Helper for removing a shift modifier from a <see cref="Key"/>.
  218. /// <code>
  219. /// var ControlAltDelete = new Key(Key.Delete).WithAlt.WithDel;
  220. /// var AltDelete = ControlAltDelete.NoCtrl;
  221. /// </code>
  222. /// </summary>
  223. public Key NoShift => new (this) { KeyCode = KeyCode & ~KeyCode.ShiftMask };
  224. /// <summary>
  225. /// Helper for specifying a shifted <see cref="Key"/>.
  226. /// <code>
  227. /// var ControlAltDelete = new Key(Key.Delete).WithAlt.WithDel;
  228. /// </code>
  229. /// </summary>
  230. public Key WithAlt => new (this) { KeyCode = KeyCode | KeyCode.AltMask };
  231. /// <summary>
  232. /// Helper for specifying a shifted <see cref="Key"/>.
  233. /// <code>
  234. /// var ControlAltDelete = new Key(Key.Delete).WithAlt.WithDel;
  235. /// </code>
  236. /// </summary>
  237. public Key WithCtrl => new (this) { KeyCode = KeyCode | KeyCode.CtrlMask };
  238. /// <summary>
  239. /// Helper for specifying a shifted <see cref="Key"/>.
  240. /// <code>
  241. /// var ControlAltDelete = new Key(Key.Delete).WithAlt.WithDel;
  242. /// </code>
  243. /// </summary>
  244. public Key WithShift => new (this) { KeyCode = KeyCode | KeyCode.ShiftMask };
  245. /// <summary>
  246. /// Tests if a KeyCode represents a key in the range of <see cref="KeyCode.A"/> to <see cref="KeyCode.Z"/>,
  247. /// regardless of the <see cref="KeyCode.ShiftMask"/>. This is useful for testing if a key is based on these keys which
  248. /// are special cased.
  249. /// </summary>
  250. /// <remarks>
  251. /// IMPORTANT: Lowercase alpha keys are encoded in <see cref="Key.KeyCode"/> as values between 65 and 90
  252. /// corresponding to the un-shifted A to Z keys on a keyboard. Helper properties are provided these (e.g.
  253. /// <see cref="Key.A"/>, <see cref="Key.B"/>, etc.). Even though the values are the same as the ASCII values for
  254. /// uppercase characters, these enum values represent *lowercase*, un-shifted characters.
  255. /// </remarks>
  256. public static bool GetIsKeyCodeAtoZ (KeyCode keyCode)
  257. {
  258. if ((keyCode & KeyCode.AltMask) != 0 || (keyCode & KeyCode.CtrlMask) != 0)
  259. {
  260. return false;
  261. }
  262. if ((keyCode & ~KeyCode.Space & ~KeyCode.ShiftMask) is >= KeyCode.A and <= KeyCode.Z)
  263. {
  264. return true;
  265. }
  266. return (keyCode & KeyCode.CharMask) is >= KeyCode.A and <= KeyCode.Z;
  267. }
  268. /// <summary>
  269. /// Converts a <see cref="KeyCode"/> to a <see cref="Rune"/>. Useful for determining if a key represents is a
  270. /// printable character.
  271. /// </summary>
  272. /// <remarks>
  273. /// <para>Keys with Ctrl or Alt modifiers will return <see langword="default"/>.</para>
  274. /// <para>
  275. /// If the key is a letter key (A-Z), the Rune will be the upper or lower case letter depending on whether
  276. /// <see cref="KeyCode.ShiftMask"/> is set.
  277. /// </para>
  278. /// <para>
  279. /// If the key is outside of the <see cref="KeyCode.CharMask"/> range, the returned Rune will be
  280. /// <see langword="default"/>.
  281. /// </para>
  282. /// </remarks>
  283. /// <param name="key"></param>
  284. /// <returns>The key converted to a Rune. <see langword="default"/> if conversion is not possible.</returns>
  285. public static Rune ToRune (KeyCode key)
  286. {
  287. if (key is KeyCode.Null or KeyCode.SpecialMask
  288. || key.HasFlag (KeyCode.CtrlMask)
  289. || key.HasFlag (KeyCode.AltMask))
  290. {
  291. return default (Rune);
  292. }
  293. // Extract the base key code
  294. KeyCode baseKey = key;
  295. if (baseKey.HasFlag (KeyCode.ShiftMask))
  296. {
  297. baseKey &= ~KeyCode.ShiftMask;
  298. }
  299. switch (baseKey)
  300. {
  301. case >= KeyCode.A and <= KeyCode.Z when !key.HasFlag (KeyCode.ShiftMask):
  302. return new ((uint)(baseKey + 32));
  303. case >= KeyCode.A and <= KeyCode.Z when key.HasFlag (KeyCode.ShiftMask):
  304. return new ((uint)baseKey);
  305. case > KeyCode.Null and < KeyCode.A:
  306. return new ((uint)baseKey);
  307. }
  308. if (Enum.IsDefined (typeof (KeyCode), baseKey))
  309. {
  310. return default (Rune);
  311. }
  312. return new ((uint)baseKey);
  313. }
  314. #region Operators
  315. /// <summary>
  316. /// Explicitly cast a <see cref="Key"/> to a <see cref="Rune"/>. The conversion is lossy because properties such
  317. /// as <see cref="Handled"/> are not encoded in <see cref="KeyCode"/>.
  318. /// </summary>
  319. /// <remarks>Uses <see cref="AsRune"/>.</remarks>
  320. /// <param name="kea"></param>
  321. public static explicit operator Rune (Key kea) { return kea.AsRune; }
  322. // BUGBUG: (Tig) I do not think this cast operator is really needed.
  323. /// <summary>
  324. /// Explicitly cast <see cref="Key"/> to a <see langword="uint"/>. The conversion is lossy because properties such
  325. /// as <see cref="Handled"/> are not encoded in <see cref="KeyCode"/>.
  326. /// </summary>
  327. /// <param name="kea"></param>
  328. public static explicit operator uint (Key kea) { return (uint)kea.KeyCode; }
  329. /// <summary>
  330. /// Explicitly cast <see cref="Key"/> to a <see cref="KeyCode"/>. The conversion is lossy because properties such
  331. /// as <see cref="Handled"/> are not encoded in <see cref="KeyCode"/>.
  332. /// </summary>
  333. /// <param name="key"></param>
  334. public static explicit operator KeyCode (Key key) { return key.KeyCode; }
  335. /// <summary>Cast <see cref="KeyCode"/> to a <see cref="Key"/>.</summary>
  336. /// <param name="keyCode"></param>
  337. public static implicit operator Key (KeyCode keyCode) { return new (keyCode); }
  338. /// <summary>Cast <see langword="char"/> to a <see cref="Key"/>.</summary>
  339. /// <remarks>See <see cref="Key(char)"/> for more information.</remarks>
  340. /// <param name="ch"></param>
  341. public static implicit operator Key (char ch) { return new (ch); }
  342. /// <summary>Cast <see langword="string"/> to a <see cref="Key"/>.</summary>
  343. /// <remarks>See <see cref="Key(string)"/> for more information.</remarks>
  344. /// <param name="str"></param>
  345. public static implicit operator Key (string str) { return new (str); }
  346. /// <summary>Cast a <see cref="Key"/> to a <see langword="string"/>.</summary>
  347. /// <remarks>See <see cref="Key(string)"/> for more information.</remarks>
  348. /// <param name="key"></param>
  349. public static implicit operator string (Key key) { return key.ToString (); }
  350. /// <inheritdoc/>
  351. public override bool Equals (object obj)
  352. {
  353. if (obj is Key other)
  354. {
  355. return other._keyCode == _keyCode && other.Handled == Handled;
  356. }
  357. return false;
  358. }
  359. bool IEquatable<Key>.Equals (Key other) { return Equals (other); }
  360. /// <inheritdoc/>
  361. public override int GetHashCode () { return _keyCode.GetHashCode (); }
  362. /// <summary>Compares two <see cref="Key"/>s for equality.</summary>
  363. /// <param name="a"></param>
  364. /// <param name="b"></param>
  365. /// <returns></returns>
  366. public static bool operator == (Key a, Key b) { return a!.Equals (b); }
  367. /// <summary>Compares two <see cref="Key"/>s for not equality.</summary>
  368. /// <param name="a"></param>
  369. /// <param name="b"></param>
  370. /// <returns></returns>
  371. public static bool operator != (Key a, Key b) { return !a!.Equals (b); }
  372. /// <summary>Compares two <see cref="Key"/>s for less-than.</summary>
  373. /// <param name="a"></param>
  374. /// <param name="b"></param>
  375. /// <returns></returns>
  376. public static bool operator < (Key a, Key b) { return a?.KeyCode < b?.KeyCode; }
  377. /// <summary>Compares two <see cref="Key"/>s for greater-than.</summary>
  378. /// <param name="a"></param>
  379. /// <param name="b"></param>
  380. /// <returns></returns>
  381. public static bool operator > (Key a, Key b) { return a?.KeyCode > b?.KeyCode; }
  382. /// <summary>Compares two <see cref="Key"/>s for greater-than-or-equal-to.</summary>
  383. /// <param name="a"></param>
  384. /// <param name="b"></param>
  385. /// <returns></returns>
  386. public static bool operator <= (Key a, Key b) { return a?.KeyCode <= b?.KeyCode; }
  387. /// <summary>Compares two <see cref="Key"/>s for greater-than-or-equal-to.</summary>
  388. /// <param name="a"></param>
  389. /// <param name="b"></param>
  390. /// <returns></returns>
  391. public static bool operator >= (Key a, Key b) { return a?.KeyCode >= b?.KeyCode; }
  392. #endregion Operators
  393. #region String conversion
  394. /// <summary>Pretty prints the Key.</summary>
  395. /// <returns></returns>
  396. public override string ToString () { return ToString (KeyCode, Separator); }
  397. private static string GetKeyString (KeyCode key)
  398. {
  399. if (key is KeyCode.Null or KeyCode.SpecialMask)
  400. {
  401. return string.Empty;
  402. }
  403. // Extract the base key (removing modifier flags)
  404. KeyCode baseKey = key & ~KeyCode.CtrlMask & ~KeyCode.AltMask & ~KeyCode.ShiftMask;
  405. if (!key.HasFlag (KeyCode.ShiftMask) && baseKey is >= KeyCode.A and <= KeyCode.Z)
  406. {
  407. return ((Rune)(uint)(key + 32)).ToString ();
  408. }
  409. if (key is > KeyCode.Space and < KeyCode.A)
  410. {
  411. return ((Rune)(uint)key).ToString ();
  412. }
  413. string keyName = Enum.GetName (typeof (KeyCode), key);
  414. return !string.IsNullOrEmpty (keyName) ? keyName : ((Rune)(uint)key).ToString ();
  415. }
  416. /// <summary>Formats a <see cref="KeyCode"/> as a string using the default separator of '+'</summary>
  417. /// <param name="key">The key to format.</param>
  418. /// <returns>
  419. /// The formatted string. If the key is a printable character, it will be returned as a string. Otherwise, the key
  420. /// name will be returned.
  421. /// </returns>
  422. public static string ToString (KeyCode key) { return ToString (key, Separator); }
  423. /// <summary>Formats a <see cref="KeyCode"/> as a string.</summary>
  424. /// <param name="key">The key to format.</param>
  425. /// <param name="separator">The character to use as a separator between modifier keys and the key itself.</param>
  426. /// <returns>
  427. /// The formatted string. If the key is a printable character, it will be returned as a string. Otherwise, the key
  428. /// name will be returned.
  429. /// </returns>
  430. public static string ToString (KeyCode key, Rune separator)
  431. {
  432. if (key is KeyCode.Null)
  433. {
  434. // Same as Key.IsValid
  435. return @"Null";
  436. }
  437. var sb = new StringBuilder ();
  438. // Extract the base key (removing modifier flags)
  439. KeyCode baseKey = key & ~KeyCode.CtrlMask & ~KeyCode.AltMask & ~KeyCode.ShiftMask;
  440. // Extract and handle modifiers
  441. var hasModifiers = false;
  442. if ((key & KeyCode.CtrlMask) != 0)
  443. {
  444. sb.Append ($"Ctrl{separator}");
  445. hasModifiers = true;
  446. }
  447. if ((key & KeyCode.AltMask) != 0)
  448. {
  449. sb.Append ($"Alt{separator}");
  450. hasModifiers = true;
  451. }
  452. if ((key & KeyCode.ShiftMask) != 0 && !GetIsKeyCodeAtoZ (key))
  453. {
  454. sb.Append ($"Shift{separator}");
  455. hasModifiers = true;
  456. }
  457. // Handle special cases and modifiers on their own
  458. if (key != KeyCode.SpecialMask && (baseKey != KeyCode.Null || hasModifiers))
  459. {
  460. if ((key & KeyCode.SpecialMask) != 0 && (baseKey & ~KeyCode.Space) is >= KeyCode.A and <= KeyCode.Z)
  461. {
  462. sb.Append (baseKey & ~KeyCode.Space);
  463. }
  464. else
  465. {
  466. // Append the actual key name
  467. sb.Append (GetKeyString (baseKey));
  468. }
  469. }
  470. return TrimEndSeparator (sb.ToString (), separator);
  471. }
  472. private static string TrimEndSeparator (string input, Rune separator)
  473. {
  474. // Trim the trailing separator (+). Unless there are two separators at the end.
  475. // "+" (don't trim)
  476. // "Ctrl+" (trim)
  477. // "Ctrl++" (trim)
  478. if (input.Length > 1 && new Rune (input [^1]) == separator && new Rune (input [^2]) != separator)
  479. {
  480. return input [..^1];
  481. }
  482. return input;
  483. }
  484. private static readonly Dictionary<string, KeyCode> _modifierDict =
  485. new (StringComparer.InvariantCultureIgnoreCase)
  486. {
  487. { "Shift", KeyCode.ShiftMask }, { "Ctrl", KeyCode.CtrlMask }, { "Alt", KeyCode.AltMask }
  488. };
  489. /// <summary>Converts the provided string to a new <see cref="Key"/> instance.</summary>
  490. /// <param name="text">
  491. /// The text to analyze. Formats supported are "Ctrl+X", "Alt+X", "Shift+X", "Ctrl+Alt+X",
  492. /// "Ctrl+Shift+X", "Alt+Shift+X", "Ctrl+Alt+Shift+X", "X", and "120" (Unicode codepoint).
  493. /// <para>
  494. /// The separator can be any character, not just <see cref="Key.Separator"/> (e.g. "Ctrl@Alt@X").
  495. /// </para>
  496. /// </param>
  497. /// <param name="key">The parsed value.</param>
  498. /// <returns>A boolean value indicating whether parsing was successful.</returns>
  499. /// <remarks></remarks>
  500. public static bool TryParse (string text, [NotNullWhen (true)] out Key key)
  501. {
  502. if (string.IsNullOrEmpty (text))
  503. {
  504. key = Empty;
  505. return true;
  506. }
  507. switch (text)
  508. {
  509. case "Ctrl":
  510. key = KeyCode.CtrlMask;
  511. return true;
  512. case "Alt":
  513. key = KeyCode.AltMask;
  514. return true;
  515. case "Shift":
  516. key = KeyCode.ShiftMask;
  517. return true;
  518. }
  519. key = null;
  520. Rune separator = Separator;
  521. // Perhaps the separator was written using a different Key.Separator? Does the string
  522. // start with "Ctrl", "Alt" or "Shift"? If so, get the char after the modifier string and use that as the separator.
  523. if (text.StartsWith ("Ctrl", StringComparison.InvariantCultureIgnoreCase))
  524. {
  525. separator = (Rune)text [4];
  526. }
  527. else if (text.StartsWith ("Alt", StringComparison.InvariantCultureIgnoreCase))
  528. {
  529. separator = (Rune)text [3];
  530. }
  531. else if (text.StartsWith ("Shift", StringComparison.InvariantCultureIgnoreCase))
  532. {
  533. separator = (Rune)text [5];
  534. }
  535. else if (text.EndsWith ("Ctrl", StringComparison.InvariantCultureIgnoreCase))
  536. {
  537. separator = (Rune)text [^5];
  538. }
  539. else if (text.EndsWith ("Alt", StringComparison.InvariantCultureIgnoreCase))
  540. {
  541. separator = (Rune)text [^4];
  542. }
  543. else if (text.EndsWith ("Shift", StringComparison.InvariantCultureIgnoreCase))
  544. {
  545. separator = (Rune)text [^6];
  546. }
  547. // Split the string into parts using the set Separator
  548. string [] parts = text.Split ((char)separator.Value);
  549. if (parts.Length is > 4)
  550. {
  551. // Invalid
  552. return false;
  553. }
  554. // e.g. "Ctrl++"
  555. if ((Rune)text [^1] != separator && parts.Any (string.IsNullOrEmpty))
  556. {
  557. // Invalid
  558. return false;
  559. }
  560. if ((Rune)text [^1] == separator)
  561. {
  562. parts [^1] = separator.Value.ToString ();
  563. key = (char)separator.Value;
  564. }
  565. if (separator != Separator && (parts.Length is 1 || (key is { } && parts.Length is 2)))
  566. {
  567. parts = text.Split ((char)separator.Value);
  568. if (parts.Length is 0 or > 4 || parts.Any (string.IsNullOrEmpty))
  569. {
  570. // Invalid
  571. return false;
  572. }
  573. }
  574. var modifiers = KeyCode.Null;
  575. for (var index = 0; index < parts.Length; index++)
  576. {
  577. if (_modifierDict.TryGetValue (parts [index].ToLowerInvariant (), out KeyCode modifier))
  578. {
  579. modifiers |= modifier;
  580. parts [index] = string.Empty; // eat it
  581. }
  582. }
  583. // we now have the modifiers
  584. string partNotFound = parts.FirstOrDefault (p => !string.IsNullOrEmpty (p), string.Empty);
  585. var parsedKeyCode = KeyCode.Null;
  586. var parsedInt = 0;
  587. if (partNotFound.Length == 1)
  588. {
  589. var keyCode = (KeyCode)partNotFound [0];
  590. // if it's a single digit int, treat it as such
  591. if (int.TryParse (
  592. partNotFound,
  593. NumberStyles.Integer,
  594. CultureInfo.InvariantCulture,
  595. out parsedInt
  596. ))
  597. {
  598. keyCode = (KeyCode)((int)KeyCode.D0 + parsedInt);
  599. }
  600. else if (Enum.TryParse (partNotFound, false, out parsedKeyCode))
  601. {
  602. if (parsedKeyCode != KeyCode.Null)
  603. {
  604. if (parsedKeyCode is >= KeyCode.A and <= KeyCode.Z && modifiers == 0)
  605. {
  606. key = new (parsedKeyCode | KeyCode.ShiftMask);
  607. return true;
  608. }
  609. key = new (parsedKeyCode | modifiers);
  610. return true;
  611. }
  612. }
  613. if (GetIsKeyCodeAtoZ (keyCode) && (keyCode & KeyCode.Space) != 0)
  614. {
  615. keyCode &= ~KeyCode.Space;
  616. }
  617. key = new (keyCode | modifiers);
  618. return true;
  619. }
  620. if (Enum.TryParse (partNotFound, true, out parsedKeyCode))
  621. {
  622. if (parsedKeyCode != KeyCode.Null)
  623. {
  624. if (parsedKeyCode is >= KeyCode.A and <= KeyCode.Z && modifiers == 0)
  625. {
  626. key = new (parsedKeyCode | KeyCode.ShiftMask);
  627. return true;
  628. }
  629. if (GetIsKeyCodeAtoZ (parsedKeyCode) && (parsedKeyCode & KeyCode.Space) != 0)
  630. {
  631. parsedKeyCode = parsedKeyCode & ~KeyCode.Space;
  632. }
  633. key = new (parsedKeyCode | modifiers);
  634. return true;
  635. }
  636. }
  637. // if it's a number int, treat it as a unicode value
  638. if (int.TryParse (
  639. partNotFound,
  640. NumberStyles.Number,
  641. CultureInfo.InvariantCulture,
  642. out parsedInt
  643. ))
  644. {
  645. if (!Rune.IsValid (parsedInt))
  646. {
  647. return false;
  648. }
  649. if ((KeyCode)parsedInt is >= KeyCode.A and <= KeyCode.Z && modifiers == 0)
  650. {
  651. key = new ((KeyCode)parsedInt | KeyCode.ShiftMask);
  652. return true;
  653. }
  654. key = new ((KeyCode)parsedInt);
  655. return true;
  656. }
  657. if (!Enum.TryParse (partNotFound, true, out parsedKeyCode))
  658. {
  659. return false;
  660. }
  661. if (GetIsKeyCodeAtoZ (parsedKeyCode))
  662. {
  663. key = new (parsedKeyCode | (modifiers & ~KeyCode.Space));
  664. return true;
  665. }
  666. return false;
  667. }
  668. #endregion
  669. #region Standard Key Definitions
  670. /// <summary>An uninitialized The <see cref="Key"/> object.</summary>
  671. public new static Key Empty => new ();
  672. /// <summary>The <see cref="Key"/> object for the Backspace key.</summary>
  673. public static Key Backspace => new (KeyCode.Backspace);
  674. /// <summary>The <see cref="Key"/> object for the tab key (forwards tab key).</summary>
  675. public static Key Tab => new (KeyCode.Tab);
  676. /// <summary>The <see cref="Key"/> object for the return key.</summary>
  677. public static Key Enter => new (KeyCode.Enter);
  678. /// <summary>The <see cref="Key"/> object for the clear key.</summary>
  679. public static Key Clear => new (KeyCode.Clear);
  680. /// <summary>The <see cref="Key"/> object for the Escape key.</summary>
  681. public static Key Esc => new (KeyCode.Esc);
  682. /// <summary>The <see cref="Key"/> object for the Space bar key.</summary>
  683. public static Key Space => new (KeyCode.Space);
  684. /// <summary>The <see cref="Key"/> object for 0 key.</summary>
  685. public static Key D0 => new (KeyCode.D0);
  686. /// <summary>The <see cref="Key"/> object for 1 key.</summary>
  687. public static Key D1 => new (KeyCode.D1);
  688. /// <summary>The <see cref="Key"/> object for 2 key.</summary>
  689. public static Key D2 => new (KeyCode.D2);
  690. /// <summary>The <see cref="Key"/> object for 3 key.</summary>
  691. public static Key D3 => new (KeyCode.D3);
  692. /// <summary>The <see cref="Key"/> object for 4 key.</summary>
  693. public static Key D4 => new (KeyCode.D4);
  694. /// <summary>The <see cref="Key"/> object for 5 key.</summary>
  695. public static Key D5 => new (KeyCode.D5);
  696. /// <summary>The <see cref="Key"/> object for 6 key.</summary>
  697. public static Key D6 => new (KeyCode.D6);
  698. /// <summary>The <see cref="Key"/> object for 7 key.</summary>
  699. public static Key D7 => new (KeyCode.D7);
  700. /// <summary>The <see cref="Key"/> object for 8 key.</summary>
  701. public static Key D8 => new (KeyCode.D8);
  702. /// <summary>The <see cref="Key"/> object for 9 key.</summary>
  703. public static Key D9 => new (KeyCode.D9);
  704. /// <summary>The <see cref="Key"/> object for the A key (un-shifted). Use <c>Key.A.WithShift</c> for uppercase 'A'.</summary>
  705. public static Key A => new (KeyCode.A);
  706. /// <summary>The <see cref="Key"/> object for the B key (un-shifted). Use <c>Key.B.WithShift</c> for uppercase 'B'.</summary>
  707. public static Key B => new (KeyCode.B);
  708. /// <summary>The <see cref="Key"/> object for the C key (un-shifted). Use <c>Key.C.WithShift</c> for uppercase 'C'.</summary>
  709. public static Key C => new (KeyCode.C);
  710. /// <summary>The <see cref="Key"/> object for the D key (un-shifted). Use <c>Key.D.WithShift</c> for uppercase 'D'.</summary>
  711. public static Key D => new (KeyCode.D);
  712. /// <summary>The <see cref="Key"/> object for the E key (un-shifted). Use <c>Key.E.WithShift</c> for uppercase 'E'.</summary>
  713. public static Key E => new (KeyCode.E);
  714. /// <summary>The <see cref="Key"/> object for the F key (un-shifted). Use <c>Key.F.WithShift</c> for uppercase 'F'.</summary>
  715. public static Key F => new (KeyCode.F);
  716. /// <summary>The <see cref="Key"/> object for the G key (un-shifted). Use <c>Key.G.WithShift</c> for uppercase 'G'.</summary>
  717. public static Key G => new (KeyCode.G);
  718. /// <summary>The <see cref="Key"/> object for the H key (un-shifted). Use <c>Key.H.WithShift</c> for uppercase 'H'.</summary>
  719. public static Key H => new (KeyCode.H);
  720. /// <summary>The <see cref="Key"/> object for the I key (un-shifted). Use <c>Key.I.WithShift</c> for uppercase 'I'.</summary>
  721. public static Key I => new (KeyCode.I);
  722. /// <summary>The <see cref="Key"/> object for the J key (un-shifted). Use <c>Key.J.WithShift</c> for uppercase 'J'.</summary>
  723. public static Key J => new (KeyCode.J);
  724. /// <summary>The <see cref="Key"/> object for the K key (un-shifted). Use <c>Key.K.WithShift</c> for uppercase 'K'.</summary>
  725. public static Key K => new (KeyCode.K);
  726. /// <summary>The <see cref="Key"/> object for the L key (un-shifted). Use <c>Key.L.WithShift</c> for uppercase 'L'.</summary>
  727. public static Key L => new (KeyCode.L);
  728. /// <summary>The <see cref="Key"/> object for the M key (un-shifted). Use <c>Key.M.WithShift</c> for uppercase 'M'.</summary>
  729. public static Key M => new (KeyCode.M);
  730. /// <summary>The <see cref="Key"/> object for the N key (un-shifted). Use <c>Key.N.WithShift</c> for uppercase 'N'.</summary>
  731. public static Key N => new (KeyCode.N);
  732. /// <summary>The <see cref="Key"/> object for the O key (un-shifted). Use <c>Key.O.WithShift</c> for uppercase 'O'.</summary>
  733. public static Key O => new (KeyCode.O);
  734. /// <summary>The <see cref="Key"/> object for the P key (un-shifted). Use <c>Key.P.WithShift</c> for uppercase 'P'.</summary>
  735. public static Key P => new (KeyCode.P);
  736. /// <summary>The <see cref="Key"/> object for the Q key (un-shifted). Use <c>Key.Q.WithShift</c> for uppercase 'Q'.</summary>
  737. public static Key Q => new (KeyCode.Q);
  738. /// <summary>The <see cref="Key"/> object for the R key (un-shifted). Use <c>Key.R.WithShift</c> for uppercase 'R'.</summary>
  739. public static Key R => new (KeyCode.R);
  740. /// <summary>The <see cref="Key"/> object for the S key (un-shifted). Use <c>Key.S.WithShift</c> for uppercase 'S'.</summary>
  741. public static Key S => new (KeyCode.S);
  742. /// <summary>The <see cref="Key"/> object for the T key (un-shifted). Use <c>Key.T.WithShift</c> for uppercase 'T'.</summary>
  743. public static Key T => new (KeyCode.T);
  744. /// <summary>The <see cref="Key"/> object for the U key (un-shifted). Use <c>Key.U.WithShift</c> for uppercase 'U'.</summary>
  745. public static Key U => new (KeyCode.U);
  746. /// <summary>The <see cref="Key"/> object for the V key (un-shifted). Use <c>Key.V.WithShift</c> for uppercase 'V'.</summary>
  747. public static Key V => new (KeyCode.V);
  748. /// <summary>The <see cref="Key"/> object for the W key (un-shifted). Use <c>Key.W.WithShift</c> for uppercase 'W'.</summary>
  749. public static Key W => new (KeyCode.W);
  750. /// <summary>The <see cref="Key"/> object for the X key (un-shifted). Use <c>Key.X.WithShift</c> for uppercase 'X'.</summary>
  751. public static Key X => new (KeyCode.X);
  752. /// <summary>The <see cref="Key"/> object for the Y key (un-shifted). Use <c>Key.Y.WithShift</c> for uppercase 'Y'.</summary>
  753. public static Key Y => new (KeyCode.Y);
  754. /// <summary>The <see cref="Key"/> object for the Z key (un-shifted). Use <c>Key.Z.WithShift</c> for uppercase 'Z'.</summary>
  755. public static Key Z => new (KeyCode.Z);
  756. /// <summary>The <see cref="Key"/> object for the Delete key.</summary>
  757. public static Key Delete => new (KeyCode.Delete);
  758. /// <summary>The <see cref="Key"/> object for the Cursor up key.</summary>
  759. public static Key CursorUp => new (KeyCode.CursorUp);
  760. /// <summary>The <see cref="Key"/> object for Cursor down key.</summary>
  761. public static Key CursorDown => new (KeyCode.CursorDown);
  762. /// <summary>The <see cref="Key"/> object for Cursor left key.</summary>
  763. public static Key CursorLeft => new (KeyCode.CursorLeft);
  764. /// <summary>The <see cref="Key"/> object for Cursor right key.</summary>
  765. public static Key CursorRight => new (KeyCode.CursorRight);
  766. /// <summary>The <see cref="Key"/> object for Page Up key.</summary>
  767. public static Key PageUp => new (KeyCode.PageUp);
  768. /// <summary>The <see cref="Key"/> object for Page Down key.</summary>
  769. public static Key PageDown => new (KeyCode.PageDown);
  770. /// <summary>The <see cref="Key"/> object for Home key.</summary>
  771. public static Key Home => new (KeyCode.Home);
  772. /// <summary>The <see cref="Key"/> object for End key.</summary>
  773. public static Key End => new (KeyCode.End);
  774. /// <summary>The <see cref="Key"/> object for Insert Character key.</summary>
  775. public static Key InsertChar => new (KeyCode.Insert);
  776. /// <summary>The <see cref="Key"/> object for Delete Character key.</summary>
  777. public static Key DeleteChar => new (KeyCode.Delete);
  778. /// <summary>The <see cref="Key"/> object for Print Screen key.</summary>
  779. public static Key PrintScreen => new (KeyCode.PrintScreen);
  780. /// <summary>The <see cref="Key"/> object for F1 key.</summary>
  781. public static Key F1 => new (KeyCode.F1);
  782. /// <summary>The <see cref="Key"/> object for F2 key.</summary>
  783. public static Key F2 => new (KeyCode.F2);
  784. /// <summary>The <see cref="Key"/> object for F3 key.</summary>
  785. public static Key F3 => new (KeyCode.F3);
  786. /// <summary>The <see cref="Key"/> object for F4 key.</summary>
  787. public static Key F4 => new (KeyCode.F4);
  788. /// <summary>The <see cref="Key"/> object for F5 key.</summary>
  789. public static Key F5 => new (KeyCode.F5);
  790. /// <summary>The <see cref="Key"/> object for F6 key.</summary>
  791. public static Key F6 => new (KeyCode.F6);
  792. /// <summary>The <see cref="Key"/> object for F7 key.</summary>
  793. public static Key F7 => new (KeyCode.F7);
  794. /// <summary>The <see cref="Key"/> object for F8 key.</summary>
  795. public static Key F8 => new (KeyCode.F8);
  796. /// <summary>The <see cref="Key"/> object for F9 key.</summary>
  797. public static Key F9 => new (KeyCode.F9);
  798. /// <summary>The <see cref="Key"/> object for F10 key.</summary>
  799. public static Key F10 => new (KeyCode.F10);
  800. /// <summary>The <see cref="Key"/> object for F11 key.</summary>
  801. public static Key F11 => new (KeyCode.F11);
  802. /// <summary>The <see cref="Key"/> object for F12 key.</summary>
  803. public static Key F12 => new (KeyCode.F12);
  804. /// <summary>The <see cref="Key"/> object for F13 key.</summary>
  805. public static Key F13 => new (KeyCode.F13);
  806. /// <summary>The <see cref="Key"/> object for F14 key.</summary>
  807. public static Key F14 => new (KeyCode.F14);
  808. /// <summary>The <see cref="Key"/> object for F15 key.</summary>
  809. public static Key F15 => new (KeyCode.F15);
  810. /// <summary>The <see cref="Key"/> object for F16 key.</summary>
  811. public static Key F16 => new (KeyCode.F16);
  812. /// <summary>The <see cref="Key"/> object for F17 key.</summary>
  813. public static Key F17 => new (KeyCode.F17);
  814. /// <summary>The <see cref="Key"/> object for F18 key.</summary>
  815. public static Key F18 => new (KeyCode.F18);
  816. /// <summary>The <see cref="Key"/> object for F19 key.</summary>
  817. public static Key F19 => new (KeyCode.F19);
  818. /// <summary>The <see cref="Key"/> object for F20 key.</summary>
  819. public static Key F20 => new (KeyCode.F20);
  820. /// <summary>The <see cref="Key"/> object for F21 key.</summary>
  821. public static Key F21 => new (KeyCode.F21);
  822. /// <summary>The <see cref="Key"/> object for F22 key.</summary>
  823. public static Key F22 => new (KeyCode.F22);
  824. /// <summary>The <see cref="Key"/> object for F23 key.</summary>
  825. public static Key F23 => new (KeyCode.F23);
  826. /// <summary>The <see cref="Key"/> object for F24 key.</summary>
  827. public static Key F24 => new (KeyCode.F24);
  828. #endregion
  829. private static Rune _separator = new ('+');
  830. /// <summary>Gets or sets the separator character used when parsing and printing Keys. E.g. Ctrl+A. The default is '+'.</summary>
  831. [SerializableConfigurationProperty (Scope = typeof (SettingsScope))]
  832. public static Rune Separator
  833. {
  834. get => _separator;
  835. set
  836. {
  837. if (_separator != value)
  838. {
  839. _separator = value == default (Rune) ? new ('+') : value;
  840. }
  841. }
  842. }
  843. }