diff options
Diffstat (limited to 'doc/lispref/frames.texi')
| -rw-r--r-- | doc/lispref/frames.texi | 121 |
1 files changed, 85 insertions, 36 deletions
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 0c81718750..c513645617 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -1,7 +1,6 @@ @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, 2011 +@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 @@ -461,6 +460,7 @@ Line Arguments for Emacs Invocation, emacs, The GNU Emacs Manual}. @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 @@ -489,16 +489,19 @@ terminal frames. 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 @@ -507,6 +510,7 @@ of windows in that frame if @code{mode-line-frame-identification} uses 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 @@ -520,11 +524,13 @@ looking up X resources for the frame. @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: @@ -550,11 +556,13 @@ Some window managers ignore program-specified positions. If you want to 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 @@ -564,11 +572,13 @@ 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. +@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 @@ -576,6 +586,7 @@ the specified position was user-specified (explicitly requested in some 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 @@ -591,24 +602,31 @@ parameters represent the user's stated preference; otherwise, use @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. @@ -623,33 +641,42 @@ covers the whole screen. @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 @@ -669,17 +696,26 @@ 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, a 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.) +@vindex tool-bar-lines, a 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.) +@vindex tool-bar-position, a 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. @@ -692,6 +728,7 @@ 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 @@ -701,6 +738,7 @@ frame), the frame uses that minibuffer. 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 @@ -709,61 +747,73 @@ decide which buffers it should consider, if the predicate is not 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. +@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. @@ -775,10 +825,12 @@ it and see if it works.) @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: @@ -830,10 +882,12 @@ and bar becomes a narrower bar). @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 @@ -842,10 +896,12 @@ 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. +@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 @@ -861,6 +917,7 @@ If the parameter's value is a symbol, it specifies a number through 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 @@ -880,6 +937,7 @@ If your monitor displays colors too light, you should specify a 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 @@ -907,37 +965,45 @@ automatically equivalent to particular face attributes of particular 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 @@ -1302,7 +1368,7 @@ minibuffer-window}). 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. @@ -1684,6 +1750,15 @@ If @var{frame} is not visible, this function does nothing. The return 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 @@ -1925,28 +2000,6 @@ with X conventions.) The default for @var{data-type} is @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 @@ -1965,8 +2018,8 @@ clipboard as empty. 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. +access the clipboard at all. The default is @code{t} on systems with +clipboards. @end defopt @node Drag and Drop @@ -2430,7 +2483,3 @@ 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 |