Skip to content

Commit

Permalink
API docs
Browse files Browse the repository at this point in the history
  • Loading branch information
@tig
tig committed Oct 14, 2024
1 parent bc51f88 commit 3f3ceae
Show file tree
Hide file tree
Showing 9 changed files with 211 additions and 373 deletions.
79 changes: 19 additions & 60 deletions Terminal.Gui/View/View.Keyboard.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -255,9 +255,7 @@ private void SetHotKeyFromTitle ()
/// <para>
/// If a more focused subview does not handle the key press, this method raises <see cref="OnKeyDown"/>/
/// <see cref="KeyDown"/> to allow the
/// view to pre-process the key press. If <see cref="OnKeyDown"/>/<see cref="KeyDown"/> is not handled
/// <see cref="InvokingKeyBindings"/>/<see cref="OnInvokingKeyBindings"/> will be raised to invoke any key
/// bindings.
/// view to pre-process the key press. If <see cref="OnKeyDown"/>/<see cref="KeyDown"/> is not handled any commands bound to the key will be invoked.
/// Then, only if no key bindings are
/// handled, <see cref="OnKeyDownNotHandled"/>/<see cref="KeyDownNotHandled"/> will be raised allowing the view to
/// process the key press.
Expand Down Expand Up @@ -292,8 +290,8 @@ public bool NewKeyDownEvent (Key key)

// During (this is what can be cancelled)

// TODO: NewKeyDownEvent returns bool. It should be bool? so state of RaiseInvokingKeyBindingsAndInvokeCommands can be reflected up stack
if (RaiseInvokingKeyBindingsAndInvokeCommands (key) is true || key.Handled)
// TODO: NewKeyDownEvent returns bool. It should be bool? so state of InvokeCommands can be reflected up stack
if (InvokeCommandsBoundToKey (key) is true || key.Handled)
{
return true;
}
Expand Down Expand Up @@ -336,7 +334,7 @@ bool RaiseKeyDownNotHandled (Key k)

/// <summary>
/// Called when the user presses a key, allowing subscribers to pre-process the key down event. Called
/// before <see cref="InvokingKeyBindings"/> and <see cref="KeyDownNotHandled"/> are raised. Set
/// before key bindings are invoked and <see cref="KeyDownNotHandled"/> is raised. Set
/// <see cref="Key.Handled"/>
/// to true to
/// stop the key from being processed further.
Expand All @@ -357,7 +355,7 @@ bool RaiseKeyDownNotHandled (Key k)

/// <summary>
/// Raised when the user presses a key, allowing subscribers to pre-process the key down event. Called
/// before <see cref="InvokingKeyBindings"/> and <see cref="KeyDownNotHandled"/> are raised. Set
/// before key bindings are invoked and <see cref="KeyDownNotHandled"/> is raised. Set
/// <see cref="Key.Handled"/>
/// to true to
/// stop the key from being processed further.
Expand Down Expand Up @@ -508,37 +506,21 @@ bool RaiseKeyUp (Key k)
private Dictionary<Command, CommandImplementation> CommandImplementations { get; } = new ();

/// <summary>
/// INTERNAL API: Raises the <see cref="InvokingKeyBindings"/> event and invokes the commands bound to
/// <paramref name="key"/>.
/// INTERNAL API: Invokes any commands bound to <paramref name="key"/> on this view, adornments, and subviews.
/// </summary>
/// <param name="key"></param>
/// <returns>
/// <see langword="null"/> if no command was invoked or there was no matching key binding; input processing should
/// continue.
/// <see langword="false"/> if a command was invoked and was not handled (or cancelled); input processing should
/// continue.
/// <see langword="true"/> if <see cref="InvokingKeyBindings"/> was handled or a command was invoked and handled (or
/// <see langword="true"/> if at least one command was invoked and handled (or
/// cancelled); input processing should stop.
/// </returns>
internal bool? RaiseInvokingKeyBindingsAndInvokeCommands (Key key)
internal bool? InvokeCommandsBoundToKey (Key key)
{
KeyBindingScope scope = KeyBindingScope.Focused | KeyBindingScope.HotKey;

// During
if (OnInvokingKeyBindings (key, scope))
{
return true;
}

InvokingKeyBindings?.Invoke (this, key);

if (key.Handled)
{
return true;
}

// After

// * If no key binding was found, `InvokeKeyBindings` returns `null`.
// Continue passing the event (return `false` from `OnInvokeKeyBindings`).
// * If key bindings were found, but none handled the key (all `Command`s returned `false`),
Expand All @@ -547,62 +529,39 @@ bool RaiseKeyUp (Key k)
// `InvokeKeyBindings` returns `true`. Continue passing the event (return `false` from `OnInvokeKeyBindings`).
bool? handled = InvokeCommands (key, scope);

if (handled is { } && (bool)handled)
if (handled is true)
{
// Stop processing if any key binding handled the key.
// DO NOT stop processing if there are no matching key bindings or none of the key bindings handled the key
return handled;
}

if (Margin is { } && ProcessAdornmentKeyBindings (Margin, key, scope, ref handled))
if (Margin is { } && InvokeCommandsBoundToKeyOnAdornment (Margin, key, scope, ref handled))
{
return true;
}

if (Padding is { } && ProcessAdornmentKeyBindings (Padding, key, scope, ref handled))
if (Padding is { } && InvokeCommandsBoundToKeyOnAdornment (Padding, key, scope, ref handled))
{
return true;
}

if (Border is { } && ProcessAdornmentKeyBindings (Border, key, scope, ref handled))
if (Border is { } && InvokeCommandsBoundToKeyOnAdornment (Border, key, scope, ref handled))
{
return true;
}

if (ProcessSubViewKeyBindings (key, scope, ref handled))
if (InvokeCommandsBoundToKeyOnSubviews (key, scope, ref handled))
{
return true;
}

return handled;
}

/// <summary>
/// Called when a key is pressed that may be mapped to a key binding. Set <see cref="Key.Handled"/> to true to
/// stop the key from being processed by other views.
/// </summary>
/// <remarks>
/// <para>See <see href="../docs/keyboard.md">for an overview of Terminal.Gui keyboard APIs.</see></para>
/// </remarks>
/// <param name="key">Contains the details about the key that produced the event.</param>
/// <param name="scope">The scope.</param>
/// <returns>
/// <see langword="false"/> if the event was raised and was not handled (or cancelled); input processing should
/// continue.
/// <see langword="true"/> if the event was raised and handled (or cancelled); input processing should stop.
/// </returns>
protected virtual bool OnInvokingKeyBindings (Key key, KeyBindingScope scope) { return false; }

// TODO: This does not carry KeyBindingScope, but OnInvokingKeyBindings does
/// <summary>
/// Raised when a key is pressed that may be mapped to a key binding. Set <see cref="Key.Handled"/> to true to
/// stop the key from being processed by other views.
/// </summary>
public event EventHandler<Key>? InvokingKeyBindings;

private bool ProcessAdornmentKeyBindings (Adornment adornment, Key key, KeyBindingScope scope, ref bool? handled)
private static bool InvokeCommandsBoundToKeyOnAdornment (Adornment adornment, Key key, KeyBindingScope scope, ref bool? handled)
{
bool? adornmentHandled = adornment.RaiseInvokingKeyBindingsAndInvokeCommands (key);
bool? adornmentHandled = adornment.InvokeCommandsBoundToKey (key);

if (adornmentHandled is true)
{
Expand All @@ -616,7 +575,7 @@ private bool ProcessAdornmentKeyBindings (Adornment adornment, Key key, KeyBindi

foreach (View subview in adornment.Subviews)
{
bool? subViewHandled = subview.RaiseInvokingKeyBindingsAndInvokeCommands (key);
bool? subViewHandled = subview.InvokeCommandsBoundToKey (key);

if (subViewHandled is { })
{
Expand All @@ -632,7 +591,7 @@ private bool ProcessAdornmentKeyBindings (Adornment adornment, Key key, KeyBindi
return false;
}

private bool ProcessSubViewKeyBindings (Key key, KeyBindingScope scope, ref bool? handled, bool invoke = true)
private bool InvokeCommandsBoundToKeyOnSubviews (Key key, KeyBindingScope scope, ref bool? handled, bool invoke = true)
{
// Now, process any key bindings in the subviews that are tagged to KeyBindingScope.HotKey.
foreach (View subview in Subviews)
Expand All @@ -654,7 +613,7 @@ private bool ProcessSubViewKeyBindings (Key key, KeyBindingScope scope, ref bool
return true;
}

bool? subViewHandled = subview.RaiseInvokingKeyBindingsAndInvokeCommands (key);
bool? subViewHandled = subview.InvokeCommandsBoundToKey (key);

if (subViewHandled is { })
{
Expand All @@ -667,7 +626,7 @@ private bool ProcessSubViewKeyBindings (Key key, KeyBindingScope scope, ref bool
}
}

bool recurse = subview.ProcessSubViewKeyBindings (key, scope, ref handled, invoke);
bool recurse = subview.InvokeCommandsBoundToKeyOnSubviews (key, scope, ref handled, invoke);

if (recurse || (handled is { } && (bool)handled))
{
Expand Down
2 changes: 1 addition & 1 deletion Terminal.Gui/Views/Menu/Menu.cs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -309,7 +309,7 @@ private bool ExpandCollapse (MenuItem? menuItem)
protected override bool OnKeyDownNotHandled (Key keyEvent)
{
// We didn't handle the key, pass it on to host
return _host.RaiseInvokingKeyBindingsAndInvokeCommands (keyEvent) == true;
return _host.InvokeCommandsBoundToKey (keyEvent) == true;
}

private void Current_TerminalResized (object? sender, SizeChangedEventArgs e)
Expand Down
Loading

0 comments on commit 3f3ceae

Please sign in to comment.