Function: x-popup-dialog

x-popup-dialog is a function defined in menu.c.

Signature

(x-popup-dialog POSITION CONTENTS &optional HEADER)

Documentation

Pop up a dialog box and return user's selection.

POSITION specifies which frame to use. This is normally a mouse button event or a window or frame. If POSITION is t, it means to use the frame the mouse is on. The dialog box appears in the middle of the specified frame.

CONTENTS specifies the alternatives to display in the dialog box. It is a list of the form (DIALOG ITEM1 ITEM2...). Each ITEM is a cons cell (STRING . VALUE). The return value is VALUE from the chosen item.

An ITEM may also be just a string--that makes a nonselectable item. An ITEM may also be nil--that means to put all preceding items on the left of the dialog box and all following items on the right.
(By default, approximately half appear on each side.)

If HEADER is non-nil, the frame title for the box is "Information", otherwise it is "Question".

If the user gets rid of the dialog box without making a valid choice, for instance using the window manager, then this produces a quit and x-popup-dialog does not return.

Probably introduced at or before Emacs version 19.23.

Source Code

// Defined in /usr/src/emacs/src/menu.c
{
  struct frame *f = NULL;
  Lisp_Object window;

  /* Decode the first argument: find the window or frame to use.  */
  if (EQ (position, Qt)
      || (CONSP (position) && (EQ (XCAR (position), Qmenu_bar)
			       || EQ (XCAR (position), Qtab_bar)
			       || EQ (XCAR (position), Qtool_bar))))
    window = selected_window;
  else if (CONSP (position))
    {
      Lisp_Object tem = XCAR (position);
      if (CONSP (tem))
	window = Fcar (XCDR (position));
      else
	{
	  tem = Fcar (XCDR (position));  /* EVENT_START (position) */
	  window = Fcar (tem);	     /* POSN_WINDOW (tem) */
	}
    }
  else if (WINDOWP (position) || FRAMEP (position))
    window = position;
  else
    window = Qnil;

  /* Decode where to put the menu.  */

  if (FRAMEP (window))
    f = XFRAME (window);
  else if (WINDOWP (window))
    {
      CHECK_LIVE_WINDOW (window);
      f = XFRAME (WINDOW_FRAME (XWINDOW (window)));
    }
  else
    /* ??? Not really clean; should be CHECK_WINDOW_OR_FRAME,
       but I don't want to make one now.  */
    CHECK_WINDOW (window);

  /* Note that xw_popup_dialog can call menu code, so
     Vmenu_updating_frame should be set (Bug#17891).  */
  eassume (f && FRAME_LIVE_P (f));
  XSETFRAME (Vmenu_updating_frame, f);

  /* Force a redisplay before showing the dialog.  If a frame is created
     just before showing the dialog, its contents may not have been fully
     drawn, as this depends on timing of events from the X server.  Redisplay
     is not done when a dialog is shown.  If redisplay could be done in the
     X event loop (i.e. the X event loop does not run in a signal handler)
     this would not be needed.

     Do this before creating the widget value that points to Lisp
     string contents, because Fredisplay may GC and relocate them.  */
  Fredisplay (Qt);

  /* Display the popup dialog by a terminal-specific hook ... */
  if (FRAME_TERMINAL (f)->popup_dialog_hook)
    {
      Lisp_Object selection
	= FRAME_TERMINAL (f)->popup_dialog_hook (f, header, contents);
#ifdef HAVE_NTGUI
      /* NTGUI supports only simple dialogs with Yes/No choices.  For
	 other dialogs, it returns the symbol 'unsupported--w32-dialog',
	 as a signal for the caller to fall back to the emulation code.  */
      if (!EQ (selection, Qunsupported__w32_dialog))
#endif
	return selection;
    }
  /* ... or emulate it with a menu.  */
  return emulate_dialog_with_menu (f, contents);
}