Function: key-binding

key-binding is a function defined in keymap.c.

Signature

(key-binding KEY &optional ACCEPT-DEFAULT NO-REMAP POSITION)

Documentation

Return the binding for command KEY in current keymaps.

KEY is a string or vector, a sequence of keystrokes. The binding is probably a symbol with a function definition.

Normally, key-binding ignores bindings for t, which act as default bindings, used when nothing else in the keymap applies; this makes it usable as a general function for probing keymaps. However, if the optional second argument ACCEPT-DEFAULT is non-nil, key-binding does recognize the default bindings, just as read-key-sequence does.

Like the normal command loop, key-binding will remap the command resulting from looking up KEY by looking up the command in the current keymaps. However, if the optional third argument NO-REMAP is non-nil, key-binding returns the unmapped command.

If KEY is a key sequence initiated with the mouse, the used keymaps will depend on the clicked mouse position with regard to the buffer and possible local keymaps on strings.

If the optional argument POSITION is non-nil, it specifies a mouse position as returned by event-start and event-end, and the lookup occurs in the keymaps associated with it instead of KEY. It can also be a number or marker, in which case the keymap properties at the specified buffer position instead of point are used.

View in manual

Probably introduced at or before Emacs version 19.23.

Source Code

// Defined in /usr/src/emacs/src/keymap.c
{
  if (NILP (position) && VECTORP (key))
    {
      if (ASIZE (key) == 0)
	return Qnil;

      /* mouse events may have a symbolic prefix indicating the
	 scrollbar or mode line */
      Lisp_Object event
	= AREF (key, SYMBOLP (AREF (key, 0)) && ASIZE (key) > 1 ? 1 : 0);

      /* We are not interested in locations without event data */

      if (EVENT_HAS_PARAMETERS (event) && CONSP (XCDR (event)))
	{
	  Lisp_Object kind = EVENT_HEAD_KIND (EVENT_HEAD (event));
	  if (EQ (kind, Qmouse_click))
	    position = EVENT_START (event);
	}
    }

  Lisp_Object value = Flookup_key (Fcurrent_active_maps (Qt, position),
				   key, accept_default);

  if (NILP (value) || FIXNUMP (value))
    return Qnil;

  /* If the result of the ordinary keymap lookup is an interactive
     command, look for a key binding (ie. remapping) for that command.  */

  if (NILP (no_remap) && SYMBOLP (value))
    {
      Lisp_Object value1;
      if (value1 = Fcommand_remapping (value, position, Qnil), !NILP (value1))
	value = value1;
    }

  return value;
}