@chapter Frames
@cindex frame
- A @dfn{frame} is a rectangle on the screen that contains one or more
-Emacs windows. A frame initially contains a single main window (plus
-perhaps a minibuffer window), which you can subdivide vertically or
-horizontally into smaller windows.
+ In Emacs editing, A @dfn{frame} is a screen object that contains one
+or more Emacs windows. It's the kind of object that is called a
+``window'' in the terminology of graphical environments; but we can't
+call it a ``window'' here, because Emacs uses that word in a different
+way.
+
+ A frame initially contains a single main window and/or a minibuffer
+window; you can subdivide the main window vertically or horizontally
+into smaller windows. In Emacs Lisp, a @dfn{frame object} is a Lisp
+object that represents a frame on the screen.
@cindex terminal frame
When Emacs runs on a text-only terminal, it starts with one
* Mouse Position:: Asking where the mouse is, or moving it.
* Pop-Up Menus:: Displaying a menu for the user to select from.
* Dialog Boxes:: Displaying a box to ask yes or no.
-* Pointer Shapes:: Specifying the shape of the mouse pointer.
+* Pointer Shape:: Specifying the shape of the mouse pointer.
* Window System Selections:: Transferring text to and from other X clients.
* Drag and Drop:: Internals of Drag-and-Drop implementation.
* Color Names:: Getting the definitions of color names.
@end defvar
@defvar after-make-frame-functions
-@tindex after-make-frame-functions
An abnormal hook run by @code{make-frame} after it creates the frame.
Each function in @code{after-make-frame-functions} receives one argument, the
frame just created.
frame.
@defun frame-parameter frame parameter
-@tindex frame-parameter
This function returns the value of the parameter @var{parameter} (a
symbol) of @var{frame}. If @var{frame} is @code{nil}, it returns the
selected frame's parameter. If @var{frame} has no setting for
@node Management Parameters
@subsubsection Window Management Parameters
-
+
These frame parameters, meaningful only on window system displays,
interact with the window manager.
form @code{(@var{on-state} . @var{off-state})}. Whenever the cursor
type equals @var{on-state} (comparing using @code{equal}), the
corresponding @var{off-state} specifies what the cursor looks like
-when it blinks ``off''. Both @var{on-state} and @var{off-state}
+when it blinks ``off.'' Both @var{on-state} and @var{off-state}
should be suitable values for the @code{cursor-type} frame parameter.
There are various defaults for how to blink each type of cursor, if
@defvar frame-title-format
This variable specifies how to compute a name for a frame when you have
not explicitly specified one. The variable's value is actually a mode
-line construct, just like @code{mode-line-format}. @xref{Mode Line
+line construct, just like @code{mode-line-format}, except that the
+@samp{%c} and @samp{%l} constructs are ignored. @xref{Mode Line
Data}.
@end defvar
@defun visible-frame-list
This function returns a list of just the currently visible frames.
@xref{Visibility of Frames}. (Terminal frames always count as
-``visible'', even though only the selected one is actually displayed.)
+``visible,'' even though only the selected one is actually displayed.)
@end defun
@defun next-frame &optional frame minibuf
This option is how you inform Emacs whether the window manager transfers
focus when the user moves the mouse. Non-@code{nil} says that it does.
When this is so, the command @code{other-frame} moves the mouse to a
-position consistent with the new selected frame.
+position consistent with the new selected frame. (This option has no
+effect on MS-Windows, where the mouse pointer is always automatically
+moved by the OS to the selected frame.)
@end defopt
@node Visibility of Frames
Most window systems use a desktop metaphor. Part of this metaphor is
the idea that windows are stacked in a notional third dimension
perpendicular to the screen surface, and thus ordered from ``highest''
-to ``lowest''. Where two windows overlap, the one higher up covers
+to ``lowest.'' Where two windows overlap, the one higher up covers
the one underneath. Even a window at the bottom of the stack can be
seen if no other window overlaps it.
@cindex lowering a frame
A window's place in this ordering is not fixed; in fact, users tend
to change the order frequently. @dfn{Raising} a window means moving
-it ``up'', to the top of the stack. @dfn{Lowering} a window means
+it ``up,'' to the top of the stack. @dfn{Lowering} a window means
moving it to the bottom of the stack. This motion is in the notional
third dimension only, and does not change the position of the window
on the screen.
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 or more buttons. The main use of dialog boxes is
-for asking questions that the user can answer with ``yes'', ``no'',
+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
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}).
+for @code{message-box} (@pxref{message-box}).
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
@code{x-popup-dialog} does not return.
@end defun
-@node Pointer Shapes
-@section Pointer Shapes
+@node Pointer Shape
+@section Pointer Shape
@cindex pointer shape
@cindex mouse pointer shape
- These variables specify which shape to use for the mouse pointer in
-various situations, when using the X Window System:
+ You can specify the mouse pointer style for particular text or
+images using the @code{pointer} text property, and for images with the
+@code{:pointer} and @code{:map} image properties. The values you can
+use in these properties are @code{text} (or @code{nil}), @code{arrow},
+@code{hand}, @code{vdrag}, @code{hdrag}, @code{modeline}, and
+@code{hourglass}. @code{text} stands for the usual mouse pointer
+style used over text.
+
+ Over void parts of the window (parts that do not correspond to any
+of the buffer contents), the mouse pointer usually uses the
+@code{arrow} style, but you can specify a different style (one of
+those above) by setting @code{void-text-area-pointer}.
+
+@defvar void-text-area-pointer
+This variable specifies the mouse pointer style for void text areas.
+These include the areas after the end of a line or below the last line
+in the buffer. The default is to use the @code{arrow} (non-text)
+pointer style.
+@end defvar
-@table @code
-@item x-pointer-shape
-@vindex x-pointer-shape
-This variable specifies the pointer shape to use ordinarily in the Emacs
-frame.
+ You can specify what the @code{text} pointer style really looks like
+by setting the variable @code{x-pointer-shape}.
+
+@defvar x-pointer-shape
+This variable specifies the pointer shape to use ordinarily in the
+Emacs frame, for the @code{text} pointer style.
+@end defvar
-@item x-sensitive-text-pointer-shape
-@vindex x-sensitive-text-pointer-shape
+@defvar x-sensitive-text-pointer-shape
This variable specifies the pointer shape to use when the mouse
is over mouse-sensitive text.
-@end table
+@end defvar
These variables affect newly created frames. They do not normally
-affect existing frames; however, if you set the mouse color of a frame,
-that also updates its pointer shapes based on the current values of
-these variables. @xref{Color Parameters}.
+affect existing frames; however, if you set the mouse color of a
+frame, that also installs the current value of those two variables.
+@xref{Color Parameters}.
The values you can use, to specify either of these pointer shapes, are
defined in the file @file{lisp/term/x-win.el}. Use @kbd{M-x apropos
@defvar selection-coding-system
This variable specifies the coding system to use when reading and
-writing selections, the clipboard, or a cut buffer. @xref{Coding
+writing selections or the clipboard. @xref{Coding
Systems}. The default is @code{compound-text-with-extensions}, which
converts to the text representation that X11 normally uses.
@end defvar
only; if the clipboard holds other types of data, Emacs treats the
clipboard as empty.
+@cindex scrap support (for Mac OS)
+On Mac OS, selection-like data transfer between applications is
+performed through a mechanism called @dfn{scraps}. The clipboard is a
+particular scrap named @code{com.apple.scrap.clipboard}. Types of scrap
+data are called @dfn{scrap flavor types}, which are identified by
+four-char codes such as @code{TEXT}. Emacs associates a selection with
+a scrap, and a selection type with a scrap flavor type via
+@code{mac-scrap-name} and @code{mac-ostype} properties, respectively.
+
+@example
+(get 'CLIPBOARD 'mac-scrap-name)
+ @result{} "com.apple.scrap.clipboard"
+(get 'com.apple.traditional-mac-plain-text 'mac-ostype)
+ @result{} "TEXT"
+@end example
+
+Conventionally, selection types for scrap flavor types on Mac OS have
+the form of @acronym{UTI, Uniform Type Identifier} such as
+@code{com.apple.traditional-mac-plain-text},
+@code{public.utf16-plain-text}, and @code{public.file-url}.
+
@defopt x-select-enable-clipboard
If this is non-@code{nil}, the Emacs yank functions consult the
clipboard before the primary selection, and the kill functions store in
the clipboard as well as the primary selection. Otherwise they do not
access the clipboard at all. The default is @code{nil} on most systems,
-but @code{t} on MS-Windows.
+but @code{t} on MS-Windows and Mac.
@end defopt
@node Drag and Drop
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
-meaning of the term ``selected frame''.
+meaning of the term ``selected frame.''
@defun color-defined-p color &optional frame
-@tindex color-defined-p
This function reports whether a color name is meaningful. It returns
@code{t} if so; otherwise, @code{nil}. The argument @var{frame} says
which frame's display to ask about; if @var{frame} is omitted or
@end defun
@defun defined-colors &optional frame
-@tindex defined-colors
This function returns a list of the color names that are defined
and supported on frame @var{frame} (default, the selected frame).
If @var{frame} does not support colors, the value is @code{nil}.
@end defun
@defun color-supported-p color &optional frame background-p
-@tindex color-supported-p
This returns @code{t} if @var{frame} can really display the color
@var{color} (or at least something close to it). If @var{frame} is
omitted or @code{nil}, the question applies to the selected frame.
@end defun
@defun color-gray-p color &optional frame
-@tindex color-gray-p
This returns @code{t} if @var{color} is a shade of gray, as defined on
@var{frame}'s display. If @var{frame} is omitted or @code{nil}, the
question applies to the selected frame. If @var{color} is not a valid
@end defun
@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
the @var{frame} argument has no effect.
@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.
@end defun
@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 frame
-@tindex tty-color-alist
This function returns an alist recording the known colors supported by a
text-only terminal.
@end defun
@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} (a list of color values). The return value is an element of
@end defun
@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}.
obtain information about displays.
@defun display-popup-menus-p &optional display
-@tindex display-popup-menus-p
This function returns @code{t} if popup menus are supported on
@var{display}, @code{nil} if not. Support for popup menus requires that
the mouse be available, since the user cannot choose menu items without
@end defun
@defun display-graphic-p &optional display
-@tindex display-graphic-p
@cindex frames, more than one on display
@cindex fonts, more than one on display
This function returns @code{t} if @var{display} is a graphic display
@end defun
@defun display-mouse-p &optional display
-@tindex display-mouse-p
@cindex mouse, availability
This function returns @code{t} if @var{display} has a mouse available,
@code{nil} if not.
@end defun
@defun display-color-p &optional display
-@tindex display-color-p
@findex x-display-color-p
This function returns @code{t} if the screen is a color screen.
It used to be called @code{x-display-color-p}, and that name
@end defun
@defun display-grayscale-p &optional display
-@tindex display-grayscale-p
This function returns @code{t} if the screen can display shades of gray.
(All color displays can do this.)
@end defun
@defun display-supports-face-attributes-p attributes &optional display
@anchor{Display Face Attribute Testing}
-@tindex display-supports-face-attributes-p
This function returns non-@code{nil} if all the face attributes in
@var{attributes} are supported (@pxref{Face Attributes}).
@end defun
@defun display-selections-p &optional display
-@tindex display-selections-p
This function returns @code{t} if @var{display} supports selections.
Windowed displays normally support selections, but they may also be
supported in some other cases.
@end defun
@defun display-screens &optional display
-@tindex display-screens
This function returns the number of screens associated with the display.
@end defun
@defun display-pixel-height &optional display
-@tindex display-pixel-height
This function returns the height of the screen in pixels.
On a character terminal, it gives the height in characters.
@end defun
-@defun display-mm-height &optional display
-@tindex display-mm-height
-This function returns the height of the screen in millimeters,
-or @code{nil} if Emacs cannot get that information.
-@end defun
-
@defun display-pixel-width &optional display
-@tindex display-pixel-width
This function returns the width of the screen in pixels.
On a character terminal, it gives the width in characters.
@end defun
+@defun display-mm-height &optional display
+This function returns the height of the screen in millimeters,
+or @code{nil} if Emacs cannot get that information.
+@end defun
+
@defun display-mm-width &optional display
-@tindex display-mm-width
This function returns the width of the screen in millimeters,
or @code{nil} if Emacs cannot get that information.
@end defun
+@defvar display-mm-dimensions-alist
+This variable allows the user to specify the dimensions of graphical
+displays returned by @code{display-mm-height} and
+@code{display-mm-width} in case the system provides incorrect values.
+@end defvar
+
@defun display-backing-store &optional display
-@tindex display-backing-store
This function returns the backing store capability of the display.
Backing store means recording the pixels of windows (and parts of
windows) that are not exposed, so that when exposed they can be
@end defun
@defun display-save-under &optional display
-@tindex display-save-under
This function returns non-@code{nil} if the display supports the
SaveUnder feature. That feature is used by pop-up windows
to save the pixels they obscure, so that they can pop down
@end defun
@defun display-planes &optional display
-@tindex display-planes
This function returns the number of planes the display supports.
This is typically the number of bits per pixel.
For a tty display, it is log to base two of the number of colors supported.
@end defun
@defun display-visual-class &optional display
-@tindex display-visual-class
This function returns the visual class for the screen. The value is one
of the symbols @code{static-gray}, @code{gray-scale},
@code{static-color}, @code{pseudo-color}, @code{true-color}, and
@end defun
@defun display-color-cells &optional display
-@tindex display-color-cells
This function returns the number of color cells the screen supports.
@end defun
server.
When the developers of X labelled software distributors as
-``vendors'', they showed their false assumption that no system could
+``vendors,'' they showed their false assumption that no system could
ever be developed and distributed noncommercially.
@end defun