@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 Free Software Foundation, Inc.
+@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
@node Frames, Positions, Windows, Top
* 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.
* Display Feature Testing:: Determining the features of a terminal.
@end menu
- @xref{Display}, for information about the related topic of
+ @xref{Display}, for information about the related topic of
controlling Emacs redisplay.
@node Creating Frames
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
+This function alters the frame parameters of all existing frames
+according to @var{alist}, then modifies @code{default-frame-alist}
+to apply the same parameter values to frames that will be created
+henceforth.
@end defun
@node Initial Parameters
A list of buffers that have been selected in this frame,
ordered most-recently-selected first.
-@item font
-The name of the font for displaying text in the frame. This is a
-string, either a valid font name for your system or the name of an Emacs
-fontset (@pxref{Fontsets}). Changing this frame parameter on a frame
-also changes the font-related attributes of the default face on that
-frame.
-
@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).
implemented.)
@item scroll-bar-width
-The width of the vertical scroll bar, in pixels.
+The width of the vertical scroll bar, in pixels,
+or @code{nil} meaning to use the default width.
@item icon-type
The type of icon to use for this frame when it is iconified. If the
The name to use in the icon for this frame, when and if the icon
appears. If this is @code{nil}, the frame's title is used.
-@item foreground-color
-The color to use for the image of a character. This is a string; the
-window system defines the meaningful color names. Changing this
-parameter is equivalent to changing the foreground color of the face
-@code{default} on the frame in question.
-
-@item background-color
-The color to use for the background of characters. Changing this
-parameter is equivalent to changing the foreground color of the face
-@code{default} on the frame in question.
-
@item background-mode
This parameter is either @code{dark} or @code{light}, according
to whether the background color is a light one or a dark one.
-@item mouse-color
-The color for the mouse pointer. Changing this parameter is equivalent
-to changing the background color of face @code{mouse}.
-
-@item cursor-color
-The color for the cursor that shows point. Changing this parameter is
-equivalent to changing the background color of face @code{cursor}.
-
-@item border-color
-The color for the border of the frame. Changing this parameter is
-equivalent to changing the background color of face @code{border}.
-
@item tty-color-mode
@cindex standard colors for character terminals
This parameter overrides the terminal's color support as given by the
@code{tty-color-mode-alist}, and if found, the associated number is
used as the color support mode.
-@item scroll-bar-foreground
-If non-@code{nil}, the color for the foreground of scroll bars.
-Changing this parameter is equivalent to setting the foreground color of
-face @code{scroll-bar}.
-
-@item scroll-bar-background
-If non-@code{nil}, the color for the background of scroll bars.
-Changing this parameter is equivalent to setting the background color of
-face @code{scroll-bar}.
-
@item display-type
This parameter describes the range of possible colors that can be used
in this frame. Its value is @code{color}, @code{grayscale} or
@code{mono}.
@item cursor-type
-The way to display the cursor. The legitimate values are @code{bar},
-@code{box}, and @code{(bar . @var{width})}. The symbol @code{box}
-specifies an ordinary black box overlaying the character after point;
-that is the default. The symbol @code{bar} specifies a vertical bar
-between characters as the cursor. @code{(bar . @var{width})}
-specifies a bar @var{width} pixels wide. The symbol @code{hbar}
-specifies a horizontal bar, an underscore-like cursor. @code{(hbar .
-@var{width})} specifiles a horizontal bar @var{width} pixels high.
+How to display the cursor. Legitimate values are:
+
+@table @code
+@item box
+Display a filled box. (This is the default.)
+@item hollow
+Display a hollow box.
+@item nil
+Don't display a cursor.
+@item bar
+Display a vertical bar between characters.
+@item (bar . @var{width})
+Display a vertical bar @var{width} pixels wide between characters.
+@item hbar
+Display a horizontal bar.
+@item (bar . @var{width})
+Display a horizontal bar @var{width} pixels high.
+@end table
@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 internal-border-width
The distance in pixels between text and border.
+@item left-fringe
+@itemx right-fringe
+The default width of the left and right fringes of windows in this
+frame (@pxref{Fringes}). If either of these is zero, that effectively
+removes the corresponding fringe. A value of @code{nil} stands for
+the standard fringe width, which is the width needed to display the
+fringe bitmaps.
+
+The combined fringe widths must add up to an integral number of
+columns, so the actual default fringe widths for the frame may be
+larger than the specified values. The extra width needed to reach an
+acceptable total is distributed evenly between the left and right
+fringe. However, you can force one frame or the other to a precise
+width by specifying that width a negative integer. If both widths are
+negative, only the left fringe gets the specified width.
+
@item unsplittable
If non-@code{nil}, this frame's window is never split automatically.
@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).
@end ignore
@end table
+@defvar 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}), Emacs uses
+@var{off-state} to specify what the cursor looks like 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 the type is not mentioned as an @var{on-state} here. Changes
+in this variable do not take effect immediately, because the variable
+is examined only when you specify a cursor type for a frame.
+@end defvar
+
+These frame parameters are semi-obsolete in that they are automatically
+equivalent to particular face attributes of particular faces.
+
+@table @code
+@item font
+The name of the font for displaying text in the frame. This is a
+string, either a valid font name for your system or the name of an Emacs
+fontset (@pxref{Fontsets}). It is equivalent to the @code{font}
+attribute of the @code{default} face.
+
+@item foreground-color
+The color to use for the image of a character. It is equivalent to
+the @code{:foreground} attribute of the @code{default} face.
+
+@item background-color
+The color to use for the background of characters. It is equivalent to
+the @code{:background} attribute of the @code{default} face.
+
+@item mouse-color
+The color for the mouse pointer. It is equivalent to the @code{:background}
+attribute of the @code{mouse} face.
+
+@item cursor-color
+The color for the cursor that shows point. It is equivalent to the
+@code{:background} attribute of the @code{cursor} face.
+
+@item border-color
+The color for the border of the frame. It is equivalent to the
+@code{:background} attribute of the @code{border} face.
+
+@item scroll-bar-foreground
+If non-@code{nil}, the color for the foreground of scroll bars. It is
+equivalent to the @code{:foreground} attribute of the
+@code{scroll-bar} face.
+
+@item scroll-bar-background
+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
@subsection Frame Size And Position
@cindex size of frame
way windows behave.
@deffn Command delete-frame &optional frame force
-@vindex delete-frame-hook
+@vindex delete-frame-functions
This function deletes the frame @var{frame} after running the hook
-@code{delete-frame-hook}. By default, @var{frame} is the selected
-frame.
+@code{delete-frame-functions} (each function gets one argument,
+@var{frame}). By default, @var{frame} is the selected frame.
A frame cannot be deleted if its minibuffer is used by other frames.
Normally, you cannot delete a frame if all other frames are invisible,
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
+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.
@end defun
Conversely, selecting a window for Emacs with @code{select-window} also
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}.
The functions in this section describe the basic capabilities of a
particular display. Lisp programs can use them to adapt their behavior
-to what the display can do. For example, a program that ordinarly uses
+to what the display can do. For example, a program that ordinarily uses
a popup menu could use the minibuffer if popup menus are not supported.
The optional argument @var{display} in these functions specifies which
(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}).
Point (2) implies that a @code{:weight black} attribute will be
satisfied by any display that can display bold, as will
@code{:foreground "yellow"} as long as some yellowish color can be
-displayed, but @code{:slant italic} will @emph{not} be satisified by
+displayed, but @code{:slant italic} will @emph{not} be satisfied by
the tty display code's automatic substitution of a `dim' face for
italic.
@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
+
+@ignore
+ arch-tag: 94977df6-3dca-4730-b57b-c6329e9282ba
+@end ignore
HCoop / bpt / emacs.git / blobdiff