From 4189d0ef7bf935fb8e6ab941e93d591be654ddac Mon Sep 17 00:00:00 2001 From: Martin Rudalics Date: Sun, 29 Oct 2017 11:35:32 +0100 Subject: [PATCH] Fix minibuffer window related docs and strings (Bug#28978) * src/frame.c (Vdefault_minibuffer_frame): Fix doc-string. * src/window.c (Fminibuffer_selected_window): Fix doc-string. * doc/lispref/frames.texi (Buffer Parameters): Rewrite description of `minibuffer' parameter. * doc/lispref/minibuf.texi (Minibuffer Windows): Reorder entries and partly rewrite section. (Minibuffer Misc): Clarify description of `minibuffer-selected-window'. * etc/NEWS: Mention new semantics of 'minibuffer' frame parameter. --- doc/lispref/frames.texi | 11 ++++++++-- doc/lispref/minibuf.texi | 45 ++++++++++++++++++++++------------------ etc/NEWS | 5 +++++ src/frame.c | 15 +++++--------- src/window.c | 2 +- 5 files changed, 45 insertions(+), 33 deletions(-) diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index ad853418ac4..5ea7125882f 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1850,8 +1850,14 @@ yes, @code{nil} means no, @code{only} means this frame is just a minibuffer. If the value is a minibuffer window (in some other frame), the frame uses that minibuffer. -This frame parameter takes effect when the frame is created, and can -not be changed afterwards. +This parameter takes effect when the frame is created. If specified as +@code{nil}, Emacs will try to set it to the minibuffer window of +@code{default-minibuffer-frame} (@pxref{Minibuffers and Frames}). For +an existing frame, this parameter can be used exclusively to specify +another minibuffer window. It is not allowed to change it from a +minibuffer window to @code{t} and vice-versa, or from @code{t} to +@code{nil}. If the parameter specifies a minibuffer window already, +setting it to @code{nil} has no effect. @vindex buffer-predicate, a frame parameter @item buffer-predicate @@ -1872,6 +1878,7 @@ most-recently-selected first. If non-@code{nil}, this frame's window is never split automatically. @end table + @node Frame Interaction Parameters @subsubsection Frame Interaction Parameters @cindex frame interaction parameters diff --git a/doc/lispref/minibuf.texi b/doc/lispref/minibuf.texi index 1ece8996008..db69e7d8919 100644 --- a/doc/lispref/minibuf.texi +++ b/doc/lispref/minibuf.texi @@ -2256,39 +2256,44 @@ contents of the minibuffer before the point. These functions access and select minibuffer windows, test whether they are active and control how they get resized. -@defun active-minibuffer-window -This function returns the currently active minibuffer window, or -@code{nil} if there is none. -@end defun - @defun minibuffer-window &optional frame @anchor{Definition of minibuffer-window} This function returns the minibuffer window used for frame @var{frame}. -If @var{frame} is @code{nil}, that stands for the current frame. Note -that the minibuffer window used by a frame need not be part of that +If @var{frame} is @code{nil}, that stands for the selected frame. + +Note that the minibuffer window used by a frame need not be part of that frame---a frame that has no minibuffer of its own necessarily uses some -other frame's minibuffer window. +other frame's minibuffer window. The minibuffer window of a +minibuffer-less frame can be changed by setting that frame's +@code{minibuffer} frame parameter (@pxref{Buffer Parameters}). @end defun @defun set-minibuffer-window window This function specifies @var{window} as the minibuffer window to use. This affects where the minibuffer is displayed if you put text in it -without invoking the usual minibuffer commands. It has no effect on -the usual minibuffer input functions because they all start by -choosing the minibuffer window according to the current frame. +without invoking the usual minibuffer commands. It has no effect on the +usual minibuffer input functions because they all start by choosing the +minibuffer window according to the selected frame. @end defun @c Emacs 19 feature @defun window-minibuffer-p &optional window This function returns non-@code{nil} if @var{window} is a minibuffer -window. -@var{window} defaults to the selected window. +window. @var{window} defaults to the selected window. @end defun -It is not correct to determine whether a given window is a minibuffer by -comparing it with the result of @code{(minibuffer-window)}, because -there can be more than one minibuffer window if there is more than one -frame. +The following function returns the window showing the currently active +minibuffer. + +@defun active-minibuffer-window +This function returns the currently active minibuffer window, or +@code{nil} if there is none. +@end defun + +It is not sufficient to determine whether a given window is the +currently active minibuffer window by comparing it with the result of +@code{(minibuffer-window)}, because there can be more than one +minibuffer window if there is more than one frame. @defun minibuffer-window-active-p window This function returns non-@code{nil} if @var{window} is the currently @@ -2439,9 +2444,9 @@ minibuffer, it scrolls this window. @end defvar @defun minibuffer-selected-window -This function returns the window that was selected when the -minibuffer was entered. If selected window is not a minibuffer -window, it returns @code{nil}. +This function returns the window that was selected at the moment the +minibuffer was entered. If the currently selected window is not a +minibuffer window, it returns @code{nil}. @end defun @defopt max-mini-window-height diff --git a/etc/NEWS b/etc/NEWS index 357d528924f..1166e81da03 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1814,6 +1814,11 @@ handle fitting a frame to its buffer individually. 'drag-with-mode-line', 'snap-width', 'top-visible' and 'bottom-visible' allow to drag and resize frames with the mouse. ++++ +**** 'minibuffer' is now set to the default minibuffer window when +initially specified as nil and is not reset to nil when initially +specifying a minibuffer window. + *** The new function 'frame-list-z-order' returns a list of all frames in Z (stacking) order. diff --git a/src/frame.c b/src/frame.c index ab801eec9c7..fe1709e6ede 100644 --- a/src/frame.c +++ b/src/frame.c @@ -5895,16 +5895,11 @@ or call the function `tool-bar-mode'. */); #endif DEFVAR_KBOARD ("default-minibuffer-frame", Vdefault_minibuffer_frame, - doc: /* Minibufferless frames use this frame's minibuffer. -Emacs cannot create minibufferless frames unless this is set to an -appropriate surrogate. - -Emacs consults this variable only when creating minibufferless -frames; once the frame is created, it sticks with its assigned -minibuffer, no matter what this variable is set to. This means that -this variable doesn't necessarily say anything meaningful about the -current set of frames, or where the minibuffer is currently being -displayed. + doc: /* Minibuffer-less frames by default use this frame's minibuffer. +Emacs consults this variable only when creating a minibuffer-less frame +and no explicit minibuffer window has been specified for that frame via +the `minibuffer' frame parameter. Once such a frame has been created, +setting this variable does not change that frame's previous association. This variable is local to the current terminal and cannot be buffer-local. */); diff --git a/src/window.c b/src/window.c index ba86d73911f..f08979e1320 100644 --- a/src/window.c +++ b/src/window.c @@ -5833,7 +5833,7 @@ by this function. This happens in an interactive call. */) DEFUN ("minibuffer-selected-window", Fminibuffer_selected_window, Sminibuffer_selected_window, 0, 0, 0, doc: /* Return the window which was selected when entering the minibuffer. -Returns nil, if selected window is not a minibuffer window. */) +Return nil if the selected window is not a minibuffer window. */) (void) { if (minibuf_level > 0