@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
-@c Free Software Foundation, Inc.
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2012 Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
-@setfilename ../../info/frames
@node Frames, Positions, Windows, Top
@chapter Frames
@cindex frame
more Emacs frames. In Emacs Lisp, a @dfn{terminal object} is a Lisp
object that represents a terminal. @xref{Terminal Type}.
-@cindex terminal frame
-@cindex window frame
- There are two classes of terminals: text-only terminals and
-graphical terminals. Text-only terminals are non-graphics-capable
-display devices, including ``terminal emulators'' such as xterm. On
-text-only terminals, each frame occupies the entire terminal screen;
-although you can create additional frames and switch between them,
-only one frame can be shown at any given time. We refer to frames on
-text-only terminals as @dfn{terminal frames}. Graphical terminals, on
-the other hand, are graphics-capable windowing systems, such as the X
-Window System. On a graphical terminal, Emacs can display multiple
-frames simultaneously. We refer to such frames as @dfn{window
-frames}.
+@cindex text terminal
+@cindex graphical terminal
+@cindex graphical display
+ There are two classes of terminals: @dfn{text terminals} and
+@dfn{graphical terminals}. Text terminals are non-graphics-capable
+displays, including @command{xterm} and other terminal emulators. On
+a text terminal, each Emacs frame occupies the terminal's entire
+screen; although you can create additional frames and switch between
+them, the terminal only shows one frame at a time. Graphical
+terminals, on the other hand, are managed by graphical display systems
+such as the X Window System, which allow Emacs to show multiple frames
+simultaneously on the same display.
On GNU and Unix systems, you can create additional frames on any
available terminal, within a single Emacs session, regardless of
-whether Emacs was started on a text-only or graphical terminal. Emacs
-can display on both graphical and text-only terminals simultaneously.
-This comes in handy, for instance, when you connect to the same
-session from several remote locations. @xref{Multiple Terminals}.
+whether Emacs was started on a text or graphical terminal. Emacs can
+display on both graphical and text terminals simultaneously. This
+comes in handy, for instance, when you connect to the same session
+from several remote locations. @xref{Multiple Terminals}.
@defun framep object
This predicate returns a non-@code{nil} value if @var{object} is a
kind of display the frame uses:
@table @code
-@item x
-The frame is displayed in an X window.
@item t
-A terminal frame on a character display.
+The frame is displayed on a text terminal.
+@item x
+The frame is displayed on an X graphical terminal.
@item w32
-The frame is displayed on MS-Windows 9X/NT.
+The frame is displayed on a MS-Windows graphical terminal.
@item ns
-The frame is displayed on a GNUstep or Macintosh Cocoa display.
+The frame is displayed on a GNUstep or Macintosh Cocoa graphical
+terminal.
@item pc
The frame is displayed on an MS-DOS terminal.
@end table
@defun terminal-live-p object
This predicate returns a non-@code{nil} value if @var{object} is a
-terminal that is alive (i.e.@: was not deleted), and @code{nil}
-otherwise. For live terminals, the return value indicates what kind
-of frames are displayed on that terminal; the list of possible values
-is the same as for @code{framep} above.
+terminal that is live (i.e.@: not deleted), and @code{nil} otherwise.
+For live terminals, the return value indicates what kind of frames are
+displayed on that terminal; the list of possible values is the same as
+for @code{framep} above.
@end defun
@menu
* Frame Titles:: Automatic updating of frame titles.
* Deleting Frames:: Frames last until explicitly deleted.
* Finding All Frames:: How to examine all existing frames.
-* Frames and Windows:: A frame contains windows;
- display of text always works through windows.
* Minibuffers and Frames:: How a frame finds the minibuffer to use.
* Input Focus:: Specifying the selected frame.
* Visibility of Frames:: Frames may be visible or invisible, or icons.
* 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.
-* Text Terminal Colors:: Defining colors for text-only terminals.
+* Text Terminal Colors:: Defining colors for text terminals.
* Resources:: Getting resource values from the server.
* Display Feature Testing:: Determining the features of a terminal.
@end menu
@code{terminal} parameter in @var{alist}, the new frame is created on
that terminal. Otherwise, if you specify the @code{window-system}
frame parameter in @var{alist}, that determines whether the frame
-should be displayed on a text-only or graphical terminal.
+should be displayed on a text terminal or a graphical terminal.
@xref{Window Systems}. If neither is specified, the new frame is
created in the same terminal as the selected frame.
@cindex multiple X displays
@cindex displays, multiple
- Emacs represents each terminal, whether graphical or text-only, as a
-@dfn{terminal object} data type (@pxref{Terminal Type}). On GNU and
-Unix systems, Emacs can use multiple terminals simultaneously in each
-session. On other systems, it can only use a single terminal. Each
-terminal object has the following attributes:
+ Emacs represents each terminal as a @dfn{terminal object} data type
+(@pxref{Terminal Type}). On GNU and Unix systems, Emacs can use
+multiple terminals simultaneously in each session. On other systems,
+it can only use a single terminal. Each terminal object has the
+following attributes:
@itemize @bullet
@item
-The name of the device used by the terminal (e.g., @samp{:0.0} or
+The name of the device used by the terminal (e.g.@: @samp{:0.0} or
@file{/dev/tty}).
@item
@item
The kind of display associated with the terminal. This is the symbol
-returned by the function @code{terminal-live-p} (i.e., @code{x},
+returned by the function @code{terminal-live-p} (i.e.@: @code{x},
@code{t}, @code{w32}, @code{ns}, or @code{pc}). @xref{Frames}.
@item
There is no primitive for creating terminal objects. Emacs creates
them as needed, such as when you call @code{make-frame-on-display}
-(which is described below).
+(described below).
@defun terminal-name &optional terminal
This function returns the file name of the device used by
@end defun
@defun terminal-list
-This function returns a list of all terminal objects currently in use.
+This function returns a list of all live terminal objects.
@end defun
@defun get-device-terminal device
On GNU and Unix systems, each X display is a separate graphical
terminal. When Emacs is started from within the X window system, it
-uses the X display chosen with the @code{DISPLAY} environment
-variable, or with the @samp{--display} option. @xref{Initial
-Options,,, emacs, The GNU Emacs Manual}. Emacs can connect to other X
-displays via the command @code{make-frame-on-display}. Each X display
-has its own selected frame and its own minibuffer windows; however,
-only one of those frames is ``@emph{the} selected frame'' at any given
-moment (@pxref{Input Focus}). Emacs can even connect to other
-text-only terminals, by interacting with the @command{emacsclient}
-program. @xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
+uses the X display specified by the @env{DISPLAY} environment
+variable, or by the @samp{--display} option (@pxref{Initial Options,,,
+emacs, The GNU Emacs Manual}). Emacs can connect to other X displays
+via the command @code{make-frame-on-display}. Each X display has its
+own selected frame and its own minibuffer windows; however, only one
+of those frames is ``@emph{the} selected frame'' at any given moment
+(@pxref{Input Focus}). Emacs can even connect to other text
+terminals, by interacting with the @command{emacsclient} program.
+@xref{Emacs Server,,, emacs, The GNU Emacs Manual}.
A single X server can handle more than one display. Each X display
has a three-part name, @samp{@var{host}:@var{server}.@var{screen}}.
single keyboard.
On some ``multi-monitor'' setups, a single X display outputs to more
-than one monitor. Currently, there is no way for Emacs to distinguish
-between the different physical monitors.
+than one physical monitor. Currently, there is no way for Emacs to
+distinguish between the different physical monitors.
@deffn Command make-frame-on-display display &optional parameters
This function creates and returns a new frame on @var{display}, taking
Before creating the frame, this function ensures that Emacs is ``set
up'' to display graphics. For instance, if Emacs has not processed X
-resources (e.g., if it was started on a text-only terminal), it does
-so at this time. In all other respects, this function behaves like
+resources (e.g.@: if it was started on a text terminal), it does so at
+this time. In all other respects, this function behaves like
@code{make-frame} (@pxref{Creating Frames}).
@end deffn
Just what parameters a frame has depends on what display mechanism it
uses.
- Frame parameters exist mostly for the sake of window systems. A
-terminal frame has a few parameters, mostly for compatibility's sake;
-only the @code{height}, @code{width}, @code{name}, @code{title},
-@code{menu-bar-lines}, @code{buffer-list} and @code{buffer-predicate}
-parameters do something special. If the terminal supports colors, the
-parameters @code{foreground-color}, @code{background-color},
-@code{background-mode} and @code{display-type} are also meaningful.
-If the terminal supports frame transparency, the parameter
-@code{alpha} is also meaningful.
-
- You can use frame parameters to define frame-local bindings for
-variables. @xref{Frame-Local Variables}.
+ Frame parameters exist mostly for the sake of graphical displays.
+Most frame parameters have no effect when applied to a frame on a text
+terminal; only the @code{height}, @code{width}, @code{name},
+@code{title}, @code{menu-bar-lines}, @code{buffer-list} and
+@code{buffer-predicate} parameters do something special. If the
+terminal supports colors, the parameters @code{foreground-color},
+@code{background-color}, @code{background-mode} and
+@code{display-type} are also meaningful. If the terminal supports
+frame transparency, the parameter @code{alpha} is also meaningful.
@menu
* Parameter Access:: How to change a frame's parameters.
parameter. If you don't mention a parameter in @var{alist}, its value
doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
frame.
-
-You can use this function to define frame-local bindings for
-variables, see @ref{Frame-Local Variables}.
@end defun
@defun set-frame-parameter frame parm value
@node Initial Parameters
@subsection Initial Frame Parameters
-You can specify the parameters for the initial startup frame
-by setting @code{initial-frame-alist} in your init file (@pxref{Init File}).
+You can specify the parameters for the initial startup frame by
+setting @code{initial-frame-alist} in your init file (@pxref{Init
+File}).
@defopt initial-frame-alist
-This variable's value is an alist of parameter values used when creating
-the initial window frame. You can set this variable to specify the
+This variable's value is an alist of parameter values used when
+creating the initial frame. You can set this variable to specify the
appearance of the initial frame without altering subsequent frames.
Each element has the form:
@code{initial-frame-alist} with values that match the X resources.
@end defopt
-If these parameters specify a separate minibuffer-only frame with
+If these parameters specify a separate @dfn{minibuffer-only frame} with
@code{(minibuffer . nil)}, and you have not created one, Emacs creates
one for you.
+@cindex minibuffer-only frame
@defopt minibuffer-frame-alist
This variable's value is an alist of parameter values used when
creating an initial minibuffer-only frame. This is the
default parameters by supplying their own parameters. @xref{Definition
of special-display-frame-alist}.
-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{Emacs Invocation,, Command
-Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
+If you invoke Emacs with command-line options that specify frame
+appearance, those options take effect by adding elements to either
+@code{initial-frame-alist} or @code{default-frame-alist}. Options
+which affect just the initial frame, such as @samp{-geometry} and
+@samp{--maximized}, add to @code{initial-frame-alist}; the others add
+to @code{default-frame-alist}. @pxref{Emacs Invocation,, Command Line
+Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}.
@node Window Frame Parameters
@subsection Window Frame Parameters
meanings on some or all kinds of terminals. 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.
+frames, and @code{tty-color-mode} is meaningful only for frames on
+text terminals.
@menu
* Basic Parameters:: Parameters that are fundamental.
@item display
The display on which to open this frame. It should be a string of the
form @code{"@var{host}:@var{dpy}.@var{screen}"}, just like the
-@code{DISPLAY} environment variable.
+@env{DISPLAY} environment variable.
@vindex display-type, a frame parameter
@item display-type
@cindex window position on display
Position parameters' values are normally measured in pixels, but on
-text-only terminals they count characters or lines instead.
+text terminals they count characters or lines instead.
@table @code
@vindex left, a frame parameter
@vindex icon-left, a frame parameter
@item icon-left
-The screen position of the left edge @emph{of the frame's icon}, in
-pixels, counting from the left edge of the screen. This takes effect if
-and when the frame is iconified.
-
-If you specify a value for this parameter, then you must also specify
-a value for @code{icon-top} and vice versa. The window manager may
-ignore these two parameters.
+The screen position of the left edge of the frame's icon, in pixels,
+counting from the left edge of the screen. This takes effect when the
+frame is iconified, if the window manager supports this feature. If
+you specify a value for this parameter, then you must also specify a
+value for @code{icon-top} and vice versa.
@vindex icon-top, a frame parameter
@item icon-top
-The screen position of the top edge @emph{of the frame's icon}, in
-pixels, counting from the top edge of the screen. This takes effect if
-and when the frame is iconified.
+The screen position of the top edge of the frame's icon, in pixels,
+counting from the top edge of the screen. This takes effect when the
+frame is iconified, if the window manager supports this feature.
@vindex user-position, a frame parameter
@item user-position
@subsubsection Size Parameters
@cindex window size on display
- Size parameters' values are normally measured in pixels, but on
-text-only terminals they count characters or lines instead.
+ Frame parameters specify frame sizes in character units. On
+graphical displays, the @code{default} face determines the actual
+pixel sizes of these character units (@pxref{Face Attributes}).
@table @code
@vindex height, a frame parameter
precise width by specifying that width as a negative integer. If both
widths are negative, only the left fringe gets the specified width.
-@vindex menu-bar-lines, a frame parameter
+@vindex menu-bar-lines frame parameter
@item menu-bar-lines
The number of lines to allocate at the top of the frame for a menu
-bar. The default is 1. A value of @code{nil} means don't display a
-menu bar. @xref{Menu Bar}. (The X toolkit and GTK allow at most one
-menu bar line; they treat larger values as 1.)
+bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise.
+@xref{Menu Bars,,,emacs, The GNU Emacs Manual}.
-@vindex tool-bar-lines, a frame parameter
+@vindex tool-bar-lines frame parameter
@item tool-bar-lines
-The number of lines to use for the tool bar. A value of @code{nil}
-means don't display a tool bar. (GTK and Nextstep allow at most one
-tool bar line; they treat larger values as 1.)
+The number of lines to use for the tool bar. The default is 1 if Tool
+Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The
+GNU Emacs Manual}.
-@vindex tool-bar-position, a frame parameter
+@vindex tool-bar-position frame parameter
@item tool-bar-position
The position of the tool bar. Currently only for the GTK tool bar.
Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}.
@subsubsection Window Management Parameters
@cindex window manager interaction, and frame parameters
- These frame parameters, meaningful only on window system displays,
-interact with the window manager.
+ The following frame parameters control various aspects of the
+frame's interaction with the window manager. They have no effect on
+text terminals.
@table @code
@vindex visibility, a frame parameter
@vindex auto-raise, a frame parameter
@item auto-raise
-Whether selecting the frame raises it (non-@code{nil} means yes).
+If non-@code{nil}, Emacs automatically raises the frame when it is
+selected. Some window managers do not allow this.
@vindex auto-lower, a frame parameter
@item auto-lower
-Whether deselecting the frame lowers it (non-@code{nil} means yes).
+If non-@code{nil}, Emacs automatically lowers the frame when it is
+deselected. Some window managers do not allow this.
@vindex icon-type, a frame parameter
@item icon-type
-The type of icon to use for this frame when it is iconified. If the
-value is a string, that specifies a file containing a bitmap to use.
-Any other non-@code{nil} value specifies the default bitmap icon (a
-picture of a gnu); @code{nil} specifies a text icon.
+The type of icon to use for this frame. If the value is a string,
+that specifies a file containing a bitmap to use; @code{nil} specifies
+no icon (in which case the window manager decides what to show); any
+other non-@code{nil} value specifies the default Emacs icon.
@vindex icon-name, a frame parameter
@item icon-name
@vindex window-id, a frame parameter
@item window-id
-The number of the window-system window used by the frame
-to contain the actual Emacs windows.
+The ID number which the graphical display uses for this frame. Emacs
+assigns this parameter when the frame is created; changing the
+parameter has no effect on the actual ID number.
@vindex outer-window-id, a frame parameter
@item outer-window-id
-The number of the outermost window-system window used for the whole frame.
+The ID number of the outermost window-system window in which the frame
+exists. As with @code{window-id}, changing this parameter has no
+actual effect.
@vindex wait-for-wm, a frame parameter
@item wait-for-wm
@end table
@vindex cursor-type
-The buffer-local variable @code{cursor-type} overrides the value of
-the @code{cursor-type} frame parameter, but if it is @code{t}, that
-means to use the cursor specified for the frame.
+The @code{cursor-type} frame parameter may be overridden by the
+variables @code{cursor-type} and
+@code{cursor-in-non-selected-windows}:
+
+@defvar cursor-type
+This buffer-local variable controls how the cursor looks in a selected
+window showing the buffer. If its value is @code{t}, that means to
+use the cursor specified by the @code{cursor-type} frame parameter.
+Otherwise, the value should be one of the cursor types listed above,
+and it overrides the @code{cursor-type} frame parameter.
+@end defvar
+
+@defopt cursor-in-non-selected-windows
+This buffer-local variable controls how the cursor looks in a window
+that is not selected. It supports the same values as the
+@code{cursor-type} frame parameter; also, @code{nil} means don't
+display a cursor in nonselected windows, and @code{t} (the default)
+means use a standard modification of the usual cursor type (solid box
+becomes hollow box, and bar becomes a narrower bar).
+@end defopt
@defopt blink-cursor-alist
This variable specifies how to blink the cursor. Each element has the
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
@code{cursor-type} frame parameter.
@end defopt
-@defopt cursor-in-non-selected-windows
-This variable controls how the cursor looks in a window that is not
-selected. It supports the same values as the @code{cursor-type} frame
-parameter; also, @code{nil} means don't display a cursor in
-nonselected windows, and @code{t} (the default) means use a standard
-modification of the usual cursor type (solid box becomes hollow box,
-and bar becomes a narrower bar).
-@end defopt
-
@node Font and Color Parameters
@subsubsection Font and Color Parameters
@cindex font and color, frame parameters
A list of symbols, specifying the @dfn{font backends} to use for
drawing fonts in the frame, in order of priority. On X, there are
currently two available font backends: @code{x} (the X core font
-driver) and @code{xft} (the Xft font driver). On other systems, there
-is only one available font backend, so it does not make sense to
-modify this frame parameter.
+driver) and @code{xft} (the Xft font driver). On Windows, there are
+currently two available font backends: @code{gdi} and
+@code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs
+Manual}). On other systems, there is only one available font backend,
+so it does not make sense to modify this frame parameter.
@vindex background-mode, a frame parameter
@item background-mode
@cindex standard colors for character terminals
This parameter overrides the terminal's color support as given by the
system's terminal capabilities database in that this parameter's value
-specifies the color mode to use in terminal frames. The value can be
+specifies the color mode to use on a text terminal. The value can be
either a symbol or a number. A number specifies the number of colors
to use (and, indirectly, what commands to issue to produce each
color). For example, @code{(tty-color-mode . 8)} specifies use of the
The @code{alpha} frame parameter can also be a cons cell
@code{(@samp{active} . @samp{inactive})}, where @samp{active} is the
opacity of the frame when it is selected, and @samp{inactive} is the
-opactity when it is not selected.
+opacity when it is not selected.
@end table
The following frame parameters are semi-obsolete in that they are
@defunx frame-pixel-width &optional frame
These functions return the height and width of the main display area
of @var{frame}, measured in pixels. If you don't supply @var{frame},
-they use the selected frame. For a text-only terminal, the results are
-in characters rather than pixels.
+they use the selected frame. For a text terminal, the results are in
+characters rather than pixels.
-These values include the internal borders, and windows' scroll bars and
-fringes (which belong to individual windows, not to the frame itself).
-The exact value of the heights depends on the window-system and toolkit
-in use. With Gtk+, the height does not include any tool bar or menu
-bar. With the Motif or Lucid toolkits, it includes the tool bar but
-not the menu bar. In a graphical version with no toolkit, it includes
-both the tool bar and menu bar. For a text-only terminal, the result
-includes the menu bar.
+These values include the internal borders, and windows' scroll bars
+and fringes (which belong to individual windows, not to the frame
+itself). The exact value of the heights depends on the window-system
+and toolkit in use. With GTK+, the height does not include any tool
+bar or menu bar. With the Motif or Lucid toolkits, it includes the
+tool bar but not the menu bar. In a graphical version with no
+toolkit, it includes both the tool bar and menu bar. For a text
+terminal, the result includes the menu bar.
@end defun
@defun frame-char-height &optional frame
If @var{pretend} is non-@code{nil}, then Emacs displays @var{lines}
lines of output in @var{frame}, but does not change its value for the
-actual height of the frame. This is only useful for a terminal frame.
+actual height of the frame. This is only useful on text terminals.
Using a smaller height than the terminal actually implements may be
useful to reproduce behavior observed on a smaller screen, or if the
terminal malfunctions when using its whole screen. Setting the frame
height ``for real'' does not always work, because knowing the correct
-actual size may be necessary for correct cursor positioning on a
-terminal frame.
+actual size may be necessary for correct cursor positioning on
+text terminals.
@end defun
@defun set-frame-width frame width &optional pretend
@code{set-frame-height}.
@end defun
-@findex set-screen-height
-@findex set-screen-width
- The older functions @code{set-screen-height} and
-@code{set-screen-width} were used to specify the height and width of the
-screen, in Emacs versions that did not support multiple frames. They
-are semi-obsolete, but still work; they apply to the selected frame.
-
@node Geometry
@subsection Geometry
@section Deleting Frames
@cindex deleting frames
-Frames remain potentially visible until you explicitly @dfn{delete}
-them. A deleted frame cannot appear on the screen, but continues to
-exist as a Lisp object until there are no references to it.
+ A @dfn{live frame} is one that has not been deleted. When a frame
+is deleted, it is removed from its terminal display, although it may
+continue to exist as a Lisp object until there are no more references
+to it.
@deffn Command delete-frame &optional frame force
@vindex delete-frame-functions
@cindex frames, scanning all
@defun frame-list
-The function @code{frame-list} returns a list of all the live frames,
-i.e.@: those that have not been deleted. It is analogous to
-@code{buffer-list} for buffers, and includes frames on all terminals.
-The list that you get is newly created, so modifying the list doesn't
-have any effect on the internals of Emacs.
+This function returns a list of all the live frames, i.e.@: those that
+have not been deleted. It is analogous to @code{buffer-list} for
+buffers, and includes frames on all terminals. The list that you get
+is newly created, so modifying the list doesn't have any effect on the
+internals of Emacs.
@end defun
@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.)
+@xref{Visibility of Frames}. Frames on text terminals always count as
+``visible'', even though only the selected one is actually displayed.
@end defun
@defun next-frame &optional frame minibuf
-The function @code{next-frame} lets you cycle conveniently through all
-the frames on the current display from an arbitrary starting point. It
-returns the ``next'' frame after @var{frame} in the cycle. If
-@var{frame} is omitted or @code{nil}, it defaults to the selected frame
-(@pxref{Input Focus}).
+This function lets you cycle conveniently through all the frames on
+the current display from an arbitrary starting point. It returns the
+``next'' frame after @var{frame} in the cycle. If @var{frame} is
+omitted or @code{nil}, it defaults to the selected frame (@pxref{Input
+Focus}).
The second argument, @var{minibuf}, says which frames to consider:
See also @code{next-window} and @code{previous-window}, in @ref{Cyclic
Window Ordering}.
-@node Frames and Windows
-@section Frames and Windows
-
- Each window is part of one and only one frame; you can get that frame
-with @code{window-frame}.
-
-@defun window-frame window
-This function returns the frame that @var{window} is on.
-@end defun
-
- All the non-minibuffer windows in a frame are arranged in a cyclic
-order. The order runs from the frame's top window, which is at the
-upper left corner, down and to the right, until it reaches the window at
-the lower right corner (always the minibuffer window, if the frame has
-one), and then it moves back to the top. @xref{Cyclic Window Ordering}.
-
-@defun frame-first-window &optional frame
-This returns the topmost, leftmost window of frame @var{frame}.
-If omitted or @code{nil}, @var{frame} defaults to the selected frame.
-@end defun
-
-At any time, exactly one window on any frame is @dfn{selected within the
-frame}. The significance of this designation is that selecting the
-frame also selects this window. Conversely, selecting a window for
-Emacs with @code{select-window} also makes that window selected within
-its frame. @xref{Selecting Windows}.
-
-@defun frame-selected-window &optional frame
-This function returns the window on @var{frame} that is selected
-within @var{frame}. If omitted or @code{nil}, @var{frame} defaults to
-the selected frame.
-@end defun
-
-@defun set-frame-selected-window frame window &optional norecord
-This sets the selected window of frame @var{frame} to @var{window}.
-If @var{frame} is @code{nil}, it operates on the selected frame. If
-@var{frame} is the selected frame, this makes @var{window} the
-selected window. This function returns @var{window}.
-
-Optional argument @var{norecord} non-@code{nil} means to neither change
-the order of recently selected windows nor the buffer list (@pxref{The
-Buffer List}).
-@end defun
-
- Another function that (usually) returns one of the windows in a given
-frame is @code{minibuffer-window}. @xref{Definition of minibuffer-window}.
-
@node Minibuffers and Frames
@section Minibuffers and Frames
concept of focus; rather, it escapes from the window manager's control
until that control is somehow reasserted.
-When using a text-only terminal, only one frame can be displayed at a
-time on the terminal, so after a call to @code{select-frame}, the next
+When using a text terminal, only one frame can be displayed at a time
+on the terminal, so after a call to @code{select-frame}, the next
redisplay actually displays the newly selected frame. This frame
remains selected until a subsequent call to @code{select-frame}. Each
-terminal frame has a number which appears in the mode line before the
-buffer name (@pxref{Mode Line Variables}).
+frame on a text terminal has a number which appears in the mode line
+before the buffer name (@pxref{Mode Line Variables}).
-@defun select-frame-set-input-focus frame
+@defun select-frame-set-input-focus frame &optional norecord
This function selects @var{frame}, raises it (should it happen to be
-obscured by other frames) and tries to give it the X server's focus. On
-a text-only terminal, the next redisplay displays the new frame on the
-entire terminal screen. The return value of this function is not
-significant.
+obscured by other frames) and tries to give it the X server's focus.
+On a text terminal, the next redisplay displays the new frame on the
+entire terminal screen. The optional argument @var{norecord} has the
+same meaning as for @code{select-frame} (see below). The return value
+of this function is not significant.
@end defun
-@c ??? This is not yet implemented properly.
@defun select-frame frame &optional norecord
This function selects frame @var{frame}, temporarily disregarding the
focus of the X server if any. The selection of @var{frame} lasts until
selected frame after return to the command loop, because it still may
have the window system's input focus.)
-The specified @var{frame} becomes the selected frame, as explained
-above, and the terminal that @var{frame} is on becomes the selected
-terminal. The window selected within @var{frame} becomes the selected
-window. This function returns @var{frame}, or @code{nil} if @var{frame}
-has been deleted.
+The specified @var{frame} becomes the selected frame, and its terminal
+becomes the selected terminal. This function then calls
+@code{select-window} as a subroutine, passing the window selected
+within @var{frame} as its first argument and @var{norecord} as its
+second argument (hence, if @var{norecord} is non-@code{nil}, this
+avoids changing the order of recently selected windows nor the buffer
+list). @xref{Selecting Windows}.
-Optional argument @var{norecord} non-@code{nil} means to neither change
-the order of recently selected windows nor the buffer list. @xref{The
-Buffer List}.
+This function returns @var{frame}, or @code{nil} if @var{frame} has
+been deleted.
-In general, you should never use @code{select-frame} in a way that could
-switch to a different terminal without switching back when you're done.
+In general, you should never use @code{select-frame} in a way that
+could switch to a different terminal without switching back when
+you're done.
@end defun
Emacs cooperates with the window system by arranging to select frames as
@cindex visible frame
@cindex invisible frame
@cindex iconified frame
+@cindex minimized frame
@cindex frame visibility
-A window frame may be @dfn{visible}, @dfn{invisible}, or
-@dfn{iconified}. If it is visible, you can see its contents, unless
-other windows cover it. If it is iconified, the frame's contents do
-not appear on the screen, but an icon does. (Note: because of the
-way in which some window managers implement the concept of multiple
-workspaces, or desktops, all frames on other workspaces may appear to
-Emacs to be iconified.) If the frame is invisible, it doesn't show on
-the screen, not even as an icon.
+A frame on a graphical display may be @dfn{visible}, @dfn{invisible},
+or @dfn{iconified}. If it is visible, its contents are displayed in
+the usual manner. If it is iconified, its contents are not displayed,
+but there is a little icon somewhere to bring the frame back into view
+(some window managers refer to this state as @dfn{minimized} rather
+than @dfn{iconified}, but from Emacs' point of view they are the same
+thing). If a frame is invisible, it is not displayed at all.
-Visibility is meaningless for terminal frames, since only the selected
+ Visibility is meaningless on text terminals, since only the selected
one is actually displayed in any case.
+@defun frame-visible-p frame
+This function returns the visibility status of frame @var{frame}. The
+value is @code{t} if @var{frame} is visible, @code{nil} if it is
+invisible, and @code{icon} if it is iconified.
+
+On a text terminal, all frames are considered visible, whether they
+are currently being displayed or not.
+@end defun
+
+@deffn Command iconify-frame &optional frame
+This function iconifies frame @var{frame}. If you omit @var{frame}, it
+iconifies the selected frame.
+@end deffn
+
@deffn Command make-frame-visible &optional frame
This function makes frame @var{frame} visible. If you omit
@var{frame}, it makes the selected frame visible. This does not raise
@var{frame} invisible if all other frames are invisible..
@end deffn
-@deffn Command iconify-frame &optional frame
-This function iconifies frame @var{frame}. If you omit @var{frame}, it
-iconifies the selected frame.
-@end deffn
-
-@defun frame-visible-p frame
-This returns the visibility status of frame @var{frame}. The value is
-@code{t} if @var{frame} is visible, @code{nil} if it is invisible, and
-@code{icon} if it is iconified.
-
-On a text-only terminal, all frames are considered visible, whether
-they are currently being displayed or not, and this function returns
-@code{t} for all frames.
-@end defun
-
The visibility status of a frame is also available as a frame
parameter. You can read or change it as such. @xref{Management
-Parameters}.
-
- The user can iconify and deiconify frames with the window manager.
-This happens below the level at which Emacs can exert any control, but
-Emacs does provide events that you can use to keep track of such
-changes. @xref{Misc Events}.
+Parameters}. The user can also iconify and deiconify frames with the
+window manager. This happens below the level at which Emacs can exert
+any control, but Emacs does provide events that you can use to keep
+track of such changes. @xref{Misc Events}.
@node Raising and Lowering
@section Raising and Lowering 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.
@var{frame} omitted or @code{nil} means the selected frame. This is
useful when @code{make-pointer-invisible} is set to @code{t}: it
allows to know if the pointer has been hidden.
-@xref{Mouse Avoidance,,,emacs}.
+@xref{Mouse Avoidance,,,emacs, The Emacs Manual}.
@end defun
@need 3000
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
@node Window System Selections
@section Window System Selections
@cindex selection (for window systems)
-
-The X server records a set of @dfn{selections} which permit transfer of
-data between application programs. The various selections are
-distinguished by @dfn{selection types}, represented in Emacs by
-symbols. X clients including Emacs can read or set the selection for
-any given type.
+@cindex clipboard
+@cindex primary selection
+@cindex secondary selection
+
+ In the X window system, data can be transferred between different
+applications by means of @dfn{selections}. X defines an arbitrary
+number of @dfn{selection types}, each of which can store its own data;
+however, only three are commonly used: the @dfn{clipboard},
+@dfn{primary selection}, and @dfn{secondary selection}. @xref{Cut and
+Paste,, Cut and Paste, emacs, The GNU Emacs Manual}, for Emacs
+commands that make use of these selections. This section documents
+the low-level functions for reading and setting X selections.
@deffn Command x-set-selection type data
-This function sets a ``selection'' in the X server. It takes two
-arguments: a selection type @var{type}, and the value to assign to it,
-@var{data}. If @var{data} is @code{nil}, it means to clear out the
-selection. Otherwise, @var{data} may be a string, a symbol, an integer
-(or a cons of two integers or list of two integers), an overlay, or a
-cons of two markers pointing to the same buffer. An overlay or a pair
-of markers stands for text in the overlay or between the markers.
-
-The argument @var{data} may also be a vector of valid non-vector
-selection values.
-
-Each possible @var{type} has its own selection value, which changes
-independently. The usual values of @var{type} are @code{PRIMARY},
-@code{SECONDARY} and @code{CLIPBOARD}; these are symbols with upper-case
-names, in accord with X Window System conventions. If @var{type} is
-@code{nil}, that stands for @code{PRIMARY}.
+This function sets an X selection. It takes two arguments: a
+selection type @var{type}, and the value to assign to it, @var{data}.
+
+@var{type} should be a symbol; it is usually one of @code{PRIMARY},
+@code{SECONDARY} or @code{CLIPBOARD}. These are symbols with
+upper-case names, in accord with X Window System conventions. If
+@var{type} is @code{nil}, that stands for @code{PRIMARY}.
+
+If @var{data} is @code{nil}, it means to clear out the selection.
+Otherwise, @var{data} may be a string, a symbol, an integer (or a cons
+of two integers or list of two integers), an overlay, or a cons of two
+markers pointing to the same buffer. An overlay or a pair of markers
+stands for text in the overlay or between the markers. The argument
+@var{data} may also be a vector of valid non-vector selection values.
This function returns @var{data}.
@end deffn
only; if the clipboard holds other types of data, Emacs treats the
clipboard as empty.
-@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{t} on systems with
-clipboards.
-@end defopt
-
@node Drag and Drop
@section 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''.
To read user input of color names with completion, use
@code{read-color} (@pxref{High-Level Completion, read-color}).
@node Text Terminal Colors
@section Text Terminal Colors
-@cindex colors on text-only terminals
+@cindex colors on text terminals
- Text-only terminals usually support only a small number of colors,
-and the computer uses small integers to select colors on the terminal.
+ Text 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
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 different colors on different text-only terminals; 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{frame} argument has no effect.
+Emacs support different colors on different text terminals; 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{frame} argument has no effect.
@defun tty-color-define name number &optional rgb frame
This function associates the color name @var{name} with
@end defun
@defun tty-color-clear &optional frame
-This function clears the table of defined colors for a text-only terminal.
+This function clears the table of defined colors for a text terminal.
@end defun
@defun tty-color-alist &optional frame
-This function returns an alist recording the known colors supported by a
-text-only terminal.
+This function returns an alist recording the known colors supported by
+a text 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
@defun display-graphic-p &optional display
This function returns @code{t} if @var{display} is a graphic display
capable of displaying several frames and several different fonts at
-once. This is true for displays that use a window system such as X, and
-false for text-only terminals.
+once. This is true for displays that use a window system such as X,
+and false for text terminals.
@end defun
@defun display-mouse-p &optional display
@end defun
@defun display-visual-class &optional display
-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
-@code{direct-color}.
+This function returns the visual class for the screen. The value is
+one of the symbols @code{static-gray} (a limited, unchangeable number
+of grays), @code{gray-scale} (a full range of grays),
+@code{static-color} (a limited, unchangeable number of colors),
+@code{pseudo-color} (a limited number of colors), @code{true-color} (a
+full range of colors), and @code{direct-color} (a full range of
+colors).
@end defun
@defun display-color-cells &optional display
software (as a string). Really this means whoever distributes the X
server.
-When the developers of X labelled software distributors as
-``vendors,'' they showed their false assumption that no system could
+When the developers of X labeled software distributors as
+``vendors'', they showed their false assumption that no system could
ever be developed and distributed noncommercially.
@end defun
The functions @code{x-pixel-width} and @code{x-pixel-height} return the
width and height of an X Window frame, measured in pixels.
@end ignore
-
HCoop / bpt / emacs.git / blobdiff