keymap.h File Reference

Manage keymappings. More...

#include "config.h"
#include <stddef.h>
#include <stdint.h>
#include "mutt/lib.h"
#include "core/lib.h"
#include "menu/lib.h"

Include dependency graph for keymap.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	Keymap
	A keyboard mapping. More...
struct	KeyEvent
	An event such as a keypress. More...
struct	MenuFuncOp
	Mapping between a function and an operation. More...
struct	MenuOpSeq
	Mapping between an operation and a key sequence. More...
struct	EventBinding
	A key binding Event. More...

Macros
#define	MUTT_UNBIND   1<<0
#define	MUTT_UNMACRO   1<<1
#define	MAX_SEQ   8

Typedefs
typedef short	keycode_t
	Type for key storage, the rest of neomutt works fine with int type. More...

Enumerations
enum	NotifyBinding {   NT_BINDING_ADD = 1 , NT_BINDING_DELETE , NT_BINDING_DELETE_ALL , NT_MACRO_ADD ,   NT_MACRO_DELETE , NT_MACRO_DELETE_ALL }
	Key Binding notification types. More...

Functions
void	init_extended_keys (void)
	Initialise map of ncurses extended keys. More...
	STAILQ_HEAD (KeymapList, Keymap)
int	km_expand_key (char *s, size_t len, struct Keymap *map)
	Get the key string bound to a Keymap. More...
struct Keymap *	km_find_func (enum MenuType menu, int func)
	Find a function's mapping in a Menu. More...
void	km_init (void)
	Initialise all the menu keybindings. More...
void	km_error_key (enum MenuType menu)
	Handle an unbound key sequence. More...
void	mutt_what_key (void)
	Ask the user to press a key. More...
void	mutt_init_abort_key (void)
	Parse the abort_key config string. More...
int	main_config_observer (struct NotifyCallback *nc)
	Notification that a Config Variable has changed - Implements observer_t -. More...
enum CommandResult	km_bind (char *s, enum MenuType menu, int op, char *macro, char *desc)
	Bind a key to a macro. More...
int	km_dokey (enum MenuType menu)
	Determine what a keypress should do. More...
struct KeyEvent	km_dokey_event (enum MenuType menu)
	Determine what a keypress should do. More...
const struct MenuFuncOp *	km_get_table (enum MenuType mtype)
	Lookup a Menu's functions. More...
const char *	mutt_get_func (const struct MenuFuncOp *bindings, int op)
	Get the name of a function. More...
void	mutt_keys_free (void)
	Free the key maps. More...
enum CommandResult	mutt_parse_bind (struct Buffer *buf, struct Buffer *s, intptr_t data, struct Buffer *err)
	Parse the 'bind' command - Implements Command::parse() -. More...
enum CommandResult	mutt_parse_exec (struct Buffer *buf, struct Buffer *s, intptr_t data, struct Buffer *err)
	Parse the 'exec' command - Implements Command::parse() -. More...
enum CommandResult	mutt_parse_macro (struct Buffer *buf, struct Buffer *s, intptr_t data, struct Buffer *err)
	Parse the 'macro' command - Implements Command::parse() -. More...
enum CommandResult	mutt_parse_push (struct Buffer *buf, struct Buffer *s, intptr_t data, struct Buffer *err)
	Parse the 'push' command - Implements Command::parse() -. More...
enum CommandResult	mutt_parse_unbind (struct Buffer *buf, struct Buffer *s, intptr_t data, struct Buffer *err)
	Parse the 'unbind' command - Implements Command::parse() -. More...
enum CommandResult	mutt_parse_unmacro (struct Buffer *buf, struct Buffer *s, intptr_t data, struct Buffer *err)

Variables
struct KeymapList	Keymaps []
	Array of Keymap keybindings, one for each Menu. More...
keycode_t	AbortKey
	key to abort edits etc, normally Ctrl-G More...
const struct Mapping	Menus []

Detailed Description

Manage keymappings.

Authors

• Michael R. Elkins

Copyright

This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Definition in file keymap.h.

Macro Definition Documentation

MUTT_UNBIND

#define MUTT_UNBIND   1<<0

Definition at line 33 of file keymap.h.

MUTT_UNMACRO

#define MUTT_UNMACRO   1<<1

Definition at line 34 of file keymap.h.

MAX_SEQ

#define MAX_SEQ   8

Definition at line 36 of file keymap.h.

Typedef Documentation

keycode_t

typedef short keycode_t

Type for key storage, the rest of neomutt works fine with int type.

Definition at line 39 of file keymap.h.

Enumeration Type Documentation

NotifyBinding

enum NotifyBinding

Key Binding notification types.

Observers of NT_BINDING will be passed an EventBinding.

Note

Notifications are sent after the event.

Enumerator
NT_BINDING_ADD	Key binding has been added.
NT_BINDING_DELETE	Key binding has been deleted.
NT_BINDING_DELETE_ALL	All key bindings have been deleted.
NT_MACRO_ADD	Key macro has been added.
NT_MACRO_DELETE	Key macro has been deleted.
NT_MACRO_DELETE_ALL	All key macros have been deleted.

Definition at line 123 of file keymap.h.

{
  NT_BINDING_ADD = 1,    
  NT_BINDING_DELETE,     
  NT_BINDING_DELETE_ALL, 
 
  NT_MACRO_ADD,          
  NT_MACRO_DELETE,       
  NT_MACRO_DELETE_ALL,   
};

Function Documentation

init_extended_keys()

void init_extended_keys

(

void

)

Initialise map of ncurses extended keys.

Determine the keycodes for ncurses extended keys and fill in the KeyNames array.

This function must be called after initscr(), or tigetstr() returns -1. This creates a bit of a chicken-and-egg problem because km_init() is called prior to start_curses(). This means that the default keybindings can't include any of the extended keys because they won't be defined until later.

Definition at line 997 of file keymap.c.

{
#ifdef HAVE_USE_EXTENDED_NAMES
  use_extended_names(true);
 
  for (int j = 0; KeyNames[j].name; j++)
  {
    if (KeyNames[j].value == -1)
    {
      const char *keyname = find_ext_name(KeyNames[j].name);
 
      if (keyname)
      {
        char *s = tigetstr((char *) keyname);
        if (s && ((long) (s) != -1))
        {
          int code = key_defined(s);
          if (code > 0)
            KeyNames[j].value = code;
        }
      }
    }
  }
#endif
}

Here is the call graph for this function:

Here is the caller graph for this function:

STAILQ_HEAD()

STAILQ_HEAD	(	KeymapList	,
		Keymap
	)

km_expand_key()

int km_expand_key	(	char *	s,
		size_t	len,
		struct Keymap *	map
	)

Get the key string bound to a Keymap.

Parameters

s	Buffer for the key string
len	Length of buffer
map	Keybinding map

Return values

1	Success
0	Error

Definition at line 929 of file keymap.c.

{
  if (!map)
    return 0;
 
  int p = 0;
 
  while (true)
  {
    mutt_str_copy(s, km_keyname(map->keys[p]), len);
    const size_t l = mutt_str_len(s);
    len -= l;
 
    if ((++p >= map->len) || !len)
      return 1;
 
    s += l;
  }
 
  /* not reached */
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_find_func()

struct Keymap * km_find_func	(	enum MenuType	mtype,
		int	func
	)

Find a function's mapping in a Menu.

Parameters

mtype	Menu type, e.g. MENU_PAGER
func	Function, e.g. OP_DELETE

Return values

ptr	Keymap for the function

Definition at line 957 of file keymap.c.

{
  struct Keymap *np = NULL;
  STAILQ_FOREACH(np, &Keymaps[mtype], entries)
  {
    if (np->op == func)
      break;
  }
  return np;
}

Here is the caller graph for this function:

km_init()

void km_init

(

void

)

Initialise all the menu keybindings.

Definition at line 1026 of file keymap.c.

{
  memset(Keymaps, 0, sizeof(struct KeymapList) * MENU_MAX);
 
  create_bindings(AliasDefaultBindings, MENU_ALIAS);
  create_bindings(AttachDefaultBindings, MENU_ATTACH);
#ifdef USE_AUTOCRYPT
  create_bindings(AutocryptAcctDefaultBindings, MENU_AUTOCRYPT_ACCT);
#endif
  create_bindings(BrowserDefaultBindings, MENU_FOLDER);
  create_bindings(ComposeDefaultBindings, MENU_COMPOSE);
  create_bindings(EditorDefaultBindings, MENU_EDITOR);
  create_bindings(GenericDefaultBindings, MENU_GENERIC);
  create_bindings(IndexDefaultBindings, MENU_INDEX);
#ifdef MIXMASTER
  create_bindings(MixDefaultBindings, MENU_MIX);
#endif
  create_bindings(PagerDefaultBindings, MENU_PAGER);
  create_bindings(PostDefaultBindings, MENU_POSTPONE);
  create_bindings(QueryDefaultBindings, MENU_QUERY);
 
  if (WithCrypto & APPLICATION_PGP)
    create_bindings(PgpDefaultBindings, MENU_PGP);
  if (WithCrypto & APPLICATION_SMIME)
    create_bindings(SmimeDefaultBindings, MENU_SMIME);
 
#ifdef CRYPT_BACKEND_GPGME
  create_bindings(PgpDefaultBindings, MENU_KEY_SELECT_PGP);
  create_bindings(SmimeDefaultBindings, MENU_KEY_SELECT_SMIME);
#endif
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_error_key()

void km_error_key

(

enum MenuType

mtype

)

Handle an unbound key sequence.

Parameters

mtype

Menu type, e.g. MENU_PAGER

Definition at line 1062 of file keymap.c.

{
  char buf[128] = { 0 };
  int p, op;
 
  struct Keymap *key = km_find_func(mtype, OP_HELP);
  if (!key && (mtype != MENU_EDITOR) && (mtype != MENU_PAGER))
    key = km_find_func(MENU_GENERIC, OP_HELP);
  if (!key)
  {
    mutt_error(_("Key is not bound"));
    return;
  }
 
  /* Make sure the key is really the help key in this menu.
   *
   * OP_END_COND is used as a barrier to ensure nothing extra
   * is left in the unget buffer.
   *
   * Note that km_expand_key() + tokenize_unget_string() should
   * not be used here: control sequences are expanded to a form
   * (e.g. "^H") not recognized by km_dokey(). */
  mutt_unget_op(OP_END_COND);
  p = key->len;
  while (p--)
    mutt_unget_ch(key->keys[p]);
 
  /* Note, e.g. for the index menu:
   *   bind generic ?   noop
   *   bind generic ,a  help
   *   bind index   ,ab quit
   * The index keybinding shadows the generic binding.
   * OP_END_COND will be read and returned as the op.
   *
   *   bind generic ?   noop
   *   bind generic dq  help
   *   bind index   d   delete-message
   * OP_DELETE will be returned as the op, leaving "q" + OP_END_COND
   * in the unget buffer.
   */
  op = km_dokey(mtype);
  if (op != OP_END_COND)
    mutt_flush_unget_to_endcond();
  if (op != OP_HELP)
  {
    mutt_error(_("Key is not bound"));
    return;
  }
 
  km_expand_key(buf, sizeof(buf), key);
  mutt_error(_("Key is not bound.  Press '%s' for help."), buf);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_what_key()

void mutt_what_key

(

void

)

Ask the user to press a key.

Displays the octal value back to the user.

Definition at line 1877 of file keymap.c.

{
  int ch;
 
  struct MuttWindow *win = msgwin_get_window();
  if (!win)
    return;
 
  mutt_curses_set_normal_backed_color_by_id(MT_COLOR_PROMPT);
  mutt_window_mvprintw(win, 0, 0, _("Enter keys (%s to abort): "), km_keyname(AbortKey));
  mutt_curses_set_color_by_id(MT_COLOR_NORMAL);
  enum MuttCursorState cursor = mutt_curses_set_cursor(MUTT_CURSOR_VISIBLE);
  do
  {
    ch = getch();
    if ((ch != ERR) && (ch != AbortKey))
    {
      mutt_message(_("Char = %s, Octal = %o, Decimal = %d"), km_keyname(ch), ch, ch);
      mutt_window_move(win, 0, 0);
    }
  } while (ch != ERR && ch != AbortKey);
  mutt_curses_set_cursor(cursor);
 
  mutt_flushinp();
  mutt_clear_error();
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_init_abort_key()

void mutt_init_abort_key

(

void

)

Parse the abort_key config string.

Parse the string into $abort_key and put the keycode into AbortKey.

Definition at line 858 of file keymap.c.

{
  keycode_t buf[2];
  const char *const c_abort_key = cs_subset_string(NeoMutt->sub, "abort_key");
  size_t len = parsekeys(c_abort_key, buf, mutt_array_size(buf));
  if (len == 0)
  {
    mutt_error(_("Abort key is not set, defaulting to Ctrl-G"));
    AbortKey = ctrl('G');
    return;
  }
  if (len > 1)
  {
    mutt_warning(_("Specified abort key sequence (%s) will be truncated to first key"),
                 c_abort_key);
  }
  AbortKey = buf[0];
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_bind()

enum CommandResult km_bind	(	char *	s,
		enum MenuType	mtype,
		int	op,
		char *	macro,
		char *	desc
	)

Bind a key to a macro.

Parameters

s	Key string
mtype	Menu type, e.g. MENU_EDITOR
op	Operation, e.g. OP_DELETE
macro	Macro string
desc	Description of macro (OPTIONAL)

Return values

CommandResult

Result e.g. MUTT_CMD_SUCCESS

Definition at line 459 of file keymap.c.

{
  return km_bind_err(s, mtype, op, macro, desc, NULL);
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_dokey()

int km_dokey

(

enum MenuType

mtype

)

Determine what a keypress should do.

Parameters

mtype

Menu type, e.g. MENU_EDITOR

Return values

>0	Function to execute
OP_NULL	No function bound to key sequence
-1	Error occurred while reading input
-2	A timeout or sigwinch occurred

Definition at line 796 of file keymap.c.

{
  return km_dokey_event(mtype).op;
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_dokey_event()

struct KeyEvent km_dokey_event

(

enum MenuType

mtype

)

Determine what a keypress should do.

Parameters

mtype

Menu type, e.g. MENU_EDITOR

Return values

ptr

Event

Definition at line 638 of file keymap.c.

{
  struct KeyEvent tmp = { OP_NULL, OP_NULL };
  struct Keymap *map = STAILQ_FIRST(&Keymaps[mtype]);
  int pos = 0;
  int n = 0;
 
  if (!map && (mtype != MENU_EDITOR))
    return retry_generic(mtype, NULL, 0, 0);
 
#ifdef USE_IMAP
  const short c_imap_keepalive = cs_subset_number(NeoMutt->sub, "imap_keepalive");
#endif
 
  while (true)
  {
    const short c_timeout = cs_subset_number(NeoMutt->sub, "timeout");
    int i = (c_timeout > 0) ? c_timeout : 60;
#ifdef USE_IMAP
    /* keepalive may need to run more frequently than `$timeout` allows */
    if (c_imap_keepalive)
    {
      if (c_imap_keepalive >= i)
        imap_keepalive();
      else
      {
        while (c_imap_keepalive && (c_imap_keepalive < i))
        {
          tmp = mutt_getch_timeout(c_imap_keepalive * 1000);
          /* If a timeout was not received, or the window was resized, exit the
           * loop now.  Otherwise, continue to loop until reaching a total of
           * $timeout seconds.  */
          if ((tmp.op != OP_TIMEOUT) || SigWinch)
            goto gotkey;
#ifdef USE_INOTIFY
          if (MonitorFilesChanged)
            goto gotkey;
#endif
          i -= c_imap_keepalive;
          imap_keepalive();
        }
      }
    }
#endif
 
    tmp = mutt_getch_timeout(i * 1000);
 
#ifdef USE_IMAP
  gotkey:
#endif
    /* hide timeouts, but not window resizes, from the line editor. */
    if ((mtype == MENU_EDITOR) && (tmp.op == OP_TIMEOUT) && !SigWinch)
      continue;
 
    if ((tmp.op == OP_TIMEOUT) || (tmp.op == OP_ABORT))
    {
      return tmp;
    }
 
    /* do we have an op already? */
    if (tmp.op != OP_NULL)
    {
      const char *func = NULL;
      const struct MenuFuncOp *funcs = NULL;
 
      /* is this a valid op for this menu type? */
      if ((funcs = km_get_table(mtype)) && (func = mutt_get_func(funcs, tmp.op)))
        return tmp;
 
      if ((mtype != MENU_EDITOR) && (mtype != MENU_PAGER) && (mtype != MENU_GENERIC))
      {
        /* check generic menu type */
        funcs = OpGeneric;
        func = mutt_get_func(funcs, tmp.op);
        if (func)
          return tmp;
      }
 
      /* Sigh. Valid function but not in this context.
       * Find the literal string and push it back */
      for (i = 0; MenuNames[i].name; i++)
      {
        funcs = km_get_table(MenuNames[i].value);
        if (funcs)
        {
          func = mutt_get_func(funcs, tmp.op);
          if (func)
          {
            mutt_unget_ch('>');
            mutt_unget_string(func);
            mutt_unget_ch('<');
            break;
          }
        }
      }
      /* continue to chew */
      if (func)
        continue;
    }
 
    if (!map)
      return tmp;
 
    /* Nope. Business as usual */
    while (tmp.ch > map->keys[pos])
    {
      if ((pos > map->eq) || !STAILQ_NEXT(map, entries))
        return retry_generic(mtype, map->keys, pos, tmp.ch);
      map = STAILQ_NEXT(map, entries);
    }
 
    if (tmp.ch != map->keys[pos])
      return retry_generic(mtype, map->keys, pos, tmp.ch);
 
    if (++pos == map->len)
    {
      if (map->op != OP_MACRO)
        return (struct KeyEvent){ .ch = tmp.ch, .op = map->op };
 
      /* OptIgnoreMacroEvents turns off processing the MacroEvents buffer
       * in mutt_getch().  Generating new macro events during that time would
       * result in undesired behavior once the option is turned off.
       *
       * Originally this returned -1, however that results in an unbuffered
       * username or password prompt being aborted.  Returning OP_NULL allows
       * mutt_enter_string_full() to display the keybinding pressed instead.
       *
       * It may be unexpected for a macro's keybinding to be returned,
       * but less so than aborting the prompt.  */
      if (OptIgnoreMacroEvents)
      {
        return (struct KeyEvent){ .ch = tmp.ch, .op = OP_NULL };
      }
 
      if (n++ == 10)
      {
        mutt_flushinp();
        mutt_error(_("Macro loop detected"));
        return (struct KeyEvent){ .ch = '\0', .op = -1 };
      }
 
      generic_tokenize_push_string(map->macro, mutt_push_macro_event);
      map = STAILQ_FIRST(&Keymaps[mtype]);
      pos = 0;
    }
  }
 
  /* not reached */
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_get_table()

const struct MenuFuncOp * km_get_table

(

enum MenuType

mtype

)

Lookup a Menu's functions.

Parameters

mtype

Menu type, e.g. MENU_EDITOR

Return values

ptr	Array of functions

Definition at line 1231 of file keymap.c.

{
  switch (mtype)
  {
    case MENU_ALIAS:
      return OpAlias;
    case MENU_ATTACH:
      return OpAttach;
#ifdef USE_AUTOCRYPT
    case MENU_AUTOCRYPT_ACCT:
      return OpAutocrypt;
#endif
    case MENU_COMPOSE:
      return OpCompose;
    case MENU_EDITOR:
      return OpEditor;
    case MENU_FOLDER:
      return OpBrowser;
    case MENU_GENERIC:
      return OpGeneric;
    case MENU_INDEX:
      return OpIndex;
#ifdef CRYPT_BACKEND_GPGME
    case MENU_KEY_SELECT_PGP:
      return OpPgp;
    case MENU_KEY_SELECT_SMIME:
      return OpSmime;
#endif
#ifdef MIXMASTER
    case MENU_MIX:
      return OpMix;
#endif
    case MENU_PAGER:
      return OpPager;
    case MENU_PGP:
      return (WithCrypto & APPLICATION_PGP) ? OpPgp : NULL;
    case MENU_POSTPONE:
      return OpPostpone;
    case MENU_QUERY:
      return OpQuery;
    default:
      return NULL;
  }
}

Here is the caller graph for this function:

mutt_get_func()

const char * mutt_get_func	(	const struct MenuFuncOp *	funcs,
		int	op
	)

Get the name of a function.

Parameters

funcs	Functions table
op	Operation, e.g. OP_DELETE

Return values

ptr	Name of function
NULL	Operation not found

Note

This returns a static string.

Definition at line 519 of file keymap.c.

{
  for (int i = 0; funcs[i].name; i++)
  {
    if (funcs[i].op == op)
      return funcs[i].name;
  }
 
  return NULL;
}

Here is the caller graph for this function:

mutt_keys_free()

void mutt_keys_free

(

void

)

Free the key maps.

Definition at line 1907 of file keymap.c.

{
  for (int i = 0; i < MENU_MAX; i++)
  {
    mutt_keymaplist_free(&Keymaps[i]);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_parse_unmacro()

enum CommandResult mutt_parse_unmacro	(	struct Buffer *	buf,
		struct Buffer *	s,
		intptr_t	data,
		struct Buffer *	err
	)

Variable Documentation

Keymaps

struct KeymapList Keymaps[]

extern

Array of Keymap keybindings, one for each Menu.

Definition at line 127 of file keymap.c.

AbortKey

keycode_t AbortKey

extern

key to abort edits etc, normally Ctrl-G

key to abort edits etc, normally Ctrl-G

Definition at line 125 of file keymap.c.

Menus

const struct Mapping Menus[]

extern