Get a key from the user. More...

#include "config.h"
#include <stdbool.h>
#include <stddef.h>
#include <unistd.h>
#include "mutt/lib.h"
#include "config/lib.h"
#include "core/lib.h"
#include "gui/lib.h"
#include "key/lib.h"
#include "menu/lib.h"
#include "globals.h"
#include "monitor.h"

Include dependency graph for get.c:

Go to the source code of this file.

Functions
void	mutt_flushinp (void)
	Empty all the keyboard buffers.

static struct KeyEvent *	array_pop (struct KeyEventArray *a)
	Remove an event from the array.

static void	array_add (struct KeyEventArray *a, int ch, int op)
	Add an event to the end of the array.

static void	array_to_endcond (struct KeyEventArray *a)
	Clear the array until an OP_END_COND.

void	mutt_unget_ch (int ch)
	Return a keystroke to the input buffer.

void	mutt_unget_op (int op)
	Return an operation to the input buffer.

void	mutt_unget_string (const char *s)
	Return a string to the input buffer.

void	mutt_push_macro_event (int ch, int op)
	Add the character/operation to the macro buffer.

void	mutt_flush_macro_to_endcond (void)
	Drop a macro from the input buffer.

static int	mutt_monitor_getch (void)
	Get a character and poll the filesystem monitor.

struct KeyEvent	mutt_getch (GetChFlags flags)
	Read a character from the input buffer.

void	km_error_key (enum MenuType mtype)
	Handle an unbound key sequence.

static struct KeyEvent	retry_generic (enum MenuType mtype, keycode_t *keys, int keyslen, int lastkey, GetChFlags flags)
	Try to find the key in the generic menu bindings.

struct KeyEvent	km_dokey_event (enum MenuType mtype, GetChFlags flags)
	Determine what a keypress should do.

int	km_dokey (enum MenuType mtype, GetChFlags flags)
	Determine what a keypress should do.

Variables
struct KeyEventArray	MacroEvents = ARRAY_HEAD_INITIALIZER
	These are used for macros and exec/push commands.

static struct KeyEventArray	UngetKeyEvents = ARRAY_HEAD_INITIALIZER
	These are used in all other "normal" situations, and are not ignored when passing GETCH_IGNORE_MACRO.

Detailed Description

Get a key from the user.

Authors

Richard Russon

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 get.c.

Function Documentation

◆ mutt_flushinp()

void mutt_flushinp ( void )

Empty all the keyboard buffers.

Definition at line 58 of file get.c.

{
  ARRAY_SHRINK(&UngetKeyEvents, ARRAY_SIZE(&UngetKeyEvents));
  ARRAY_SHRINK(&MacroEvents, ARRAY_SIZE(&MacroEvents));
  flushinp();
}

Here is the caller graph for this function:

◆ array_pop()

static struct KeyEvent * array_pop ( struct KeyEventArray * a )

static

Remove an event from the array.

Parameters

a Array

Return values

ptr Event

Definition at line 70 of file get.c.

{
  if (ARRAY_EMPTY(a))
  {
    return NULL;
  }
 
  struct KeyEvent *event = ARRAY_LAST(a);
  ARRAY_SHRINK(a, 1);
  return event;
}

Here is the caller graph for this function:

◆ array_add()

static void array_add	(	struct KeyEventArray *	a,
		int	ch,
		int	op
	)

static

Add an event to the end of the array.

Parameters

a	Array
ch	Character
op	Operation, e.g. OP_DELETE

Definition at line 88 of file get.c.

{
  struct KeyEvent event = { ch, op };
  ARRAY_ADD(a, event);
}

Here is the caller graph for this function:

◆ array_to_endcond()

static void array_to_endcond ( struct KeyEventArray * a )

static

Clear the array until an OP_END_COND.

Parameters

a Array

Definition at line 98 of file get.c.

{
  while (!ARRAY_EMPTY(a))
  {
    if (array_pop(a)->op == OP_END_COND)
    {
      return;
    }
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mutt_unget_ch()

void mutt_unget_ch ( int ch )

Return a keystroke to the input buffer.

Parameters

ch Key press

This puts events into the UngetKeyEvents buffer

Definition at line 115 of file get.c.

{
  array_add(&UngetKeyEvents, ch, OP_NULL);
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mutt_unget_op()

void mutt_unget_op ( int op )

Return an operation to the input buffer.

Parameters

op	Operation, e.g. OP_DELETE

This puts events into the UngetKeyEvents buffer

Definition at line 126 of file get.c.

{
  array_add(&UngetKeyEvents, 0, op);
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mutt_unget_string()

void mutt_unget_string ( const char * s )

Return a string to the input buffer.

Parameters

s	String to return

This puts events into the UngetKeyEvents buffer

Definition at line 137 of file get.c.

{
  const char *p = s + mutt_str_len(s) - 1;
 
  while (p >= s)
  {
    mutt_unget_ch((unsigned char) *p--);
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mutt_push_macro_event()

void mutt_push_macro_event	(	int	ch,
		int	op
	)

Add the character/operation to the macro buffer.

Parameters

ch	Character to add
op	Operation to add

Adds the ch/op to the macro buffer. This should be used for macros, push, and exec commands only.

Definition at line 155 of file get.c.

{
  array_add(&MacroEvents, ch, op);
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mutt_flush_macro_to_endcond()

void mutt_flush_macro_to_endcond ( void )

Drop a macro from the input buffer.

All the macro text is deleted until an OP_END_COND command, or the buffer is empty.

Definition at line 166 of file get.c.

{
  array_to_endcond(&MacroEvents);
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mutt_monitor_getch()

static int mutt_monitor_getch ( void )

static

Get a character and poll the filesystem monitor.

Return values

num	Character pressed
ERR	Timeout

Definition at line 177 of file get.c.

{
  /* ncurses has its own internal buffer, so before we perform a poll,
   * we need to make sure there isn't a character waiting */
  timeout(0);
  int ch = getch();
  timeout(1000); // 1 second
  if (ch == ERR)
  {
    if (mutt_monitor_poll() != 0)
      ch = ERR;
    else
      ch = getch();
  }
  return ch;
}

Here is the call graph for this function:

Here is the caller graph for this function:

◆ mutt_getch()

struct KeyEvent mutt_getch ( GetChFlags flags )

Read a character from the input buffer.

Parameters

flags Flags, e.g. GETCH_IGNORE_MACRO

Return values

obj	KeyEvent to process

The priority for reading events is:

UngetKeyEvents buffer
MacroEvents buffer
Keyboard

This function can return:

Abort { 0, OP_ABORT }
Repaint { 0, OP_REPAINT }
Timeout { 0, OP_TIMEOUT }

Definition at line 210 of file get.c.

{
  static const struct KeyEvent event_abort = { 0, OP_ABORT };
  static const struct KeyEvent event_repaint = { 0, OP_REPAINT };
  static const struct KeyEvent event_timeout = { 0, OP_TIMEOUT };
 
  if (OptNoCurses)
    return event_abort;
 
  struct KeyEvent *event_key = array_pop(&UngetKeyEvents);
  if (event_key)
    return *event_key;
 
  if (!(flags & GETCH_IGNORE_MACRO))
  {
    event_key = array_pop(&MacroEvents);
    if (event_key)
      return *event_key;
  }
 
  int ch;
  SigInt = false;
  mutt_sig_allow_interrupt(true);
  timeout(1000); // 1 second
#ifdef USE_INOTIFY
  ch = mutt_monitor_getch();
#else
  ch = getch();
#endif
  mutt_sig_allow_interrupt(false);
 
  if (SigInt)
  {
    mutt_query_exit();
    return event_abort;
  }
 
  if (ch == KEY_RESIZE)
  {
    timeout(0);
    while ((ch = getch()) == KEY_RESIZE)
    {
      // do nothing
    }
  }
 
  if (ch == ERR)
  {
    if (!isatty(0)) // terminal was lost
      mutt_exit(1);
 
    if (SigWinch)
    {
      SigWinch = false;
      notify_send(NeoMutt->notify_resize, NT_RESIZE, 0, NULL);
      return event_repaint;
    }
 
    notify_send(NeoMutt->notify_timeout, NT_TIMEOUT, 0, NULL);
    return event_timeout;
  }
 
  if (ch == AbortKey)
    return event_abort;
 
  if (ch & 0x80)
  {
    const bool c_meta_key = cs_subset_bool(NeoMutt->sub, "meta_key");
    if (c_meta_key)
    {
      /* send ALT-x as ESC-x */
      ch &= ~0x80;
      mutt_unget_ch(ch);
      return (struct KeyEvent){ '\033', OP_NULL }; // Escape
    }
  }
 
  return (struct KeyEvent){ ch, OP_NULL };
}

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 294 of file get.c.

{
  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;
  }
 
  char buf[128] = { 0 };
  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:

◆ retry_generic()

static struct KeyEvent retry_generic	(	enum MenuType	mtype,
		keycode_t *	keys,
		int	keyslen,
		int	lastkey,
		GetChFlags	flags
	)

static

Try to find the key in the generic menu bindings.

Parameters

mtype	Menu type, e.g. MENU_PAGER
keys	Array of keys to return to the input queue
keyslen	Number of keys in the array
lastkey	Last key pressed (to return to input queue)
flags	Flags, e.g. GETCH_IGNORE_MACRO

Return values

num	Operation, e.g. OP_DELETE

Definition at line 319 of file get.c.

{
  if (lastkey)
    mutt_unget_ch(lastkey);
  for (; keyslen; keyslen--)
    mutt_unget_ch(keys[keyslen - 1]);
 
  if ((mtype != MENU_EDITOR) && (mtype != MENU_GENERIC) && (mtype != MENU_PAGER))
  {
    return km_dokey_event(MENU_GENERIC, flags);
  }
  if ((mtype != MENU_EDITOR) && (mtype != MENU_GENERIC))
  {
    /* probably a good idea to flush input here so we can abort macros */
    mutt_flushinp();
  }
 
  return (struct KeyEvent){ mutt_getch(flags).ch, OP_NULL };
}

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,
		GetChFlags	flags
	)

Determine what a keypress should do.

Parameters

mtype	Menu type, e.g. MENU_EDITOR
flags	Flags, e.g. GETCH_IGNORE_MACRO

Return values

ptr Event

Definition at line 346 of file get.c.

{
  struct KeyEvent event = { 0, 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, flags);
 
  while (true)
  {
    event = mutt_getch(flags);
 
    // abort, timeout, repaint
    if (event.op < OP_NULL)
      return event;
 
    /* do we have an op already? */
    if (event.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, event.op)))
        return event;
 
      if ((mtype != MENU_EDITOR) && (mtype != MENU_PAGER) && (mtype != MENU_GENERIC))
      {
        /* check generic menu type */
        funcs = OpGeneric;
        func = mutt_get_func(funcs, event.op);
        if (func)
          return event;
      }
 
      /* Sigh. Valid function but not in this context.
       * Find the literal string and push it back */
      for (int i = 0; MenuNames[i].name; i++)
      {
        funcs = km_get_table(MenuNames[i].value);
        if (funcs)
        {
          func = mutt_get_func(funcs, event.op);
          if (func)
          {
            mutt_unget_ch('>');
            mutt_unget_string(func);
            mutt_unget_ch('<');
            break;
          }
        }
      }
      /* continue to chew */
      if (func)
        continue;
    }
 
    if (!map)
      return event;
 
    /* Nope. Business as usual */
    while (event.ch > map->keys[pos])
    {
      if ((pos > map->eq) || !STAILQ_NEXT(map, entries))
        return retry_generic(mtype, map->keys, pos, event.ch, flags);
      map = STAILQ_NEXT(map, entries);
    }
 
    if (event.ch != map->keys[pos])
      return retry_generic(mtype, map->keys, pos, event.ch, flags);
 
    if (++pos == map->len)
    {
      if (map->op != OP_MACRO)
        return (struct KeyEvent){ event.ch, map->op };
 
      /* #GETCH_IGNORE_MACRO 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
       * mw_get_field() 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 (flags & GETCH_IGNORE_MACRO)
      {
        return (struct KeyEvent){ event.ch, OP_NULL };
      }
 
      if (n++ == 10)
      {
        mutt_flushinp();
        mutt_error(_("Macro loop detected"));
        return (struct KeyEvent){ '\0', OP_ABORT };
      }
 
      generic_tokenize_push_string(map->macro);
      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_dokey()

int km_dokey	(	enum MenuType	mtype,
		GetChFlags	flags
	)

Determine what a keypress should do.

Parameters

mtype	Menu type, e.g. MENU_EDITOR
flags	Flags, e.g. GETCH_IGNORE_MACRO

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 464 of file get.c.

{
  return km_dokey_event(mtype, flags).op;
}

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

◆ MacroEvents

struct KeyEventArray MacroEvents = ARRAY_HEAD_INITIALIZER

These are used for macros and exec/push commands.

They can be temporarily ignored by passing GETCH_IGNORE_MACRO

Definition at line 49 of file get.c.

◆ UngetKeyEvents

struct KeyEventArray UngetKeyEvents = ARRAY_HEAD_INITIALIZER

static

These are used in all other "normal" situations, and are not ignored when passing GETCH_IGNORE_MACRO.

Definition at line 53 of file get.c.

Functions

Variables

Detailed Description

Function Documentation

◆ mutt_flushinp()

◆ array_pop()

◆ array_add()

◆ array_to_endcond()

◆ mutt_unget_ch()

◆ mutt_unget_op()

◆ mutt_unget_string()

◆ mutt_push_macro_event()

◆ mutt_flush_macro_to_endcond()

◆ mutt_monitor_getch()

◆ mutt_getch()

◆ km_error_key()

◆ retry_generic()

◆ km_dokey_event()

◆ km_dokey()

Variable Documentation

◆ MacroEvents

◆ UngetKeyEvents