diff options
Diffstat (limited to 'doc/lispref/frames.texi')
| -rw-r--r-- | doc/lispref/frames.texi | 170 |
1 files changed, 133 insertions, 37 deletions
diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index b993f4932cd..629cec3c5fe 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -181,6 +181,12 @@ the value of that parameter in the created frame to its value in the selected frame. @end defvar +@defopt server-after-make-frame-hook +A normal hook run when the Emacs server creates a client frame. When +this hook is called, the created frame is the selected one. +@xref{Emacs Server,,, emacs, The GNU Emacs Manual}. +@end defopt + @node Multiple Terminals @section Multiple Terminals @@ -434,6 +440,17 @@ This function returns the attributes of the physical monitor dominating (see above) @var{frame}, which defaults to the selected frame. @end defun +On multi-monitor displays it is possible to use the command +@code{make-frame-on-monitor} to make frames on the specified monitor. + +@deffn Command make-frame-on-monitor monitor &optional display parameters +This function creates and returns a new frame on @var{monitor} located +on @var{display}, taking the other frame parameters from the alist +@var{parameters}. @var{monitor} should be the name of the physical +monitor, the same string as returned by the function +@code{display-monitor-attributes-list} in the attribute @code{name}. +@var{display} should be the name of an X display (a string). +@end deffn @node Frame Geometry @section Frame Geometry @@ -1867,6 +1884,12 @@ minibuffer window to @code{t} and vice-versa, or from @code{t} to @code{nil}. If the parameter specifies a minibuffer window already, setting it to @code{nil} has no effect. +The special value @code{child-frame} means to make a minibuffer-only +child frame (@pxref{Child Frames}) whose parent becomes the frame +created. As if specified as @code{nil}, Emacs will set this parameter +to the minibuffer window of the child frame but will not select the +child frame after its creation. + @vindex buffer-predicate@r{, a frame parameter} @item buffer-predicate The buffer-predicate function for this frame. The function @@ -2255,13 +2278,21 @@ variable do not take effect immediately, only when you specify the @vindex font-backend@r{, 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 -currently two available font backends: @code{x} (the X core font -driver) and @code{xft} (the Xft font driver). On MS-Windows, there are -currently two available font backends: @code{gdi} and -@code{uniscribe} (@pxref{Windows Fonts,,, emacs, The GNU Emacs -Manual}). On other systems, there is only one available font backend, -so it does not make sense to modify this frame parameter. +drawing characters on the frame, in order of priority. In Emacs built +without Cairo drawing on X, there are currently three available font +backends: @code{x} (the X core font driver), @code{xft} (the Xft font +driver), and @code{xfthb} (the Xft font driver with HarfBuzz text +shaping). If built with the Cairo drawing, there are also three +available font backends on X: @code{x}, @code{ftcr} (the FreeType font +driver on Cairo), and @code{ftcrhb} (the FreeType font driver on Cairo +with HarfBuzz text shaping). On MS-Windows, there are currently three +available font backends: @code{gdi} (the core MS-Windows font driver), +@code{uniscribe} (font driver for OTF and TTF fonts with text shaping +by the Uniscribe engine), and @code{harfbuzz} (font driver for OTF and +TTF fonts with HarfBuzz text shaping) (@pxref{Windows Fonts,,, emacs, +The GNU Emacs Manual}). On other systems, there is only one available +font backend, so it does not make sense to modify this frame +parameter. @vindex background-mode@r{, a frame parameter} @item background-mode @@ -2524,6 +2555,7 @@ it. @deffn Command delete-frame &optional frame force @vindex delete-frame-functions +@vindex after-delete-frame-functions This function deletes the frame @var{frame}. The argument @var{frame} must specify a live frame (see below) and defaults to the selected frame. @@ -2535,7 +2567,9 @@ performed recursively; so this step makes sure that no other frames with @var{frame} as their ancestor will exist. Then, unless @var{frame} specifies a tooltip, this function runs the hook @code{delete-frame-functions} (each function getting one argument, -@var{frame}) before actually killing the frame. +@var{frame}) before actually killing the frame. After actually killing +the frame and removing the frame from the frame list, @code{delete-frame} +runs @code{after-delete-frame-functions}. Note that a frame cannot be deleted as long as its minibuffer serves as surrogate minibuffer for another frame (@pxref{Minibuffers and Frames}). @@ -2696,14 +2730,22 @@ This function returns the selected frame. Some window systems and window managers direct keyboard input to the window object that the mouse is in; others require explicit clicks or commands to @dfn{shift the focus} to various window objects. Either -way, Emacs automatically keeps track of which frame has the focus. To +way, Emacs automatically keeps track of which frames have focus. To explicitly switch to a different frame from a Lisp function, call @code{select-frame-set-input-focus}. -Lisp programs can also switch frames temporarily by calling the -function @code{select-frame}. This does not alter the window system's -concept of focus; rather, it escapes from the window manager's control -until that control is somehow reasserted. +The plural ``frames'' in the previous paragraph is deliberate: while +Emacs itself has only one selected frame, Emacs can have frames on +many different terminals (recall that a connection to a window system +counts as a terminal), and each terminal has its own idea of which +frame has input focus. When you set the input focus to a frame, you +set the focus for that frame's terminal, but frames on other terminals +may still remain focused. + +Lisp programs can switch frames temporarily by calling the function +@code{select-frame}. This does not alter the window system's concept +of focus; rather, it escapes from the window manager's control until +that control is somehow reasserted. When using a text terminal, only one frame can be displayed at a time on the terminal, so after a call to @code{select-frame}, the next @@ -2714,11 +2756,11 @@ before the buffer name (@pxref{Mode Line Variables}). @defun select-frame-set-input-focus frame &optional norecord This function selects @var{frame}, raises it (should it happen to be -obscured by other frames) and tries to give it the X server's focus. -On a text terminal, the next redisplay displays the new frame on the -entire terminal screen. The optional argument @var{norecord} has the -same meaning as for @code{select-frame} (see below). The return value -of this function is not significant. +obscured by other frames) and tries to give it the window system's +focus. On a text terminal, the next redisplay displays the new frame +on the entire terminal screen. The optional argument @var{norecord} +has the same meaning as for @code{select-frame} (see below). +The return value of this function is not significant. @end defun Ideally, the function described next should focus a frame without also @@ -2766,17 +2808,35 @@ could switch to a different terminal without switching back when you're done. @end deffn -Emacs cooperates with the window system by arranging to select frames as -the server and window manager request. It does so by generating a -special kind of input event, called a @dfn{focus} event, when -appropriate. The command loop handles a focus event by calling -@code{handle-switch-frame}. @xref{Focus Events}. +@cindex text-terminal focus notification +Emacs cooperates with the window system by arranging to select frames +as the server and window manager request. When a window system +informs Emacs that one of its frames has been selected, Emacs +internally generates a @dfn{focus-in} event. When an Emacs frame is +displayed on a text-terminal emulator, such as @command{xterm}, which +supports reporting of focus-change notification, the focus-in and +focus-out events are available even for text-mode frames. Focus +events are normally handled by @code{handle-focus-in}. + +@deffn Command handle-focus-in event +This function handles focus-in events from window systems and +terminals that support explicit focus notifications. It updates the +per-frame focus flags that @code{frame-focus-state} queries and calls +@code{after-focus-change-function}. In addition, it generates a +@code{switch-frame} event in order to switch the Emacs notion of the +selected frame to the frame most recently focused in some terminal. +It's important to note that this switching of the Emacs selected frame +to the most recently focused frame does not mean that other frames do +not continue to have the focus in their respective terminals. Do not +invoke this function yourself: instead, attach logic to +@code{after-focus-change-function}. +@end deffn @deffn Command handle-switch-frame frame -This function handles a focus event by selecting frame @var{frame}. - -Focus events normally do their job by invoking this command. -Don't call it for any other reason. +This function handles a switch-frame event, which Emacs generates for +itself upon focus notification or under various other circumstances +involving an input event arriving at a different frame from the last +event. Do not invoke this function yourself. @end deffn @defun redirect-frame-focus frame &optional focus-frame @@ -2810,14 +2870,42 @@ The redirection lasts until @code{redirect-frame-focus} is called to change it. @end defun -@defvar focus-in-hook -This is a normal hook run when an Emacs frame gains input focus. The -frame gaining focus is selected when this hook is run. -@end defvar +@defun frame-focus-state frame +This function retrieves the last known focus state of @var{frame}. + +It returns @code{nil} if the frame is known not to be focused, +@code{t} if the frame is known to be focused, or @code{unknown} if +Emacs does not know the focus state of the frame. (You may see this +last state in TTY frames running on terminals that do not support +explicit focus notifications.) +@end defun -@defvar focus-out-hook -This is a normal hook run when an Emacs frame has lost input focus and -no other Emacs frame has gained input focus instead. +@defvar after-focus-change-function +This function is an extension point that code can use to receive a +notification that focus has changed. + +This function is called with no arguments when Emacs notices that the +set of focused frames may have changed. Code wanting to do something +when frame focus changes should use @code{add-function} to add a +function to this one, and in this added function, re-scan the set of +focused frames, calling @code{frame-focus-state} to retrieve the last +known focus state of each frame. Focus events are delivered +asynchronously, and frame input focus according to an external system +may not correspond to the notion of the Emacs selected frame. +Multiple frames may appear to have input focus simultaneously due to +focus event delivery differences, the presence of multiple Emacs +terminals, and other factors, and code should be robust in the face of +this situation. + +Depending on window system, focus events may also be delivered +repeatedly and with different focus states before settling to the +expected values. Code relying on focus notifications should +``debounce'' any user-visible updates arising from focus changes, +perhaps by deferring work until redisplay. + +This function may be called in arbitrary contexts, including from +inside @code{read-event}, so take the same care as you might when +writing a process filter. @end defvar @defopt focus-follows-mouse @@ -3140,9 +3228,17 @@ top-level frame which also always appears on top of its parent window---the desktop's root window. When a parent frame is iconified or made invisible (@pxref{Visibility of Frames}), its child frames are made invisible. When a parent frame is deiconified or made visible, its -child frames are made visible. When a parent frame is about to be -deleted (@pxref{Deleting Frames}), its child frames are recursively -deleted before it. +child frames are made visible. + + When a parent frame is about to be deleted (@pxref{Deleting +Frames}), its child frames are recursively deleted before it. There +is one exception to this rule: When the child frame serves as a +surrogate minibuffer frame (@pxref{Minibuffers and Frames}) for +another frame, it is retained until the parent frame has been deleted. +If, at this time, no remaining frame uses the child frame as its +minibuffer frame, Emacs will try to delete the child frame too. If +that deletion fails for whatever reason, the child frame is made a +top-level frame. Whether a child frame can have a menu or tool bar is window-system or window manager dependent. Most window-systems explicitly disallow menus |