If you use options that specify window appearance when you invoke Emacs,
they take effect by adding elements to @code{default-frame-alist}. One
exception is @samp{-geometry}, which adds the specified position to
-@code{initial-frame-alist} instead. @xref{Command Arguments,,, emacs,
-The GNU Emacs Manual}.
+@code{initial-frame-alist} instead. @xref{Emacs Invocation,, Command
+Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
@node Window Frame Parameters
@subsection Window Frame Parameters
-Just what parameters a frame has depends on what display mechanism it
+ Just what parameters a frame has depends on what display mechanism it
uses. Here is a table of the parameters that have special meanings in a
window frame; of these, @code{name}, @code{title}, @code{height},
@code{width}, @code{buffer-list} and @code{buffer-predicate} provide
meaningful information in terminal frames, and @code{tty-color-mode}
-is meaningful @emph{only} in terminal frames.
+is meaningful @emph{only} in terminal frames. Frame parameter whose
+values measured in pixels, when used on text-only terminals, count
+characters or lines instead.
@table @code
@item display
@item top
The screen position of the top edge, in pixels, with respect to the
-top edge of the screen. The value may be a positive number @var{pos},
-or a list of the form @code{(+ @var{pos})} which permits specifying a
-negative @var{pos} value.
-
-A negative number @minus{}@var{pos}, or a list of the form @code{(-
-@var{pos})}, actually specifies the position of the bottom edge of the
-window with respect to the bottom edge of the screen. A positive value
-of @var{pos} counts toward the top. @strong{Reminder:} if the
-parameter is a negative integer @minus{}@var{pos}, then @var{pos} is
-positive.
-
-Some window managers ignore program-specified positions. If you want to
-be sure the position you specify is not ignored, specify a
-non-@code{nil} value for the @code{user-position} parameter as well.
+top edge of the screen. It works just like @code{left}, except vertically
+instead of horizontally.
@item icon-left
The screen position of the left edge @emph{of the frame's icon}, in
The width of the frame contents, in characters. (To get the height in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
+@item user-size
+This does for the size parameters @code{height} and @code{width} what
+the @code{user-position} parameter (see above) does for the position
+parameters @code{top} and @code{left}.
+
@item fullscreen
Specify that width, height or both shall be set to the size of the screen.
The value @code{fullwidth} specifies that width shall be the size of the
what selection the user makes.
The argument @var{position} specifies where on the screen to put the
-menu. It can be either a mouse button event (which says to put the menu
-where the user actuated the button) or a list of this form:
+top left corner of the menu. It can be either a mouse button event
+(which says to put the menu where the user actuated the button) or a
+list of this form:
@example
((@var{xoffset} @var{yoffset}) @var{window})
@noindent
where @var{xoffset} and @var{yoffset} are coordinates, measured in
-pixels, counting from the top left corner of @var{window}'s frame.
+pixels, counting from the top left corner of @var{window}. @var{window}
+may be a window or a frame.
If @var{position} is @code{t}, it means to use the current mouse
position. If @var{position} is @code{nil}, it means to precompute the
without actually displaying or popping up the menu.
The argument @var{menu} says what to display in the menu. It can be a
-keymap or a list of keymaps (@pxref{Menu Keymaps}). Alternatively, it
-can have the following form:
+keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
+return value is the list of events corresponding to the user's choice.
+(This list has more than one element if the choice occurred in a
+submenu.) Note that @code{x-popup-menu} does not actually execute the
+command bound to that sequence of events.
+
+Alternatively, @var{menu} can have the following form:
@example
(@var{title} @var{pane1} @var{pane2}...)
where each pane is a list of form
@example
-(@var{title} (@var{line} . @var{item})...)
+(@var{title} @var{item1} @var{item2}...)
@end example
-Each @var{line} should be a string, and each @var{item} should be the
-value to return if that @var{line} is chosen.
+Each item should normally be a cons cell @code{(@var{line} . @var{value})},
+where @var{line} is a string, and @var{value} is the value to return if
+that @var{line} is chosen. An item can also be a string; this makes a
+non-selectable line in the menu.
+
+If the user gets rid of the menu without making a valid choice, for
+instance by clicking the mouse away from a valid choice or by typing
+keyboard input, then this normally results in a quit and
+@code{x-popup-menu} does not return. But if @var{position} is a mouse
+button event (indicating that the user invoked the menu with the
+mouse) then no quit occurs and @code{x-popup-menu} returns @code{nil}.
@end defun
@strong{Usage note:} Don't use @code{x-popup-menu} to display a menu
submenu using @code{x-popup-menu}, it cannot work with the menu bar in
an integrated fashion. This is why all menu bar submenus are
implemented with menu keymaps within the parent menu, and never with
-@code{x-popup-menu}. @xref{Menu Bar},
+@code{x-popup-menu}. @xref{Menu Bar}.
If you want a menu bar submenu to have contents that vary, you should
still use a menu keymap to implement it. To make the contents vary, add
A dialog box is a variant of a pop-up menu---it looks a little
different, it always appears in the center of a frame, and it has just
-one level and one pane. The main use of dialog boxes is for asking
-questions that the user can answer with ``yes'', ``no'', and a few other
-alternatives. The functions @code{y-or-n-p} and @code{yes-or-no-p} use
-dialog boxes instead of the keyboard, when called from commands invoked
-by mouse clicks.
-
-@defun x-popup-dialog position contents
+one level and one or more buttons. The main use of dialog boxes is
+for asking questions that the user can answer with ``yes'', ``no'',
+and a few other alternatives. With a single button, they can also
+force the user to acknowledge important information. The functions
+@code{y-or-n-p} and @code{yes-or-no-p} use dialog boxes instead of the
+keyboard, when called from commands invoked by mouse clicks.
+
+@defun x-popup-dialog position contents &optional header
This function displays a pop-up dialog box and returns an indication of
what selection the user makes. The argument @var{contents} specifies
the alternatives to offer; it has this format:
The return value is @var{value} from the chosen alternative.
-An element of the list may be just a string instead of a cons cell
-@code{(@var{string} . @var{value})}. That makes a box that cannot
-be selected.
+As for @code{x-popup-menu}, an element of the list may be just a
+string instead of a cons cell @code{(@var{string} . @var{value})}.
+That makes a box that cannot be selected.
If @code{nil} appears in the list, it separates the left-hand items from
the right-hand items; items that precede the @code{nil} appear on the
Dialog boxes always appear in the center of a frame; the argument
@var{position} specifies which frame. The possible values are as in
-@code{x-popup-menu}, but the precise coordinates don't matter; only the
-frame matters.
+@code{x-popup-menu}, but the precise coordinates or the individual
+window don't matter; only the frame matters.
+
+If @var{header} is non-@code{nil}, the frame title for the box is
+@samp{Information}, otherwise it is @samp{Question}. The former is used
+for @code{message-box} (@pxref{The Echo Area}).
In some configurations, Emacs cannot display a real dialog box; so
instead it displays the same items in a pop-up menu in the center of the
frame.
+
+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
+@code{x-popup-dialog} does not return.
@end defun
@node Pointer Shapes
@node Color Names
@section Color Names
+@cindex color names
+@cindex specify color
+@cindex numerical RGB color specification
+ A color name is text (usually in a string) that specifies a color.
+Symbolic names such as @samp{black}, @samp{white}, @samp{red}, etc.,
+are allowed; use @kbd{M-x list-colors-display} to see a list of
+defined names. You can also specify colors numerically in forms such
+as @samp{#@var{rgb}} and @samp{RGB:@var{r}/@var{g}/@var{b}}, where
+@var{r} specifies the red level, @var{g} specifies the green level,
+and @var{b} specifies the blue level. You can use either one, two,
+three, or four hex digits for @var{r}; then you must use the same
+number of hex digits for all @var{g} and @var{b} as well, making
+either 3, 6, 9 or 12 hex digits in all. (See the documentation of the
+X Window System for more details about numerical RGB specification of
+colors.)
+
These functions provide a way to determine which color names are
valid, and what they look like. In some cases, the value depends on the
@dfn{selected frame}, as described below; see @ref{Input Focus}, for the
@defun color-values color &optional frame
@tindex color-values
+@cindex rgb value
This function returns a value that describes what @var{color} should
ideally look like on @var{frame}. If @var{color} is defined, the
value is a list of three integers, which give the amount of red, the
amount of green, and the amount of blue. Each integer ranges in
principle from 0 to 65535, but some displays may not use the full
-range. This kind of three-element list is called an @dfn{rgb value}.
+range. This three-element list is called the @dfn{rgb values} of the
+color.
If @var{color} is not defined, the value is @code{nil}.
@result{} nil
@end example
-The color values are returned for @var{frame}'s display. If @var{frame}
-is omitted or @code{nil}, the information is returned for the selected
-frame's display.
+The color values are returned for @var{frame}'s display. If
+@var{frame} is omitted or @code{nil}, the information is returned for
+the selected frame's display. If the frame cannot display colors, the
+value is @code{nil}.
@findex x-color-values
This function used to be called @code{x-color-values},
@section Text Terminal Colors
@cindex colors on text-only terminals
- Emacs can display color on text-only terminals, starting with version
-21. These terminals usually support only a small number of colors, and
-the computer uses small integers to select colors on the terminal. This
-means that the computer cannot reliably tell what the selected color
-looks like; instead, you have to inform your application which small
-integers correspond to which colors. However, Emacs does know the
-standard set of colors and will try to use them automatically.
+ Text-only terminals usually support only a small number of colors,
+and the computer uses small integers to select colors on the terminal.
+This means that the computer cannot reliably tell what the selected
+color looks like; instead, you have to inform your application which
+small integers correspond to which colors. However, Emacs does know
+the standard set of colors and will try to use them automatically.
The functions described in this section control how terminal colors
are used by Emacs.
-@cindex rgb value
- Several of these functions use or return @dfn{rgb values}. An rgb
-value is a list of three integers, which give the amount of red, the
-amount of green, and the amount of blue. Each integer ranges in
-principle from 0 to 65535, but some displays may not use the full range. .
+ Several of these functions use or return @dfn{rgb values}, described
+in @ref{Color Names}.
These functions accept a display (either a frame or the name of a
terminal) as an optional argument. We hope in the future to make Emacs
support more than one text-only terminal at one time; then this argument
will specify which terminal to operate on (the default being the
selected frame's terminal; @pxref{Input Focus}). At present, though,
-the @var{display} argument has no effect.
+the @var{frame} argument has no effect.
-@defun tty-color-define name number &optional rgb display
+@defun tty-color-define name number &optional rgb frame
@tindex tty-color-define
This function associates the color name @var{name} with
color number @var{number} on the terminal.
-The optional argument @var{rgb}, if specified, is an rgb value; it says
-what the color actually looks like. If you do not specify @var{rgb},
-then this color cannot be used by @code{tty-color-approximate} to
-approximate other colors, because Emacs does not know what it looks
-like.
+The optional argument @var{rgb}, if specified, is an rgb value, a list
+of three numbers that specify what what the color actually looks like.
+If you do not specify @var{rgb}, then this color cannot be used by
+@code{tty-color-approximate} to approximate other colors, because
+Emacs will not know what it looks like.
@end defun
-@defun tty-color-clear &optional display
+@defun tty-color-clear &optional frame
@tindex tty-color-clear
This function clears the table of defined colors for a text-only terminal.
@end defun
-@defun tty-color-alist &optional display
+@defun tty-color-alist &optional frame
@tindex tty-color-alist
This function returns an alist recording the known colors supported by a
text-only terminal.
Each element has the form @code{(@var{name} @var{number} . @var{rgb})}
or @code{(@var{name} @var{number})}. Here, @var{name} is the color
name, @var{number} is the number used to specify it to the terminal.
-If present, @var{rgb} is an rgb value that says what the color
-actually looks like.
+If present, @var{rgb} is a list of three color values (for red, green,
+and blue) that says what the color actually looks like.
@end defun
-@defun tty-color-approximate rgb &optional display
+@defun tty-color-approximate rgb &optional frame
@tindex tty-color-approximate
-This function finds the closest color, among the known colors supported
-for @var{display}, to that described by the rgb value @var{rgb}.
-The return value is an element of @code{tty-color-alist}.
+This function finds the closest color, among the known colors
+supported for @var{display}, to that described by the rgb value
+@var{rgb} (a list of color values). The return value is an element of
+@code{tty-color-alist}.
@end defun
-@defun tty-color-translate color &optional display
+@defun tty-color-translate color &optional frame
@tindex tty-color-translate
This function finds the closest color to @var{color} among the known
colors supported for @var{display} and returns its index (an integer).
If the name @var{color} is not defined, the value is @code{nil}.
-
-@var{color} can be an X-style @code{"#@var{xxxyyyzzz}"} specification
-instead of an actual name. The format
-@code{"RGB:@var{xx}/@var{yy}/@var{zz}"} is also supported.
@end defun
@node Resources