procyberian/emacs
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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. * Display Feature Testing:: Determining the features of a terminal.
@end menu @end menu
@node Creating Frames @node Creating Frames
@section Creating Frames @section Creating Frames
@cindex frame creation @cindex frame creation
To create a new frame, call the function @code{make-frame}. 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 This function creates and returns a new frame, displaying the current
buffer. buffer.
The @var{alist} argument is an alist that specifies frame parameters The @var{parameters} argument is an alist that specifies frame
for the new frame. @xref{Frame Parameters}. If you specify the parameters for the new frame. @xref{Frame Parameters}. If you specify
@code{terminal} parameter in @var{alist}, the new frame is created on the @code{terminal} parameter in @var{parameters}, the new frame is
that terminal. Otherwise, if you specify the @code{window-system} created on that terminal. Otherwise, if you specify the
frame parameter in @var{alist}, that determines whether the frame @code{window-system} frame parameter in @var{parameters}, that
should be displayed on a text terminal or a graphical terminal. determines whether the frame should be displayed on a text terminal or a
@xref{Window Systems}. If neither is specified, the new frame is graphical terminal. @xref{Window Systems}. If neither is specified,
created in the same terminal as the selected frame. 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 Any parameters not mentioned in @var{parameters} default to the values
the alist @code{default-frame-alist} (@pxref{Initial Parameters}); in the alist @code{default-frame-alist} (@pxref{Initial Parameters});
parameters not specified there default from the X resources or its parameters not specified there default from the X resources or its
equivalent on your operating system (@pxref{X Resources,, X Resources, equivalent on your operating system (@pxref{X Resources,, X Resources,
emacs, The GNU Emacs Manual}). After the frame is created, Emacs emacs, The GNU Emacs Manual}). After the frame is created, this
applies any parameters listed in @code{frame-inherited-parameters} function applies any parameters specified in
(see below) and not present in the argument, taking the values from @code{frame-inherited-parameters} (see below) it has no assigned yet,
the frame that was selected when @code{make-frame} was called. 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 Note that on multi-monitor displays (@pxref{Multiple Terminals}), the
window manager might position the frame differently than specified by 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 Parameters}). For example, some window managers have a policy of
displaying the frame on the monitor that contains the largest part of displaying the frame on the monitor that contains the largest part of
the window (a.k.a.@: the @dfn{dominating} monitor). 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 @end defvar
@defvar after-make-frame-functions @defvar after-make-frame-functions
An abnormal hook run by @code{make-frame} after it creates the frame. 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 Each function in @code{after-make-frame-functions} receives one
frame just created. argument, the frame just created.
@end defvar @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 @defvar frame-inherited-parameters
This variable specifies the list of frame parameters that a newly This variable specifies the list of frame parameters that a newly
created frame inherits from the currently selected frame. For each created frame inherits from the currently selected frame. For each
parameter (a symbol) that is an element in the list and is not present parameter (a symbol) that is an element in this list and has not been
in the argument to @code{make-frame}, the function sets the value of assigned earlier when processing @code{make-frame}, the function sets
that parameter in the created frame to its value in the selected the value of that parameter in the created frame to its value in the
frame. selected frame.
@end defvar @end defvar
@node Multiple Terminals @node Multiple Terminals
@section Multiple Terminals @section Multiple Terminals
@cindex multiple terminals @cindex multiple terminals

20
lisp/frame.el
View file

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