/ 
Chandra-0.10
River stage one • 1 direct dependent • 1 total dependent
/ Chandra::Shortcut

NAME

Chandra::Shortcut - Keyboard shortcuts and global hotkeys for Chandra applications

SYNOPSIS

use Chandra::App;

my $app = Chandra::App->new(title => 'Editor');

# Direct binding on app
$app->shortcut('mod+s', sub { save() });

# Access Shortcut instance
my $sc = $app->shortcuts;

$sc->bind('ctrl+s', sub {
    my ($event) = @_;
    save_document();
});

$sc->bind('ctrl+shift+p', sub {
    open_command_palette();
});

# Platform-aware modifier (Cmd on macOS, Ctrl on Linux/Windows)
$sc->bind('mod+z', sub { undo() });
$sc->bind('mod+shift+z', sub { redo() });

# Unbind
$sc->unbind('ctrl+s');

# List registered shortcuts
my @bindings = $sc->list;

# Check if combo is bound
my $bound = $sc->is_bound('ctrl+s');

# Disable/enable
$sc->disable('ctrl+s');
$sc->enable('ctrl+s');
$sc->disable_all;
$sc->enable_all;

# Key sequence (chord) support
$sc->bind('ctrl+k ctrl+c', sub { comment_selection() });

# Prevent default browser behavior
$sc->bind('ctrl+p', sub { custom_print() }, prevent_default => 1);

# Shortcut map (bulk registration)
$app->shortcut_map({
    'mod+s'       => \&save,
    'mod+o'       => \&open_file,
    'mod+shift+s' => \&save_as,
    'mod+q'       => sub { $app->terminate },
    'f11'         => sub { $app->fullscreen },
});

$app->run;

DESCRIPTION

Chandra::Shortcut registers app-level keyboard shortcuts from Perl. It handles key combos like Ctrl+S, Cmd+K, etc. without raw JS event listeners. A keydown listener is injected via the existing Bridge mechanism, and key events are normalised and dispatched to registered Perl handlers.

CONSTRUCTOR

new(%args)

Create a new Shortcut instance. Usually accessed via $app->shortcuts.

METHODS

bind($combo, $handler, %opts)

Register a keyboard shortcut. $combo is a string like ctrl+s, mod+shift+p, or ctrl+k ctrl+c (chord). $handler receives a Chandra::Event object.

Options:

prevent_default => 1

Prevent the browser's default action for this key combo.

unbind($combo)

Remove a previously registered shortcut.

list()

Return a list of hashrefs describing registered shortcuts:

({ combo => 'ctrl+s', handler => $sub, enabled => 1, prevent_default => 0 }, ...)

is_bound($combo)

Returns true if the combo is registered.

disable($combo)

Temporarily disable a specific shortcut without removing it.

enable($combo)

Re-enable a previously disabled shortcut.

disable_all()

Disable all shortcuts globally.

enable_all()

Re-enable all shortcuts after a global disable.

inject()

Inject the shortcut listener JavaScript into the webview. Called automatically by Chandra::App->run().

js_code()

Return the JavaScript source for manual injection.

KEY NORMALIZATION

  • Key names are case-insensitive.

  • mod maps to meta (Cmd) on macOS, ctrl on Linux/Windows.

  • Aliases: space, enter, escape, tab, backspace, delete, up, down, left, right, plus, minus, equal.

  • Function keys f1–f12 are supported.

  • Modifiers are canonically ordered: ctrl, shift, alt, meta.

SEE ALSO

Chandra::App, Chandra::Event, Chandra::Bridge