Mapping

Basic Mapping

map

map is the most basic Keymando command. It lets you map a source event to a target event. In the following example, we’ll map <Ctrl-m> to <Ctrl-F2> to give us quick access to the Mac menu bar.

    map "<Ctrl-m>", "<Ctrl-F2>"

NOTE: <Cmd-s> is not the same as <Cmd-S>. However, <Cmd-S> and <Cmd-Shift-s> are the same.

Blocks

map also lets you map a source event, in this case <Ctrl-W>, to a block of code that gets executed everytime that event is occurs.

    map "<Ctrl-W>" do
      alert("This is a block")
    end

See Mnemonics for an advanced example of map blocks.

imap – Map in Insert Mode

imap specifies a keymapping which is only valid when focus is inside a textfield, similar to imap in vi and vim.

    imap "<Ctrl-j>", "<Down>"

nmap – Map in Normal Mode

nmap specifies a keymapping which is only valid when focus is not inside a textfield, similar to nmap in vi and vim.

    nmap "<Ctrl-[>", "<Escape>"

NOTE: nmap and imap only work for native OSX textfields. Currently, Safari is the only browser exposes its textfields and therefore the only browser that will support the imap method.

Advanced Mapping

Mapping Strings of Characters

map also works mapping a string of characters.

    only /Chrome/ do
      map '<Ctrl-a>p', '<Cmd-{>'
      map '<Ctrl-a>n', '<Cmd-}>'
    end

This example mimics tmux tab switch in Google Chrome.

Swallowed Events

One thing to keep in mind when using this type of mapping is that map will swallow events if until the possible mapping is matched.

    map 'abc', '123'

• 1) Typing ‘a’ will be swallowed by Keymando since there is a possible mapping of ‘abc’.
• 2) Typing ‘b’ will be swallowed by Keymando since there is a possible mapping of ‘abc’.
• 3a) Typing ‘d’ would passthrough Keymando and type a ‘d’, also clearing the running history of events.
• 3b) Typing ‘c’, instead, would be swallowed by Keymando and trigger the mapping to type ’123′

Greediness

Example of mapping collision:

    map 'a', '1'
    map 'abc', '123'

Keymando will always trigger the first mapping because when an ‘a’ is typed, the mapping is run and the history of the ‘a’ event is forgotten. To remedy these issues, use filters to restrict mappings to certain appliactions, etc.

Re-enabling Keys

If you’ve setup a mapping that disables a key like example below:

    map "<Down>", nil

You can re-enable the mapping in a filter like so:

    only "TextEdit" do
      map "<Down>", "<Down>"
    end