mirror/emacs
1
0
Fork 0
mirror of https://git.savannah.gnu.org/git/emacs.git synced 2024-11-24 07:20:37 +00:00
Code Issues Releases Activity

Fix documentation of `make-frame' and related variables and hooks

Browse Source 
* lisp/frame.el (before-make-frame-hook)
(after-make-frame-functions, frame-inherited-parameters)
(make-frame): Fix doc-strings.
* doc/lispref/frames.texi (Creating Frames): Fix description
of `make-frame' and related variables and hooks.
This commit is contained in:
Martin Rudalics 2017-09-25 10:09:32 +02:00
parent 3d3778d82a
commit dc6b3560e5
2 changed files with 42 additions and 34 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

56
doc/lispref/frames.texi
View File

@ -112,37 +112,39 @@ window of another Emacs frame. @xref{Child Frames}.
* Display Feature Testing:: Determining the features of a terminal.
@end menu
@node Creating Frames
@section Creating Frames
@cindex frame creation
To create a new frame, call the function @code{make-frame}.
@deffn Command make-frame &optional alist
@deffn Command make-frame &optional parameters
This function creates and returns a new frame, displaying the current
buffer.
The @var{alist} argument is an alist that specifies frame parameters
for the new frame. @xref{Frame Parameters}. If you specify the
@code{terminal} parameter in @var{alist}, the new frame is created on
that terminal. Otherwise, if you specify the @code{window-system}
frame parameter in @var{alist}, that determines whether the frame
should be displayed on a text terminal or a graphical terminal.
@xref{Window Systems}. If neither is specified, the new frame is
created in the same terminal as the selected frame.
The @var{parameters} argument is an alist that specifies frame
parameters for the new frame. @xref{Frame Parameters}. If you specify
the @code{terminal} parameter in @var{parameters}, the new frame is
created on that terminal. Otherwise, if you specify the
@code{window-system} frame parameter in @var{parameters}, that
determines whether the frame should be displayed on a text terminal or a
graphical terminal. @xref{Window Systems}. If neither is specified,
the new frame is created in the same terminal as the selected frame.
Any parameters not mentioned in @var{alist} default to the values in
the alist @code{default-frame-alist} (@pxref{Initial Parameters});
Any parameters not mentioned in @var{parameters} default to the values
in the alist @code{default-frame-alist} (@pxref{Initial Parameters});
parameters not specified there default from the X resources or its
equivalent on your operating system (@pxref{X Resources,, X Resources,
emacs, The GNU Emacs Manual}). After the frame is created, Emacs
applies any parameters listed in @code{frame-inherited-parameters}
(see below) and not present in the argument, taking the values from
the frame that was selected when @code{make-frame} was called.
emacs, The GNU Emacs Manual}). After the frame is created, this
function applies any parameters specified in
@code{frame-inherited-parameters} (see below) it has no assigned yet,
taking the values from the frame that was selected when
@code{make-frame} was called.
Note that on multi-monitor displays (@pxref{Multiple Terminals}), the
window manager might position the frame differently than specified by
the positional parameters in @var{alist} (@pxref{Position
the positional parameters in @var{parameters} (@pxref{Position
Parameters}). For example, some window managers have a policy of
displaying the frame on the monitor that contains the largest part of
the window (a.k.a.@: the @dfn{dominating} monitor).
@ -158,20 +160,28 @@ A normal hook run by @code{make-frame} before it creates the frame.
@end defvar
@defvar after-make-frame-functions
An abnormal hook run by @code{make-frame} after it creates the frame.
Each function in @code{after-make-frame-functions} receives one argument, the
frame just created.
An abnormal hook run by @code{make-frame} after it created the frame.
Each function in @code{after-make-frame-functions} receives one
argument, the frame just created.
@end defvar
Note that any functions added to these hooks by your initial file are
usually not run for the initial frame, since Emacs reads the initial
file only after creating that frame. However, if the initial frame is
specified to use a separate minibuffer frame (@pxref{Minibuffers and
Frames}), the functions will be run for both, the minibuffer-less and
the minibuffer frame.
@defvar frame-inherited-parameters
This variable specifies the list of frame parameters that a newly
created frame inherits from the currently selected frame. For each
parameter (a symbol) that is an element in the list and is not present
in the argument to @code{make-frame}, the function sets the value of
that parameter in the created frame to its value in the selected
frame.
parameter (a symbol) that is an element in this list and has not been
assigned earlier when processing @code{make-frame}, the function sets
the value of that parameter in the created frame to its value in the
selected frame.
@end defvar
@node Multiple Terminals
@section Multiple Terminals
@cindex multiple terminals

20
lisp/frame.el
View File

@ -604,11 +604,12 @@ new frame."
(select-frame (make-frame))))
(defvar before-make-frame-hook nil
"Functions to run before a frame is created.")
"Functions to run before `make-frame' creates a new frame.")
(defvar after-make-frame-functions nil
"Functions to run after a frame is created.
The functions are run with one arg, the newly created frame.")
"Functions to run after `make-frame' created a new frame.
The functions are run with one argument, the newly created
frame.")
(defvar after-setting-font-hook nil
"Functions to run after a frame's font has been changed.")
@ -617,7 +618,7 @@ The functions are run with one arg, the newly created frame.")
(define-obsolete-function-alias 'new-frame 'make-frame "22.1")
(defvar frame-inherited-parameters '()
"Parameters `make-frame' copies from the `selected-frame' to the new frame.")
"Parameters `make-frame' copies from the selected to the new frame.")
(defvar x-display-name)
@ -632,9 +633,6 @@ form (NAME . VALUE), for example:
(width . NUMBER) The frame should be NUMBER characters in width.
(height . NUMBER) The frame should be NUMBER text lines high.
You cannot specify either `width' or `height', you must specify
neither or both.
(minibuffer . t) The frame should have a minibuffer.
(minibuffer . nil) The frame should have no minibuffer.
(minibuffer . only) The frame should contain only a minibuffer.
@ -650,10 +648,10 @@ neither or both.
In addition, any parameter specified in `default-frame-alist',
but not present in PARAMETERS, is applied.
Before creating the frame (via `frame-creation-function-alist'),
this function runs the hook `before-make-frame-hook'. After
creating the frame, it runs the hook `after-make-frame-functions'
with one arg, the newly created frame.
Before creating the frame (via `frame-creation-function'), this
function runs the hook `before-make-frame-hook'. After creating
the frame, it runs the hook `after-make-frame-functions' with one
argument, the newly created frame.
If a display parameter is supplied and a window-system is not,
guess the window-system from the display.