diff lispref/frames.texi @ 89910:548375b6b1f8

Update unicode branch

--- a/lispref/frames.texi	Fri Apr 16 12:51:06 2004 +0000
+++ b/lispref/frames.texi	Mon Apr 19 07:01:43 2004 +0000
@@ -56,7 +56,7 @@
 * 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.
@@ -212,9 +212,10 @@
 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
@@ -222,7 +223,15 @@
 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
@@ -423,13 +432,6 @@
 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).
 
@@ -447,7 +449,8 @@
 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
@@ -459,33 +462,10 @@
 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
@@ -500,16 +480,6 @@
 @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
@@ -537,9 +507,8 @@
 
 @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.
@@ -547,6 +516,22 @@
 @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.
 
@@ -558,7 +543,7 @@
 @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
@@ -582,7 +567,9 @@
 
 @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).
@@ -611,6 +598,53 @@
 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
@@ -798,10 +832,10 @@
 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,
@@ -884,8 +918,9 @@
 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
@@ -893,9 +928,16 @@
 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
@@ -994,14 +1036,14 @@
 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.
 
@@ -1426,9 +1468,10 @@
 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
@@ -1440,6 +1483,7 @@
 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},
@@ -1449,15 +1493,17 @@
 @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
 
+@anchor{Definition of x-set-cut-buffer}
 @defun x-set-cut-buffer string &optional push
 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.
@@ -1661,7 +1707,7 @@
 
 @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
@@ -1683,6 +1729,12 @@
 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}.
 
 @node Display Feature Testing
@@ -1872,3 +1924,7 @@
 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