Zyzanie

Emacs-like key bindings in your browser!

And like emacs, you can rebind them on-the-fly!

C-g will cancel any started key sequence.

Inspired by https://github.com/AndreasKostler/dyscord

Usage

Simply add [zyzanie "0.2.5"] in your project dependencies.

Key binding

(global-set-key "C-c a" #(js/alert "Are you a global person?"))

(local-set-key "C-c a" #(js/alert "Local!") (domina/by-id "some-id"))

In the previous example, if you try C-c + a from inside the dom element “some-id”, you will get the dialog:

Local!

Anywhere else, C-c + a will give you:

Are you a global person?

You can easily make the same key sequence have different behavior for different dom elements.

The local dom element must be focusable, otherwise the event won’t be fired by it.

You can use any dom element selector; here I use domina. The only important part is to select the element that will fire the events.

Key names

Here are the possible key names you can use in a global or local set key function:

Special keys:

up, del, end, esc, tab, down, home, left, clear, enter, right, space, pagedown, backspace, delete, escape, pageup, return.

Modifiers:

C, M, S, f1, f2, f3, f4, f5, f6, f7, f8, f9, alt, cmd, f10, f11, f12, f13, f14, f15, f16, f17, f18, f19, ctrl, shift, command, control, option.

Mouse buttons:

mouseleft, mouseright, mousemiddle, mouse0, mouse1, mouse2, mwheelup, mwheeldown.

Please note that the middle and right button are associated to the :mousedown event, but that the left button is associated with the :click event. This insure compatibility with drag and drop.

Every other key uses its own character as a name. For example: “a” is the key a.

Adding key notifications

If you want to see which keys are recorded as a key sequence while you are pressing them, call the function add-notifications from the zyzanie.notification namespace, as shown here:

(ns my.namespace
  (:require [zyzanie.core :as z]
            [zyzanie.notification :as zn]))

(zn/add-notifications)

To remove them, use remove-notifications in the same namespace.

Accessing events

The last event that triggered a complete key sequence is transmitted to the bound function. For example:

(defn log-event [event] (domina/log (str "You pressed "(.-keyCode (domina.events/raw-event event)))))

A simple logging function to see if we really captured the event.

Note that the events returned are domina events. If you want to get the raw-event, you must use the raw-event function from domina.events.

(global-set-key "C-a" #(log-event %))

Then, when C-a is pressed, we get in the javascript console:

You pressed 65

65 is the keyCode for the letter “a”.

Preventing default

Zyzanie will automatically prevent any default when a keystroke can be a potential key sequence. In order words, it will not greedily prevent everything, but only what is really necessary to be able to input a currently valid key sequence.

For example, let’s bind C-mouseright to a log message:

(global-set-key "C-mouseright" #(domina/log "Right button!"))

Now, if you right click, you will see the context menu as usual. But because the Ctrl and mouseright are present in a key sequence, it will disable the context menu for this particular key chord. Try it now: Ctrl + mouseright. Tada! No context menu!

If you add a local key sequence, every other dom element will remain unaffected.

Rebinding

You can safely rebind any key sequence without the need to unset them first.

Unset Key Sequence

You can unset key sequences with the following:

(global-unset-key "C-c a")

(local-unset-key "C-c a" (domina/by-id "some-id"))

Hooks

You can add functions that will be called each time a key sequence is completed (this includes C-g) with:

(add-global-hook! #(domina/log "This is called after each valid key-sequence"))

You can also add a hook for local key-sequences only.

(add-local-hook! #(domina/log "This is called after each valid local key-sequence") (domina/by-id "some-id"))

Unfortunately there’s isn’t a way to easily select a precise hook and remove it, so you’ll have to be careful with the hooks you add. If you make a mistake, you can remove them with these functions:

(remove-local-hooks! (domina/by-id "some-id")) ;remove local hooks

(remove-global-hooks!) ;remove global hooks

(remove-all-hooks!) ;remove all hooks

As with the key binding functions, the hooks will receive the event as their argument.

Side effects

In order to be able to trigger local events with the keyboard, the items (div, span…) on which the key bindings are attached must be focusable.

Zyzanie will solve this problem by giving them a tabindex of -1. (Focusable by JS). Also, these items will be automatically focused when hovered with the mouse. Be carefull if you use the :focus pseudoclass in your CSS!

By default most browser will show an outline for focused objects. If you don’t want to show them, you can add the following to your CSS:

:focus {outline:none}

Be carefull, you should still provide a way to the user to know where the focus is!

License

Copyright © 2013 Frozenlock

Distributed under the Eclipse Public License, the same as Clojure.