KeyBindings.cs 9.6 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258
  1. #nullable enable
  2. namespace Terminal.Gui;
  3. /// <summary>
  4. /// Provides a collection of <see cref="KeyBinding"/> objects bound to a <see cref="Key"/>.
  5. /// </summary>
  6. public class KeyBindings
  7. {
  8. /// <summary>
  9. /// Initializes a new instance. This constructor is used when the <see cref="KeyBindings"/> are not bound to a
  10. /// <see cref="View"/>, such as in unit tests.
  11. /// </summary>
  12. public KeyBindings () { }
  13. /// <summary>Initializes a new instance bound to <paramref name="boundView"/>.</summary>
  14. public KeyBindings (View boundView) { BoundView = boundView; }
  15. /// <summary>
  16. /// The view that the <see cref="KeyBindings"/> are bound to.
  17. /// </summary>
  18. public View? BoundView { get; }
  19. // TODO: Add a dictionary comparer that ignores Scope
  20. // TODO: This should not be public!
  21. /// <summary>The collection of <see cref="KeyBinding"/> objects.</summary>
  22. public Dictionary<Key, KeyBinding> Bindings { get; } = new ();
  23. /// <summary>Adds a <see cref="KeyBinding"/> to the collection.</summary>
  24. /// <param name="key"></param>
  25. /// <param name="binding"></param>
  26. public void Add (Key key, KeyBinding binding)
  27. {
  28. if (TryGet (key, out KeyBinding _))
  29. {
  30. Bindings [key] = binding;
  31. }
  32. else
  33. {
  34. Bindings.Add (key, binding);
  35. if (binding.Scope.FastHasFlags (KeyBindingScope.Application))
  36. {
  37. Application.AddKeyBinding (key, BoundView);
  38. }
  39. }
  40. }
  41. /// <summary>
  42. /// <para>Adds a new key combination that will trigger the commands in <paramref name="commands"/>.</para>
  43. /// <para>
  44. /// If the key is already bound to a different array of <see cref="Command"/>s it will be rebound
  45. /// <paramref name="commands"/>.
  46. /// </para>
  47. /// </summary>
  48. /// <remarks>
  49. /// Commands are only ever applied to the current <see cref="View"/> (i.e. this feature cannot be used to switch
  50. /// focus to another view and perform multiple commands there).
  51. /// </remarks>
  52. /// <param name="key">The key to check.</param>
  53. /// <param name="scope">The scope for the command.</param>
  54. /// <param name="commands">
  55. /// The command to invoked on the <see cref="View"/> when <paramref name="key"/> is pressed. When
  56. /// multiple commands are provided,they will be applied in sequence. The bound <paramref name="key"/> strike will be
  57. /// consumed if any took effect.
  58. /// </param>
  59. public void Add (Key key, KeyBindingScope scope, params Command [] commands)
  60. {
  61. if (key is null || !key.IsValid)
  62. {
  63. //throw new ArgumentException ("Invalid Key", nameof (commands));
  64. return;
  65. }
  66. if (commands.Length == 0)
  67. {
  68. throw new ArgumentException (@"At least one command must be specified", nameof (commands));
  69. }
  70. if (TryGet (key, out KeyBinding _))
  71. {
  72. Bindings [key] = new (commands, scope);
  73. }
  74. else
  75. {
  76. Add (key, new KeyBinding (commands, scope));
  77. }
  78. }
  79. /// <summary>
  80. /// <para>
  81. /// Adds a new key combination that will trigger the commands in <paramref name="commands"/> (if supported by the
  82. /// View - see <see cref="View.GetSupportedCommands"/>).
  83. /// </para>
  84. /// <para>
  85. /// This is a helper function for <see cref="Add(Key,KeyBindingScope,Terminal.Gui.Command[])"/> for
  86. /// <see cref="KeyBindingScope.Focused"/> scoped commands.
  87. /// </para>
  88. /// <para>
  89. /// If the key is already bound to a different array of <see cref="Command"/>s it will be rebound
  90. /// <paramref name="commands"/>.
  91. /// </para>
  92. /// </summary>
  93. /// <remarks>
  94. /// Commands are only ever applied to the current <see cref="View"/> (i.e. this feature cannot be used to switch
  95. /// focus to another view and perform multiple commands there).
  96. /// </remarks>
  97. /// <param name="key">The key to check.</param>
  98. /// <param name="commands">
  99. /// The command to invoked on the <see cref="View"/> when <paramref name="key"/> is pressed. When
  100. /// multiple commands are provided,they will be applied in sequence. The bound <paramref name="key"/> strike will be
  101. /// consumed if any took effect.
  102. /// </param>
  103. public void Add (Key key, params Command [] commands)
  104. {
  105. Add (key, KeyBindingScope.Focused, commands);
  106. }
  107. /// <summary>Removes all <see cref="KeyBinding"/> objects from the collection.</summary>
  108. public void Clear ()
  109. {
  110. Application.ClearKeyBindings (BoundView);
  111. Bindings.Clear ();
  112. }
  113. /// <summary>
  114. /// Removes all key bindings that trigger the given command set. Views can have multiple different keys bound to
  115. /// the same command sets and this method will clear all of them.
  116. /// </summary>
  117. /// <param name="command"></param>
  118. public void Clear (params Command [] command)
  119. {
  120. KeyValuePair<Key, KeyBinding> [] kvps = Bindings
  121. .Where (kvp => kvp.Value.Commands.SequenceEqual (command))
  122. .ToArray ();
  123. foreach (KeyValuePair<Key, KeyBinding> kvp in kvps)
  124. {
  125. Remove (kvp.Key);
  126. }
  127. }
  128. /// <summary>Gets the <see cref="KeyBinding"/> for the specified <see cref="Key"/>.</summary>
  129. /// <param name="key"></param>
  130. /// <returns></returns>
  131. public KeyBinding Get (Key key)
  132. {
  133. if (TryGet (key, out KeyBinding binding))
  134. {
  135. return binding;
  136. }
  137. throw new InvalidOperationException ($"Key {key} is not bound.");
  138. }
  139. /// <summary>Gets the <see cref="KeyBinding"/> for the specified <see cref="Key"/>.</summary>
  140. /// <param name="key"></param>
  141. /// <param name="scope"></param>
  142. /// <returns></returns>
  143. public KeyBinding Get (Key key, KeyBindingScope scope)
  144. {
  145. if (TryGet (key, scope, out KeyBinding binding))
  146. {
  147. return binding;
  148. }
  149. throw new InvalidOperationException ($"Key {key}/{scope} is not bound.");
  150. }
  151. /// <summary>Gets the array of <see cref="Command"/>s bound to <paramref name="key"/> if it exists.</summary>
  152. /// <param name="key">The key to check.</param>
  153. /// <returns>
  154. /// The array of <see cref="Command"/>s if <paramref name="key"/> is bound. An empty <see cref="Command"/> array
  155. /// if not.
  156. /// </returns>
  157. public Command [] GetCommands (Key key)
  158. {
  159. if (TryGet (key, out KeyBinding bindings))
  160. {
  161. return bindings.Commands;
  162. }
  163. return Array.Empty<Command> ();
  164. }
  165. /// <summary>Gets the Key used by a set of commands.</summary>
  166. /// <remarks></remarks>
  167. /// <param name="commands">The set of commands to search.</param>
  168. /// <returns>The <see cref="Key"/> used by a <see cref="Command"/></returns>
  169. /// <exception cref="InvalidOperationException">If no matching set of commands was found.</exception>
  170. public Key GetKeyFromCommands (params Command [] commands) { return Bindings.First (a => a.Value.Commands.SequenceEqual (commands)).Key; }
  171. /// <summary>Removes a <see cref="KeyBinding"/> from the collection.</summary>
  172. /// <param name="key"></param>
  173. public void Remove (Key key)
  174. {
  175. Bindings.Remove (key);
  176. Application.RemoveKeyBinding (key, BoundView);
  177. }
  178. /// <summary>Replaces a key combination already bound to a set of <see cref="Command"/>s.</summary>
  179. /// <remarks></remarks>
  180. /// <param name="oldKey">The key to be replaced.</param>
  181. /// <param name="newKey">The new key to be used.</param>
  182. public void Replace (Key oldKey, Key newKey)
  183. {
  184. if (!TryGet (oldKey, out KeyBinding _))
  185. {
  186. return;
  187. }
  188. KeyBinding value = Bindings [oldKey];
  189. Remove (oldKey);
  190. Add (newKey, value);
  191. }
  192. /// <summary>Gets the commands bound with the specified Key.</summary>
  193. /// <remarks></remarks>
  194. /// <param name="key">The key to check.</param>
  195. /// <param name="binding">
  196. /// When this method returns, contains the commands bound with the specified Key, if the Key is
  197. /// found; otherwise, null. This parameter is passed uninitialized.
  198. /// </param>
  199. /// <returns><see langword="true"/> if the Key is bound; otherwise <see langword="false"/>.</returns>
  200. public bool TryGet (Key key, out KeyBinding binding)
  201. {
  202. if (key.IsValid)
  203. {
  204. return Bindings.TryGetValue (key, out binding);
  205. }
  206. binding = new (Array.Empty<Command> (), KeyBindingScope.Focused);
  207. return false;
  208. }
  209. /// <summary>Gets the commands bound with the specified Key that are scoped to a particular scope.</summary>
  210. /// <remarks></remarks>
  211. /// <param name="key">The key to check.</param>
  212. /// <param name="scope">the scope to filter on</param>
  213. /// <param name="binding">
  214. /// When this method returns, contains the commands bound with the specified Key, if the Key is
  215. /// found; otherwise, null. This parameter is passed uninitialized.
  216. /// </param>
  217. /// <returns><see langword="true"/> if the Key is bound; otherwise <see langword="false"/>.</returns>
  218. public bool TryGet (Key key, KeyBindingScope scope, out KeyBinding binding)
  219. {
  220. if (key.IsValid && Bindings.TryGetValue (key, out binding))
  221. {
  222. if (scope.HasFlag (binding.Scope))
  223. {
  224. return true;
  225. }
  226. }
  227. binding = new (Array.Empty<Command> (), KeyBindingScope.Focused);
  228. return false;
  229. }
  230. }