KeyBinding struct

Namespace: Arlecchino.Input · Assembly: Arlecchino.Core

A key plus the exact modifiers that must be held with it, so Ctrl+S never fires on a bare S. It is added to with KeyBinding.AddAlternative and turned into a chord with KeyBinding.ThenKey.

public readonly struct KeyBinding : IEquatable<KeyBinding>

Implements IEquatable<T><KeyBinding>

Constructors

Member	Summary
KeyBinding(char)	A binding on a character rather than on a key, which is the only dependable way to name punctuation. It answers wherever that character can be typed, and the key screen writes the character itself.
KeyBinding(ConsoleKey, KeyModifiers)	A key plus the exact modifiers that must be held with it, so Ctrl+S never fires on a bare S. It is added to with KeyBinding.AddAlternative and turned into a chord with KeyBinding.ThenKey.

Properties

Member	Summary
Alternatives	The other combinations that trigger the same thing, in the order they were added. They are matched but never written, and each is a single press even where the binding itself is a chord.
Character	The character this binding answers to, or '\0' when it is a binding on a key.
First	The combination the binding is named after, and the one it is written from.
IsChord	Whether this takes two keystrokes rather than one. A chord spends one combination on a leader and hands back the whole alphabet behind it, which is how an application reaches past what a terminal gives it.
IsNone	Whether this binding is unset and therefore matches nothing.
Key	The key itself.
Modifiers	Modifiers that must be held, exactly.
Second	The keystroke that finishes a chord, or null when the binding is one press.

Methods

Member	Summary
AddAlternative(ConsoleKey, KeyModifiers)	The same binding, with one more combination that triggers it, for the habits platforms disagree about. Call it as often as there are habits.
Closes(KeyPress)	Whether a key press is the second half of this chord.
Deconstruct(out ConsoleKey, out KeyModifiers)
Equals(KeyBinding)	Whether two bindings stand for the same keys. The alternatives count and so does their order, since that is the order they are matched in.
GetHashCode()	A hash over the same keystrokes equality compares.
Matches(KeyPress)	Whether one key press is this whole binding. The combination it is named after counts only when the binding is one keystroke, since a chord is opened rather than matched; an alternative counts either way.
Opens(KeyPress)	Whether a key press is the first half of this chord. A binding of one keystroke opens nothing: it either matches or it does not.
Replacing(KeyModifiers, KeyModifiers)	The same binding with one modifier put in place of another, wherever it appears. It is how an application moves off a modifier its users cannot press.
ThenKey(ConsoleKey, KeyModifiers)	The same binding, finished by a second keystroke pressed after the first one is let go. A binding gets one finishing key, so calling this twice replaces it rather than growing a third keystroke.
ToString()	How the binding is shown to the user — Ctrl+S, Alt+←, Esc. A chord is written as its two keystrokes with a space between them, Ctrl+X T.

Constructors in detail

KeyBinding(char)

public KeyBinding(char character);

A binding on a character rather than on a key, which is the only dependable way to name punctuation. It answers wherever that character can be typed, and the key screen writes the character itself.

Parameters

Name	Type	Description
character	char	The character to answer to.

KeyBinding(ConsoleKey, KeyModifiers)

public KeyBinding(ConsoleKey Key, KeyModifiers Modifiers = None);

A key plus the exact modifiers that must be held with it, so Ctrl+S never fires on a bare S. It is added to with KeyBinding.AddAlternative and turned into a chord with KeyBinding.ThenKey.

Parameters

Name	Type	Description
Key	ConsoleKey	The key itself.
Modifiers	KeyModifiers	Modifiers that must be held, exactly.

Properties in detail

Alternatives

public IReadOnlyList<KeyStroke> Alternatives { get; }

The other combinations that trigger the same thing, in the order they were added. They are matched but never written, and each is a single press even where the binding itself is a chord.

Type IReadOnlyList<T><KeyStroke>

Character

public char Character { get; }

The character this binding answers to, or '\0' when it is a binding on a key.

Type char

First

public KeyStroke First { get; }

The combination the binding is named after, and the one it is written from.

Type KeyStroke

IsChord

public bool IsChord { get; }

Whether this takes two keystrokes rather than one. A chord spends one combination on a leader and hands back the whole alphabet behind it, which is how an application reaches past what a terminal gives it.

Type bool

IsNone

public bool IsNone { get; }

Whether this binding is unset and therefore matches nothing.

Type bool

Key

public ConsoleKey Key { get; init; }

The key itself.

Type ConsoleKey

Modifiers

public KeyModifiers Modifiers { get; init; }

Modifiers that must be held, exactly.

Type KeyModifiers

Second

public Nullable<KeyStroke> Second { get; }

The keystroke that finishes a chord, or null when the binding is one press.

Type Nullable<T><KeyStroke>

Methods in detail

AddAlternative(ConsoleKey, KeyModifiers)

public KeyBinding AddAlternative(ConsoleKey key, KeyModifiers modifiers = None);

The same binding, with one more combination that triggers it, for the habits platforms disagree about. Call it as often as there are habits.

Parameters

Name	Type	Description
key	ConsoleKey	The key of the added combination.
modifiers	KeyModifiers	Modifiers that must be held with it, exactly.

Returns KeyBinding — The binding, with the combination added after the ones already there.

Closes(KeyPress)

public bool Closes(KeyPress press);

Whether a key press is the second half of this chord.

Parameters

Name	Type	Description
press	KeyPress	The key that was pressed.

Returns bool — true when the chord is complete.

Deconstruct(out ConsoleKey, out KeyModifiers)

public void Deconstruct(out ConsoleKey Key, out KeyModifiers Modifiers);

Parameters

Name	Type	Description
Key	ConsoleKey
Modifiers	KeyModifiers

Equals(KeyBinding)

public bool Equals(KeyBinding other);

Whether two bindings stand for the same keys. The alternatives count and so does their order, since that is the order they are matched in.

Parameters

Name	Type	Description
other	KeyBinding	The binding to compare with.

Returns bool — true when both are made of the same keystrokes.

GetHashCode()

public override int GetHashCode();

A hash over the same keystrokes equality compares.

Returns int — The hash code.

Matches(KeyPress)

public bool Matches(KeyPress press);

Whether one key press is this whole binding. The combination it is named after counts only when the binding is one keystroke, since a chord is opened rather than matched; an alternative counts either way.

Parameters

Name	Type	Description
press	KeyPress	The key that was pressed.

Returns bool — true when the press should trigger this binding on its own.

Opens(KeyPress)

public bool Opens(KeyPress press);

Whether a key press is the first half of this chord. A binding of one keystroke opens nothing: it either matches or it does not.

Parameters

Name	Type	Description
press	KeyPress	The key that was pressed.

Returns bool — true when the chord has been started and the next key will finish it.

Replacing(KeyModifiers, KeyModifiers)

public KeyBinding Replacing(KeyModifiers from, KeyModifiers to);

The same binding with one modifier put in place of another, wherever it appears. It is how an application moves off a modifier its users cannot press.

Parameters

Name	Type	Description
from	KeyModifiers	The modifier to take out.
to	KeyModifiers	The modifier to put in its place.

Returns KeyBinding — The rewritten binding, or this one when the modifier is not in it.

ThenKey(ConsoleKey, KeyModifiers)

public KeyBinding ThenKey(ConsoleKey key, KeyModifiers modifiers = None);

The same binding, finished by a second keystroke pressed after the first one is let go. A binding gets one finishing key, so calling this twice replaces it rather than growing a third keystroke.

Parameters

Name	Type	Description
key	ConsoleKey	The key that finishes the chord.
modifiers	KeyModifiers	Modifiers held with it, which is usually none.

Returns KeyBinding — The chord.

ToString()

public override string ToString();

How the binding is shown to the user — Ctrl+S, Alt+←, Esc. A chord is written as its two keystrokes with a space between them, Ctrl+X T.

Returns string — The readable form, or an empty string when the binding is unset.

Example

new KeyBinding(ConsoleKey.Insert, KeyModifiers.Control)
.AddAlternative(ConsoleKey.C, KeyModifiers.Control | KeyModifiers.Shift);

new KeyBinding(ConsoleKey.X, KeyModifiers.Control).ThenKey(ConsoleKey.T);