keybinder

A utility class used to bind callbacks to a combination of one or more physical keys on a keyboard; utilizing the global [RawKeyboard] instance.

Usage

import 'package:keybinder/keybinder.dart';

KeyCodes

Keys in keybinder are represented by KeyCodes, which consist of a set of one or more key IDs, which correspond to physical or logical keyboard keys.

A KeyCode is treated as a single abstract key, in that if any of the keys in the set of key IDs representing it are pressed, the KeyCode is considered pressed.

KeyCodes can be constructed directly from a set of key IDs, or can be constructed from one or more [LogicalKeyboardKey]s and/or [PhysicalKeyboardKey]s.

/// This [KeyCode]s key IDs represent the logical left and right
/// control keys, and is considered pressed when either of those
/// keys are pressed.
final ctrlA = KeyCode({0x001000700e0, 0x001000700e4});

/// This [KeyCode] is the same as the one above, but constructed
/// from [LogicalKeyboardKey]'s constants.
final ctrlB = KeyCode.fromSet({LogicalKeyboardKey.ctrlLeft, LogicalKeyboardKey.ctrlRight});

/// This [KeyCode] is considered pressed when the left control key
/// is pressed, but not the right control key.
final ctrlLeft = KeyCode.from(LogicalKeyboardKey.ctrlLeft);

KeyCode has constants for the alt, ctrl, and shift keys, represented by their respective left and right logical keys, like the first two examples above.

/// This [KeyCode] is considered pressed if either `alt` key is pressed.
final alt = KeyCode.alt;

/// This [KeyCode] is considered pressed if either `ctrl` key is pressed.
final ctrl = KeyCode.ctrl;

/// This [KeyCode] is considered pressed if either `shift` key is pressed.
final shift = KeyCode.shift;

Keybindings

Keybindings consist of a set of KeyCodes and are used to bind callbacks to a combination of zero or more keys on a keyboard.

By default, Keybindings are exclusive, meaning they're only treated as pressed if all of their KeyCodes are pressed, and no additional keys have been pressed. If inclusive is set to true, the Keybinding will be treated as pressed as long as all of its KeyCodes are pressed, regardless of whether any additional keys are pressed.

/// This [Keybinding] is considered pressed if both the control and shift keys
/// are pressed, but no additional keys are pressed.
final exclusive = Keybinding({KeyCode.ctrl, KeyCode.shift});

/// This [Keybinding] is considered pressed if both the control and shift keys
/// are pressed, regardless of whether any additional keys are pressed.
final inclusive = Keybinding({KeyCode.ctrl, KeyCode.shift}, inclusive: true);

Note: Keybinding has constants for the alt, ctrl, and shift keys, and the combinations thereof. See: Keybinding

Empty Keybindings

Keybindings may be empty, in which case they will be considered pressed when no other keys are pressed, regardless of whether the Keybinding is inclusive or not.

/// Empty [Keybinding]s can be created with the [empty] constructor, or
/// by constructing a [Keybinding] with an empty [Set]: `Keybinding({})`.
final empty = Keybinding.empty();

isPressed

A Keybinding's isPressed getter can be called at any time to check whether the keys representing it are currently pressed on the keyboard.

/// Prints `true` if either `ctrl` key is currently pressed on
/// the keyboard, otherwise prints `false`.
print(Keybinding.ctrl.isPressed);

Keybinder

Keybinder is the utility class that handles binding Keybindings to their respective callbacks, and calling those callbacks when their Keybinding has been pressed or released.

Callbacks

Keybindings can be bound to one of three types of callbacks:

A function without parameters, which will only be called when the Keybinding is pressed, but not when it's released.

/// When the `space` key is pressed, this callback will
/// print `Keybinding was pressed`.
void onPressed() {
  print('Keybinding was pressed');
}

A ValueChanged<bool> callback (a function with a single boolean parameter,) which will be called with true when the Keybinding is pressed, or false when it's been released.

/// When the `space` key is pressed or released, this callback will print
/// `Keybinding was pressed` or `Keybinding was released`.
void onToggle(bool pressed) {
  print('Keybinding was ${pressed ? 'pressed' : 'released'}');
}

Or, a KeybindingEvent, which is provided the relevant Keybinding and a boolean value representing whether the key was pressed or released, as described by the previous callback.

/// When the key(s) bound to this callback are pressed/released, in this case,
/// the `space` key, this callback will print: `Keybinding(space) was pressed`
/// or `Keybinding(space) was released`.
void onKeyToggled(Keybinding keybinding, bool pressed) {
  print('$keybinding was ${pressed ? 'pressed' : 'released'}');
}

Binding Keybindings

Keybindings can be bound to a callback with Keybinder's register method.

/// A keybinding associated with the `space` key.
final keybinding = Keybinding.from(
    {LogicalKeyboardKey.space}, debugLabel: 'space');

/// Binds all three callbacks above to the `space` key.
Keybinder.bind(keybinding, onPressed);
Keybinder.bind(keybinding, onToggle);
Keybinder.bind(keybinding, onKeyToggled);

Removing Keybindings

Keybindings and their associated callbacks can be removed by Keybinder's remove method.

/// Removes the [Keybinding] bound in the previous example from [Keybinder].
Keybinder.remove(keybinding, onPressed);

Note: Keybinder has a dispose method which clears every bound/registered Keybinding and their respective callbacks, and removes Keybinder's listener from the RawKeyboard instance. Keybinder can continue to be used normally after dispose has been called, a new listener will be added to the RawKeyboard instance once another Keybinding has been registered.

/// Removes every [Keybinding], as well as the listener on
/// the global [RawKeyboard] instance.
Keybinder.dispose();