elisp: Intro to Minibuffers
19.1 Introduction to Minibuffers
================================
In most ways, a minibuffer is a normal Emacs buffer. Most operations
_within_ a buffer, such as editing commands, work normally in a
minibuffer. However, many operations for managing buffers do not apply
to minibuffers. The name of a minibuffer always has the form
‘ *Minibuf-NUMBER*’, and it cannot be changed. Minibuffers are
displayed only in special windows used only for minibuffers; these
windows always appear at the bottom of a frame. (Sometimes frames have
no minibuffer window, and sometimes a special kind of frame contains
nothing but a minibuffer window; see Minibuffers and Frames.)
The text in the minibuffer always starts with the “prompt string”,
the text that was specified by the program that is using the minibuffer
to tell the user what sort of input to type. This text is marked
read-only so you won’t accidentally delete or change it. It is also
marked as a field (Fields), so that certain motion functions,
including ‘beginning-of-line’, ‘forward-word’, ‘forward-sentence’, and
‘forward-paragraph’, stop at the boundary between the prompt and the
actual text.
The minibuffer’s window is normally a single line; it grows
automatically if the contents require more space. Whilst it is active,
you can explicitly resize it temporarily with the window sizing
commands; it reverts to its normal size when the minibuffer is exited.
When the minibuffer is not active, you can resize it permanently by
using the window sizing commands in the frame’s other window, or
dragging the mode line with the mouse. (Due to details of the current
implementation, for this to work ‘resize-mini-windows’ must be ‘nil’.)
If the frame contains just a minibuffer, you can change the minibuffer’s
size by changing the frame’s size.
Use of the minibuffer reads input events, and that alters the values
of variables such as ‘this-command’ and ‘last-command’ (Command
Loop Info). Your program should bind them around the code that uses
the minibuffer, if you do not want that to change them.
Under some circumstances, a command can use a minibuffer even if
there is an active minibuffer; such a minibuffer is called a “recursive
minibuffer”. The first minibuffer is named ‘ *Minibuf-1*’. Recursive
minibuffers are named by incrementing the number at the end of the name.
(The names begin with a space so that they won’t show up in normal
buffer lists.) Of several recursive minibuffers, the innermost (or most
recently entered) is the active minibuffer. We usually call this _the_
minibuffer. You can permit or forbid recursive minibuffers by setting
the variable ‘enable-recursive-minibuffers’, or by putting properties of
that name on command symbols (Recursive Mini.)
Like other buffers, a minibuffer uses a local keymap (
Keymaps) to specify special key bindings. The function that invokes
the minibuffer also sets up its local map according to the job to be
done. Text from Minibuffer, for the non-completion minibuffer
local maps. Completion Commands, for the minibuffer local maps
for completion.
When a minibuffer is inactive, its major mode is
‘minibuffer-inactive-mode’, with keymap ‘minibuffer-inactive-mode-map’.
This is only really useful if the minibuffer is in a separate frame.
Minibuffers and Frames.
When Emacs is running in batch mode, any request to read from the
minibuffer actually reads a line from the standard input descriptor that
was supplied when Emacs was started. This supports only basic input:
none of the special minibuffer features (history, completion, etc.) are
available in batch mode.