Module keymap

Defining global key bindings.

This module is used to define keybindings that are recognized throughout the application:

keymap.bind('C-a q', function()
  alert("hi!")
end)

Usually, however, you won’t use this module directly but instead call the bind function of a widget class to restrict the binding to a certain widget type (often an Editbox or a Panel):

ui.Listbox.bind('C-a q', function()
  alert("hi from a listbox!")
end)
-- One place where you can test this is the
-- "Directory hotlist" dialog, which contains
-- a listbox.

The above code is equivalent to:

keymap.bind('C-a q', {
  fn = function()
    alert("hi from a listbox!!")
  end,
  condition = function()
    -- this effectively returns 'true' if the current
    -- widget is a listbox.
    return ui.current_widget("Listbox")
  end,
  arg = function()
    return ui.current_widget()
  end,
})
-- Of course, in practice you won't need to type all
-- this: simply use ui.Listbox.bind() instead.

We see here that using the ‘condition’ entry one can make a keybinding active under a certain condition only. This creates the impression of having several “keymaps” (one for each widget type). (In reality there’s only one keymap, but you don’t need to be aware of this implementation detail.)

Key sequences

The first argument to bind() is a key sequence: it’s one or more key names separated by a space character. Examples:

  • “control-f meta-p home”
  • “C-f M-p <home>” (emacs-like syntax is recognized)
  • “C-M-x”
  • “C-f any”

A special key name is “any”, which stands for any key. It can be used to implement a screensaver or an abbreviations utility for the editor. The keycode is passed as the second argument to the function; see example at widget:fixate.

Binding chain

You may register several different functions to run for the same key sequence.

This happens when you call bind() several times, or, more commonly, when you pick a key already in use by MC.

The last function registered whose condition is met will be the one to run. If this function returns an explicit false, the lookup will be resumed with the previously registered function (or, if there’s none, the default action). This little device lets you conditionally override a default action, as demonstrated at ui.Panel:current.

To help you remember what this explicit false does, think of it as saying “No, dear system, you haven’t seen me!”

Functions

bind(keyseq, function_or_table) Binds a function to a key sequence.


Functions

bind(keyseq, function_or_table)

Binds a function to a key sequence.

It its simplest form, the second parameter is the function. It might also be a table with the following fields:

  • fn: the function to run.
  • condition: the condition to satisfy in order to run,
  • arg: a function returning an argument to pass to fn.

In addition to this argument the function will receive another, second argument which is the keycode pressed (this is especially useful when using the any key).

  • description: an optional string describing the action. Isn’t currently used. May be used in the future to produce friendly keybinding listings.
generated by LDoc 1.4.3 Last updated 2016-08-23 17:29:40