@c -*-texinfo-*-
@c This is part of the GNU Emacs Lisp Reference Manual.
-@c Copyright (C) 1990, 1991, 1992, 1993, 1994, 1995, 1998, 1999, 2001,
-@c 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010
+@c Copyright (C) 1990-1995, 1998-1999, 2001-2011
@c Free Software Foundation, Inc.
@c See the file elisp.texi for copying conditions.
@setfilename ../../info/frames
* 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.
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}.
-
@menu
* Parameter Access:: How to change a frame's parameters.
* Initial Parameters:: Specifying frame parameters when you make a frame.
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 Window Frame Parameters
@subsection Window Frame Parameters
+@cindex frame parameters for windowed displays
Just what parameters a frame has depends on what display mechanism
it uses. This section describes the parameters that have special
frame. @code{title} and @code{name} are meaningful on all terminals.
@table @code
+@vindex display, a frame parameter
@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.
+@vindex display-type, a frame parameter
@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}.
+@vindex title, a frame parameter
@item title
If a frame has a non-@code{nil} title, it appears in the window
system's title bar at the top of the frame, and also in the mode line
Emacs is not using a window system, and can only display one frame at
a time. @xref{Frame Titles}.
+@vindex name, a frame parameter
@item name
The name of the frame. The frame name serves as a default for the frame
title, if the @code{title} parameter is unspecified or @code{nil}. If
If you specify the frame name explicitly when you create the frame, the
name is also used (instead of the name of the Emacs executable) when
looking up X resources for the frame.
+
+@item explicit-name
+If the frame name was specified explicitly when the frame was created,
+this parameter will be that name. If the frame wasn't explicitly
+named, this parameter will be @code{nil}.
@end table
@node Position Parameters
@subsubsection Position Parameters
+@cindex window position on display
Position parameters' values are normally measured in pixels, but on
text-only terminals they count characters or lines instead.
@table @code
+@vindex left, a frame parameter
@item left
The position, in pixels, of the left (or right) edge of the frame with
respect to the left (or right) edge of the screen. The value may be:
be sure the position you specify is not ignored, specify a
non-@code{nil} value for the @code{user-position} parameter as well.
+@vindex top, a frame parameter
@item top
The screen position of the top (or bottom) edge, in pixels, with respect
to the top (or bottom) edge of the screen. It works just like
@code{left}, except vertically instead of horizontally.
+@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
a value for @code{icon-top} and vice versa. The window manager may
ignore these two parameters.
+@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.
+@vindex user-position, a frame parameter
@item user-position
When you create a frame and specify its screen position with the
@code{left} and @code{top} parameters, use this parameter to say whether
way by a human user) or merely program-specified (chosen by a program).
A non-@code{nil} value says the position was user-specified.
+@cindex window positions and window managers
Window managers generally heed user-specified positions, and some heed
program-specified positions too. But many ignore program-specified
positions, placing the window in a default fashion or letting the user
@node Size Parameters
@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.
@table @code
+@vindex height, a frame parameter
@item height
The height of the frame contents, in characters. (To get the height in
pixels, call @code{frame-pixel-height}; see @ref{Size and Position}.)
+@vindex width, a frame parameter
@item width
The width of the frame contents, in characters. (To get the width in
pixels, call @code{frame-pixel-width}; see @ref{Size and Position}.)
+@vindex user-size, a frame parameter
@item user-size
This does for the size parameters @code{height} and @code{width} what
-the @code{user-position} parameter (see above) does for the position
-parameters @code{top} and @code{left}.
+the @code{user-position} parameter (@pxref{Position Parameters,
+user-position}) does for the position parameters @code{top} and
+@code{left}.
+@cindex full-screen frames
+@vindex fullscreen, a frame parameter
@item fullscreen
Specify that width, height or both shall be maximized. The value
@code{fullwidth} specifies that width shall be as wide as possible.
@node Layout Parameters
@subsubsection Layout Parameters
+@cindex layout parameters of frames
+@cindex frame layout parameters
These frame parameters enable or disable various parts of the
frame, or control their sizes.
@table @code
+@vindex border-width, a frame parameter
@item border-width
The width in pixels of the frame's border.
+@vindex internal-border-width, a frame parameter
@item internal-border-width
The distance in pixels between text (or fringe) and the frame's border.
+@vindex vertical-scroll-bars, a frame parameter
@item vertical-scroll-bars
Whether the frame has scroll bars for vertical scrolling, and which side
of the frame they should be on. The possible values are @code{left},
@code{right}, and @code{nil} for no scroll bars.
@ignore
+@vindex horizontal-scroll-bars, a frame parameter
@item horizontal-scroll-bars
Whether the frame has scroll bars for horizontal scrolling
(non-@code{nil} means yes). Horizontal scroll bars are not currently
implemented.
@end ignore
+@vindex scroll-bar-width, a frame parameter
@item scroll-bar-width
The width of vertical scroll bars, in pixels, or @code{nil} meaning to
use the default width.
+@vindex left-fringe, a frame parameter
+@vindex right-fringe, a frame parameter
@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.
+removes the corresponding fringe.
-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 fringe or the other to a precise
-width by specifying that width as a negative integer. If both widths are
-negative, only the left fringe gets the specified width.
+When you use @code{frame-parameter} to query the value of either of
+these two frame parameters, the return value is always an integer.
+When using @code{set-frame-parameter}, passing a @code{nil} value
+imposes an actual default value of 8 pixels.
+The combined fringe widths must add up to an integral number of
+columns, so the actual default fringe widths for the frame, as
+reported by @code{frame-parameter}, may be larger than what you
+specify. Any extra width is distributed evenly between the left and
+right fringe. However, you can force one fringe or the other to a
+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 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 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 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}.
The default is @code{top}.
+@vindex line-spacing, a frame parameter
@item line-spacing
Additional space to leave below each text line, in pixels (a positive
integer). @xref{Line Height}, for more information.
with which buffers have been, or should, be displayed in the frame.
@table @code
+@vindex minibuffer, a frame parameter
@item minibuffer
Whether this frame has its own minibuffer. The value @code{t} means
yes, @code{nil} means no, @code{only} means this frame is just a
This frame parameter takes effect when the frame is created, and can
not be changed afterwards.
+@vindex buffer-predicate, a frame parameter
@item buffer-predicate
The buffer-predicate function for this frame. The function
@code{other-buffer} uses this predicate (from the selected frame) to
each buffer; if the predicate returns a non-@code{nil} value, it
considers that buffer.
+@vindex buffer-list, a frame parameter
@item buffer-list
-A list of buffers that have been selected in this frame,
-ordered most-recently-selected first.
+A list of buffers that have been selected in this frame, ordered
+most-recently-selected first.
+@vindex unsplittable, a frame parameter
@item unsplittable
If non-@code{nil}, this frame's window is never split automatically.
@end table
@node Management Parameters
@subsubsection Window Management Parameters
-@cindex window manager, and frame parameters
+@cindex window manager interaction, and frame parameters
These frame parameters, meaningful only on window system displays,
interact with the window manager.
@table @code
+@vindex visibility, a frame parameter
@item visibility
The state of visibility of the frame. There are three possibilities:
@code{nil} for invisible, @code{t} for visible, and @code{icon} for
iconified. @xref{Visibility of Frames}.
+@vindex auto-raise, a frame parameter
@item auto-raise
Whether selecting the frame raises it (non-@code{nil} means yes).
+@vindex auto-lower, a frame parameter
@item auto-lower
Whether deselecting the frame lowers it (non-@code{nil} means yes).
+@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
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.
+@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.
+@vindex outer-window-id, a frame parameter
@item outer-window-id
The number of the outermost window-system window used for the whole frame.
+@vindex wait-for-wm, a frame parameter
@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.
+@vindex sticky, a frame parameter
@item sticky
If non-@code{nil}, the frame is visible on all virtual desktops on systems
with virtual desktops.
@ignore
+@vindex parent-id, a frame parameter
@item parent-id
@c ??? Not yet working.
The X window number of the window that should be the parent of this one.
@node Cursor Parameters
@subsubsection Cursor Parameters
+@cindex cursor, and frame parameters
This frame parameter controls the way the cursor looks.
@table @code
+@vindex cursor-type, a frame parameter
@item cursor-type
How to display the cursor. Legitimate values are:
@node Font and Color Parameters
@subsubsection Font and Color Parameters
+@cindex font and color, frame parameters
These frame parameters control the use of fonts and colors.
@table @code
+@vindex font-backend, a frame parameter
@item font-backend
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
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
This parameter is either @code{dark} or @code{light}, according
to whether the background color is a light one or a dark one.
+@vindex tty-color-mode, a frame parameter
@item tty-color-mode
@cindex standard colors for character terminals
This parameter overrides the terminal's color support as given by the
the value of @code{tty-color-mode-alist}, and the associated number is
used instead.
+@vindex screen-gamma, a frame parameter
@item screen-gamma
@cindex gamma correction
If this is a number, Emacs performs ``gamma correction'' which adjusts
that makes colors darker. A screen gamma value of 1.5 may give good
results for LCD color displays.
+@vindex alpha, a frame parameter
@item alpha
@cindex opacity, frame
@cindex transparency, frame
faces (@pxref{Standard Faces,,, emacs, The Emacs Manual}):
@table @code
+@vindex font, a frame parameter
@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.
+@vindex foreground-color, a frame parameter
@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.
+@vindex background-color, a frame parameter
@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.
+@vindex mouse-color, a frame parameter
@item mouse-color
The color for the mouse pointer. It is equivalent to the @code{:background}
attribute of the @code{mouse} face.
+@vindex cursor-color, a frame parameter
@item cursor-color
The color for the cursor that shows point. It is equivalent to the
@code{:background} attribute of the @code{cursor} face.
+@vindex border-color, a frame parameter
@item border-color
The color for the border of the frame. It is equivalent to the
@code{:background} attribute of the @code{border} face.
+@vindex scroll-bar-foreground, a frame parameter
@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.
+@vindex scroll-bar-background, a frame parameter
@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
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
However, you can also create a frame with no minibuffer. Such a frame
must use the minibuffer window of some other frame. When you create the
-frame, you can specify explicitly the minibuffer window to use (in some
+frame, you can explicitly specify the minibuffer window to use (in some
other frame). If you don't, then the minibuffer is found in the frame
which is the value of the variable @code{default-minibuffer-frame}. Its
value should be a frame that does have a minibuffer.
value is not significant.
@end defun
+@defun frame-pointer-visible-p &optional frame
+This predicate function returns non-@code{nil} if the mouse pointer
+displayed on @var{frame} is visible; otherwise it returns @code{nil}.
+@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}.
+@end defun
+
@need 3000
@node Pop-Up Menus
The argument @var{menu} says what to display in the menu. It can be a
keymap or a list of keymaps (@pxref{Menu Keymaps}). In this case, the
return value is the list of events corresponding to the user's choice.
-(This list has more than one element if the choice occurred in a
-submenu.) Note that @code{x-popup-menu} does not actually execute the
-command bound to that sequence of events.
+This list has more than one element if the choice occurred in a
+submenu. (Note that @code{x-popup-menu} does not actually execute the
+command bound to that sequence of events.) On toolkits that support
+menu titles, the title is taken from the prompt string of @var{menu}
+if @var{menu} is a keymap, or from the prompt string of the first
+keymap in @var{menu} if it is a list of keymaps (@pxref{Defining
+Menus}).
Alternatively, @var{menu} can have the following form:
@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
@code{STRING}.
@end defun
-@cindex cut buffer
-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. Cut buffers are numbered from 0 to 7.
-
-@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
-through the series of cut buffers, much like the way successive kills in
-Emacs move down the kill ring. In other words, the previous value of
-the first cut buffer moves into the second cut buffer, and the second to
-the third, and so on through all eight cut buffers.
-@end defun
-
@defopt selection-coding-system
This variable specifies the coding system to use when reading and
writing selections or the clipboard. @xref{Coding
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{nil} on most systems,
-but @code{t} on MS-Windows.
-@end defopt
-
@node Drag and Drop
@section Drag and Drop
@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
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