diff man/lispref/frames.texi @ 54:05472e90ae02 r19-16-pre2

Import from CVS: tag r19-16-pre2
author cvs
date Mon, 13 Aug 2007 08:57:55 +0200
parents ac2d302a0011
children 7df0dd720c89
line wrap: on
line diff
--- a/man/lispref/frames.texi	Mon Aug 13 08:57:25 2007 +0200
+++ b/man/lispref/frames.texi	Mon Aug 13 08:57:55 2007 +0200
@@ -9,7 +9,7 @@
 @cindex frame
 
   A @var{frame} is a rectangle on the screen that contains one or more
-Emacs windows.  A frame initially contains a single main window (plus
+XEmacs windows.  A frame initially contains a single main window (plus
 perhaps a minibuffer window), which you can subdivide vertically or
 horizontally into smaller windows.
 
@@ -31,7 +31,7 @@
 
 @menu
 * Creating Frames::		Creating additional frames.
-* Frame Parameters::		Controlling frame size, position, font, etc.
+* Frame Properties::		Controlling frame size, position, font, etc.
 * Frame Titles::                Automatic updating of frame titles.
 * Deleting Frames::		Frames last until explicitly deleted.
 * Finding All Frames::		How to examine all existing frames.
@@ -53,81 +53,86 @@
 
 To create a new frame, call the function @code{make-frame}.
 
-@defun make-frame &optional alist device
+@defun make-frame &optional props device
 This function creates a new frame on @var{device}, if @var{device}
 permits creation of frames.  (An X server does; an ordinary terminal
-does not.)  @var{device} defaults to the selected device if omitted.
+does not (yet).)  @var{device} defaults to the selected device if omitted.
 @xref{Consoles and Devices}.
 
-The argument is an alist specifying frame parameters.  Any parameters
-not mentioned in @var{alist} default according to the value of the
-variable @code{default-frame-alist}.  For X devices, parameters not
-specified in @code{default-frame-alist} default in turn from
-@code{default-x-frame-alist} and, if not specified there, from the X
-resources.  For TTY devices, @code{default-tty-frame-alist} is
-consulted as well as @code{default-frame-alist}.
+The argument @var{props} is a property list (a list of alternating
+keyword-value specifications) of properties for the new frame. (An alist
+is accepted for backward compatibility but should not be passed in.) Any
+properties not mentioned in @var{props} default according to the value
+of the variable @code{default-frame-plist}.  For X devices, properties
+not specified in @code{default-frame-plist} default in turn from
+@code{default-x-frame-plist} and, if not specified there, from the X
+resources.  For TTY devices, @code{default-tty-frame-plist} is consulted
+as well as @code{default-frame-plist}.
 
-The set of possible parameters depends in principle on what kind of
+The set of possible properties depends in principle on what kind of
 window system XEmacs uses to display its frames.  @xref{X Frame
-Parameters}, for documentation of individual parameters you can specify
+Properties}, for documentation of individual properties you can specify
 when creating an X window frame.
 @end defun
 
-@node Frame Parameters
-@section Frame Parameters
+@node Frame Properties
+@section Frame Properties
 
-A frame has many parameters that control its appearance and behavior.
-Just what parameters a frame has depends on what display mechanism it
+A frame has many properties that control its appearance and behavior.
+Just what properties a frame has depends on which display mechanism it
 uses.
 
-Frame parameters exist for the sake of window systems.  A terminal frame
-has a few parameters, mostly for compatibility's sake; only the height,
-width and @code{buffer-predicate} parameters really do something.
+Frame properties exist for the sake of window systems.  A terminal frame
+has few properties, mostly for compatibility's sake; only the height,
+width and @code{buffer-predicate} properties really do something.
 
 @menu
-* Parameter Access::       How to change a frame's parameters.
-* Initial Parameters::	   Specifying frame parameters when you make a frame.
-* X Frame Parameters::     List of frame parameters.
-* Size and Position::      Changing the size and position of a frame.
-* Frame Name::             The name of a frame (as opposed to its title).
+* Property Access::	How to change a frame's properties.
+* Initial Properties::	Specifying frame properties when you make a frame.
+* X Frame Properties::	List of frame properties.
+* Size and Position::	Changing the size and position of a frame.
+* Frame Name::		The name of a frame (as opposed to its title).
 @end menu
 
-@node Parameter Access
-@subsection Access to Frame Parameters
+@node Property Access
+@subsection Access to Frame Properties
+
+These functions let you read and change the properties of a frame.
 
-These functions let you read and change the parameter values of a
-frame.
+@defun frame-properties &optional frame
+This function returns a plist listing all the properties of @var{frame}
+and their values.
+@end defun
 
-@defun frame-parameters frame
-The function @code{frame-parameters} returns an alist listing all the
-parameters of @var{frame} and their values.
+@defun frame-property frame property &optional default
+This function returns @var{frame}'s value for the property
+@var{property}.
 @end defun
 
-@defun modify-frame-parameters frame alist
-This function alters the parameters of frame @var{frame} based on the
-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.
+@defun set-frame-properties frame plist
+This function alters the properties of frame @var{frame} based on the
+elements of property list @var{plist}.  If you don't mention a property
+in @var{plist}, its value doesn't change.
+@end defun
+
+@defun set-frame-property frame prop val
+This function sets the property @var{prop} of frame @var{frame} to the
+value @var{val}.
 @end defun
 
-@node Initial Parameters
-@subsection Initial Frame Parameters
+@node Initial Properties
+@subsection Initial Frame Properties
 
-You can specify the parameters for the initial startup frame
-by setting @code{initial-frame-alist} in your @file{.emacs} file.
+You can specify the properties for the initial startup frame by setting
+@code{initial-frame-plist} in your @file{.emacs} file.
 
-@defvar initial-frame-alist
-This variable's value is an alist of parameter values used when creating
-the initial X window frame.  Each element has the form:
+@defvar initial-frame-plist
+This variable's value is a plist of alternating property-value pairs
+used when creating the initial X window frame.
 
-@example
-(@var{parameter} . @var{value})
-@end example
-
-Emacs creates the initial frame before it reads your @file{~/.emacs}
-file.  After reading that file, Emacs checks @code{initial-frame-alist},
-and applies the parameter settings in the altered value to the already
+XEmacs creates the initial frame before it reads your @file{~/.emacs}
+file.  After reading that file, XEmacs checks @code{initial-frame-plist},
+and applies the property settings in the altered value to the already
 created initial frame.
 
 If these settings affect the frame geometry and appearance, you'll see
@@ -139,40 +144,40 @@
 X resource settings typically apply to all frames.  If you want to
 specify some X resources solely for the sake of the initial frame, and
 you don't want them to apply to subsequent frames, here's how to achieve
-this.  Specify parameters in @code{default-frame-alist} to override the
-X resources for subsequent frames; then, to prevent these from affecting
-the initial frame, specify the same parameters in
-@code{initial-frame-alist} with values that match the X resources.
+this: specify properties in @code{default-frame-plist} to override the X
+resources for subsequent frames; then, to prevent these from affecting
+the initial frame, specify the same properties in
+@code{initial-frame-plist} with values that match the X resources.
 @end defvar
 
-If these parameters specify a separate minibuffer-only frame with
-@code{(minibuffer . nil)}, and you have not created one, Emacs creates
-one for you.
+If these properties specify a separate minibuffer-only frame via a
+@code{minibuffer} property of @code{nil}, and you have not yet created
+one, XEmacs creates one for you.
 
-@defvar minibuffer-frame-alist
-This variable's value is an alist of parameter values used when creating
-an initial minibuffer-only frame---if such a frame is needed, according
-to the parameters for the main initial frame.
+@defvar minibuffer-frame-plist
+This variable's value is a plist of properties used when creating an
+initial minibuffer-only frame---if such a frame is needed, according to
+the properties for the main initial frame.
 @end defvar
 
-@defvar default-frame-alist
-This is an alist specifying default values of frame parameters for
-subsequent Emacs frames (not the initial ones).
+@defvar default-frame-plist
+This is a plist specifying default values of frame properties for
+subsequent XEmacs frames (not the initial ones).
 @end defvar
 
-See also @code{special-display-frame-alist}, in @ref{Choosing Window}.
+See also @code{special-display-frame-plist}, in @ref{Choosing Window}.
 
-If you use options that specify window appearance when you invoke Emacs,
-they take effect by adding elements to @code{default-frame-alist}.  One
+If you use options that specify window appearance when you invoke XEmacs,
+they take effect by adding elements to @code{default-frame-plist}.  One
 exception is @samp{-geometry}, which adds the specified position to
-@code{initial-frame-alist} instead.  @xref{Command Arguments,,, emacs,
+@code{initial-frame-plist} instead.  @xref{Command Arguments,,, emacs,
 The XEmacs User's Manual}.
 
-@node X Frame Parameters
-@subsection X Window Frame Parameters
+@node X Frame Properties
+@subsection X Window Frame Properties
 
-Just what parameters a frame has depends on what display mechanism it
-uses.  Here is a table of the parameters of an X window frame; of these,
+Just what properties a frame has depends on what display mechanism it
+uses.  Here is a table of the properties of an X window frame; of these,
 @code{name}, @code{height}, @code{width}, and @code{buffer-predicate}
 provide meaningful information in non-X frames.
 
@@ -180,11 +185,11 @@
 @item name
 The name of the frame.  Most window managers display the frame's name in
 the frame's border, at the top of the frame.  If you don't specify a
-name, and you have more than one frame, Emacs sets the frame name based
+name, and you have more than one frame, XEmacs sets the frame name based
 on the buffer displayed in the frame's selected window.
 
 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
+name is also used (instead of the name of the XEmacs executable) when
 looking up X resources for the frame.
 
 @item display
@@ -201,7 +206,7 @@
 A negative number @minus{}@var{pos}, or a list of the form @code{(-
 @var{pos})}, actually specifies the position of the right edge of the
 window with respect to the right edge of the screen.  A positive value
-of @var{pos} counts toward the left.  If the parameter is a negative
+of @var{pos} counts toward the left.  If the property is a negative
 integer @minus{}@var{pos} then @var{pos} is positive!
 
 @item top
@@ -213,7 +218,7 @@
 A negative number @minus{}@var{pos}, or a list of the form @code{(-
 @var{pos})}, actually specifies the position of the bottom edge of the
 window with respect to the bottom edge of the screen.  A positive value
-of @var{pos} counts toward the top.  If the parameter is a negative
+of @var{pos} counts toward the top.  If the property is a negative
 integer @minus{}@var{pos} then @var{pos} is positive!
 
 @item icon-left
@@ -229,9 +234,9 @@
 @item user-position
 Non-@code{nil} if the screen position of the frame was explicitly
 requested by the user (for example, with the @samp{-geometry} option).
-Nothing automatically makes this parameter non-@code{nil}; it is up to
-Lisp programs that call @code{make-frame} to specify this parameter as
-well as specifying the @code{left} and @code{top} parameters.
+Nothing automatically makes this property non-@code{nil}; it is up to
+Lisp programs that call @code{make-frame} to specify this property as
+well as specifying the @code{left} and @code{top} properties.
 
 @item height
 The height of the frame contents, in characters.  (To get the height in
@@ -318,8 +323,8 @@
 @cindex position of frame
 
   You can read or change the size and position of a frame using the
-frame parameters @code{left}, @code{top}, @code{height}, and
-@code{width}.  Whatever geometry parameters you don't specify are chosen
+frame properties @code{left}, @code{top}, @code{height}, and
+@code{width}.  Whatever geometry properties you don't specify are chosen
 by the window manager in its usual fashion.
 
   Here are some special features for working with sizes and positions:
@@ -327,7 +332,7 @@
 @defun set-frame-position frame left top
 This function sets the position of the top left corner of @var{frame} to
 @var{left} and @var{top}.  These arguments are measured in pixels, and
-count from the top left corner of the screen.  Negative parameter values
+count from the top left corner of the screen.  Negative property values
 count up or rightward from the top left corner of the screen.
 @end defun
 
@@ -364,19 +369,19 @@
 @defun x-parse-geometry geom
 @cindex geometry specification
 The function @code{x-parse-geometry} converts a standard X windows
-geometry string to an alist that you can use as part of the argument to
+geometry string to a plist that you can use as part of the argument to
 @code{make-frame}.
 
-The alist describes which parameters were specified in @var{geom}, and
+The plist describes which properties were specified in @var{geom}, and
 gives the values specified for them.  Each element looks like
-@code{(@var{parameter} . @var{value})}.  The possible @var{parameter}
+@code{(@var{property} . @var{value})}.  The possible @var{property}
 values are @code{left}, @code{top}, @code{width}, and @code{height}.
 
-For the size parameters, the value must be an integer.  The position
-parameter names @code{left} and @code{top} are not totally accurate,
+For the size properties, the value must be an integer.  The position
+property names @code{left} and @code{top} are not totally accurate,
 because some values indicate the position of the right or bottom edges
 instead.  These are the @var{value} possibilities for the position
-parameters:
+properties:
 
 @table @asis
 @item an integer
@@ -421,7 +426,7 @@
 @defun frame-name &optional frame
 This function returns the name of @var{frame}, which defaults to the
 selected frame if not specified.  The name of a frame can also be
-obtained from the frame's parameters.  @xref{Frame Parameters}.
+obtained from the frame's properties.  @xref{Frame Properties}.
 @end defun
 
 @defvar default-frame-name
@@ -436,9 +441,9 @@
 Every frame has a title; most window managers display the frame title at
 the top of the frame.  You can specify an explicit title with the
 @code{name} frame property.  But normally you don't specify this
-explicitly, and Emacs computes the title automatically.
+explicitly, and XEmacs computes the title automatically.
 
-Emacs computes the frame title based on a template stored in the
+XEmacs computes the frame title based on a template stored in the
 variable @code{frame-title-format}.
 
 @defvar frame-title-format
@@ -496,7 +501,7 @@
 @ignore Not in XEmacs currently
   Some window managers provide a command to delete a window.  These work
 by sending a special message to the program that operates the window.
-When Emacs gets one of these commands, it generates a
+When XEmacs gets one of these commands, it generates a
 @code{delete-frame} event, whose normal definition is a command that
 calls the function @code{delete-frame}.  @xref{Misc Events}.
 @end ignore
@@ -658,7 +663,7 @@
 Only the selected terminal frame is actually displayed on the terminal.
 Each terminal screen except for the initial one has a number, and the
 number of the selected frame appears in the mode line after the word
-@samp{Emacs} (@pxref{Modeline Variables}).
+@samp{XEmacs} (@pxref{Modeline Variables}).
 
 @defun select-frame frame
 This function selects frame @var{frame}, temporarily disregarding the
@@ -673,7 +678,7 @@
 waiting for an event.
 
 @ignore (FSF Emacs)
-Emacs cooperates with the X server and the window managers by arranging
+XEmacs cooperates with the X server and the window managers by arranging
 to select frames according to what the server and window manager ask
 for.  It does so by generating a special kind of input event, called a
 @dfn{focus} event.  The command loop handles a focus event by calling
@@ -774,13 +779,13 @@
 
 @ignore  @c Not in XEmacs.
   The visibility status of a frame is also available as a frame
-parameter.  You can read or change it as such.  @xref{X Frame
-Parameters}.
+property.  You can read or change it as such.  @xref{X Frame
+Properties}.
 
-  The user can iconify and deiconify frames with the window manager.
-This happens below the level at which Emacs can exert any control, but
-Emacs does provide events that you can use to keep track of such
-changes.  @xref{Misc Events}.
+The user can iconify and deiconify frames with the window manager.  This
+happens below the level at which XEmacs can exert any control, but XEmacs
+does provide events that you can use to keep track of such changes.
+@xref{Misc Events}.
 @end ignore
 
 @node Raising and Lowering
@@ -818,7 +823,7 @@
 this for you, but the following variables are provided in case you're
 using a broken WM.  (Under FSF Emacs, the same functionality is
 provided through the @code{auto-raise} and @code{auto-lower}
-frame parameters.)
+frame properties.)
 
 @defvar auto-raise-frame
 This variable's value is @code{t} if frames will be raised to the top