@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002
+@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2002, 2004
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../info/frames
* Input Focus:: Specifying the selected frame.
* Visibility of Frames:: Frames may be visible or invisible, or icons.
* Raising and Lowering:: Raising a frame makes it hide other windows;
- lowering it makes the others hide them.
+ lowering it makes the others hide it.
* Frame Configurations:: Saving the state of all frames.
* Mouse Tracking:: Getting events that say when the mouse moves.
* Mouse Position:: Asking where the mouse is, or moving it.
selected frame's parameter.
@end defun
-@defun frame-parameters frame
+@defun frame-parameters &optional frame
The function @code{frame-parameters} returns an alist listing all the
-parameters of @var{frame} and their values.
+parameters of @var{frame} and their values. If @var{frame} is
+@code{nil} or omitted, this returns the selected frame's parameters
@end defun
@defun modify-frame-parameters frame alist
elements of @var{alist}. Each element of @var{alist} has the form
@code{(@var{parm} . @var{value})}, where @var{parm} is a symbol naming a
parameter. If you don't mention a parameter in @var{alist}, its value
-doesn't change.
+doesn't change. If @var{frame} is @code{nil}, it defaults to the selected
+frame.
@end defun
@defun modify-all-frames-parameters alist
@vindex cursor-type
The buffer-local variable @code{cursor-type} overrides the value of
-the @code{cursor-type} frame parameter, and can in addition have
-values @code{t} (use the cursor specified for the frame) and
-@code{nil} (don't display a cursor).
+the @code{cursor-type} frame parameter, but if it is @code{t}, that
+means to use the cursor specified for the frame.
@item border-width
The width in pixels of the window border.
@item menu-bar-lines
The number of lines to allocate at the top of the frame for a menu bar.
The default is 1. @xref{Menu Bar}. (In Emacs versions that use the X
-toolkit, there is only one menu bar line; all that matters about the
+toolkit or GTK, there is only one menu bar line; all that matters about the
number you specify is whether it is greater than zero.)
@item screen-gamma
@item tool-bar-lines
The number of lines to use for the toolbar. A value of @code{nil} means
-don't display a tool bar.
+don't display a tool bar. (In Emacs versions that use GTK, there is
+only one tool bar line; all that matters about the number you specify
+is whether it is greater than zero.)
@item line-spacing
Additional space put below text lines in pixels (a positive integer).
If non-@code{nil}, the color for the background of scroll bars. It is
equivalent to the @code{:background} attribute of the
@code{scroll-bar} face.
+
+@item wait-for-wm
+If non-@code{nil}, tell Xt to wait for the window manager to confirm
+geometry changes. Some window managers, including versions of Fvwm2
+and KDE, fail to confirm, so Xt hangs. Set this to @code{nil} to
+prevent hanging with those window managers.
@end table
@node Size and Position
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 frame
+@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 also selects this window. You can get the frame's current
selected window with @code{frame-selected-window}.
-@defun frame-selected-window frame
+@defun frame-selected-window &optional frame
This function returns the window on @var{frame} that is selected within
-@var{frame}.
+@var{frame}. If omitted or @code{nil}, @var{frame} defaults to the selected frame.
@end defun
@defun set-frame-selected-window frame window
Some window systems and window managers direct keyboard input to the
window object that the mouse is in; others require explicit clicks or
commands to @dfn{shift the focus} to various window objects. Either
-way, Emacs automatically keeps track of which frame has the focus.
+way, Emacs automatically keeps track of which frame has the focus. To
+switch to a different frame from a Lisp function, call
+@code{select-frame-set-input-focus}.
Lisp programs can also switch frames ``temporarily'' by calling the
function @code{select-frame}. This does not alter the window system's
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 the selected terminal frame is
-actually displayed on the terminal. @code{switch-frame} is the only way
-to switch frames, and the change lasts until overridden by a subsequent
-call to @code{switch-frame}. Each terminal screen except for the
-initial one has a number, and the number of the selected frame appears
-in the mode line before the buffer name (@pxref{Mode Line Variables}).
+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
+redisplay actually displays the newly selected frame. This frame
+remains selected until a subsequent call to @code{select-frame} or
+@code{select-frame-set-input-focus}. Each terminal frame has a number
+which appears in the mode line before the buffer name (@pxref{Mode
+Line Variables}).
+
+@defun select-frame-set-input-focus frame
+This function makes @var{frame} the selected 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.
+@end defun
@c ??? This is not yet implemented properly.
@defun select-frame frame
the next time the user does something to select a different frame, or
until the next time this function is called. The specified @var{frame}
becomes the selected frame, as explained above, and the terminal that
-@var{frame} is on becomes the selected terminal.
+@var{frame} is on becomes the selected terminal. 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.
Don't call it for any other reason.
@end deffn
-@defun redirect-frame-focus frame focus-frame
+@defun redirect-frame-focus frame &optional focus-frame
This function redirects focus from @var{frame} to @var{focus-frame}.
This means that @var{focus-frame} will receive subsequent keystrokes and
events intended for @var{frame}. After such an event, the value of
@code{last-event-frame} will be @var{focus-frame}. Also, switch-frame
events specifying @var{frame} will instead select @var{focus-frame}.
-If @var{focus-frame} is @code{nil}, that cancels any existing
+If @var{focus-frame} is omitted or @code{nil}, that cancels any existing
redirection for @var{frame}, which therefore once again receives its own
events.
selection values.
Each possible @var{type} has its own selection value, which changes
-independently. The usual values of @var{type} are @code{PRIMARY} and
-@code{SECONDARY}; these are symbols with upper-case names, in accord
-with X Window System conventions. The default is @code{PRIMARY}.
+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. The default is
+@code{PRIMARY}.
@end defun
@defun x-get-selection &optional type data-type
The @var{data-type} argument specifies the form of data conversion to
use, to convert the raw data obtained from another X client into Lisp
data. Meaningful values include @code{TEXT}, @code{STRING},
+@code{UTF8_STRING},
@code{TARGETS}, @code{LENGTH}, @code{DELETE}, @code{FILE_NAME},
@code{CHARACTER_POSITION}, @code{LINE_NUMBER}, @code{COLUMN_NUMBER},
@code{OWNER_OS}, @code{HOST_NAME}, @code{USER}, @code{CLASS},
@end defun
@cindex cut buffer
-The X server also has a set of numbered @dfn{cut buffers} which can
+The X server also has a set of eight numbered @dfn{cut buffers} which can
store text or other data being moved between applications. Cut buffers
are considered obsolete, but Emacs supports them for the sake of X
-clients that still use them.
+clients that still use them. Cut buffers are numbered from 0 to 7.
-@defun x-get-cut-buffer n
+@defun x-get-cut-buffer &optional n
This function returns the contents of cut buffer number @var{n}.
+If omitted @var{n} defaults to 0.
@end defun
@defun x-set-cut-buffer string &optional push
+@anchor{Definition of x-set-cut-buffer}
This function stores @var{string} into the first cut buffer (cut buffer
0). If @var{push} is @code{nil}, only the first cut buffer is changed.
If @var{push} is non-@code{nil}, that says to move the values down
@defun x-get-resource attribute class &optional component subclass
The function @code{x-get-resource} retrieves a resource value from the X
-Windows defaults database.
+Window defaults database.
Resources are indexed by a combination of a @dfn{key} and a @dfn{class}.
This function searches using a key of the form
should look up. The default value is @code{"Emacs"}. You can examine X
resources for application names other than ``Emacs'' by binding this
variable to some other string, around a call to @code{x-get-resource}.
+@end defvar
+
+@defvar x-resource-name
+This variable specifies the instance name that @code{x-get-resource}
+should look up. The default value is the name Emacs was invoked with,
+or the value specified with the @samp{-name} or @samp{-rn} switches.
@end defvar
@xref{X Resources,, X Resources, emacs, The GNU Emacs Manual}.
(All color displays can do this.)
@end defun
-@anchor{Display Face Attribute Testing}
@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}).