get.h File Reference

Get a key from the user. More...

#include <stdint.h>
#include "mutt/lib.h"
#include "menu/lib.h"
#include "keymap.h"

Include dependency graph for get.h:

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

Go to the source code of this file.

Data Structures
struct	KeyEvent
	An event such as a keypress. More...
struct	KeymapMatch
	Result of Matching Keybinding. More...

Macros
#define	GETCH_NO_FLAGS   0
	No flags are set.
#define	GETCH_IGNORE_MACRO   (1 << 0)
	Don't use MacroEvents.
#define	KEY_GATHER_NO_MATCH   0
	No bindings match the search string.
#define	KEY_GATHER_MATCH   (1 << 0)
	Binding matches the search string.
#define	KEY_GATHER_LONGER   (1 << 1)
	No bindings match, but longer strings might.
#define	MFF_NO_FLAGS   0
	No flags are set.
#define	MFF_DEPRECATED   (1 << 1)
	Redraw the pager.

Typedefs
typedef uint8_t	GetChFlags
	Flags for mutt_getch(), e.g. GETCH_NO_FLAGS.
typedef uint8_t	KeyGatherFlags
	Flags for gather_functions(), e.g. KEY_GATHER_NO_MATCH.
typedef uint8_t	MenuFuncFlags
	Flags, e.g. MFF_DEPRECATED.

Functions
	ARRAY_HEAD (KeyEventArray, struct KeyEvent)
	ARRAY_HEAD (KeymapMatchArray, struct KeymapMatch)
void	array_add (struct KeyEventArray *a, int ch, int op)
	Add an event to the end of the array.
struct KeyEvent *	array_pop (struct KeyEventArray *a)
	Remove an event from the array.
void	array_to_endcond (struct KeyEventArray *a)
	Clear the array until an OP_END_COND.
KeyGatherFlags	gather_functions (const struct MenuDefinition *md, const keycode_t *keys, int key_len, struct KeymapMatchArray *kma)
	Find functions whose keybindings match.
void	generic_tokenize_push_string (char *s)
	Parse and queue a 'push' command.
struct KeyEvent	km_dokey (const struct MenuDefinition *md, GetChFlags flags)
	Determine what a keypress should do.
void	km_error_key (const struct MenuDefinition *md)
	Handle an unbound key sequence.
void	mutt_flushinp (void)
	Empty all the keyboard buffers.
void	mutt_flush_macro_to_endcond (void)
	Drop a macro from the input buffer.
struct KeyEvent	mutt_getch (GetChFlags flags)
	Read a character from the input buffer.
int	mutt_monitor_getch (void)
	Get a character and poll the filesystem monitor.
void	mutt_push_macro_event (int ch, int op)
	Add the character/operation to the macro buffer.
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.

Variables
struct KeyEventArray	MacroEvents
	These are used for macros and exec/push commands.
struct KeyEventArray	UngetKeyEvents
	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.h.

Macro Definition Documentation

GETCH_NO_FLAGS

#define GETCH_NO_FLAGS   0

No flags are set.

Definition at line 34 of file get.h.

GETCH_IGNORE_MACRO

#define GETCH_IGNORE_MACRO   (1 << 0)

Don't use MacroEvents.

Definition at line 35 of file get.h.

KEY_GATHER_NO_MATCH

#define KEY_GATHER_NO_MATCH   0

No bindings match the search string.

Definition at line 38 of file get.h.

KEY_GATHER_MATCH

#define KEY_GATHER_MATCH   (1 << 0)

Binding matches the search string.

Definition at line 39 of file get.h.

KEY_GATHER_LONGER

#define KEY_GATHER_LONGER   (1 << 1)

No bindings match, but longer strings might.

Definition at line 40 of file get.h.

MFF_NO_FLAGS

#define MFF_NO_FLAGS   0

No flags are set.

Definition at line 43 of file get.h.

MFF_DEPRECATED

#define MFF_DEPRECATED   (1 << 1)

Redraw the pager.

Definition at line 44 of file get.h.

Typedef Documentation

GetChFlags

typedef uint8_t GetChFlags

Flags for mutt_getch(), e.g. GETCH_NO_FLAGS.

Definition at line 33 of file get.h.

KeyGatherFlags

typedef uint8_t KeyGatherFlags

Flags for gather_functions(), e.g. KEY_GATHER_NO_MATCH.

Definition at line 37 of file get.h.

MenuFuncFlags

typedef uint8_t MenuFuncFlags

Flags, e.g. MFF_DEPRECATED.

Definition at line 42 of file get.h.

Function Documentation

ARRAY_HEAD() [1/2]

ARRAY_HEAD	(	KeyEventArray	,
		struct KeyEvent	)

ARRAY_HEAD() [2/2]

ARRAY_HEAD	(	KeymapMatchArray	,
		struct KeymapMatch	)

Here is the call graph for this function:

array_add()

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

Add an event to the end of the array.

Parameters

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

Definition at line 95 of file get.c.

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

Here is the caller graph for this function:

array_pop()

struct KeyEvent * array_pop

(

struct KeyEventArray *

a

)

Remove an event from the array.

Parameters

a

Array

Return values

ptr

Event

Definition at line 77 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_to_endcond()

void array_to_endcond

(

struct KeyEventArray *

a

)

Clear the array until an OP_END_COND.

Parameters

a

Array

Definition at line 105 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:

gather_functions()

KeyGatherFlags gather_functions	(	const struct MenuDefinition *	md,
		const keycode_t *	keys,
		int	key_len,
		struct KeymapMatchArray *	kma )

Find functions whose keybindings match.

Parameters

[in]	md	Menu Definition of all valid functions
[in]	keys	User-entered key string to match
[in]	key_len	Length of key string
[out]	kma	Array for the results

Return values

flags

Results, e.g. KEY_GATHER_MATCH

Definition at line 383 of file get.c.

{
  if (!md || !keys || !kma)
    return 0;
 
  struct SubMenu **smp = NULL;
  KeyGatherFlags flags = KEY_GATHER_NO_MATCH;
 
  ARRAY_FOREACH(smp, &md->submenus)
  {
    struct Keymap *km = NULL;
 
    STAILQ_FOREACH(km, &(*smp)->keymaps, entries)
    {
      bool match = true;
 
      for (int i = 0; i < key_len; i++)
      {
        if (keys[i] != km->keys[i])
        {
          match = false;
          break;
        }
      }
 
      if (match)
      {
        KeyGatherFlags fmatch = KEY_GATHER_NO_MATCH;
        if (km->len == key_len)
          fmatch = KEY_GATHER_MATCH;
        else
          fmatch = KEY_GATHER_LONGER;
 
        flags |= fmatch;
 
        struct KeymapMatch kmatch = { md->id, fmatch, km };
        ARRAY_ADD(kma, kmatch);
      }
    }
  }
 
  return flags;
}

Here is the caller graph for this function:

generic_tokenize_push_string()

void generic_tokenize_push_string

(

char *

s

)

Parse and queue a 'push' command.

Parameters

s	String to push into the key queue

Parses s for <function> syntax and adds the whole sequence the macro buffer.

Definition at line 309 of file get.c.

{
  char *pp = NULL;
  char *p = s + mutt_str_len(s) - 1;
  size_t l;
  int i, op = OP_NULL;
 
  while (p >= s)
  {
    /* if we see something like "<PageUp>", look to see if it is a real
     * function name and return the corresponding value */
    if (*p == '>')
    {
      for (pp = p - 1; pp >= s && *pp != '<'; pp--)
        ; // do nothing
 
      if (pp >= s)
      {
        i = parse_fkey(pp);
        if (i > 0)
        {
          mutt_push_macro_event(KEY_F(i), 0);
          p = pp - 1;
          continue;
        }
 
        l = p - pp + 1;
        for (i = 0; KeyNames[i].name; i++)
        {
          if (mutt_istrn_equal(pp, KeyNames[i].name, l))
            break;
        }
        if (KeyNames[i].name)
        {
          /* found a match */
          mutt_push_macro_event(KeyNames[i].value, 0);
          p = pp - 1;
          continue;
        }
 
        /* See if it is a valid command
         * skip the '<' and the '>' when comparing */
        struct Buffer *buf = buf_pool_get();
        buf_strcpy_n(buf, pp + 1, l - 2);
 
        for (enum MenuType j = 0; j < MENU_MAX; j++)
        {
          op = km_get_op_menu(j, buf_string(buf));
          if (op != OP_NULL)
            break;
        }
 
        buf_pool_release(&buf);
 
        if (op != OP_NULL)
        {
          mutt_push_macro_event(0, op);
          p = pp - 1;
          continue;
        }
      }
    }
    mutt_push_macro_event((unsigned char) *p--, 0); /* independent 8 bits chars */
  }
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_dokey()

struct KeyEvent km_dokey	(	const struct MenuDefinition *	md,
		GetChFlags	flags )

Determine what a keypress should do.

Parameters

md	Menu Definition
flags	Flags, e.g. GETCH_IGNORE_MACRO

Return values

ptr

Event

Definition at line 434 of file get.c.

{
  struct KeyEvent event = { 0, OP_NULL };
  int pos = 0;
  keycode_t keys[MAX_SEQ] = { 0 };
 
  if (!md)
    return event;
 
  for (int n = 0; n < MaxKeyLoop; n++)
  {
    event = mutt_getch(flags);
    mutt_debug(LL_DEBUG1, "KEY: \n");
 
    // abort, timeout, repaint
    if (event.op < OP_NULL)
    {
      mutt_debug(LL_DEBUG1, "KEY: getch() %s\n", opcodes_get_name(event.op));
      return event;
    }
 
    mutt_debug(LL_DEBUG1, "KEY: getch() '%c'\n", isprint(event.ch) ? event.ch : '?');
 
    keys[pos] = event.ch;
    struct KeymapMatchArray kma = ARRAY_HEAD_INITIALIZER;
    KeyGatherFlags kfg = gather_functions(md, keys, pos + 1, &kma);
 
    mutt_debug(LL_DEBUG1, "KEY: flags = %x\n", kfg);
 
    if (kfg == KEY_GATHER_NO_MATCH)
    {
      mutt_debug(LL_DEBUG1, "KEY: \033[1;31mFAIL1: ('%c', %s)\033[0m\n",
                 isprint(event.ch) ? event.ch : '?', opcodes_get_name(event.op));
      return event;
    }
 
    if ((kfg & KEY_GATHER_MATCH) == KEY_GATHER_MATCH)
    {
      struct KeymapMatch *kmatch = NULL;
 
      ARRAY_FOREACH(kmatch, &kma)
      {
        if (kmatch->flags == KEY_GATHER_MATCH)
        {
          struct Keymap *map = kmatch->keymap;
 
          if (map->op != OP_MACRO)
          {
            mutt_debug(LL_DEBUG1, "KEY: \033[1;32mSUCCESS: ('%c', %s)\033[0m\n",
                       isprint(event.ch) ? event.ch : '?', opcodes_get_name(map->op));
            ARRAY_FREE(&kma);
            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)
          {
            ARRAY_FREE(&kma);
            return (struct KeyEvent) { event.ch, OP_NULL };
          }
 
          generic_tokenize_push_string(map->macro);
          pos = 0;
          ARRAY_FREE(&kma);
          break;
        }
      }
    }
    else
    {
      mutt_debug(LL_DEBUG1, "KEY: \033[1;33mLONGER: getch() '%c'\033[0m\n",
                 isprint(event.ch) ? event.ch : '?');
      pos++;
    }
 
    ARRAY_FREE(&kma);
  }
 
  mutt_flushinp();
  mutt_error(_("Macro loop detected"));
  return (struct KeyEvent) { '\0', OP_ABORT };
}

Here is the call graph for this function:

Here is the caller graph for this function:

km_error_key()

void km_error_key

(

const struct MenuDefinition *

md

)

Handle an unbound key sequence.

Parameters

md	Menu Definition

Definition at line 285 of file get.c.

{
  if (!md)
    return;
 
  struct Keymap *key = km_find_func(md, OP_HELP);
  if (!key)
  {
    mutt_error(_("Key is not bound"));
    return;
  }
 
  struct Buffer *buf = buf_pool_get();
  keymap_expand_key(key, buf);
  mutt_error(_("Key is not bound.  Press '%s' for help."), buf_string(buf));
  buf_pool_release(&buf);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mutt_flushinp()

void mutt_flushinp

(

void

)

Empty all the keyboard buffers.

Definition at line 65 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:

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 157 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_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:

1. UngetKeyEvents buffer
2. MacroEvents buffer
3. Keyboard

This function can return:

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

Definition at line 201 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 (!OptGui)
    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(STDIN_FILENO)) // 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:

mutt_monitor_getch()

int mutt_monitor_getch

(

void

)

Get a character and poll the filesystem monitor.

Return values

num	Character pressed
ERR	Timeout

Definition at line 168 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_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 146 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_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 122 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 133 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:

Variable Documentation

MacroEvents

struct KeyEventArray MacroEvents

extern

These are used for macros and exec/push commands.

They can be temporarily ignored by passing GETCH_IGNORE_MACRO

Definition at line 56 of file get.c.

UngetKeyEvents

struct KeyEventArray UngetKeyEvents

extern

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

Definition at line 60 of file get.c.