GUI: Message Windows

The Message Window is a one-line interactive window at the bottom of the screen. More...

Functions
int	mw_get_field (const char *prompt, struct Buffer *buf, CompletionFlags complete, enum HistoryClass hclass, const struct CompleteOps *comp_api, void *cdata)
	Ask the user for a string -.
int	mw_change_flag (struct Mailbox *m, struct EmailArray *ea, bool bf)
	Change the flag on a Message -.
int	mw_enter_fname (const char *prompt, struct Buffer *fname, bool mailbox, struct Mailbox *m, bool multiple, char ***files, int *numfiles, SelectFileFlags flags)
	Ask the user to select a file -.
void	mw_what_key (void)
	Display the value of a key -.
int	mw_multi_choice (const char *prompt, const char *letters)
	Offer the user a multiple choice question -.
static enum QuadOption	mw_yesorno (const char *prompt, enum QuadOption def, struct ConfigDef *cdef, GetChFlags flags)
	Ask the user a Yes/No question offering help -.

Detailed Description

The Message Window is a one-line interactive window at the bottom of the screen.

It's used for asking the user questions, displaying messages and for a progress bar.

Behaviour

The Message Window has two modes of behaviour: passive, active.

Passive

Most of the time, the Message Window will be passively displaying messages to the user (or empty). This is characterised by the Window focus being somewhere else. In this mode, the Message Window is responsible for drawing itself.

See also

mutt_message(), mutt_error()

Active

The Message Window can be hijacked by other code to be used for user interaction, commonly for simple questions, "Are you sure? [Y/n]". In this active state the Window will have focus and it's the responsibility of the hijacker to perform the drawing.

See also

query_yesorno(), Progress Bar

Windows

Name	Type	Constructor
Message Window	WT_MESSAGE	msgwin_new()

Parent

• Message Container

Children

• None

Data

• MsgWinWindowData

The Message Window caches the formatted string.

Events

Once constructed, it is controlled by the following events:

Event Type	Handler
NT_WINDOW	msgwin_window_observer()
MuttWindow::recalc()	msgwin_recalc()
MuttWindow::repaint()	msgwin_repaint()

Function Documentation

mw_get_field()

int mw_get_field	(	const char *	prompt,
		struct Buffer *	buf,
		CompletionFlags	complete,
		enum HistoryClass	hclass,
		const struct CompleteOps *	comp_api,
		void *	cdata
	)

Ask the user for a string -.

Parameters

[in]	prompt	Prompt
[in]	buf	Buffer for the result
[in]	hclass	History class to use
[in]	complete	Flags, see CompletionFlags
[in]	comp_api	Auto-completion API
[in]	cdata	Auto-completion private data

Return values

0	Selection made
-1	Aborted

This function uses the message window.

Ask the user to enter a free-form string. This function supports auto-completion and saves the result to the history.

It also supports readline style text editing. See OpEditor for a list of functions.

Definition at line 273 of file window.c.

{
  struct MuttWindow *win = mutt_window_new(WT_CUSTOM, MUTT_WIN_ORIENT_VERTICAL, MUTT_WIN_SIZE_FIXED,
                                           MUTT_WIN_SIZE_UNLIMITED, 1);
 
  GetChFlags flags = GETCH_NO_FLAGS;
  if (complete & MUTT_COMP_UNBUFFERED)
    flags = GETCH_IGNORE_MACRO;
 
  int rc = 0;
 
  struct EnterState *es = enter_state_new();
 
  win->help_data = EditorHelp;
  win->help_menu = MENU_EDITOR;
 
  msgcont_push_window(win);
  struct MuttWindow *old_focus = window_set_focus(win);
 
  mbstate_t mbstate = { 0 };
  // clang-format off
  struct EnterWindowData wdata = { buf, complete, es, hclass, comp_api, cdata, prompt, ENTER_REDRAW_NONE, (complete & MUTT_COMP_PASS), true, NULL, 0, &mbstate, 0, false, NULL, 0, 0 };
  // clang-format on
 
  win->wdata = &wdata;
  win->wdata_free = NULL; // No need, we hold the data
  win->recalc = enter_recalc;
  win->repaint = enter_repaint;
  win->recursor = enter_recursor;
 
  window_redraw(win);
 
  if (es->wbuf[0] == L'\0')
  {
    /* Initialise wbuf from buf */
    wdata.state->wbuflen = 0;
    wdata.state->lastchar = mutt_mb_mbstowcs(&wdata.state->wbuf, &wdata.state->wbuflen,
                                             0, buf_string(wdata.buffer));
    wdata.redraw = ENTER_REDRAW_INIT;
  }
  else
  {
    wdata.redraw = ENTER_REDRAW_LINE;
    wdata.first = false;
  }
 
  do
  {
    memset(&mbstate, 0, sizeof(mbstate));
 
    do
    {
      if (wdata.redraw != ENTER_REDRAW_NONE)
        win->actions |= WA_REPAINT;
 
      window_redraw(NULL);
      struct KeyEvent event = km_dokey_event(MENU_EDITOR, flags);
      if ((event.op == OP_TIMEOUT) || (event.op == OP_REPAINT))
      {
        continue;
      }
 
      if (event.op == OP_ABORT)
      {
        rc = -1;
        goto bye;
      }
 
      if (event.op == OP_NULL)
      {
        if (complete & MUTT_COMP_PASS)
          mutt_debug(LL_DEBUG5, "Got char *\n");
        else
          mutt_debug(LL_DEBUG5, "Got char %c (0x%02x)\n", event.ch, event.ch);
 
        if (self_insert(&wdata, event.ch))
        {
          rc = 0;
          goto bye;
        }
        win->actions |= WA_REPAINT;
        continue;
      }
      else
      {
        mutt_debug(LL_DEBUG1, "Got op %s (%d)\n", opcodes_get_name(event.op),
                   event.op);
      }
 
      wdata.first = false;
      if ((event.op != OP_EDITOR_COMPLETE) && (event.op != OP_EDITOR_COMPLETE_QUERY))
        wdata.tabs = 0;
      wdata.redraw = ENTER_REDRAW_LINE;
      int rc_disp = enter_function_dispatcher(win, event.op);
      switch (rc_disp)
      {
        case FR_NO_ACTION:
        {
          if (self_insert(&wdata, event.ch))
          {
            rc = 0;
            goto bye;
          }
          break;
        }
        case FR_CONTINUE: // repaint
          rc = 1;
          goto bye;
 
        case FR_SUCCESS:
          rc = 0;
          break;
 
        case FR_UNKNOWN:
        case FR_ERROR:
        default:
          mutt_beep(false);
      }
    } while (!wdata.done);
 
  bye:
    mutt_hist_reset_state(wdata.hclass);
    FREE(&wdata.tempbuf);
    completion_data_free(&wdata.cd);
  } while (rc == 1);
 
  msgcont_pop_window();
  window_set_focus(old_focus);
  mutt_window_free(&win);
 
  if (rc == 0)
    buf_fix_dptr(buf);
  else
    buf_reset(buf);
 
  enter_state_free(&es);
 
  return rc;
}

Here is the call graph for this function:

mw_change_flag()

int mw_change_flag	(	struct Mailbox *	m,
		struct EmailArray *	ea,
		bool	bf
	)

Change the flag on a Message -.

Parameters

m	Mailbox
ea	Array of Emails to change
bf	true: set the flag; false: clear the flag

Return values

0	Success
-1	Failure

This function uses the message window.

Ask the user which flag they'd like to set/clear, e.g. Clear flag? (D/N/O/r/!):

Definition at line 454 of file flags.c.

{
  if (!m || !ea || ARRAY_EMPTY(ea))
    return -1;
 
  // blank window (0, 0)
  struct MuttWindow *win = msgwin_new(true);
  if (!win)
    return -1;
 
  char prompt[256] = { 0 };
  snprintf(prompt, sizeof(prompt),
           "%s? (D/N/O/r/*/!): ", bf ? _("Set flag") : _("Clear flag"));
  msgwin_set_text(win, prompt, MT_COLOR_PROMPT);
 
  msgcont_push_window(win);
  struct MuttWindow *old_focus = window_set_focus(win);
  window_redraw(win);
 
  struct KeyEvent event = { 0, OP_NULL };
  do
  {
    window_redraw(NULL);
    event = mutt_getch(GETCH_NO_FLAGS);
  } while ((event.op == OP_TIMEOUT) || (event.op == OP_REPAINT));
 
  win = msgcont_pop_window();
  window_set_focus(old_focus);
  mutt_window_free(&win);
 
  if (event.op == OP_ABORT)
    return -1;
 
  enum MessageType flag = MUTT_NONE;
  switch (event.ch)
  {
    case 'd':
    case 'D':
      if (!bf)
        mutt_emails_set_flag(m, ea, MUTT_PURGE, bf);
      flag = MUTT_DELETE;
      break;
 
    case 'N':
    case 'n':
      flag = MUTT_NEW;
      break;
 
    case 'o':
    case 'O':
      mutt_emails_set_flag(m, ea, MUTT_READ, !bf);
      flag = MUTT_OLD;
      break;
 
    case 'r':
    case 'R':
      flag = MUTT_REPLIED;
      break;
 
    case '*':
      flag = MUTT_TAG;
      break;
 
    case '!':
      flag = MUTT_FLAG;
      break;
 
    default:
      mutt_beep(false);
      return -1;
  }
 
  mutt_emails_set_flag(m, ea, flag, bf);
  return 0;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mw_enter_fname()

int mw_enter_fname	(	const char *	prompt,
		struct Buffer *	fname,
		bool	mailbox,
		struct Mailbox *	m,
		bool	multiple,
		char ***	files,
		int *	numfiles,
		SelectFileFlags	flags
	)

Ask the user to select a file -.

Parameters

[in]	prompt	Prompt
[in]	fname	Buffer for the result
[in]	mailbox	If true, select mailboxes
[in]	multiple	Allow multiple selections
[in]	m	Mailbox
[out]	files	List of files selected
[out]	numfiles	Number of files selected
[in]	flags	Flags, see SelectFileFlags

Return values

0	Success
-1	Error

This function uses the message window.

Allow the user to enter a filename. If they hit '?' then the browser will be started. See: dlg_browser()

Definition at line 237 of file curs_lib.c.

{
  struct MuttWindow *win = msgwin_new(true);
  if (!win)
    return -1;
 
  int rc = -1;
 
  struct Buffer *text = buf_pool_get();
  const struct AttrColor *ac_normal = simple_color_get(MT_COLOR_NORMAL);
  const struct AttrColor *ac_prompt = merged_color_overlay(ac_normal,
                                                           simple_color_get(MT_COLOR_PROMPT));
 
  msgwin_add_text(win, prompt, ac_prompt);
  msgwin_add_text(win, _(" ('?' for list): "), ac_prompt);
  if (!buf_is_empty(fname))
    msgwin_add_text(win, buf_string(fname), ac_normal);
 
  msgcont_push_window(win);
  struct MuttWindow *old_focus = window_set_focus(win);
 
  struct KeyEvent event = { 0, OP_NULL };
  do
  {
    window_redraw(NULL);
    event = mutt_getch(GETCH_NO_FLAGS);
  } while ((event.op == OP_TIMEOUT) || (event.op == OP_REPAINT));
 
  mutt_refresh();
  win = msgcont_pop_window();
  window_set_focus(old_focus);
  mutt_window_free(&win);
 
  if (event.ch < 0)
    goto done;
 
  if (event.ch == '?')
  {
    buf_reset(fname);
 
    if (flags == MUTT_SEL_NO_FLAGS)
      flags = MUTT_SEL_FOLDER;
    if (multiple)
      flags |= MUTT_SEL_MULTI;
    if (mailbox)
      flags |= MUTT_SEL_MAILBOX;
    dlg_browser(fname, flags, m, files, numfiles);
  }
  else
  {
    char *pc = NULL;
    mutt_str_asprintf(&pc, "%s: ", prompt);
    if (event.op == OP_NULL)
      mutt_unget_ch(event.ch);
    else
      mutt_unget_op(event.op);
 
    buf_alloc(fname, 1024);
    struct FileCompletionData cdata = { multiple, m, files, numfiles };
    enum HistoryClass hclass = mailbox ? HC_MAILBOX : HC_FILE;
    if (mw_get_field(pc, fname, MUTT_COMP_CLEAR, hclass, &CompleteMailboxOps, &cdata) != 0)
    {
      buf_reset(fname);
    }
    FREE(&pc);
  }
 
  rc = 0;
 
done:
  buf_pool_release(&text);
  return rc;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mw_what_key()

void mw_what_key

(

void

)

Display the value of a key -.

This function uses the message window.

Displays the octal value back to the user. e.g. Char = h, Octal = 150, Decimal = 104

Press the $abort_key (default Ctrl-G) to exit.

Definition at line 501 of file curs_lib.c.

{
  struct MuttWindow *win = msgwin_new(true);
  if (!win)
    return;
 
  struct Buffer *key = buf_pool_get();
  struct Buffer *prompt = buf_pool_get();
  struct Buffer *text = buf_pool_get();
 
  km_keyname(AbortKey, key);
 
  buf_printf(prompt, _("Enter keys (%s to abort): "), buf_string(key));
  msgwin_set_text(win, buf_string(prompt), MT_COLOR_PROMPT);
 
  msgcont_push_window(win);
  struct MuttWindow *old_focus = window_set_focus(win);
  window_redraw(win);
 
  const struct AttrColor *ac_normal = simple_color_get(MT_COLOR_NORMAL);
  const struct AttrColor *ac_prompt = simple_color_get(MT_COLOR_PROMPT);
 
  // ---------------------------------------------------------------------------
  // Event Loop
  timeout(1000); // 1 second
  while (true)
  {
    int ch = getch();
    if (ch == AbortKey)
      break;
 
    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);
        window_redraw(NULL);
      }
      else
      {
        notify_send(NeoMutt->notify_timeout, NT_TIMEOUT, 0, NULL);
      }
 
      continue;
    }
 
    msgwin_clear_text(win);
 
    buf_reset(key);
    km_keyname(ch, key);
 
    buf_printf(text, _("Char = %s, Octal = %o, Decimal = %d\n"), buf_string(key), ch, ch);
 
    msgwin_add_text(win, buf_string(text), ac_normal);
    msgwin_add_text(win, buf_string(prompt), ac_prompt);
    msgwin_add_text(win, NULL, NULL);
    window_redraw(NULL);
  }
  // ---------------------------------------------------------------------------
 
  buf_pool_release(&key);
  buf_pool_release(&prompt);
  buf_pool_release(&text);
 
  win = msgcont_pop_window();
  window_set_focus(old_focus);
  mutt_window_free(&win);
}

Here is the call graph for this function:

Here is the caller graph for this function:

mw_multi_choice()

int mw_multi_choice	(	const char *	prompt,
		const char *	letters
	)

Offer the user a multiple choice question -.

Parameters

prompt	Message prompt
letters	Allowable selection keys

Return values

>=1	1-based user selection
-1	Selection aborted

This function uses a message window.

Ask the user a multiple-choice question, using shortcut letters, e.g. PGP (e)ncrypt, (s)ign, sign (a)s, (b)oth, s/(m)ime or (c)lear?

Colours:

• Question: color prompt
• Shortcuts: color options

Definition at line 63 of file question.c.

{
  struct MuttWindow *win = msgwin_new(true);
  if (!win)
    return -1;
 
  int choice = 0;
 
  const struct AttrColor *ac_normal = simple_color_get(MT_COLOR_NORMAL);
  const struct AttrColor *ac_prompt = merged_color_overlay(ac_normal,
                                                           simple_color_get(MT_COLOR_PROMPT));
 
  if (simple_color_is_set(MT_COLOR_OPTIONS))
  {
    const struct AttrColor *ac_opts = merged_color_overlay(ac_prompt,
                                                           simple_color_get(MT_COLOR_OPTIONS));
    char *cur = NULL;
 
    while ((cur = strchr(prompt, '(')))
    {
      // write the part between prompt and cur using MT_COLOR_PROMPT
      msgwin_add_text_n(win, prompt, cur - prompt, ac_prompt);
 
      if (isalnum(cur[1]) && (cur[2] == ')'))
      {
        // we have a single letter within parentheses - MT_COLOR_OPTIONS
        msgwin_add_text_n(win, cur + 1, 1, ac_opts);
        prompt = cur + 3;
      }
      else
      {
        // we have a parenthesis followed by something else
        msgwin_add_text_n(win, cur, 1, ac_prompt);
        prompt = cur + 1;
      }
    }
  }
 
  msgwin_add_text(win, prompt, ac_prompt);
  msgwin_add_text(win, " ", ac_normal);
 
  msgcont_push_window(win);
  struct MuttWindow *old_focus = window_set_focus(win);
  window_redraw(win);
 
  // ---------------------------------------------------------------------------
  // Event Loop
  struct KeyEvent event = { 0, OP_NULL };
  while (true)
  {
    event = mutt_getch(GETCH_NO_FLAGS);
    mutt_debug(LL_DEBUG1, "mw_multi_choice: EVENT(%d,%d)\n", event.ch, event.op);
 
    if (event.op == OP_REPAINT)
      window_redraw(NULL);
 
    if ((event.op == OP_TIMEOUT) || (event.op == OP_REPAINT))
      continue;
 
    if ((event.op == OP_ABORT) || key_is_return(event.ch))
    {
      choice = -1;
      break;
    }
 
    char *p = strchr(letters, event.ch);
    if (p)
    {
      choice = p - letters + 1;
      break;
    }
 
    if ((event.ch > '0') && (event.ch <= '9'))
    {
      choice = event.ch - '0';
      if (choice <= mutt_str_len(letters))
        break;
    }
  }
  // ---------------------------------------------------------------------------
 
  win = msgcont_pop_window();
  window_set_focus(old_focus);
  mutt_window_free(&win);
 
  return choice;
}

Here is the call graph for this function:

Here is the caller graph for this function:

mw_yesorno()

static enum QuadOption mw_yesorno ( const char *  prompt, enum QuadOption  def, struct ConfigDef *  cdef, GetChFlags  flags  )

static

Ask the user a Yes/No question offering help -.

Parameters

prompt	Prompt
def	Default answer, e.g. MUTT_YES
cdef	Config definition for help
flags	mutt_getch Flags, e.g. GETCH_IGNORE_MACRO

Return values

enum	QuadOption, Selection made

This function uses a message window.

Ask the user a yes/no question, using shortcut letters, e.g. Quit NeoMutt? ([yes]/no):

This question can be answered using locale-dependent letters, e.g.

• English, [+1yY] or [-0nN]
• Serbian, [+1yYdDДд] or [-0nNНн]

If a config variable (cdef) is given, then help is offered. The options change to: ([yes]/no/?)

Pressing '?' will show the name and one-line description of the config variable. Additionally, if $help is set, a link to the config's documentation is shown.

Definition at line 174 of file question.c.

{
  struct MuttWindow *win = msgwin_new(true);
  if (!win)
    return MUTT_ABORT;
 
  char *yes = N_("yes");
  char *no = N_("no");
  char *trans_yes = _(yes);
  char *trans_no = _(no);
 
  regex_t reyes = { 0 };
  regex_t reno = { 0 };
 
  bool reyes_ok = false;
  bool reno_ok = false;
 
#ifdef OpenBSD
  /* OpenBSD only supports locale C and UTF-8
   * so there is no suitable base system's locale identification
   * Remove this code immediately if this situation changes! */
  char rexyes[16] = "^[+1YyYy]";
  rexyes[6] = toupper(trans_yes[0]);
  rexyes[7] = tolower(trans_yes[0]);
 
  char rexno[16] = "^[-0NnNn]";
  rexno[6] = toupper(trans_no[0]);
  rexno[7] = tolower(trans_no[0]);
 
  if (REG_COMP(&reyes, rexyes, REG_NOSUB) == 0)
    reyes_ok = true;
 
  if (REG_COMP(&reno, rexno, REG_NOSUB) == 0)
    reno_ok = true;
 
#else
  char *expr = NULL;
  reyes_ok = (expr = nl_langinfo(YESEXPR)) && (expr[0] == '^') &&
             (REG_COMP(&reyes, expr, REG_NOSUB) == 0);
  reno_ok = (expr = nl_langinfo(NOEXPR)) && (expr[0] == '^') &&
            (REG_COMP(&reno, expr, REG_NOSUB) == 0);
#endif
 
  if ((yes != trans_yes) && (no != trans_no) && reyes_ok && reno_ok)
  {
    // If all parts of the translation succeeded...
    yes = trans_yes;
    no = trans_no;
  }
  else
  {
    // otherwise, fallback to English
    if (reyes_ok)
    {
      regfree(&reyes);
      reyes_ok = false;
    }
    if (reno_ok)
    {
      regfree(&reno);
      reno_ok = false;
    }
  }
 
  bool show_help_prompt = cdef;
 
  struct Buffer *text = buf_pool_get();
  buf_printf(text, "%s ([%s]/%s%s): ", prompt, (def == MUTT_YES) ? yes : no,
             (def == MUTT_YES) ? no : yes, show_help_prompt ? "/?" : "");
 
  msgwin_set_text(win, buf_string(text), MT_COLOR_PROMPT);
  msgcont_push_window(win);
  struct MuttWindow *old_focus = window_set_focus(win);
 
  struct KeyEvent event = { 0, OP_NULL };
  window_redraw(NULL);
  while (true)
  {
    event = mutt_getch(flags);
    if ((event.op == OP_TIMEOUT) || (event.op == OP_REPAINT))
    {
      window_redraw(NULL);
      mutt_refresh();
      continue;
    }
 
    if (key_is_return(event.ch))
      break; // Do nothing, use default
 
    if (event.op == OP_ABORT)
    {
      def = MUTT_ABORT;
      break;
    }
 
    char answer[4] = { 0 };
    answer[0] = event.ch;
    if (reyes_ok ? (regexec(&reyes, answer, 0, 0, 0) == 0) : (tolower(event.ch) == 'y'))
    {
      def = MUTT_YES;
      break;
    }
    if (reno_ok ? (regexec(&reno, answer, 0, 0, 0) == 0) : (tolower(event.ch) == 'n'))
    {
      def = MUTT_NO;
      break;
    }
    if (show_help_prompt && (event.ch == '?'))
    {
      show_help_prompt = false;
      msgwin_clear_text(win);
      buf_printf(text, "$%s - %s\n", cdef->name, cdef->docs);
 
      char hyphen[128] = { 0 };
      mutt_str_hyphenate(hyphen, sizeof(hyphen), cdef->name);
      buf_add_printf(text, "https://neomutt.org/guide/reference#%s\n", hyphen);
 
      msgwin_add_text(win, buf_string(text), simple_color_get(MT_COLOR_NORMAL));
 
      buf_printf(text, "%s ([%s]/%s): ", prompt, (def == MUTT_YES) ? yes : no,
                 (def == MUTT_YES) ? no : yes);
      msgwin_add_text(win, buf_string(text), simple_color_get(MT_COLOR_PROMPT));
      msgwin_add_text(win, NULL, NULL);
 
      window_redraw(NULL);
      mutt_refresh();
    }
 
    mutt_beep(false);
  }
 
  win = msgcont_pop_window();
  window_set_focus(old_focus);
  mutt_window_free(&win);
 
  if (reyes_ok)
    regfree(&reyes);
  if (reno_ok)
    regfree(&reno);
 
  buf_pool_release(&text);
  return def;
}

Here is the call graph for this function:

Here is the caller graph for this function: