commit 96644ed496cfc36ef886c401250203c57d77ab75 (HEAD, refs/remotes/origin/master) Author: Martin Rudalics Date: Fri Apr 14 09:26:03 2017 +0200 A few additional copy-edits in documentation of frames * doc/lispref/frames.texi (Frame Layout) (Implied Frame Resizing): Windows -> MS-Windows. (Deleting Frames): Fix typo. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index b8f4257811..9a32f0045a 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -575,7 +575,7 @@ frames. Display of the title bar can be suppressed by setting the @cindex external menu bar The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs itself) or external (drawn by the toolkit). Most builds (GTK+, Lucid, -Motif and Windows) rely on an external menu bar. NS also uses an +Motif and MS-Windows) rely on an external menu bar. NS also uses an external menu bar which, however, is not part of the outer frame. Non-toolkit builds can provide an internal menu bar. On text terminal frames, the menu bar is part of the frame's root window (@pxref{Windows @@ -648,8 +648,9 @@ indicate that position for the various builds: @end itemize Accordingly, the native height of a frame may include the height of the -tool bar but not that of the menu bar (Lucid, Motif, Windows) or those -of the menu bar and the tool bar (non-toolkit and text terminal frames). +tool bar but not that of the menu bar (Lucid, Motif, MS-Windows) or +those of the menu bar and the tool bar (non-toolkit and text terminal +frames). The native position of a frame is the reference position for functions that set or return the current position of the mouse (@pxref{Mouse @@ -1153,7 +1154,7 @@ unchanged if this option is either @code{t} or a list containing @code{vertical-scroll-bars}. The default value is @code{'(tool-bar-lines)} for Lucid, Motif and -Windows (which means that adding/removing a tool bar there does not +MS-Windows (which means that adding/removing a tool bar there does not change the outer frame height), @code{nil} on all other window systems including GTK+ (which means that changing any of the parameters listed above may change the size of the outer frame), and @code{t} otherwise @@ -2275,9 +2276,9 @@ frame. It first deletes any child frame of @var{frame} (@pxref{Child Frames}) and any frame whose @code{delete-before} frame parameter (@pxref{Frame Interaction Parameters}) specifies @var{frame}. All such deletions are -performed recursively; so this step makes sure that there no other -frames with @var{frame} as their ancestor will exist. Then, unless -@var{frame} specifies a tooltip, this function runs the hook +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. commit 86e512ed10d83e2d233cfb95bff68b6c05729686 Author: Glenn Morris Date: Thu Apr 13 21:17:09 2017 -0400 Use user-error for some ert.el errors * lisp/emacs-lisp/ert.el (ert-read-test-name, ert-delete-all-tests) (ert-results-find-test-at-point-other-window, ert-describe-test): Use user-error. diff --git a/lisp/emacs-lisp/ert.el b/lisp/emacs-lisp/ert.el index e7387e463c..7eaf33a27d 100644 --- a/lisp/emacs-lisp/ert.el +++ b/lisp/emacs-lisp/ert.el @@ -1602,7 +1602,7 @@ Signals an error if no test name was read." (let ((sym (intern-soft input))) (if (ert-test-boundp sym) sym - (error "Input does not name a test"))))) + (user-error "Input does not name a test"))))) (defun ert-read-test-name-at-point (prompt) "Read the name of a test and return it as a symbol. @@ -1628,7 +1628,7 @@ Nothing more than an interactive interface to `ert-make-test-unbound'." (interactive) (when (called-interactively-p 'any) (unless (y-or-n-p "Delete all tests? ") - (error "Aborted"))) + (user-error "Aborted"))) ;; We can't use `ert-select-tests' here since that gives us only ;; test objects, and going from them back to the test name symbols ;; can fail if the `ert-test' defstruct has been redefined. @@ -2141,7 +2141,7 @@ To be used in the ERT results buffer." To be used in the ERT results buffer." (or (ert--results-test-node-or-null-at-point) - (error "No test at point"))) + (user-error "No test at point"))) (defun ert-results-next-test () "Move point to the next test. @@ -2191,7 +2191,7 @@ To be used in the ERT results buffer." (interactive) (let ((name (ert-test-at-point))) (unless name - (error "No test at point")) + (user-error "No test at point")) (ert-find-test-other-window name))) (defun ert--test-name-button-action (button) @@ -2352,7 +2352,7 @@ To be used in the ERT results buffer." (cl-destructuring-bind (test redefinition-state) (ert--results-test-at-point-allow-redefinition) (when (null test) - (error "No test at point")) + (user-error "No test at point")) (let* ((stats ert--results-stats) (progress-message (format "Running %stest %S" (cl-ecase redefinition-state @@ -2525,7 +2525,7 @@ To be used in the ERT results buffer." "Display the documentation for TEST-OR-TEST-NAME (a symbol or ert-test)." (interactive (list (ert-read-test-name-at-point "Describe test"))) (when (< emacs-major-version 24) - (error "Requires Emacs 24")) + (user-error "Requires Emacs 24 or later")) (let (test-name test-definition) (cl-etypecase test-or-test-name commit a855473b7079b467ac01dbcee89cb57b3599fdac Author: Glenn Morris Date: Thu Apr 13 20:17:08 2017 -0400 Use user-error for customize's "invalid face" error * lisp/cus-edit.el (customize-face): Use user-error. (debug-ignored-errors): No more need to add "Invalid face". diff --git a/lisp/cus-edit.el b/lisp/cus-edit.el index f408e83576..ca6b8a38d9 100644 --- a/lisp/cus-edit.el +++ b/lisp/cus-edit.el @@ -1334,7 +1334,7 @@ suggest to customize that face, if it's customizable." (if (get face 'face-alias) (setq face (get face 'face-alias))) (unless (facep face) - (error "Invalid face %S" face)) + (user-error "Invalid face %S" face)) (funcall display-fun (list (list face 'custom-face)) (format "*Customize Face: %s*" @@ -4846,8 +4846,6 @@ if that value is non-nil." (define-obsolete-function-alias 'custom-mode 'Custom-mode "23.1") -(add-to-list 'debug-ignored-errors "^Invalid face:? ") - ;;; The End. (provide 'cus-edit) commit e8adf68824178ea25a5fda0c53233a42883de861 Author: Glenn Morris Date: Thu Apr 13 20:15:34 2017 -0400 Remove duplicate lisp-eval-defun definition * lisp/emacs-lisp/lisp-mode.el (lisp-eval-defun): Autoload rather than defining a stub. diff --git a/lisp/emacs-lisp/lisp-mode.el b/lisp/emacs-lisp/lisp-mode.el index b7a5eb774d..2e6e13f1dd 100644 --- a/lisp/emacs-lisp/lisp-mode.el +++ b/lisp/emacs-lisp/lisp-mode.el @@ -725,11 +725,7 @@ or to switch back to an existing one." ;; Used in old LispM code. (defalias 'common-lisp-mode 'lisp-mode) -;; This will do unless inf-lisp.el is loaded. -(defun lisp-eval-defun (&optional _and-go) - "Send the current defun to the Lisp process made by \\[run-lisp]." - (interactive) - (error "Process lisp does not exist")) +(autoload 'lisp-eval-defun "inf-lisp" nil t) ;; May still be used by some external Lisp-mode variant. (define-obsolete-function-alias 'lisp-comment-indent commit 393228bd7a96b121f2ffba5fb7072a6cbf5ecefd Author: Glenn Morris Date: Thu Apr 13 20:14:01 2017 -0400 * lisp/Makefile.in (check-defun-dups): Ignore obsolete files. diff --git a/lisp/Makefile.in b/lisp/Makefile.in index b82f2c6918..c1b063246e 100644 --- a/lisp/Makefile.in +++ b/lisp/Makefile.in @@ -476,7 +476,7 @@ check-declare: check-defun-dups: sed -n -e '/^(defun /s/\(.\)(.*/\1/p' \ $$(find . -name '*.el' -print | \ - grep -Ev '(loaddefs|ldefs-boot)\.el') | sort | uniq -d + grep -Ev '(loaddefs|ldefs-boot)\.el|obsolete') | sort | uniq -d # Dependencies commit ad128fee434a954da2ead75647b6396ddbf91f6a Author: Glenn Morris Date: Thu Apr 13 20:12:02 2017 -0400 Create generated lisp files before main loaddefs.el This should improve reproducibility of lisp/loaddefs.el. * lisp/Makefile.in (gen-lisp): New phony target. ($(lisp)/loaddefs.el, compile-main): Depend on gen-lisp. * src/Makefile.in ($(leimdir)/leim-list.el): Depend on all of ../leim. * lisp/cedet/semantic.el (semantic-mode): * lisp/cedet/semantic/fw.el (top-level): * lisp/emacs-lisp/eieio-core.el (top-level): Robustify to generated input files maybe not yet existing. diff --git a/lisp/Makefile.in b/lisp/Makefile.in index ec9ea16021..b82f2c6918 100644 --- a/lisp/Makefile.in +++ b/lisp/Makefile.in @@ -179,6 +179,10 @@ $(lisp)/finder-inf.el: # Note that we set no-update-autoloads in _generated_ leim files. # If you want to allow autoloads in such files, remove that, # and make this depend on leim. +# Actually this should depend on leim anyway, since no-update-autoloads +# files are still recorded in loaddefs. So we should ensure +# that all input files are generated before we create loaddefs. +# Otherwise making loaddefs again will change the output. # # Write to a temporary file in case we're doing a parallel build and a # CANNOT_DUMP-mode Emacs needs to read loaddefs at startup. @@ -192,7 +196,7 @@ $(lisp)/finder-inf.el: # slow; starting from an almost-correct content will enable the "only # update where necessary" feature of batch-update-autoloads. autoloads .PHONY: $(lisp)/loaddefs.el -$(lisp)/loaddefs.el: $(LOADDEFS) +$(lisp)/loaddefs.el: gen-lisp $(LOADDEFS) @echo Directories for loaddefs: ${SUBDIRS_ALMOST} @if test -f $@ ; then cp $@ $(lisp)/loaddefs.tmp ; fi $(AM_V_GEN)$(emacs) -l autoload \ @@ -319,7 +323,7 @@ compile-targets: $(TARGETS) # Compile all the Elisp files that need it. Beware: it approximates # 'no-byte-compile', so watch out for false-positives! -compile-main: leim semantic compile-clean +compile-main: gen-lisp compile-clean @(cd $(lisp) && \ els=`echo "${SUBDIRS_REL} " | sed -e 's|/\./|/|g' -e 's|/\. | |g' -e 's| |/*.el |g'`; \ for el in $$els; do \ @@ -343,7 +347,10 @@ compile-clean: fi \ done -.PHONY: leim semantic +.PHONY: gen-lisp leim semantic + +gen-lisp: leim semantic + leim: $(MAKE) -C ../leim all EMACS="$(EMACS)" diff --git a/lisp/cedet/semantic.el b/lisp/cedet/semantic.el index 6a264cabd6..c38afed396 100644 --- a/lisp/cedet/semantic.el +++ b/lisp/cedet/semantic.el @@ -1116,8 +1116,9 @@ Semantic mode. ;; Enable all the global auxiliary minor modes in ;; `semantic-submode-list'. (dolist (mode semantic-submode-list) - (if (memq mode semantic-default-submodes) - (funcall mode 1))) + (and (memq mode semantic-default-submodes) + (fboundp mode) + (funcall mode 1))) (unless semantic-load-system-cache-loaded (setq semantic-load-system-cache-loaded t) (when (and (boundp 'semanticdb-default-system-save-directory) @@ -1139,7 +1140,7 @@ Semantic mode. (add-hook 'completion-at-point-functions 'semantic-analyze-completion-at-point-function) - (if global-ede-mode + (if (bound-and-true-p global-ede-mode) (define-key cedet-menu-map [cedet-menu-separator] '("--"))) (dolist (b (buffer-list)) (with-current-buffer b diff --git a/lisp/cedet/semantic/fw.el b/lisp/cedet/semantic/fw.el index 3884cd09cc..3527f3e6af 100644 --- a/lisp/cedet/semantic/fw.el +++ b/lisp/cedet/semantic/fw.el @@ -30,7 +30,7 @@ ;; (require 'mode-local) (require 'eieio) -(load "semantic/loaddefs" nil 'nomessage) +(load "semantic/loaddefs" 'noerror 'nomessage) ;;; Compatibility ;; diff --git a/lisp/emacs-lisp/eieio-core.el b/lisp/emacs-lisp/eieio-core.el index c59f85d6fb..7c149421d4 100644 --- a/lisp/emacs-lisp/eieio-core.el +++ b/lisp/emacs-lisp/eieio-core.el @@ -33,7 +33,7 @@ (require 'cl-lib) (require 'pcase) -(require 'eieio-loaddefs) +(require 'eieio-loaddefs nil t) ;;; ;; A few functions that are better in the official EIEIO src, but diff --git a/src/Makefile.in b/src/Makefile.in index 7890ea9878..0b0d1768b5 100644 --- a/src/Makefile.in +++ b/src/Makefile.in @@ -495,7 +495,7 @@ LIBES = $(LIBS) $(W32_LIBS) $(LIBS_GNUSTEP) $(LIBX_BASE) $(LIBIMAGE) \ $(NOTIFY_LIBS) $(LIB_MATH) $(LIBZ) $(LIBMODULES) $(LIBSYSTEMD_LIBS) $(leimdir)/leim-list.el: bootstrap-emacs$(EXEEXT) - $(MAKE) -C ../leim leim-list.el EMACS="$(bootstrap_exe)" + $(MAKE) -C ../leim all EMACS="$(bootstrap_exe)" ## FORCE it so that admin/unidata can decide whether these files ## are up-to-date. Although since charprop depends on bootstrap-emacs, commit 8201263765d01ab02d45830c03b2b8992c2b5759 Author: Paul Eggert Date: Thu Apr 13 15:37:07 2017 -0700 Fix minor quoting issues in Makefile.in * Makefile.in (install-arch-dep, uninstall): Quote EMACS and EMACS_NAME more consistently. diff --git a/Makefile.in b/Makefile.in index 1b41205057..a31d416bd7 100644 --- a/Makefile.in +++ b/Makefile.in @@ -489,7 +489,7 @@ ifeq (${ns_self_contained},no) -chmod 755 "$(DESTDIR)${bindir}/$(EMACSFULL)" ifndef NO_BIN_LINK rm -f "$(DESTDIR)${bindir}/$(EMACS)" - cd "$(DESTDIR)${bindir}" && $(LN_S_FILEONLY) $(EMACSFULL) $(EMACS) + cd "$(DESTDIR)${bindir}" && $(LN_S_FILEONLY) "$(EMACSFULL)" "$(EMACS)" endif else subdir=${ns_appresdir}/site-lisp && ${write_subdir} @@ -772,10 +772,10 @@ uninstall: uninstall-$(NTDIR) uninstall-doc for page in *.1; do \ rm -f "$(DESTDIR)${man1dir}"/`echo "$${page}" | sed -e 's/\.1$$//' -e '$(TRANSFORM)'`.1$$ext; done; \ fi) - (cd "$(DESTDIR)${bindir}" && rm -f $(EMACSFULL) $(EMACS) || true) + rm -f "$(DESTDIR)${bindir}/$(EMACS)" "$(DESTDIR)${bindir}/$(EMACSFULL)" (if cd "$(DESTDIR)${icondir}"; then \ - rm -f hicolor/*x*/apps/${EMACS_NAME}.png \ - hicolor/scalable/apps/${EMACS_NAME}.svg \ + rm -f hicolor/*x*/apps/"${EMACS_NAME}.png" \ + "hicolor/scalable/apps/${EMACS_NAME}.svg" \ hicolor/scalable/mimetypes/`echo emacs-document | sed '$(TRANSFORM)'`.svg; \ fi) -rm -f "$(DESTDIR)${desktopdir}/${EMACS_NAME}.desktop" commit 900caf992e5686778e22e6f6e839bdd58b75c271 Author: Glenn Morris Date: Thu Apr 13 13:52:09 2017 -0400 * Makefile.in (install-etc): Use existing Makefile variables. diff --git a/Makefile.in b/Makefile.in index 06909c3444..1b41205057 100644 --- a/Makefile.in +++ b/Makefile.in @@ -694,9 +694,8 @@ EMACS_ICON=emacs install-etc: umask 022; ${MKDIR_P} "$(DESTDIR)${desktopdir}" tmp=etc/emacs.tmpdesktop; rm -f $${tmp}; \ - emacs_name=`echo emacs | sed '$(TRANSFORM)'`; \ - sed -e "/^Exec=emacs/ s/emacs/$${emacs_name}/" \ - -e "/^Icon=emacs/ s/emacs/$${emacs_name}/" \ + sed -e "/^Exec=emacs/ s/emacs/${EMACS_NAME}/" \ + -e "/^Icon=emacs/ s/emacs/${EMACS_NAME}/" \ ${srcdir}/etc/emacs.desktop > $${tmp}; \ ${INSTALL_DATA} $${tmp} "$(DESTDIR)${desktopdir}/${EMACS_NAME}.desktop"; \ rm -f $${tmp} @@ -708,12 +707,10 @@ install-etc: rm -f $${tmp} umask 022; $(MKDIR_P) "$(DESTDIR)$(systemdunitdir)" tmp=etc/emacs.tmpservice; rm -f $${tmp}; \ - emacs_name=`echo emacs | sed '$(TRANSFORM)'`; \ - exe_name=$${emacs_name}${EXEEXT}; \ client_name=`echo emacsclient | sed '$(TRANSFORM)'`${EXEEXT}; \ sed -e '/^##/d' \ - -e "/^Documentation/ s/emacs(1)/$${emacs_name}(1)/" \ - -e "/^ExecStart/ s|emacs|${bindir}/$${exe_name}|" \ + -e "/^Documentation/ s/emacs(1)/${EMACS_NAME}(1)/" \ + -e "/^ExecStart/ s|emacs|${bindir}/${EMACS}|" \ -e "/^ExecStop/ s|emacsclient|${bindir}/$${client_name}|" \ ${srcdir}/etc/emacs.service > $${tmp}; \ $(INSTALL_DATA) $${tmp} "$(DESTDIR)$(systemdunitdir)/${EMACS_NAME}.service"; \ commit 030c4f94b630f8ca925ad59e814dc1f4fa69cfe3 Author: Eli Zaretskii Date: Thu Apr 13 20:52:30 2017 +0300 Minor copyedits of recent changes in documentation * doc/lispref/frames.texi (Frame Layout, Frame Position) (Frame Size, Frame Interaction Parameters, Input Focus) (Raising and Lowering, Child Frames): Improve wording and indexing. * doc/emacs/cmdargs.texi (Borders X): Improve indexing. diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index 721a2cebb2..6c39fe7b64 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -1077,6 +1077,7 @@ frame's text area), in pixels. @itemx --border-width=@var{width} @opindex --border-width @cindex main border width, command-line argument +@cindex outer border width, command-line argument Specify @var{width} as the width of the outer border, in pixels. @end table diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 2fac8020ff..b8f4257811 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -505,17 +505,17 @@ two frames adjacent to each other on the screen. Usually, the outer size of a frame is available only after the frame has been mapped (made visible, @pxref{Visibility of Frames}) at least once. For the initial frame or a frame that has not been created yet, the outer size can be -estimated only or must be calculated from the window-system's or window -manager defaults. One workaround is to obtain the differences of the +only estimated or must be calculated from the window-system's or window +manager's defaults. One workaround is to obtain the differences of the outer and native (see below) sizes of a mapped frame and use them for calculating the outer size of the new frame. @cindex outer position -The upper left corner of the outer frame (indicated by @samp{(0)} in the -drawing above) is the @dfn{outer position} of the frame. The outer -position of a graphical frame is also referred to as ``the position'' of -the frame because it usually remains unchanged on its display whenever -the frame is resized or its layout is changed. +The position of the upper left corner of the outer frame (indicated by +@samp{(0)} in the drawing above) is the @dfn{outer position} of the +frame. The outer position of a graphical frame is also referred to as +``the position'' of the frame because it usually remains unchanged on +its display whenever the frame is resized or its layout is changed. The outer position is specified by and can be set via the @code{left} and @code{top} frame parameters (@pxref{Position Parameters}). For a @@ -551,22 +551,24 @@ frames (@pxref{Child Frames}) and @code{undecorated} or @code{override-redirect} frames (@pxref{Management Parameters}). Outer borders are never shown on text terminal frames and on frames -generated by GTK+ routines. On Windows, the outer border is emulated +generated by GTK+ routines. On MS-Windows, the outer border is emulated with the help of a one pixel wide external border. Non-toolkit builds -allow to change the color of the outer border by setting the +on X allow to change the color of the outer border by setting the @code{border-color} frame parameter (@pxref{Layout Parameters}). @item Title Bar @cindex title bar -The @dfn{title bar} is also part of the window manager's decorations and -typically displays the title of the frame (@pxref{Frame Titles}) as well -as buttons for minimizing, maximizing and deleting the frame. It can be -also used for dragging the frame with the mouse. The title bar is -usually not displayed for fullboth (@pxref{Size Parameters}), tooltip -(@pxref{Tooltips}) and child frames (@pxref{Child Frames}) and doesn't -exist for terminal frames. Display of the title bar can be suppressed -by setting the @code{override-redirect} or the @code{undecorated} frame -parameters (@pxref{Management Parameters}). +@cindex caption bar +The @dfn{title bar}, a.k.a.@ @dfn{caption bar}, is also part of the +window manager's decorations and typically displays the title of the +frame (@pxref{Frame Titles}) as well as buttons for minimizing, +maximizing and deleting the frame. It can be also used for dragging +the frame with the mouse. The title bar is usually not displayed for +fullboth (@pxref{Size Parameters}), tooltip (@pxref{Tooltips}) and +child frames (@pxref{Child Frames}) and doesn't exist for terminal +frames. Display of the title bar can be suppressed by setting the +@code{override-redirect} or the @code{undecorated} frame parameters +(@pxref{Management Parameters}). @item Menu Bar @cindex internal menu bar @@ -582,11 +584,12 @@ and Frames}). As a rule, menu bars are never shown on child frames setting the @code{menu-bar-lines} parameter (@pxref{Layout Parameters}) to zero. -It depends on the toolkit whether to wrap or truncate the menu bar -whenever it becomes too long to fit on its frame. Usually, only Motif -and Windows builds can wrap the menu bar. When they (un-)wrap the menu -bar, they try to keep the outer height of the frame unchanged, so the -native height of the frame (see below) will change instead. +Whether the menu bar is wrapped or truncated whenever its width +becomes too large to fit on its frame depends on the toolkit . +Usually, only Motif and MS-Windows builds can wrap the menu bar. When +they (un-)wrap the menu bar, they try to keep the outer height of the +frame unchanged, so the native height of the frame (see below) will +change instead. @item Tool Bar @cindex internal tool bar @@ -602,12 +605,13 @@ setting the @code{tool-bar-lines} parameter (@pxref{Layout Parameters}) to zero. If the variable @code{auto-resize-tool-bars} is non-@code{nil}, Emacs -wraps the internal tool bar when it becomes too long for its frame. If -and when Emacs (un-)wraps the internal tool bar, it by default keeps the -outer height of the frame unchanged, so the native height of the frame -(see below) will change instead. Emacs built with GTK+, on the other -hand, never wraps the tool bar but may automatically increase the outer -width of a frame in order to accommodate an overlong tool bar. +wraps the internal tool bar when its width becomes too large for its +frame. If and when Emacs (un-)wraps the internal tool bar, it by +default keeps the outer height of the frame unchanged, so the native +height of the frame (see below) will change instead. Emacs built with +GTK+, on the other hand, never wraps the tool bar but may +automatically increase the outer width of a frame in order to +accommodate an overlong tool bar. @item Native Frame @cindex native frame @@ -631,14 +635,14 @@ button in the title bar or when dragging its external border with the mouse. @cindex native position -The top left corner of the native frame specifies the @dfn{native -position} of the frame. (1)--(3) in the drawing above indicate that -position for the various builds: +The position of the top left corner of the native frame specifies the +@dfn{native position} of the frame. (1)--(3) in the drawing above +indicate that position for the various builds: @itemize @w{} @item (1) non-toolkit and terminal frames -@item (2) Lucid, Motif and Windows frames +@item (2) Lucid, Motif and MS-Windows frames @item (3) GTK+ and NS frames @end itemize @@ -697,11 +701,11 @@ The @dfn{text area} of a frame is a somewhat fictitious area that can be embedded in the native frame. Its position is unspecified. Its width can be obtained by removing from that of the native width the widths of the internal border, one vertical scroll bar, and one left and one right -fringe as specified for this frame, see @ref{Layout Parameters}. Its -height can be obtained by removing from that of the native height the -widths of the internal border and the heights of the frame's internal -menu and tool bars and one horizontal scroll bar as specified for this -frame. +fringe if they are specified for this frame, see @ref{Layout +Parameters}. Its height can be obtained by removing from that of the +native height the widths of the internal border and the heights of the +frame's internal menu and tool bars and one horizontal scroll bar if +specified for this frame. @end table @cindex absolute position @@ -715,7 +719,7 @@ horizontal and vertical pixel offsets relative to an origin (0, 0) of the frame's display. Correspondingly, the @dfn{absolute edges} of a frame are given as pixel offsets from that origin. - Note that with multiple monitors the origin of the display does not + Note that with multiple monitors, the origin of the display does not necessarily coincide with the top-left corner of the entire usable display area of the terminal. Hence the absolute position of a frame can be negative in such an environment even when that frame is @@ -724,7 +728,7 @@ completely visible. By convention, vertical offsets increase ``downwards''. This means that the height of a frame is obtained by subtracting the offset of its top edge from that of its bottom edge. Horizontal offsets increase -``leftwards'' as expected so a frame's width is calculated by +``rightwards'', as expected, so a frame's width is calculated by subtracting the offset of its left edge from that of its right edge. For a frame on a graphical terminal the following function returns the @@ -734,9 +738,10 @@ sizes of the areas described above: This function returns geometric attributes of @var{frame}. The return value is an association list of the attributes listed below. All coordinate, height and width values are integers counting pixels. Note -that if @var{frame} has not been mapped (@pxref{Visibility of Frames}) -yet, some of the return values may only represent approximations of the -actual values---those that can be seen after the frame has been mapped. +that if @var{frame} has not been mapped yet, (@pxref{Visibility of +Frames}) some of the return values may only represent approximations of +the actual values---those that can be seen after the frame has been +mapped. @table @code @item outer-position @@ -792,10 +797,10 @@ native and inner frame. @defun frame-edges &optional frame type This function returns the absolute edges of the outer, native or inner frame of @var{frame}. @var{frame} must be a live frame and defaults to -the selected one. The list returned has the form (@var{left} @var{top} -@var{right} @var{bottom}) where all values are in pixels relative to the -origin of @var{frame}'s display. For terminal frames the values -returned for @var{left} and @var{top} are always zero. +the selected one. The returned list has the form @w{@code{(@var{left} +@var{top} @var{right} @var{bottom})}} where all values are in pixels +relative to the origin of @var{frame}'s display. For terminal frames +the values returned for @var{left} and @var{top} are always zero. Optional argument @var{type} specifies the type of the edges to return: @code{outer-edges} means to return the outer edges of @var{frame}, @@ -803,14 +808,15 @@ Optional argument @var{type} specifies the type of the edges to return: @code{inner-edges} means to return its inner edges. By convention, the pixels of the display at the values returned for -@var{left} and @var{top} are inside (part of) @var{frame}. Hence, if -@var{left} and @var{top} are both zero, the pixel at the display's -origin is part of @var{frame}. The pixels at @var{bottom} and -@var{right}, on the other hand, lie immediately outside @var{frame}. -This means that if you have, for example, two side-by-side frames -positioned such that the right outer edge of the frame on the left -equals the left outer edge of the frame on the right, the pixels at that -edge show a part of the frame on the right. +@var{left} and @var{top} are considered to be inside (part of) +@var{frame}. Hence, if @var{left} and @var{top} are both zero, the +pixel at the display's origin is part of @var{frame}. The pixels at +@var{bottom} and @var{right}, on the other hand, are considered to lie +immediately outside @var{frame}. This means that if you have, for +example, two side-by-side frames positioned such that the right outer +edge of the frame on the left equals the left outer edge of the frame on +the right, the pixels at that edge show a part of the frame on the +right. @end defun @@ -878,21 +884,21 @@ Geometry}). The position of a child frame (@pxref{Child Frames}) is specified via pixel offsets of its outer edges relative to the native position of its parent frame. - You can read or change the position of a frame using the frame + You can access or change the position of a frame using the frame parameters @code{left} and @code{top} (@pxref{Position Parameters}). Here are two additional functions for working with the positions of an existing, visible frame. For both functions, the argument @var{frame} must denote a live frame and defaults to the selected frame. @defun frame-position &optional frame -For a normal, non-child frame this function returns a cons of the (X, Y) -pixel coordinates of its outer position (@pxref{Frame Layout}) with -respect to the origin (0, 0) of its display. For a child frame +For a normal, non-child frame this function returns a cons of the pixel +coordinates of its outer position (@pxref{Frame Layout}) with respect to +the origin @code{(0, 0)} of its display. For a child frame (@pxref{Child Frames}) this function returns the pixel coordinates of -its outer position with respect to an origin (0, 0) at the native +its outer position with respect to an origin @code{(0, 0)} at the native position of @var{frame}'s parent. -Negative return values never indicate an offset from the right or bottom +Negative values never indicate an offset from the right or bottom edge of @var{frame}'s display or parent frame. Rather, they mean that @var{frame}'s outer position is on the left and/or above the origin of its display or the native position of its parent frame. This usually @@ -907,7 +913,7 @@ On a text terminal frame both values are zero. @defun set-frame-position frame x y This function sets the outer frame position of @var{frame} to (@var{x}, @var{y}). The latter arguments specify pixels and normally count from -an origin at the position (0, 0) of @var{frame}'s display. For child +the origin at the position (0, 0) of @var{frame}'s display. For child frames, they count from the native position of @var{frame}'s parent frame. @@ -921,14 +927,15 @@ edge of @var{frame} exactly at the right or bottom edge of its display or parent frame. Neither do they allow to specify a position that does not lie within the edges of the display or parent frame. The frame parameters @code{left} and @code{top} (@pxref{Position Parameters}) -allow to do that but may still fail to provide good results for the +allow to do that, but may still fail to provide good results for the initial or a new frame. This function has no effect on text terminal frames. @end defun @defvar move-frame-functions -This hook specifies the functions run when an Emacs frame is moved +@cindex frame position changes, a hook +This hook specifies the functions that are run when an Emacs frame is moved (assigned a new position) by the window-system or window manager. The functions are run with one argument, the frame that moved. For a child frame (@pxref{Child Frames}), the functions are run only when the @@ -954,8 +961,8 @@ This means that in general you cannot use the native size to specify the initial size of a frame. As soon as you know the native size of a visible frame, you can calculate its outer size (@pxref{Frame Layout}) by adding in the remaining components from the return value of -@code{frame-geometry} . For invisible frames or for frames that have -yet to be created, however, the outer size can be estimated only. This +@code{frame-geometry}. For invisible frames or for frames that have +yet to be created, however, the outer size can only be estimated. This also means that calculating an exact initial position of a frame specified via offsets from the right or bottom edge of the screen (@pxref{Frame Position}) is impossible. @@ -1006,8 +1013,8 @@ leaving some empty space below and/or on the right of the frame. The following option may help in that case. @defopt frame-resize-pixelwise -If this option is @code{nil}, a frame's text pixel size is usually -rounded to a multiple of the current values of that frame's +If this option is @code{nil} (the default), a frame's text pixel size is +usually rounded to a multiple of the current values of that frame's @code{frame-char-height} and @code{frame-char-width} whenever the frame is resized. If this is non-@code{nil}, no rounding occurs, hence frame sizes can increase/decrease by one pixel. @@ -1747,6 +1754,8 @@ If non-@code{nil}, this frame's window is never split automatically. @node Frame Interaction Parameters @subsubsection Frame Interaction Parameters +@cindex frame interaction parameters +@cindex interaction parameters between frames These parameters supply forms of interactions between different frames. @@ -1754,7 +1763,7 @@ These parameters supply forms of interactions between different frames. @vindex parent-frame, a frame parameter @item parent-frame If non-@code{nil}, this means that this frame is a child frame -(@pxref{Child Frames}) and this parameter specifies its parent frame. +(@pxref{Child Frames}), and this parameter specifies its parent frame. If nil, this means that this frame is a normal, top-level frame. @vindex delete-before, a frame parameter @@ -1852,13 +1861,13 @@ display bugs or pine for that retro, flicker-y feeling. If non-@code{nil}, this tells the window manager to remove the frame's icon from the taskbar associated with the frame's display and inhibit switching to the frame's window via the combination @kbd{Alt-@key{TAB}}. -On Windows, iconifying such a frame will "roll in" its window-system +On MS-Windows, iconifying such a frame will "roll in" its window-system window at the bottom of the desktop. Some window managers may not honor this parameter. @vindex no-focus-on-map, a frame parameter @item no-focus-on-map -If non-@code{nil}, this means that the frame dos not want to receive +If non-@code{nil}, this means that the frame does not want to receive input focus when it is mapped (@pxref{Visibility of Frames}). Some window managers may not honor this parameter. @@ -1875,8 +1884,8 @@ this parameter. @vindex undecorated, a frame parameter @item undecorated If non-@code{nil}, this frame's window-system window is drawn without -decorations like title, minimize/maximize boxes and external borders. -This usually means that the window cannot be dragged, resized, +decorations, like the title, minimize/maximize boxes and external +borders. This usually means that the window cannot be dragged, resized, iconified, maximized or deleted with the mouse. If nil, the frame's window is usually drawn with all the elements listed above unless their display has been suspended via window manager settings. @@ -2266,8 +2275,8 @@ frame. It first deletes any child frame of @var{frame} (@pxref{Child Frames}) and any frame whose @code{delete-before} frame parameter (@pxref{Frame Interaction Parameters}) specifies @var{frame}. All such deletions are -performed recursively; so this step makes sure that there will not exist -any other frames with @var{frame} as their ancestor. Then, unless +performed recursively; so this step makes sure that there 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. @@ -2468,7 +2477,7 @@ non-@code{nil}, means to avoid making @var{frame}'s window-system window the ``active'' window which should insist a bit more on avoiding to raise @var{frame} above other frames. -On Windows the @var{noactivate} argument has no effect. However, if +On MS-Windows the @var{noactivate} argument has no effect. However, if @var{frame} is a child frame (@pxref{Child Frames}), this function usualy does focus @var{frame} without raising it above other child frames. @@ -2593,7 +2602,7 @@ Note that this option does not distinguish ``sloppy'' focus (where the frame that previously had focus retains focus as long as the mouse pointer does not move into another window manager window) from ``strict'' focus (where a frame immediately loses focus when it's left -by the mouse pointer). It neither recognizes whether your window +by the mouse pointer). Neither does it recognize whether your window manager supports delayed focusing or auto-raising where you can explicitly specify the time until a new frame gets focus or is auto-raised. @@ -2656,7 +2665,7 @@ you can do that with @code{raise-frame} if you wish (@pxref{Raising and Lowering}). Making a frame visible usually makes all its child frames (and their -descendants) visible too (@pxref{Child Frames}). +descendants) visible as well (@pxref{Child Frames}). @end deffn @deffn Command make-frame-invisible &optional frame force @@ -2691,6 +2700,7 @@ selected frame. @cindex restacking a frame @cindex frame stacking order @cindex frame Z-order +@cindex Z-order Most window systems use a desktop metaphor. Part of this metaphor is the idea that system-level windows (representing, e.g., Emacs frames) are stacked in a notional third dimension perpendicular to the screen @@ -2865,8 +2875,8 @@ frame does not show a menu or tool bar, any other of the frame's borders (@pxref{Layout Parameters}) can be used instead of the external borders. In particular, under X (but not when building with GTK+), the frame's -outer border can be used. On Windows, specifying a non-zero outer -border width will show a one pixel wide external border. Under all +outer border can be used. On MS-Windows, specifying a non-zero outer +border width will show a one-pixel wide external border. Under all window-systems, the internal border can be used. In either case, it's advisable to disable a child frame's window manager decorations with the @code{undecorated} frame parameter @pxref{Management Parameters}). @@ -2902,9 +2912,9 @@ policy to child frames. Customizing @code{mouse-autoselect-window} can help in this regard (@pxref{Mouse Window Auto-selection}). @item -Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed too +Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed to work on all window-systems. Some will drop the object on the parent -frame or some ancestor instead. +frame or on some ancestor instead. @end itemize The following two functions may be useful when working with child and diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 931d1060d5..fed2dea757 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -1752,9 +1752,9 @@ whenever a window gets selected more ``permanently''. not related to window management, it will usually make sense to save the value of the selected window somewhere and compare it with the value of @code{selected-window} while running that hook. Also, to avoid false -positives when using @code{buffer-list-update-hook} it is good practice +positives when using @code{buffer-list-update-hook}, it is good practice that every @code{select-window} call supposed to select a window only -temporarily, passes a non-@code{nil} @var{norecord} argument. If +temporarily passes a non-@code{nil} @var{norecord} argument. If possible, the macro @code{with-selected-window} (see below) should be used in such cases. @@ -4623,7 +4623,7 @@ Any other non-@code{nil} value means to select a window instantaneously as soon as the mouse pointer enters it. @end table -In either case the mouse pointer must enter the text area of a window in +In either case, the mouse pointer must enter the text area of a window in order to trigger its selection. Dragging the scroll bar slider or the mode line of a window conceptually should not cause its auto-selection. commit dbae41896c325de5cae3d98afedb27f42e306ed5 Author: Glenn Morris Date: Thu Apr 13 13:44:35 2017 -0400 Small src/Makefile simplification * src/Makefile.in ($(lispsource)/international/ucs-normalize.elc) ($(lispsource)/term/ns-win.elc): Combine rules. diff --git a/src/Makefile.in b/src/Makefile.in index bed53f8f4b..7890ea9878 100644 --- a/src/Makefile.in +++ b/src/Makefile.in @@ -507,12 +507,8 @@ $(srcdir)/macuvs.h $(lispsource)/international/charprop.el: \ ## We require charprop.el to exist before ucs-normalize.el is ## byte-compiled, because ucs-normalize.el needs to load 2 uni-*.el files. -$(lispsource)/international/ucs-normalize.elc: | \ - $(lispsource)/international/charprop.el - -## ns-win.el loads ucs-normalize, so it also needs the above-mentioned -## 2 uni-*.el files to exist. -$(lispsource)/term/ns-win.elc: | \ +## And ns-win requires ucs-normalize. +$(lispsource)/international/ucs-normalize.elc $(lispsource)/term/ns-win.elc: | \ $(lispsource)/international/charprop.el lispintdir = ${lispsource}/international commit a61fa4af2802a47defe61543eb97276d74ba60bd Author: Martin Rudalics Date: Thu Apr 13 18:59:37 2017 +0200 ; Update NEWS for frame and window changes diff --git a/etc/NEWS b/etc/NEWS index 799a2b31e5..76c9dbc331 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -789,8 +789,8 @@ processes on exit. +++ *** A new submode of 'html-mode', 'mhtml-mode', is now the default - mode for *.html files. This mode handles indentation, - fontification, and commenting for embedded JavaScript and CSS. +mode for *.html files. This mode handles indentation, +fontification, and commenting for embedded JavaScript and CSS. * Incompatible Lisp Changes in Emacs 26.1 @@ -806,10 +806,6 @@ table implementation. This uses a new bytecode op 'switch', which isn't compatible with previous Emacs versions. This functionality can be disabled by setting 'byte-compile-cond-use-jump-table' to nil. -+++ -** Resizing a frame no longer runs 'window-configuration-change-hook'. -Put your function on 'window-size-change-functions' instead. - ** 'C-up', 'C-down', 'C-left' and 'C-right' are now defined in term mode to send the same escape sequences that xterm does. This makes things like forward-word in readline work. @@ -921,21 +917,6 @@ If no insurmountable problems before next release, it can stay that way. ** 'gnutls-boot' now takes a parameter ':complete-negotiation' that says that negotiation should complete even on non-blocking sockets. -+++ -** New functions 'window-pixel-width-before-size-change' and -'window-pixel-height-before-size-change' support detecting which -window changed size when 'window-size-change-functions' are run. - -+++ -** New function 'display-buffer-reuse-mode-window' is an action function -suitable for use in 'display-buffer-alist'. For example, to avoid creating -a new window when opening man pages when there's already one, use -(add-to-list 'display-buffer-alist - '("\\`\\*Man .*\\*\\'" . - (display-buffer-reuse-mode-window - (inhibit-same-window . nil) - (mode . Man-mode)))) - --- ** There is now a new variable 'flyspell-sort-corrections-function' that allows changing the way corrections are sorted. @@ -1075,9 +1056,101 @@ that does not exist. operating recursively and when some other process deletes the directory or its files before 'delete-directory' gets to them. ++++ +*** New error type 'user-search-failed' like 'search-failed' but +avoids debugger like 'user-error'. + ** Changes in Frame- and Window- Handling +++ +*** Resizing a frame no longer runs 'window-configuration-change-hook'. +'window-size-change-functions' should be used instead. + ++++ +*** The new function 'frame-size-changed-p' can tell whether a frame has +been resized since the last time 'window-size-change-functions' has been +run. + ++++ +*** The function 'frame-geometry' now also returns the width of a +frame's outer border. + ++++ +*** New frame parameters + ++++ +**** 'z-group' positions a frame above or below all others. + ++++ +**** 'min-width' and 'min-height' specify the absolute minimum size of a +frame. + ++++ +**** 'parent-frame' makes a frame the child frame of another Emacs +frame. The section "Child Frames" in the Elisp manual describes the +intrinsics of that relationship. + ++++ +**** 'delete-before' triggers deletion of one frame before that of +another. + ++++ +**** 'mouse-wheel-frame' specifies another frame whose windows shall be +scrolled instead. + ++++ +**** 'no-other-frame' has 'next-frame' and 'previous-frame' skip this +frame. + ++++ +**** 'skip-taskbar' removes a frame's icon from the taskbar and has +Alt- skip this frame. + ++++ +**** 'no-focus-on-map' avoids that a frame gets input focus when mapped. + ++++ +**** 'no-accept-focus' means that a frame does not want to get input +focus via the mouse. + ++++ +**** 'undecorated' removes the window manager decorations from a frame. + ++++ +**** 'override-redirect' tells the window manager to disregard this +frame. + ++++ +*** The 'width' and 'height' frame parameters allow to specify pixel +values now. + ++++ +*** The new function 'frame-list-z-order' returns a list of all frames +in Z (stacking) order. + ++++ +*** The function 'x-focus-frame' optionally tries to not activate its +frame. + ++++ +*** The variable 'focus-follows-mouse' has a third meaningful value +'auto-raise' to indicate that the window manager automatically raises a +frame when the mouse pointer enters it. + ++++ +*** The new function 'frame-restack' puts a frame above or below +another on the display. + ++++ +*** The new face 'internal-border' specifies the background of a frame's +internal border. + ++++ +*** The NORECORD argument of 'select-window' now has a meaningful value +'mark-for-redisplay' which is like any other non-nil value but marks +WINDOW for redisplay. + ++++ *** Support for side windows is now official. The display action function 'display-buffer-in-side-window' will display its buffer in a side window. Functions for toggling all side windows on a frame, @@ -1096,6 +1169,16 @@ section "Atomic Windows" in the Elisp manual. assign window parameters to the window used for displaying the buffer. +++ +*** New function 'display-buffer-reuse-mode-window' is an action function +suitable for use in 'display-buffer-alist'. For example, to avoid creating +a new window when opening man pages when there's already one, use +(add-to-list 'display-buffer-alist + '("\\`\\*Man .*\\*\\'" . + (display-buffer-reuse-mode-window + (inhibit-same-window . nil) + (mode . Man-mode)))) + ++++ *** New window parameter 'no-delete-other-window' prevents that its window gets deleted by 'delete-other-windows'. @@ -1104,9 +1187,14 @@ its window gets deleted by 'delete-other-windows'. windows. +++ -*** New error type 'user-search-failed' like 'search-failed' but -avoids debugger like 'user-error'. +*** New functions 'window-pixel-width-before-size-change' and +'window-pixel-height-before-size-change' support detecting which +window changed size when 'window-size-change-functions' are run. ++++ +*** The semantics of 'mouse-autoselect-window' has changed slightly. +For details see the section "Mouse Window Auto-selection" in the Elisp +manual. * Changes in Emacs 26.1 on Non-Free Operating Systems commit 02220c174eee5a98de756b899a93381021c1c858 Author: Simen Heggestøyl Date: Thu Apr 13 18:54:19 2017 +0200 Add grid layout module to CSS property list * lisp/textmodes/css-mode.el (css-property-alist) (css-value-class-alist): Add new properties and value classes from CSS Grid Layout Module. diff --git a/lisp/textmodes/css-mode.el b/lisp/textmodes/css-mode.el index b1feca7ca6..2088ea0a1e 100644 --- a/lisp/textmodes/css-mode.el +++ b/lisp/textmodes/css-mode.el @@ -123,7 +123,10 @@ "table-column" "table-cell" "table-caption" "none" ;; CSS Flexible Box Layout Module Level 1 ;; (https://www.w3.org/TR/css3-flexbox/#valdef-display-flex) - "flex" "inline-flex") + "flex" "inline-flex" + ;; CSS Grid Layout Module Level 1 + ;; (https://www.w3.org/TR/css-grid-1/#grid-containers) + "grid" "inline-grid" "subgrid") ("elevation" angle "below" "level" "above" "higher" "lower") ("empty-cells" "show" "hide") ("float" "left" "right" "none") @@ -272,6 +275,29 @@ ("color" color) ("opacity" alphavalue) + ;; CSS Grid Layout Module Level 1 + ;; (https://www.w3.org/TR/css-grid-1/#property-index) + ("grid" grid-template grid-template-rows "auto-flow" "dense" + grid-auto-columns grid-auto-rows grid-template-columns) + ("grid-area" grid-line) + ("grid-auto-columns" track-size) + ("grid-auto-flow" "row" "column" "dense") + ("grid-auto-rows" track-size) + ("grid-column" grid-line) + ("grid-column-end" grid-line) + ("grid-column-gap" length-percentage) + ("grid-column-start" grid-line) + ("grid-gap" grid-row-gap grid-column-gap) + ("grid-row" grid-line) + ("grid-row-end" grid-line) + ("grid-row-gap" length-percentage) + ("grid-row-start" grid-line) + ("grid-template" "none" grid-template-rows grid-template-columns + line-names string track-size line-names explicit-track-list) + ("grid-template-areas" "none" string) + ("grid-template-columns" "none" track-list auto-track-list) + ("grid-template-rows" "none" track-list auto-track-list) + ;; CSS Flexible Box Layout Module Level 1 ;; (http://www.w3.org/TR/css-flexbox-1/#property-index) ("align-content" "flex-start" "flex-end" "center" "space-between" @@ -469,6 +495,8 @@ further value candidates, since that list would be infinite.") (angle "calc()") (animateable-feature "scroll-position" "contents" custom-ident) (attachment "scroll" "fixed" "local") + (auto-repeat "repeat()") + (auto-track-list line-names fixed-size fixed-repeat auto-repeat) (bg-image image "none") (bg-layer bg-image position repeat-style attachment box) (bg-size length percentage "auto" "cover" "contain") @@ -484,6 +512,7 @@ further value candidates, since that list would be infinite.") (east-asian-variant-values "jis78" "jis83" "jis90" "jis04" "simplified" "traditional") (east-asian-width-values "full-width" "proportional-width") + (explicit-track-list line-names track-size) (family-name "Courier" "Helvetica" "Times") (feature-tag-value string integer "on" "off") (filter-function @@ -493,6 +522,9 @@ further value candidates, since that list would be infinite.") (filter-function-list filter-function uri) (final-bg-layer bg-image position repeat-style attachment box color) + (fixed-breadth length-percentage) + (fixed-repeat "repeat()") + (fixed-size fixed-breadth "minmax()") (font-variant-css21 "normal" "small-caps") (frequency "calc()") (generic-family @@ -501,13 +533,17 @@ further value candidates, since that list would be infinite.") (gradient linear-gradient radial-gradient repeating-linear-gradient repeating-radial-gradient) + (grid-line "auto" custom-ident integer "span") (historical-lig-values "historical-ligatures" "no-historical-ligatures") (image uri image-list element-reference gradient) (image-list "image()") + (inflexible-breadth length-percentage "min-content" "max-content" + "auto") (integer "calc()") (length "calc()" number) (line-height "normal" number length percentage) + (line-names custom-ident) (line-style "none" "hidden" "dotted" "dashed" "solid" "double" "groove" "ridge" "inset" "outset") @@ -576,6 +612,11 @@ further value candidates, since that list would be infinite.") (specific-voice identifier) (target-name string) (time "calc()") + (track-breadth length-percentage flex "min-content" "max-content" + "auto") + (track-list line-names track-size track-repeat) + (track-repeat "repeat()") + (track-size track-breadth "minmax()" "fit-content()") (transform-list "matrix()" "translate()" "translateX()" "translateY()" "scale()" "scaleX()" "scaleY()" "rotate()" "skew()" "skewX()" "skewY()" @@ -594,8 +635,8 @@ other entries in this list, not to properties. The following classes have been left out above because they cannot be completed sensibly: `custom-ident', -`element-reference', `id', `identifier', `percentage', and -`string'.") +`element-reference', `flex', `id', `identifier', +`length-percentage', `percentage', and `string'.") (defcustom css-electric-keys '(?\} ?\;) ;; '() "Self inserting keys which should trigger re-indentation." commit 7cc613dc68b8c388a7ccd8f79e37a641ad05312c Author: Martin Rudalics Date: Thu Apr 13 17:45:12 2017 +0200 Describe recent frame and window changes in manuals * doc/emacs/emacs.texi (Top): * doc/emacs/cmdargs.texi (Borders X): Clearly separate the terms "outer border" (for the X border which can be set from within Emacs) and "external border" (for the border which is added by the window manager). * doc/lispref/display.texi (Tooltips): Clarify slightly. * doc/lispref/elisp.texi (Top): Update node and section names. * doc/lispref/frames.texi (Frames): Describe difference between top-level and child frames. (Frame Layout): Describe outer border. Add more details about how Emacs obtains the outer size and position of a frame and about menu bar/tool bar wrapping. Add references to new frame parameters. (Size and Position): Remove subsection. (Frame Position): New subsection excerpted from the earlier Size and Position subsection. Clarify positioning concepts and some of their shortcomings. Describe `move-frame-functions'. (Frame Size): New subsection excerpted from the earlier Size and Position subsection. Describe how to track frame size changes and the new function `frame-size-changed-p'. (Position Parameters): Describe child frame positioning. Warn about negative offsets. Describe 'z-group' parameter. (Size Parameters): Describe 'text-pixels' specification facility and new 'min-width' and 'min-height' parameters. (Layout Parameters): Clarify description of 'tool-bar-lines' and 'menu-bar-lines' parameters. (Frame Interaction Parameters): New subsubsection describing 'parent-frame', 'delete-before', 'mouse-wheel-frame' and 'no-other-frame' parameters. (Management Parameters): Describe 'skip-taskbar', 'no-focus-on-map', 'no-accept-focus', 'undecorated' and 'override-redirect' parameters. (Deleting Frames): Describe handling of 'delete-before' parameter and child frames for `delete-frame' and `delete-other-frames'. (Finding All Frames): Describe `frame-list-z-order' and handling of 'no-other-frame' parameter by `next-frame'. (Minibuffers and Frames): Minor clarifications. (Input Focus): Document `x-focus-frame'. Clarify descriptions of `focus-in-hook', `focus-out-hook' and `focus-follows-mouse'. (Visibility of Frames): Describe mapping and how the visibility of a parent frame affects that of its child frames. (Raising and Lowering): Describe restacking of frames and z-groups. (Child Frames): New section. * doc/lispref/windows.texi (Selecting Windows): Describe additional semantics of NORECORD argument of `select-window' and how `buffer-list-update-hook' can emulate a "select window hook". (Mouse Window Auto-selection): New section. diff --git a/doc/emacs/cmdargs.texi b/doc/emacs/cmdargs.texi index 6c86670824..721a2cebb2 100644 --- a/doc/emacs/cmdargs.texi +++ b/doc/emacs/cmdargs.texi @@ -71,7 +71,7 @@ arguments.) * Font X:: Choosing a font for text, under X. * Colors X:: Choosing display colors. * Window Size X:: Start-up window size, under X. -* Borders X:: Internal and external borders, under X. +* Borders X:: Internal and outer borders, under X. * Title X:: Specifying the initial frame's title. * Icons X:: Choosing what sort of icon to use, under X. * Misc X:: Other display options. @@ -1053,15 +1053,15 @@ program-specified and user-specified positions. If these are set, Emacs fails to position the window correctly. @node Borders X -@appendixsec Internal and External Borders +@appendixsec Internal and Outer Borders @cindex borders (X Window System) - An Emacs frame has an internal border and an external border. The + An Emacs frame has an internal border and an outer border. The internal border is an extra strip of the background color around the -text portion of the frame. Emacs itself draws the internal border. -The external border is added by the window manager outside the frame; -depending on the window manager you use, it may contain various boxes -you can click on to move or iconify the window. +text portion of the frame. Emacs itself draws the internal border. The +outer border is drawn by X outside the tool and menu bars of the frame. +There is also an external border which is drawn by the window manager. +The size of the external border cannot be set from within Emacs. @table @samp @item -ib @var{width} @@ -1069,15 +1069,15 @@ you can click on to move or iconify the window. @itemx --internal-border=@var{width} @opindex --internal-border @cindex internal border width, command-line argument -Specify @var{width} as the width of the internal border (between the text -and the main border), in pixels. +Specify @var{width} as the width of the internal border (around the +frame's text area), in pixels. @item -bw @var{width} @opindex -bw @itemx --border-width=@var{width} @opindex --border-width @cindex main border width, command-line argument -Specify @var{width} as the width of the main border, in pixels. +Specify @var{width} as the width of the outer border, in pixels. @end table When you specify the size of the frame, that does not count the @@ -1086,9 +1086,9 @@ external border. Use the @samp{-ib @var{n}} option to specify an internal border @var{n} pixels wide. The default is 1. Use @samp{-bw @var{n}} to -specify the width of the external border (though the window manager may -not pay attention to what you specify). The default width of the -external border is 2. +specify the width of the outer border (though the window manager may not +pay attention to what you specify). The default width of the outer +border is 2. @node Title X @appendixsec Frame Titles diff --git a/doc/emacs/emacs.texi b/doc/emacs/emacs.texi index a6f2896231..599b373fd4 100644 --- a/doc/emacs/emacs.texi +++ b/doc/emacs/emacs.texi @@ -1198,7 +1198,7 @@ Command Line Arguments for Emacs Invocation * Font X:: Choosing a font for text, under X. * Colors X:: Choosing display colors. * Window Size X:: Start-up window size, under X. -* Borders X:: Internal and external borders, under X. +* Borders X:: Internal and outer borders, under X. * Title X:: Specifying the initial frame's title. * Icons X:: Choosing what sort of icon to use, under X. * Misc X:: Other display options. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 57dd16deca..7a6a21649e 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -7190,20 +7190,22 @@ changing the value of the variable @code{x-gtk-use-system-tooltips} to @code{nil}. The rest of this subsection describes how to control non-GTK+ tooltips, which are presented by Emacs itself. -Since tooltips are special frames, they have their frame parameters -(@pxref{Frame Parameters}). Unlike other frames, the frame parameters -for tooltips are stored in a special variable. +@cindex tooltip frames +Tooltips are displayed in special frames called tooltip frames, which +have their own frame parameters (@pxref{Frame Parameters}). Unlike +other frames, the default parameters for tooltip frames are stored in a +special variable. @defvar tooltip-frame-parameters -This customizable option holds the frame parameters used for -displaying tooltips. Any font and color parameters are ignored, and -the corresponding attributes of the @code{tooltip} face are used -instead. If @code{left} or @code{top} parameters are included, they -are used as absolute frame-relative coordinates where the tooltip -should be shown. (Mouse-relative position of the tooltip can be -customized using the variables described in @ref{Tooltips,,, emacs, -The GNU Emacs Manual}.) Note that the @code{left} and @code{top} -parameters, if present, override the values of mouse-relative offsets. +This customizable option holds the default frame parameters used for +displaying tooltips. Any font and color parameters are ignored, and the +corresponding attributes of the @code{tooltip} face are used instead. +If @code{left} or @code{top} parameters are included, they are used as +absolute frame-relative coordinates where the tooltip should be shown. +(Mouse-relative position of the tooltip can be customized using the +variables described in @ref{Tooltips,,, emacs, The GNU Emacs Manual}.) +Note that the @code{left} and @code{top} parameters, if present, +override the values of mouse-relative offsets. @end defvar @vindex tooltip@r{ face} diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index bff3112d73..7cc91a8f7e 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1062,6 +1062,7 @@ Windows * Vertical Scrolling:: Moving the contents up and down on the window. * Horizontal Scrolling:: Moving the contents sideways on the window. * Coordinates and Windows:: Converting coordinates to windows. +* Mouse Window Auto-selection:: Automatically selecting windows with the mouse. * Window Configurations:: Saving and restoring the state of the screen. * Window Parameters:: Associating additional information with windows. * Window Hooks:: Hooks for scrolling, window size changes, @@ -1089,16 +1090,16 @@ Frames * Minibuffers and Frames:: How a frame finds the minibuffer to use. * 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 it. +* Raising and Lowering:: Raising, Lowering and Restacking Frames. * Frame Configurations:: Saving the state of all frames. +* Child Frames:: Making a frame the child of another. * Mouse Tracking:: Getting events that say when the mouse moves. * Mouse Position:: Asking where the mouse is, or moving it. * Pop-Up Menus:: Displaying a menu for the user to select from. * Dialog Boxes:: Displaying a box to ask yes or no. * Pointer Shape:: Specifying the shape of the mouse pointer. * Window System Selections::Transferring text to and from other X clients. -* Drag and Drop:: Internals of Drag-and-Drop implementation. +* Drag and Drop:: Internals of Drag-and-Drop implementation. * Color Names:: Getting the definitions of color names. * Text Terminal Colors:: Defining colors for text terminals. * Resources:: Getting resource values from the server. @@ -1108,7 +1109,8 @@ Frame Geometry * Frame Layout:: Basic layout of frames. * Frame Font:: The default font of a frame and how to set it. -* Size and Position:: Changing the size and position of a frame. +* Frame Position:: The position of a frame on its display. +* Frame Size:: Specifying and retrieving a frame's size. * Implied Frame Resizing:: Implied resizing of frames and how to prevent it. Frame Parameters @@ -1126,6 +1128,8 @@ Window Frame Parameters * Layout Parameters:: Size of parts of the frame, and enabling or disabling some parts. * Buffer Parameters:: Which buffers have been or should be shown. +* Frame Interaction Parameters:: Parameters for interacting with other + frames. * Management Parameters:: Communicating with the window manager. * Cursor Parameters:: Controlling the cursor appearance. * Font and Color Parameters:: Fonts and colors for the frame text. diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 68aa40fe4d..2fac8020ff 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -77,6 +77,13 @@ displayed on that terminal; the list of possible values is the same as for @code{framep} above. @end defun +@cindex top-level frame +On a graphical terminal we distinguish two types of frames: A normal +@dfn{top-level frame} is a frame whose window-system window is a child +of the window-system's root window for that terminal. A child frame is +a frame whose window-system window is the child of the window-system +window of another Emacs frame. @xref{Child Frames}. + @menu * Creating Frames:: Creating additional frames. * Multiple Terminals:: Displaying on several different devices. @@ -89,9 +96,9 @@ for @code{framep} above. * Minibuffers and Frames:: How a frame finds the minibuffer to use. * 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 it. +* Raising and Lowering:: Raising, Lowering and Restacking Frames. * Frame Configurations:: Saving the state of all frames. +* Child Frames:: Making a frame the child of another. * Mouse Tracking:: Getting events that say when the mouse moves. * Mouse Position:: Asking where the mouse is, or moving it. * Pop-Up Menus:: Displaying a menu for the user to select from. @@ -436,7 +443,8 @@ has to specify a live frame (@pxref{Deleting Frames}). If omitted or @menu * Frame Layout:: Basic layout of frames. * Frame Font:: The default font of a frame and how to set it. -* Size and Position:: Changing the size and position of a frame. +* Frame Position:: The position of a frame on its display. +* Frame Size:: Specifying and retrieving a frame's size. * Implied Frame Resizing:: Implied resizing of frames and how to prevent it. @end menu @@ -446,14 +454,16 @@ has to specify a live frame (@pxref{Deleting Frames}). If omitted or @cindex frame layout @cindex layout of frame -The drawing below sketches the layout of a frame on a graphical -terminal: +A visible frame occupies a rectangular area on its terminal's display. +This area may contain a number of nested rectangles, each serving a +different purpose. The drawing below sketches the layout of a frame on +a graphical terminal: @smallexample @group <------------ Outer Frame Width -----------> - ___________________________________________ - ^(0) ___________ External Border __________ | + ____________________________________________ + ^(0) ________ External/Outer Border _______ | | | |_____________ Title Bar ______________| | | | (1)_____________ Menu Bar ______________| | ^ | | (2)_____________ Tool Bar ______________| | ^ @@ -468,14 +478,14 @@ Height | | | Height | | | Height | | | | | | | | | | | | |___v______________________________| | | | | | |___________ Internal Border __________| | v - v |______________ External Border _____________| + v |___________ External/Outer Border __________| <-------- Native Frame Width --------> @end group @end smallexample In practice not all of the areas shown in the drawing will or may be -present. The meaning of these areas is: +present. The meaning of these areas is described below. @table @samp @item Outer Frame @@ -483,50 +493,100 @@ present. The meaning of these areas is: @cindex outer edges @cindex outer width @cindex outer height +@cindex outer size The @dfn{outer frame} is a rectangle comprising all areas shown in the drawing. The edges of that rectangle are called the @dfn{outer edges} -of the frame. The @dfn{outer width} and @dfn{outer height} of the frame -specify the size of that rectangle. +of the frame. Together, the @dfn{outer width} and @dfn{outer height} of +the frame specify the @dfn{outer size} of that rectangle. + +Knowing the outer size of a frame is useful for fitting a frame into the +working area of its display (@pxref{Multiple Terminals}) or for placing +two frames adjacent to each other on the screen. Usually, the outer +size of a frame is available only after the frame has been mapped (made +visible, @pxref{Visibility of Frames}) at least once. For the initial +frame or a frame that has not been created yet, the outer size can be +estimated only or must be calculated from the window-system's or window +manager defaults. One workaround is to obtain the differences of the +outer and native (see below) sizes of a mapped frame and use them for +calculating the outer size of the new frame. @cindex outer position The upper left corner of the outer frame (indicated by @samp{(0)} in the -drawing above) is the @dfn{outer position} or the frame. It is -specified by and settable via the @code{left} and @code{top} frame -parameters (@pxref{Position Parameters}) as well as the functions -@code{frame-position} and @code{set-frame-position} (@pxref{Size and -Position}). +drawing above) is the @dfn{outer position} of the frame. The outer +position of a graphical frame is also referred to as ``the position'' of +the frame because it usually remains unchanged on its display whenever +the frame is resized or its layout is changed. + +The outer position is specified by and can be set via the @code{left} +and @code{top} frame parameters (@pxref{Position Parameters}). For a +normal, top-level frame these parameters usually represent its absolute +position (see below) with respect to its display's origin. For a child +frame (@pxref{Child Frames}) these parameters represent its position +relative to the native position (see below) of its parent frame. For +frames on text terminals the values of these parameters are meaningless +and always zero. @item External Border @cindex external border The @dfn{external border} is part of the decorations supplied by the -window manager. It's typically used for resizing the frame with the -mouse. The external border is normally not shown on ``fullboth'' and -maximized frames (@pxref{Size Parameters}) and doesn't exist for text -terminal frames. - - The external border should not be confused with the @dfn{outer -border} specified by the @code{border-width} frame parameter -(@pxref{Layout Parameters}). Since the outer border is usually ignored -on most platforms it is not covered here. +window manager. It is typically used for resizing the frame with the +mouse and is therefore not shown on ``fullboth'' and maximized frames +(@pxref{Size Parameters}). Its width is determined by the window +manager and cannot be changed by Emacs' functions. + +External borders don't exist on text terminal frames. For graphical +frames, their display can be suppressed by setting the +@code{override-redirect} or @code{undecorated} frame parameter +(@pxref{Management Parameters}). + +@item Outer Border +@cindex outer border +The @dfn{outer border} is a separate border whose width can be specified +with the @code{border-width} frame parameter (@pxref{Layout +Parameters}). In practice, either the external or the outer border of a +frame are displayed but never both at the same time. Usually, the outer +border is shown only for special frames that are not (fully) controlled +by the window manager like tooltip frames (@pxref{Tooltips}), child +frames (@pxref{Child Frames}) and @code{undecorated} or +@code{override-redirect} frames (@pxref{Management Parameters}). + +Outer borders are never shown on text terminal frames and on frames +generated by GTK+ routines. On Windows, the outer border is emulated +with the help of a one pixel wide external border. Non-toolkit builds +allow to change the color of the outer border by setting the +@code{border-color} frame parameter (@pxref{Layout Parameters}). @item Title Bar @cindex title bar The @dfn{title bar} is also part of the window manager's decorations and typically displays the title of the frame (@pxref{Frame Titles}) as well -as buttons for minimizing, maximizing and deleting the frame. The title -bar is usually not displayed on fullboth (@pxref{Size Parameters}) -or tooltip frames. Title bars don't exist for text terminal frames. +as buttons for minimizing, maximizing and deleting the frame. It can be +also used for dragging the frame with the mouse. The title bar is +usually not displayed for fullboth (@pxref{Size Parameters}), tooltip +(@pxref{Tooltips}) and child frames (@pxref{Child Frames}) and doesn't +exist for terminal frames. Display of the title bar can be suppressed +by setting the @code{override-redirect} or the @code{undecorated} frame +parameters (@pxref{Management Parameters}). @item Menu Bar @cindex internal menu bar @cindex external menu bar The menu bar (@pxref{Menu Bar}) can be either internal (drawn by Emacs -itself) or external (drawn by a toolkit). Most builds (GTK+, Lucid, +itself) or external (drawn by the toolkit). Most builds (GTK+, Lucid, Motif and Windows) rely on an external menu bar. NS also uses an external menu bar which, however, is not part of the outer frame. Non-toolkit builds can provide an internal menu bar. On text terminal frames, the menu bar is part of the frame's root window (@pxref{Windows -and Frames}). +and Frames}). As a rule, menu bars are never shown on child frames +(@pxref{Child Frames}). Display of the menu bar can be suppressed by +setting the @code{menu-bar-lines} parameter (@pxref{Layout Parameters}) +to zero. + +It depends on the toolkit whether to wrap or truncate the menu bar +whenever it becomes too long to fit on its frame. Usually, only Motif +and Windows builds can wrap the menu bar. When they (un-)wrap the menu +bar, they try to keep the outer height of the frame unchanged, so the +native height of the frame (see below) will change instead. @item Tool Bar @cindex internal tool bar @@ -536,21 +596,39 @@ internal (drawn by Emacs itself) or external (drawn by a toolkit). The GTK+ and NS builds have the tool bar drawn by the toolkit. The remaining builds use internal tool bars. With GTK+ the tool bar can be located on either side of the frame, immediately outside the internal -border, see below. +border, see below. Tool bars are usually not shown for child frames +(@pxref{Child Frames}). Display of the tool bar can be suppressed by +setting the @code{tool-bar-lines} parameter (@pxref{Layout +Parameters}) to zero. + +If the variable @code{auto-resize-tool-bars} is non-@code{nil}, Emacs +wraps the internal tool bar when it becomes too long for its frame. If +and when Emacs (un-)wraps the internal tool bar, it by default keeps the +outer height of the frame unchanged, so the native height of the frame +(see below) will change instead. Emacs built with GTK+, on the other +hand, never wraps the tool bar but may automatically increase the outer +width of a frame in order to accommodate an overlong tool bar. @item Native Frame @cindex native frame @cindex native edges @cindex native width @cindex native height -@cindex display area +@cindex native size The @dfn{native frame} is a rectangle located entirely within the outer -frame. It excludes the areas occupied by the external border, the title -bar and any external menu or external tool bar. The area enclosed by -the native frame is sometimes also referred to as the @dfn{display area} -of the frame. The edges of the native frame are called the @dfn{native -edges} of the frame. The @dfn{native width} and @dfn{native height} of -the frame specify the size of the rectangle. +frame. It excludes the areas occupied by an external or outer border, +the title bar and any external menu or tool bar. The edges of the +native frame are called the @dfn{native edges} of the frame. Together, +the @dfn{native width} and @dfn{native height} of a frame specify the +@dfn{native size} of the frame. + +The native size of a frame is the size Emacs passes to the window-system +or window manager when creating or resizing the frame from within Emacs. +It is also the size Emacs receives from the window-system or window +manager whenever these resize the frame's window-system window, for +example, after maximizing the frame by clicking on the corresponding +button in the title bar or when dragging its external border with the +mouse. @cindex native position The top left corner of the native frame specifies the @dfn{native @@ -565,30 +643,42 @@ position for the various builds: @item (3) GTK+ and NS frames @end itemize -Accordingly, the native height of a frame includes the height of the +Accordingly, the native height of a frame may include the height of the tool bar but not that of the menu bar (Lucid, Motif, Windows) or those of the menu bar and the tool bar (non-toolkit and text terminal frames). -The native position of a frame is the reference position of functions +The native position of a frame is the reference position for functions that set or return the current position of the mouse (@pxref{Mouse Position}) and for functions dealing with the position of windows like @code{window-edges}, @code{window-at} or @code{coordinates-in-window-p} -(@pxref{Coordinates and Windows}). +(@pxref{Coordinates and Windows}). It also specifies the (0, 0) origin +for locating and positioning child frames within this frame +(@pxref{Child Frames}). + +Note also that the native position of a frame usually remains unaltered +on its display when removing or adding the window manager decorations by +changing the frame's @code{override-redirect} or @code{undecorated} +parameter (@pxref{Management Parameters}). @item Internal Border -The internal border (@pxref{Layout Parameters}) is a border drawn by -Emacs around the inner frame (see below). +The internal border is a border drawn by Emacs around the inner frame +(see below). Its width is specified by the @code{internal-border-width} +frame parameter (@pxref{Layout Parameters}). Its color is specified by +the background of the @code{internal-border} face. @item Inner Frame @cindex inner frame @cindex inner edges @cindex inner width @cindex inner height +@cindex inner size +@cindex display area The @dfn{inner frame} is the rectangle reserved for the frame's windows. It's enclosed by the internal border which, however, is not part of the inner frame. Its edges are called the @dfn{inner edges} of the frame. -The @dfn{inner width} and @dfn{inner height} specify the size of the -rectangle. +The @dfn{inner width} and @dfn{inner height} specify the @dfn{inner +size} of the rectangle. The inner frame is sometimes also referred to +as the @dfn{display area} of the frame. @cindex minibuffer-less frame @cindex minibuffer-only frame @@ -603,22 +693,39 @@ configurations. @item Text Area @cindex text area -The @dfn{text area} of a frame is a somewhat fictitious area located -entirely within the native frame. It can be obtained by removing from -the native frame any internal borders, one vertical and one horizontal -scroll bar, and one left and one right fringe as specified for this -frame, see @ref{Layout Parameters}. +The @dfn{text area} of a frame is a somewhat fictitious area that can be +embedded in the native frame. Its position is unspecified. Its width +can be obtained by removing from that of the native width the widths of +the internal border, one vertical scroll bar, and one left and one right +fringe as specified for this frame, see @ref{Layout Parameters}. Its +height can be obtained by removing from that of the native height the +widths of the internal border and the heights of the frame's internal +menu and tool bars and one horizontal scroll bar as specified for this +frame. @end table @cindex absolute position -The @dfn{absolute position} of a frame or its edges is usually given in -terms of pixels counted from an origin at position (0, 0) of the frame's -display. Note that with multiple monitors the origin does not -necessarily coincide with the top left corner of the entire usable -display area. Hence the absolute outer position of a frame or the -absolute positions of the edges of the outer, native or inner frame can -be negative in such an environment even when that frame is completely -visible. +@cindex absolute frame position +@cindex absolute edges +@cindex absolute frame edges +@cindex display origin +@cindex origin of display +The @dfn{absolute position} of a frame is given as a pair (X, Y) of +horizontal and vertical pixel offsets relative to an origin (0, 0) of +the frame's display. Correspondingly, the @dfn{absolute edges} of a +frame are given as pixel offsets from that origin. + + Note that with multiple monitors the origin of the display does not +necessarily coincide with the top-left corner of the entire usable +display area of the terminal. Hence the absolute position of a frame +can be negative in such an environment even when that frame is +completely visible. + + By convention, vertical offsets increase ``downwards''. This means +that the height of a frame is obtained by subtracting the offset of its +top edge from that of its bottom edge. Horizontal offsets increase +``leftwards'' as expected so a frame's width is calculated by +subtracting the offset of its left edge from that of its right edge. For a frame on a graphical terminal the following function returns the sizes of the areas described above: @@ -626,13 +733,15 @@ sizes of the areas described above: @defun frame-geometry &optional frame This function returns geometric attributes of @var{frame}. The return value is an association list of the attributes listed below. All -coordinate, height and width values are integers counting pixels. +coordinate, height and width values are integers counting pixels. Note +that if @var{frame} has not been mapped (@pxref{Visibility of Frames}) +yet, some of the return values may only represent approximations of the +actual values---those that can be seen after the frame has been mapped. @table @code @item outer-position -A cons of the absolute X- and Y-coordinates of the outer position of -@var{frame}, relative to the origin at position (0, 0) of @var{frame}'s -display. +A cons representing the absolute position of the outer @var{frame}, +relative to the origin at position (0, 0) of @var{frame}'s display. @item outer-size A cons of the outer width and height of @var{frame}. @@ -643,6 +752,10 @@ borders as supplied by the window manager. If the window manager doesn't supply these values, Emacs will try to guess them from the coordinates of the outer and inner frame. +@item outer-border-width +The width of the outer border of @var{frame}. The value is meaningful +for non-GTK+ X builds only. + @item title-bar-size A cons of the width and height of the title bar of @var{frame} as supplied by the window manager or operating system. If both of them are @@ -677,24 +790,27 @@ The following function can be used to retrieve the edges of the outer, native and inner frame. @defun frame-edges &optional frame type -This function returns the edges of the outer, native or inner frame of -@var{frame}. @var{frame} must be a live frame and defaults to the -selected one. The list returned has the form (@var{left} @var{top} +This function returns the absolute edges of the outer, native or inner +frame of @var{frame}. @var{frame} must be a live frame and defaults to +the selected one. The list returned has the form (@var{left} @var{top} @var{right} @var{bottom}) where all values are in pixels relative to the -position (0, 0) of @var{frame}'s display. For terminal frames -@var{left} and @var{top} are both zero. +origin of @var{frame}'s display. For terminal frames the values +returned for @var{left} and @var{top} are always zero. Optional argument @var{type} specifies the type of the edges to return: -@var{type} @code{outer-edges} means to return the outer edges of -@var{frame}, @code{native-edges} (or @code{nil}) means to return its -native edges and @code{inner-edges} means to return its inner edges. +@code{outer-edges} means to return the outer edges of @var{frame}, +@code{native-edges} (or @code{nil}) means to return its native edges and +@code{inner-edges} means to return its inner edges. -Notice that the pixels at the positions @var{bottom} and @var{right} -lie immediately outside the corresponding frame. This means that if you -have, for example, two side-by-side frames positioned such that the -right outer edge of the frame on the left equals the left outer edge of -the frame on the right, the pixels representing that edge are part -of the frame on the right. +By convention, the pixels of the display at the values returned for +@var{left} and @var{top} are inside (part of) @var{frame}. Hence, if +@var{left} and @var{top} are both zero, the pixel at the display's +origin is part of @var{frame}. The pixels at @var{bottom} and +@var{right}, on the other hand, lie immediately outside @var{frame}. +This means that if you have, for example, two side-by-side frames +positioned such that the right outer edge of the frame on the left +equals the left outer edge of the frame on the right, the pixels at that +edge show a part of the frame on the right. @end defun @@ -751,62 +867,112 @@ and all future graphical frames. @end deffn -@node Size and Position -@subsection Size and Position -@cindex frame size +@node Frame Position +@subsection Frame Position @cindex frame position @cindex position of frame -You can read or change the position of a frame using the frame -parameters @code{left} and @code{top} (@pxref{Position Parameters}) and -its size using the @code{height} and @code{width} parameters -(@pxref{Size Parameters}). Here are some special features for working -with sizes and positions. For all of these functions the argument -@var{frame} must denote a live frame and defaults to the selected frame. +On graphical systems, the position of a normal top-level frame is +specified as the absolute position of its outer frame (@pxref{Frame +Geometry}). The position of a child frame (@pxref{Child Frames}) is +specified via pixel offsets of its outer edges relative to the native +position of its parent frame. + + You can read or change the position of a frame using the frame +parameters @code{left} and @code{top} (@pxref{Position Parameters}). +Here are two additional functions for working with the positions of an +existing, visible frame. For both functions, the argument @var{frame} +must denote a live frame and defaults to the selected frame. @defun frame-position &optional frame -This function returns the outer position (@pxref{Frame Layout}) of -@var{frame} in pixels. The value is a cons giving the coordinates of -the top left corner of the outer frame of @var{frame} relative to an -origin at the position (0, 0) of the frame's display. On a text -terminal frame both values are zero. +For a normal, non-child frame this function returns a cons of the (X, Y) +pixel coordinates of its outer position (@pxref{Frame Layout}) with +respect to the origin (0, 0) of its display. For a child frame +(@pxref{Child Frames}) this function returns the pixel coordinates of +its outer position with respect to an origin (0, 0) at the native +position of @var{frame}'s parent. + +Negative return values never indicate an offset from the right or bottom +edge of @var{frame}'s display or parent frame. Rather, they mean that +@var{frame}'s outer position is on the left and/or above the origin of +its display or the native position of its parent frame. This usually +means that @var{frame} is only partially visible (or completely +invisible). However, on systems where the display's origin does not +coincide with its top-left corner, the frame may be visible on a +secondary monitor. + +On a text terminal frame both values are zero. @end defun @defun set-frame-position frame x y -This function sets the outer frame position of @var{frame} to @var{x} -and @var{y}. The latter arguments specify pixels and normally count -from an origin at the position (0, 0) of @var{frame}'s display. +This function sets the outer frame position of @var{frame} to (@var{x}, +@var{y}). The latter arguments specify pixels and normally count from +an origin at the position (0, 0) of @var{frame}'s display. For child +frames, they count from the native position of @var{frame}'s parent +frame. + +Negative parameter values position the right edge of the outer frame by +@var{-x} pixels left from the right edge of the screen (or the parent +frame's native rectangle) and the bottom edge by @var{-y} pixels up from +the bottom edge of the screen (or the parent frame's native rectangle). -A negative parameter value positions the right edge of the outer frame -by @var{-x} pixels left from the right edge of the screen or the bottom -edge by @var{-y} pixels up from the bottom edge of the screen. +Note that negative values do not permit to align the right or bottom +edge of @var{frame} exactly at the right or bottom edge of its display +or parent frame. Neither do they allow to specify a position that does +not lie within the edges of the display or parent frame. The frame +parameters @code{left} and @code{top} (@pxref{Position Parameters}) +allow to do that but may still fail to provide good results for the +initial or a new frame. This function has no effect on text terminal frames. @end defun -@defun frame-pixel-height &optional frame -@defunx frame-pixel-width &optional frame - These functions return the inner height and width (the height and -width of the display area, see @ref{Frame Layout}) of @var{frame} in -pixels. For a text terminal, the results are in characters rather than -pixels. -@end defun +@defvar move-frame-functions +This hook specifies the functions run when an Emacs frame is moved +(assigned a new position) by the window-system or window manager. The +functions are run with one argument, the frame that moved. For a child +frame (@pxref{Child Frames}), the functions are run only when the +position of the frame changes in relation to that of its parent frame. +@end defvar + + +@node Frame Size +@subsection Frame Size +@cindex frame size +@cindex text width of a frame +@cindex text height of a frame +@cindex text size of a frame +The canonical way to specify the @dfn{size of a frame} from within Emacs +is by specifying its @dfn{text size}---a tuple of the width and height +of the frame's text area (@pxref{Frame Layout}). It can be measured +either in pixels or in terms of the frame's canonical character size +(@pxref{Frame Font}). + + For frames with an internal menu or tool bar, the frame's native +height cannot be told exactly before the frame has been actually drawn. +This means that in general you cannot use the native size to specify the +initial size of a frame. As soon as you know the native size of a +visible frame, you can calculate its outer size (@pxref{Frame Layout}) +by adding in the remaining components from the return value of +@code{frame-geometry} . For invisible frames or for frames that have +yet to be created, however, the outer size can be estimated only. This +also means that calculating an exact initial position of a frame +specified via offsets from the right or bottom edge of the screen +(@pxref{Frame Position}) is impossible. + + The text size of any frame can be set and retrieved with the help of +the @code{height} and @code{width} frame parameters (@pxref{Size +Parameters}). The text size of the initial frame can be also set with +the help of an X-style geometry specification. @xref{Emacs Invocation,, +Command Line Arguments for Emacs Invocation, emacs, The GNU Emacs +Manual}. Below we list some functions to access and set the size of an +existing, visible frame. @defun frame-text-height &optional frame @defunx frame-text-width &optional frame These functions return the height and width of the text area of @var{frame} (@pxref{Frame Layout}), measured in pixels. For a text terminal, the results are in characters rather than pixels. - -The value returned by @code{frame-text-height} differs from that -returned by @code{frame-pixel-height} by not including the heights of -any internal tool bar or menu bar, the height of one horizontal scroll -bar and the widths of the internal border. - -The value returned by @code{frame-text-width} differs from that returned -by @code{frame-pixel-width} by not including the width of one vertical -scroll bar, the widths of one left and one right fringe and the widths -of the internal border. @end defun @defun frame-height &optional frame @@ -823,12 +989,28 @@ rounded down to the number of characters of the default font that fully fit into the text area. @end defun +@defun frame-pixel-height &optional frame +@defunx frame-pixel-width &optional frame +These functions return the native width and height, see @ref{Frame +Layout}) of @var{frame} in pixels. For a text terminal, the results are +in characters rather than pixels. +@end defun + +On window systems that support it, Emacs tries by default to make the +text size of a frame measured in pixels a multiple of the frame's +character size. This, however, usually means that a frame can be +resized only in character size increments when dragging its external +borders. It also may break attempts to truly maximize the frame or +making it ``fullheight'' or ``fullwidth'' (@pxref{Size Parameters}) +leaving some empty space below and/or on the right of the frame. The +following option may help in that case. + @defopt frame-resize-pixelwise -If this option is @code{nil}, a frame's size is usually rounded to a -multiple of the current values of that frame's @code{frame-char-height} -and @code{frame-char-width} whenever the frame is resized. If this is -non-@code{nil}, no rounding occurs, hence frame sizes can -increase/decrease by one pixel. +If this option is @code{nil}, a frame's text pixel size is usually +rounded to a multiple of the current values of that frame's +@code{frame-char-height} and @code{frame-char-width} whenever the frame +is resized. If this is non-@code{nil}, no rounding occurs, hence frame +sizes can increase/decrease by one pixel. Setting this variable usually causes the next resize operation to pass the corresponding size hints to the window manager. This means that @@ -855,7 +1037,7 @@ terms of the canonical height and width of a character on @var{frame} The optional argument @var{pixelwise} non-@code{nil} means to measure the new width and height in units of pixels instead. Note that if @code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to -fully honor the request if it does not increase/decrease the frame size +truly honor the request if it does not increase/decrease the frame size to a multiple of its character size. @end defun @@ -876,9 +1058,9 @@ text terminals. The optional fourth argument @var{pixelwise} non-@code{nil} means that @var{frame} should be @var{height} pixels high. Note that if -@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to -fully honor the request if it does not increase/decrease the frame -height to a multiple of its character height. +@code{frame-resize-pixelwise} is @code{nil}, some window managers may +refuse to truly honor the request if it does not increase/decrease the +frame height to a multiple of its character height. @end defun @defun set-frame-width frame width &optional pretend pixelwise @@ -888,9 +1070,9 @@ in characters. The argument @var{pretend} has the same meaning as in The optional fourth argument @var{pixelwise} non-@code{nil} means that @var{frame} should be @var{width} pixels wide. Note that if -@code{frame-resize-pixelwise} is @code{nil}, some toolkits may refuse to -fully honor the request if it does not increase/decrease the frame width -to a multiple of its character width. +@code{frame-resize-pixelwise} is @code{nil}, some window managers may +refuse to fully honor the request if it does not increase/decrease the +frame width to a multiple of its character width. @end defun None of these three functions will make a frame smaller than needed to @@ -899,7 +1081,25 @@ margins, dividers, mode and header lines. This contrasts with requests by the window manager triggered, for example, by dragging the external border of a frame with the mouse. Such requests are always honored by clipping, if necessary, portions that cannot be displayed at the right, -bottom corner of the frame. +bottom corner of the frame. The parameters @code{min-width} and +@code{min-height} (@pxref{Size Parameters}) can be used to obtain a +similar behavior when changing the frame size from within Emacs. + +@cindex tracking frame size changes + The abnormal hook @code{window-size-change-functions} (@pxref{Window +Hooks}) tracks all changes of the inner size of a frame including those +induced by request of the window-system or window manager. To rule out +false positives that might occur when changing only the sizes of a +frame's windows without actually changing the size of the inner frame, +use the following function. + +@defun frame-size-changed-p &optional frame +This function returns non-@code{nil} when the inner width or height of +@var{frame} has changed since @code{window-size-change-functions} was +run the last time for @var{frame}. It always returns @code{nil} +immediately after running @code{window-size-change-functions} for +@var{frame}. +@end defun @node Implied Frame Resizing @@ -916,7 +1116,7 @@ size change. Note that wrapping a menu or tool bar usually does not resize the frame's outer size, hence this will alter the number of displayed lines. - Occasionally, such @dfn{implied frame resizing} may be unwanted, for + Occasionally, such @dfn{implied frame resizing} may be unwanted, for example, when the frame is maximized or made full-screen (where it's turned off by default). In other cases you can disable implied resizing with the following option: @@ -928,7 +1128,7 @@ implicitly resize the frame's display area in order to preserve the number of columns or lines the frame displays. If this option is non-@code{nil}, no implied resizing is done. -The value of this option can be also be a list of frame parameters. In +The value of this option can be also a list of frame parameters. In that case, implied resizing is inhibited when changing a parameter that appears in this list. The frame parameters currently handled by this option are: @code{font}, @code{font-backend}, @@ -1135,6 +1335,8 @@ text terminals. * Layout Parameters:: Size of parts of the frame, and enabling or disabling some parts. * Buffer Parameters:: Which buffers have been or should be shown. +* Frame Interaction Parameters:: Parameters for interacting with other + frames. * Management Parameters:: Communicating with the window manager. * Cursor Parameters:: Controlling the cursor appearance. * Font and Color Parameters:: Fonts and colors for the frame text. @@ -1180,64 +1382,81 @@ 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 looking up X resources for the frame. +@vindex explicit-name, a frame parameter @item explicit-name If the frame name was specified explicitly when the frame was created, this parameter will be that name. If the frame wasn't explicitly named, this parameter will be @code{nil}. @end table + @node Position Parameters @subsubsection Position Parameters @cindex window position on display @cindex frame position - Position parameters' values are measured in pixels. (Note that none -of these parameters exist on TTY frames.) +Parameters describing the X- and Y-offsets of a frame are always +measured in pixels. For normal, non-child frames they specify the +frame's absolute outer position (@pxref{Frame Geometry}) with respect to +its display's origin. For a child frame (@pxref{Child Frames}) they +specify the frame's outer position relative to the native position of +the frame's parent frame. (Note that none of these parameters is +meaningful on TTY frames.) @table @code @vindex left, a frame parameter @item left -The position, in pixels, of the left (or right) edge of the frame with -respect to the left (or right) edge of the screen. The value may be: +The position, in pixels, of the left outer edge of the frame with +respect to the left edge of the frame's display or parent frame. @table @asis @item an integer -A positive integer relates the left edge of the frame to the left edge -of the screen. A negative integer relates the right frame edge to the -right screen edge. +A positive integer always relates the left edge of the frame to the left +edge of its display or parent frame. A negative integer relates the +right frame edge to the right edge of the display or parent frame. @item @code{(+ @var{pos})} This specifies the position of the left frame edge relative to the left -screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen or on a monitor -other than the primary one (for multi-monitor displays). +edge of its display or parent frame. The integer @var{pos} may be +positive or negative; a negative value specifies a position outside the +screen or parent frame or on a monitor other than the primary one (for +multi-monitor displays). @item @code{(- @var{pos})} -This specifies the position of the right frame edge relative to the right -screen edge. The integer @var{pos} may be positive or negative; a -negative value specifies a position outside the screen or on a monitor -other than the primary one (for multi-monitor displays). +This specifies the position of the right frame edge relative to the +right edge of the display or parent frame. The integer @var{pos} may be +positive or negative; a negative value specifies a position outside the +screen or parent frame or on a monitor other than the primary one (for +multi-monitor displays). @end table Some window managers ignore program-specified positions. If you want to be sure the position you specify is not ignored, specify a -non-@code{nil} value for the @code{user-position} parameter as well. - -If the window manager refuses to align a frame at the left or top screen -edge, combining position notation and @code{user-position} as in +non-@code{nil} value for the @code{user-position} parameter as in the +following example: @example (modify-frame-parameters nil '((user-position . t) (left . (+ -4)))) @end example -may help to override that. +In general, it is not a good idea to specify negative offsets to +position a frame relative to the right or bottom edge of its display. +Positioning the initial or a new frame is either not accurate (because +the size of the outer frame is not yet fully known before the frame has +been made visible) or will cause additional flicker (if the frame is +repositioned after becoming visible). + + Note also, that negative offsets are not stored internally and are not +returned by the function @code{frame-parameters}. This means that the +desktop saving routines will restore the frame from the positive offsets +obtained by that function. @vindex top, a frame parameter @item top The screen position of the top (or bottom) edge, in pixels, with respect -to the top (or bottom) edge of the screen. It works just like -@code{left}, except vertically instead of horizontally. +to the top (or bottom) edge of the display or parent frame. It works +just like @code{left}, except vertically instead of horizontally. @vindex icon-left, a frame parameter @item icon-left @@ -1273,6 +1492,22 @@ When you call @code{make-frame}, you should specify a non-@code{nil} value for this parameter if the values of the @code{left} and @code{top} parameters represent the user's stated preference; otherwise, use @code{nil}. + +@vindex z-group, a frame parameter +@item z-group +This parameter specifies a relative position of the frame's +window-system window in the stacking (Z-) order of the frame's display. + +If this is @code{above}, the frame's window-system window is displayed +above all other window-system windows that do not have the @code{above} +property set. If this is nil, the frame's window is displayed below all +windows that have the @code{above} property set and above all windows +that have the @code{below} property set. If this is @code{below}, the +frame's window is displayed below all windows that do not have the +@code{below} property set. + +To position the frame above or below a specific other frame use the +function @code{frame-restack} (@pxref{Raising and Lowering}). @end table @@ -1285,15 +1520,19 @@ graphical displays, the @code{default} face determines the actual pixel sizes of these character units (@pxref{Face Attributes}). @table @code -@vindex height, a frame parameter -@item height -The height of the frame's text area (@pxref{Frame Geometry}), in -characters. - @vindex width, a frame parameter @item width The width of the frame's text area (@pxref{Frame Geometry}), in -characters. +characters. The value can be also a cons cell of the symbol +@code{text-pixels} and an integer denoting the width of the text area in +pixels. + +@vindex height, a frame parameter +@item height +The height of the frame's text area (@pxref{Frame Geometry}), in +characters. The value can be also a cons cell of the symbol +@code{text-pixels} and an integer denoting the height of the text area +in pixels. @vindex user-size, a frame parameter @item user-size @@ -1302,6 +1541,28 @@ the @code{user-position} parameter (@pxref{Position Parameters, user-position}) does for the position parameters @code{top} and @code{left}. +@vindex min-width, a frame parameter +@item min-width +This parameter specifies the minimum native width of the frame +(@pxref{Frame Geometry}), in characters. Normally, the functions that +establish a frame's initial width or resize a frame horizontally make +sure that all the frame's windows, vertical scroll bars, fringes, +margins and vertical dividers can be displayed. This parameter, if +non-@code{nil} allows to make a frame narrower than that with the +consequence that any components that do not fit on the frame will be +clipped by the window manager. + +@vindex min-height, a frame parameter +@item min-height +This parameter specifies the minimum height of the native (@pxref{Frame +Geometry}), in characters. Normally, the functions that establish a +frame's initial size or resize a frame make sure that all the frame's +windows, horizontal scroll bars and dividers, mode and header lines, the +echo area and the internal menu and tool bar can be displayed. This +parameter, if non-@code{nil} allows to make a frame smaller than that +with the consequence that any components that do not fit on the frame +will be clipped by the window-system or window manager. + @cindex fullboth frames @cindex fullheight frames @cindex fullwidth frames @@ -1327,10 +1588,10 @@ of maximized and full-height frames and the widths of maximized and full-width frames often differ by a few pixels. With some window managers you may have to customize the variable -@code{frame-resize-pixelwise} (@pxref{Size and Position}) in order to -make a frame truly appear maximized or full-screen. Moreover, -some window managers might not support smooth transition between the -various full-screen or maximization states. Customizing the variable +@code{frame-resize-pixelwise} (@pxref{Frame Size}) in order to make a +frame truly appear maximized or full-screen. Moreover, some window +managers might not support smooth transition between the various +full-screen or maximization states. Customizing the variable @code{x-frame-normalize-before-maximize} can help to overcome that. @vindex fullscreen-restore, a frame parameter @@ -1364,11 +1625,12 @@ frame, or control their sizes. @table @code @vindex border-width, a frame parameter @item border-width -The width in pixels of the frame's border. +The width in pixels of the frame's outer border (@pxref{Frame Geometry}). @vindex internal-border-width, a frame parameter @item internal-border-width -The distance in pixels between text (or fringe) and the frame's border. +The width in pixels of the frame's internal border (@pxref{Frame +Geometry}). @vindex vertical-scroll-bars, a frame parameter @item vertical-scroll-bars @@ -1418,21 +1680,25 @@ to not draw bottom dividers. @vindex menu-bar-lines frame parameter @item menu-bar-lines -The number of lines to allocate at the top of the frame for a menu -bar. The default is 1 if Menu Bar mode is enabled, and 0 otherwise. -@xref{Menu Bars,,,emacs, The GNU Emacs Manual}. +The number of lines to allocate at the top of the frame for a menu bar. +The default is one if Menu Bar mode is enabled and zero otherwise. +@xref{Menu Bars,,,emacs, The GNU Emacs Manual}. For an external menu +bar, this value remains unchanged even when the menu bar wraps to two or +more lines. In that case, the @code{menu-bar-size} value returned by +@code{frame-geometry} (@pxref{Frame Geometry}) allows to derive whether +the menu bar actually occupies one or more lines. @vindex tool-bar-lines frame parameter @item tool-bar-lines -The number of lines to use for the tool bar. The default is 1 if Tool -Bar mode is enabled, and 0 otherwise. @xref{Tool Bars,,,emacs, The -GNU Emacs Manual}. +The number of lines to use for the tool bar. The default is one if Tool +Bar mode is enabled and zero otherwise. @xref{Tool Bars,,,emacs, The +GNU Emacs Manual}. This value may change whenever the tool bar wraps. @vindex tool-bar-position frame parameter @item tool-bar-position The position of the tool bar. Currently only for the GTK tool bar. Value can be one of @code{top}, @code{bottom} @code{left}, @code{right}. -The default is @code{top}. +The default is @code{top}. @vindex line-spacing, a frame parameter @item line-spacing @@ -1440,6 +1706,7 @@ Additional space to leave below each text line, in pixels (a positive integer). @xref{Line Height}, for more information. @end table + @node Buffer Parameters @subsubsection Buffer Parameters @cindex frame, which buffers to display @@ -1478,6 +1745,40 @@ most-recently-selected first. If non-@code{nil}, this frame's window is never split automatically. @end table +@node Frame Interaction Parameters +@subsubsection Frame Interaction Parameters + +These parameters supply forms of interactions between different frames. + +@table @code +@vindex parent-frame, a frame parameter +@item parent-frame +If non-@code{nil}, this means that this frame is a child frame +(@pxref{Child Frames}) and this parameter specifies its parent frame. +If nil, this means that this frame is a normal, top-level frame. + +@vindex delete-before, a frame parameter +@item delete-before +If non-@code{nil}, this parameter specifies another frame whose deletion +will automatically trigger the deletion of this frame. @xref{Deleting +Frames}. + +@vindex mouse-wheel-frame, a frame parameter +@item mouse-wheel-frame +If non-@code{nil}, this parameter specifies the frame whose windows will +be scrolled whenever the mouse wheel is scrolled with the mouse pointer +hovering over this frame (@pxref{Mouse Commands,,, emacs, The GNU Emacs +Manual}). + +@vindex no-other-frame, a frame parameter +@item no-other-frame +If this is non-@code{nil}, then this frame is not eligible as candidate +for the functions @code{next-frame}, @code{previous-frame} +(@pxref{Finding All Frames}) and @code{other-frame} (@pxref{Frame +Commands,,, emacs, The GNU Emacs Manual}). +@end table + + @node Management Parameters @subsubsection Window Management Parameters @cindex window manager interaction, and frame parameters @@ -1541,10 +1842,56 @@ with virtual desktops. @vindex inhibit-double-buffering, a frame parameter @item inhibit-double-buffering -If non-@code{nil}, the frame is drawn to the screen without double buffering. -Emacs normally attempts to use double buffering, where available, to -reduce flicker. Set this property if you experience display bugs or -pine for that retro, flicker-y feeling. +If non-@code{nil}, the frame is drawn to the screen without double +buffering. Emacs normally attempts to use double buffering, where +available, to reduce flicker. Set this property if you experience +display bugs or pine for that retro, flicker-y feeling. + +@vindex skip-taskbar, a frame parameter +@item skip-taskbar +If non-@code{nil}, this tells the window manager to remove the frame's +icon from the taskbar associated with the frame's display and inhibit +switching to the frame's window via the combination @kbd{Alt-@key{TAB}}. +On Windows, iconifying such a frame will "roll in" its window-system +window at the bottom of the desktop. Some window managers may not honor +this parameter. + +@vindex no-focus-on-map, a frame parameter +@item no-focus-on-map +If non-@code{nil}, this means that the frame dos not want to receive +input focus when it is mapped (@pxref{Visibility of Frames}). Some +window managers may not honor this parameter. + +@vindex no-accept-focus, a frame parameter +@item no-accept-focus +If non-@code{nil}, this means that the frame does not want to receive +input focus via explicit mouse clicks or when moving the mouse into it +either via @code{focus-follows-mouse} (@pxref{Input Focus}) or +@code{mouse-autoselect-window} (@pxref{Mouse Window Auto-selection}). +This may have the unwanted side-effect that a user cannot scroll a +non-selected frame with the mouse. Some window managers may not honor +this parameter. + +@vindex undecorated, a frame parameter +@item undecorated +If non-@code{nil}, this frame's window-system window is drawn without +decorations like title, minimize/maximize boxes and external borders. +This usually means that the window cannot be dragged, resized, +iconified, maximized or deleted with the mouse. If nil, the frame's +window is usually drawn with all the elements listed above unless their +display has been suspended via window manager settings. + +Under X, Emacs uses the Motif window manager hints to turn off +decorations. Some window managers may not honor these hints. + +@vindex override-redirect, a frame parameter +@item override-redirect +@cindex override redirect frames +If non-@code{nil}, this means that this is an @dfn{override redirect} +frame---a frame not handled by window managers under X. Override +redirect frames have no window manager decorations, can be positioned +and resized only via Emacs' positioning and resizing functions and are +usually drawn on top of all other frames. @ignore @vindex parent-id, a frame parameter @@ -1557,6 +1904,7 @@ it and see if it works.) @end ignore @end table + @node Cursor Parameters @subsubsection Cursor Parameters @cindex cursor, and frame parameters @@ -1904,21 +2252,28 @@ while processing @code{frame-title-format} or @section Deleting Frames @cindex deleting frames - A @dfn{live frame} is one that has not been deleted. When a frame -is deleted, it is removed from its terminal display, although it may -continue to exist as a Lisp object until there are no more references -to it. +A @dfn{live frame} is one that has not been deleted. When a frame is +deleted, it is removed from its terminal display, although it may +continue to exist as a Lisp object until there are no more references to +it. @deffn Command delete-frame &optional frame force @vindex 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. Unless @var{frame} specifies a tooltip, this function first runs -the hook @code{delete-frame-functions} (each function getting one -argument, @var{frame}). +frame. -A frame cannot be deleted as long as its minibuffer serves as surrogate -minibuffer for another frame (@pxref{Minibuffers and Frames}). +It first deletes any child frame of @var{frame} (@pxref{Child Frames}) +and any frame whose @code{delete-before} frame parameter (@pxref{Frame +Interaction Parameters}) specifies @var{frame}. All such deletions are +performed recursively; so this step makes sure that there will not exist +any other frames with @var{frame} as their ancestor. 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. + +Note that a frame cannot be deleted as long as its minibuffer serves as +surrogate minibuffer for another frame (@pxref{Minibuffers and Frames}). Normally, you cannot delete a frame if all other frames are invisible, but if @var{force} is non-@code{nil}, then you are allowed to do so. @end deffn @@ -1942,8 +2297,13 @@ minibuffer frame is left untouched. The argument @var{frame} must specify a live frame and defaults to the selected frame. Internally, this command works by calling @code{delete-frame} with @var{force} @code{nil} for all frames that shall be deleted. + +This function does not delete any of @var{frame}'s child frames +(@pxref{Child Frames}). If @var{frame} is a child frame, it deletes +@var{frame}'s siblings only. @end deffn + @node Finding All Frames @section Finding All Frames @cindex frames, scanning all @@ -1962,12 +2322,29 @@ This function returns a list of just the currently visible frames. visible, even though only the selected one is actually displayed. @end defun +@defun frame-list-z-order &optional display +This function returns a list of Emacs' frames, in Z (stacking) order +(@pxref{Raising and Lowering}). The optional argument @var{display} +specifies which display to poll. @var{display} should be either a frame +or a display name (a string). If omitted or @code{nil}, that stands for +the selected frame's display. It returns @code{nil} if @var{display} +contains no Emacs frame. + +Frames are listed from topmost (first) to bottommost (last). As a +special case, if @var{display} is non-@code{nil} and specifies a live +frame, it returns the child frames of that frame in Z (stacking) order. + +This function is not meaningful on text terminals. +@end defun + @defun next-frame &optional frame minibuf This function lets you cycle conveniently through all the frames on a specific terminal from an arbitrary starting point. It returns the frame following @var{frame}, in the list of all live frames, on @var{frame}'s terminal. The argument @var{frame} must specify a live -frame and defaults to the selected frame. +frame and defaults to the selected frame. It never returns a frame +whose @code{no-other-frame} parameter (@pxref{Frame Interaction +Parameters}) is non-@code{nil}. The second argument, @var{minibuf}, says which frames to consider: @@ -1998,8 +2375,8 @@ Window Ordering}. @section Minibuffers and Frames Normally, each frame has its own minibuffer window at the bottom, which -is used whenever that frame is selected. If the frame has a minibuffer, -you can get it with @code{minibuffer-window} (@pxref{Minibuffer Windows}). +is used whenever that frame is selected. You can get that window with +the function @code{minibuffer-window} (@pxref{Minibuffer Windows}). @cindex frame without a minibuffer @cindex surrogate minibuffer frame @@ -2009,9 +2386,10 @@ will serve as @dfn{surrogate minibuffer frame} for this frame and cannot be deleted via @code{delete-frame} (@pxref{Deleting Frames}) as long as this frame is live. -When you create the frame, you can explicitly specify the minibuffer -window to use (in some other frame). If you don't, then the minibuffer -is found in the frame which is the value of the variable +When you create the frame, you can explicitly specify its minibuffer +window (in some other frame) with the @code{minibuffer} frame parameter +(@pxref{Buffer Parameters}). If you don't, then the minibuffer is found +in the frame which is the value of the variable @code{default-minibuffer-frame}. Its value should be a frame that does have a minibuffer. @@ -2026,13 +2404,14 @@ the current terminal and cannot be buffer-local. @xref{Multiple Terminals}. @end defvar + @node Input Focus @section Input Focus @cindex input focus -@c @cindex selected frame Duplicates selected-frame, same for selected-window. +@cindex selected frame -At any time, one frame in Emacs is the @dfn{selected frame}. The selected -window always resides on the selected frame. +At any time, one frame in Emacs is the @dfn{selected frame}. The +selected window always resides on the selected frame. When Emacs displays its frames on several terminals (@pxref{Multiple Terminals}), each terminal has its own selected frame. But only one @@ -2077,6 +2456,26 @@ 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 +raising it above other frames. Unfortunately, many window-systems or +window managers may refuse to comply. + +@defun x-focus-frame &optional frame noactivate +This function gives @var{frame} the focus of the X server without +necessarily raising it. @var{frame} @code{nil} means use the selected +frame. Under X, the optional argument @var{noactivate}, if +non-@code{nil}, means to avoid making @var{frame}'s window-system window +the ``active'' window which should insist a bit more on avoiding to +raise @var{frame} above other frames. + +On Windows the @var{noactivate} argument has no effect. However, if +@var{frame} is a child frame (@pxref{Child Frames}), this function +usualy does focus @var{frame} without raising it above other child +frames. + +If there is no window system support, this function does nothing. +@end defun + @deffn Command select-frame frame &optional norecord This function selects frame @var{frame}, temporarily disregarding the focus of the X server if any. The selection of @var{frame} lasts until @@ -2091,7 +2490,7 @@ becomes the selected terminal. This function then calls @code{select-window} as a subroutine, passing the window selected within @var{frame} as its first argument and @var{norecord} as its second argument (hence, if @var{norecord} is non-@code{nil}, this -avoids changing the order of recently selected windows nor the buffer +avoids changing the order of recently selected windows and the buffer list). @xref{Selecting Windows}. This function returns @var{frame}, or @code{nil} if @var{frame} has @@ -2147,20 +2546,64 @@ change it. @end defun @defvar focus-in-hook -This is a normal hook run when an Emacs frame gains input focus. +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 @defvar focus-out-hook -This is a normal hook run when an Emacs frame loses input focus. +This is a normal hook run when an Emacs frame has lost input focus and +no other Emacs frame has gained input focus instead. @end defvar @defopt focus-follows-mouse -This option is how you inform Emacs whether the window manager transfers -focus when the user moves the mouse. Non-@code{nil} says that it does. -When this is so, the command @code{other-frame} moves the mouse to a -position consistent with the new selected frame. +This option informs Emacs whether and how the window manager transfers +focus when you move the mouse pointer into a frame. It can have three +meaningful values: + +@table @asis +@item @code{nil} +The default value @code{nil} should be used when your window manager +follows a ``click-to-focus'' policy where you have to click the mouse +inside of a frame in order for that frame to gain focus. + +@item @code{t} +The value @code{t} should be used when your window manager has the focus +automatically follow the position of the mouse pointer but a frame that +gains focus is not raised automatically and may even remain occluded by +other window-system windows. + +@item @code{auto-raise} +The value @code{auto-raise} should be used when your window manager has +the focus automatically follow the position of the mouse pointer and a +frame that gains focus is raised automatically. +@end table + +If this option is non-@code{nil}, Emacs moves the mouse pointer to the +frame selected by @code{select-frame-set-input-focus}. That function is +used by a number of commands like, for example, @code{other-frame} and +@code{pop-to-buffer}. + +The distinction between the values @code{t} and @code{auto-raise} is not +needed for ``normal'' frames because the window manager usually takes +care of raising them. It is useful to automatically raise child frames +via @code{mouse-autoselect-window} (@pxref{Mouse Window +Auto-selection}). + +Note that this option does not distinguish ``sloppy'' focus (where the +frame that previously had focus retains focus as long as the mouse +pointer does not move into another window manager window) from +``strict'' focus (where a frame immediately loses focus when it's left +by the mouse pointer). It neither recognizes whether your window +manager supports delayed focusing or auto-raising where you can +explicitly specify the time until a new frame gets focus or is +auto-raised. + +You can supply a ``focus follows mouse'' policy for individual Emacs +windows by customizing the variable @code{mouse-autoselect-window} +(@pxref{Mouse Window Auto-selection}). @end defopt + @node Visibility of Frames @section Visibility of Frames @cindex visible frame @@ -2169,16 +2612,26 @@ position consistent with the new selected frame. @cindex minimized frame @cindex frame visibility -A frame on a graphical display may be @dfn{visible}, @dfn{invisible}, -or @dfn{iconified}. If it is visible, its contents are displayed in -the usual manner. If it is iconified, its contents are not displayed, -but there is a little icon somewhere to bring the frame back into view -(some window managers refer to this state as @dfn{minimized} rather -than @dfn{iconified}, but from Emacs' point of view they are the same -thing). If a frame is invisible, it is not displayed at all. +A frame on a graphical display may be @dfn{visible}, @dfn{invisible}, or +@dfn{iconified}. If it is visible, its contents are displayed in the +usual manner. If it is iconified, its contents are not displayed, but +there is a little icon somewhere to bring the frame back into view (some +window managers refer to this state as @dfn{minimized} rather than +@dfn{iconified}, but from Emacs' point of view they are the same thing). +If a frame is invisible, it is not displayed at all. + +@cindex mapped frame +@cindex unmapped frame + The concept of visibility is strongly related to that of (un-)mapped +frames. A frame (or, more precisely, its window-system window) is and +becomes @dfn{mapped} when it is displayed for the first time and +whenever it changes its state of visibility from @code{iconified} or +@code{invisible} to @code{visible}. Conversely, a frame is and becomes +@dfn{unmapped} whenever it changes its status from @code{visible} to +@code{iconified} or @code{invisible}. Visibility is meaningless on text terminals, since only the selected -one is actually displayed in any case. +frame is actually displayed in any case. @defun frame-visible-p frame This function returns the visibility status of frame @var{frame}. The @@ -2192,22 +2645,28 @@ purposes of this function, even though only one frame is displayed. @deffn Command iconify-frame &optional frame This function iconifies frame @var{frame}. If you omit @var{frame}, it -iconifies the selected frame. +iconifies the selected frame. This usually makes all child frames of +@var{frame} (and their descendants) invisible (@pxref{Child Frames}). @end deffn @deffn Command make-frame-visible &optional frame -This function makes frame @var{frame} visible. If you omit -@var{frame}, it makes the selected frame visible. This does not raise -the frame, but you can do that with @code{raise-frame} if you wish -(@pxref{Raising and Lowering}). +This function makes frame @var{frame} visible. If you omit @var{frame}, +it makes the selected frame visible. This does not raise the frame, but +you can do that with @code{raise-frame} if you wish (@pxref{Raising and +Lowering}). + +Making a frame visible usually makes all its child frames (and their +descendants) visible too (@pxref{Child Frames}). @end deffn @deffn Command make-frame-invisible &optional frame force This function makes frame @var{frame} invisible. If you omit -@var{frame}, it makes the selected frame invisible. +@var{frame}, it makes the selected frame invisible. Usually, this makes +all child frames of @var{frame} (and their descendants) invisible too +(@pxref{Child Frames}). Unless @var{force} is non-@code{nil}, this function refuses to make -@var{frame} invisible if all other frames are invisible.. +@var{frame} invisible if all other frames are invisible. @end deffn The visibility status of a frame is also available as a frame @@ -2223,27 +2682,79 @@ being rendered with double buffering. @var{frame} defaults to the selected frame. @end defun + @node Raising and Lowering -@section Raising and Lowering Frames +@section Raising, Lowering and Restacking Frames @cindex raising a frame @cindex lowering a frame - Most window systems use a desktop metaphor. Part of this metaphor -is the idea that system-level windows (e.g., Emacs frames) are -stacked in a notional third dimension perpendicular to the screen -surface. Where two overlap, the one higher up covers the one -underneath. You can @dfn{raise} or @dfn{lower} a frame using the -functions @code{raise-frame} and @code{lower-frame}. +@cindex restacking a frame +@cindex frame stacking order +@cindex frame Z-order + Most window systems use a desktop metaphor. Part of this metaphor is +the idea that system-level windows (representing, e.g., Emacs frames) +are stacked in a notional third dimension perpendicular to the screen +surface. The order induced by stacking is total and usually referred to +as stacking (or Z-) order. Where the areas of two windows overlap, the +one higher up in that order will (partially) cover the one underneath. + + You can @dfn{raise} a frame to the top of that order or @dfn{lower} a +frame to its bottom by using the functions @code{raise-frame} and +@code{lower-frame}. You can @dfn{restack} a frame directly above or +below another frame using the function @code{frame-restack}. + + Note that all functions described below will respect the adherence of +frames (and all other window-system windows) to their respective z-group +(@pxref{Position Parameters}). For example, you usually cannot lower a +frame below that of the desktop window and you cannot raise a frame +whose @code{z-group} parameter is @code{nil} above the window-system's +taskbar or tooltip window. @deffn Command raise-frame &optional frame -This function raises frame @var{frame} (default, the selected frame). -If @var{frame} is invisible or iconified, this makes it visible. +This function raises frame @var{frame} (default, the selected frame) +above all other frames belonging to the same or a lower z-group as +@var{frame}. If @var{frame} is invisible or iconified, this makes it +visible. If @var{frame} is a child frame (@pxref{Child Frames}), this +raises @var{frame} above all other child frames of its parent. @end deffn @deffn Command lower-frame &optional frame -This function lowers frame @var{frame} (default, the selected frame). +This function lowers frame @var{frame} (default, the selected frame) +below all other frames belonging to the same or a higher z-group as +@var{frame}. If @var{frame} is a child frame (@pxref{Child Frames}), +this lowers @var{frame} below all other child frames of its parent. @end deffn +@defun frame-restack frame1 frame2 &optional above +This function restacks @var{frame1} below @var{frame2}. This implies +that if both frames are visible and their display areas overlap, +@var{frame2} will (partially) obscure @var{frame1}. If the optional +third argument @var{above} is non-@code{nil}, this function restacks +@var{frame1} above @var{frame2}. This means that if both frames are +visible and their display areas overlap, @var{frame1} will (partially) +obscure @var{frame2}. + +Technically, this function may be thought of as an atomic action +performed in two steps: The first step removes @var{frame1}'s +window-system window from the display. The second step reinserts +@var{frame1}'s window into the display below (above if @var{above} is +true) that of @var{frame2}. Hence the position of @var{frame2} in its +display's Z (stacking) order relative to all other frames excluding +@var{frame1} remains unaltered. + +Some window managers may refuse to restack windows. +@end defun + +Note that the effect of restacking will only hold as long as neither of +the involved frames is iconified or made invisible. You can use the +@code{z-group} (@pxref{Position Parameters}) frame parameter to add a +frame to a group of frames permanently shown above or below other +frames. As long as a frame belongs to one of these groups, restacking +it will only affect its relative stacking position within that group. +The effect of restacking frames belonging to different z-groups is +undefined. You can list frames in their current stacking order with the +function @code{frame-list-z-order} (@pxref{Finding All Frames}). + @defopt minibuffer-auto-raise If this is non-@code{nil}, activation of the minibuffer raises the frame that the minibuffer window is in. @@ -2265,6 +2776,7 @@ or @code{nil} (meaning the selected frame's terminal). If it does not refer to a text terminal, the return value is @code{nil}. @end defun + @node Frame Configurations @section Frame Configurations @cindex frame configuration @@ -2288,6 +2800,135 @@ Ordinarily, this function deletes all existing frames not listed in unwanted frames are iconified instead. @end defun + +@node Child Frames +@section Child Frames +@cindex child frames +@cindex parent frames + +On some window-systems the @code{parent-frame} parameter (@pxref{Frame +Interaction Parameters}) can be used to make a frame a child of the +frame specified by that parameter. The frame specified by that +parameter will then be the frame's parent frame as long as the parameter +is not changed or reset. Technically, this makes the child frame's +window-system window a child window of the parent frame's window-system +window. + + The @code{parent-frame} parameter can be changed at any time. Setting +it to another frame ``reparents'' the child frame. Setting it to +another child frame makes the frame a ``nested'' child frame. Setting +it to @code{nil} restores the frame's status as a top-level frame---one +whose window-system window is a child of its display's root window. + + Since child frames can be arbitrarily nested, a frame can be both a +child and a parent frame. Also, the relative roles of child and parent +frame may be reversed at any time (though it's usually a good idea to +keep the size of child frames sufficiently smaller than that of their +parent). An error will be signalled for the attempt to make a frame an +ancestor of itself. + + A child frame is clipped at the native edges (@pxref{Frame Geometry}) +of its parent frame---everything outside these edges is invisible. Its +@code{left} and @code{top} parameters specify positions relative to the +top-left corner of its parent's native frame. When either of the frames +is resized, the relative position of the child frame remains unaltered. +Hence, resizing either of these frames can hide or reveal parts of the +child frame. + + Usually, moving a parent frame moves along all its child frames and +their descendants as well, keeping their relative positions unaltered. +The hook @code{move-frame-functions} (@pxref{Frame Position}) is run for +a child frame only when the position of the child frame relative to its +parent frame changes. When a parent frame is resized, the child frame +retains its position respective to the left and upper native edges of +its parent. In this case, the position respective to the lower or right +native edge of the parent frame is usually lost. + + A visible child frame always appears on top of its parent frame thus +obscuring parts of it. This is comparable to the window-system window +of a 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. + + Whether a child frame can have a menu or tool bar is window-system or +window manager dependent. Most window-systems explicitly disallow menus +bars for child frames. It seems advisable to disable both, menu and +tool bars, via the frame's initial parameters settings. + + Usually, child frames do not exhibit window manager decorations like a +title bar or external borders (@pxref{Frame Geometry}). When the child +frame does not show a menu or tool bar, any other of the frame's borders +(@pxref{Layout Parameters}) can be used instead of the external borders. + + In particular, under X (but not when building with GTK+), the frame's +outer border can be used. On Windows, specifying a non-zero outer +border width will show a one pixel wide external border. Under all +window-systems, the internal border can be used. In either case, it's +advisable to disable a child frame's window manager decorations with the +@code{undecorated} frame parameter @pxref{Management Parameters}). + + The behavior of child frames deviates from that of top-level frames in +a number of other ways as well. Here we sketch a few of them: + +@itemize @bullet +@item +The semantics of maximizing and iconifying child frames is highly +window-system dependent. As a rule, applications should never invoke +these operations for child frames. + +@item +Raising, lowering and restacking child frames (@pxref{Raising and +Lowering}) or changing the @code{z-group} (@pxref{Position Parameters}) +of a child frame changes only the stacking order of child frames with +the same parent. + +@item +Many window-systems are not able to change the opacity (@pxref{Font and +Color Parameters}) of child frames. + +@item +Transferring focus from a child frame to an ancestor that is not its +parent by clicking with the mouse in a visible part of that ancestor's +window may fail with some window-systems. You may have to click into +the direct parent's window-system window first. + +@item +Window managers might not bother to extend their focus follows mouse +policy to child frames. Customizing @code{mouse-autoselect-window} can +help in this regard (@pxref{Mouse Window Auto-selection}). + +@item +Dropping (@pxref{Drag and Drop}) on child frames is not guaranteed too +work on all window-systems. Some will drop the object on the parent +frame or some ancestor instead. +@end itemize + + The following two functions may be useful when working with child and +parent frames: + +@defun frame-parent &optional frame +This function returns the parent frame of @var{frame}. The parent frame +of @var{frame} is the Emacs frame whose window-system window is the +parent window of @var{frame}'s window-system window. If such a frame +exists, @var{frame} is considered a child frame of that frame. + +This function returns @code{nil} if @var{frame} has no parent frame. +@end defun + +@defun frame-ancestor-p &optional ancestor descendant +This functions returns non-@code{nil} if @var{ancestor} is an ancestor +of @var{descendant}. @var{ancestor} is an ancestor of @var{descendant} +when it is either @var{descendant}'s parent frame or it is an ancestor +of @var{descendant}'s parent frame. Both, @var{ancestor} and +@var{descendant} must specify live frames and default to the selected +frame. +@end defun + + @node Mouse Tracking @section Mouse Tracking @cindex mouse tracking @@ -3203,9 +3844,3 @@ ever be developed and distributed noncommercially. This variable's value is @code{t} if no X window manager is in use. @end defvar @end ignore - -@ignore -@item -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 diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index 6aa9591e09..931d1060d5 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -42,6 +42,7 @@ is displayed in windows. * Vertical Scrolling:: Moving the contents up and down on the window. * Horizontal Scrolling:: Moving the contents sideways on the window. * Coordinates and Windows:: Converting coordinates to windows. +* Mouse Window Auto-selection:: Automatically selecting windows with the mouse. * Window Configurations:: Saving and restoring the state of the screen. * Window Parameters:: Associating additional information with windows. * Window Hooks:: Hooks for scrolling, window size changes, @@ -763,7 +764,7 @@ changing the size of its frame. Because live windows do not overlap, these functions are meaningful only on frames that contain two or more windows: resizing a window also changes the size of a neighboring window. If there is just one window on a frame, its size cannot be -changed except by resizing the frame (@pxref{Size and Position}). +changed except by resizing the frame (@pxref{Frame Size}). Except where noted, these functions also accept internal windows as arguments. Resizing an internal window causes its child windows to be @@ -1016,7 +1017,7 @@ A window can get resized explicitly by using one of the functions from the preceding section or implicitly, for example, when resizing an adjacent window, when splitting or deleting a window (@pxref{Splitting Windows}, @pxref{Deleting Windows}) or when resizing the window's frame -(@pxref{Size and Position}). +(@pxref{Frame Size}). It is possible to avoid implicit resizing of a specific window when there are one or more other resizable windows on the same frame. For @@ -1716,23 +1717,47 @@ value of @code{window-point} (@pxref{Window Point}) in @var{window}. @var{window} must be a live window. The return value is @var{window}. By default, this function also moves @var{window}'s buffer to the front -of the buffer list (@pxref{Buffer List}), and makes @var{window} the -most recently selected window. However, if the optional argument -@var{norecord} is non-@code{nil}, these additional actions are omitted. - -This function runs @code{buffer-list-update-hook} (@pxref{Buffer List}) -unless @var{norecord} is non-@code{nil}. Note that applications and -internal routines often temporarily select a window in order to simplify -coding. As a rule, such selections (including those made by the macros -@code{save-selected-window} and @code{with-selected-window} below) are -not recorded thus avoiding to pollute @code{buffer-list-update-hook}. -Selections that really count are those causing a visible change in -the next redisplay of @var{window}'s frame and should be always -recorded. This also means that to run a function each time a window -gets selected, putting it on @code{buffer-list-update-hook} should be -the right choice. +of the buffer list (@pxref{Buffer List}) and makes @var{window} the most +recently selected window. If the optional argument @var{norecord} is +non-@code{nil}, these additional actions are omitted. + +In addition, this function by default also tells the display engine to +update the display of @var{window} when its frame gets redisplayed the +next time. If @var{norecord} is non-@code{nil}, such updates are +usually not performed. If, however, @var{norecord} equals the special +symbol @code{mark-for-redisplay}, the additional actions mentioned above +are omitted but @var{window} will be nevertheless updated. @end defun +@cindex select window hook +@cindex running a hook when a windows gets selected +For historical reasons, Emacs does not run a separate hook whenever a +window gets selected. Applications and internal routines often +temporarily select a window to perform a few actions on it. They do +that either to simplify coding---because many functions by default +operate on the selected window when no @var{window} argument is +specified---or because some functions did not (and still do not) take a +window as argument and always operate(d) on the selected window instead. +Running a hook every time a window gets selected for a short time and +once more when the previously selected window gets restored is not +useful. + + However, when its @var{norecord} argument is @code{nil}, +@code{select-window} updates the buffer list and thus indirectly runs +the normal hook @code{buffer-list-update-hook} (@pxref{Buffer List}). +Consequently, that hook provides a reasonable way to run a function +whenever a window gets selected more ``permanently''. + + Since @code{buffer-list-update-hook} is also run by functions that are +not related to window management, it will usually make sense to save the +value of the selected window somewhere and compare it with the value of +@code{selected-window} while running that hook. Also, to avoid false +positives when using @code{buffer-list-update-hook} it is good practice +that every @code{select-window} call supposed to select a window only +temporarily, passes a non-@code{nil} @var{norecord} argument. If +possible, the macro @code{with-selected-window} (see below) should be +used in such cases. + @cindex most recently selected windows The sequence of calls to @code{select-window} with a non-@code{nil} @var{norecord} argument determines an ordering of windows by their @@ -1761,13 +1786,13 @@ the buffer list. @defmac with-selected-window window forms@dots{} This macro selects @var{window}, executes @var{forms} in sequence, then -restores the previously selected window and current buffer. The ordering -of recently selected windows and the buffer list remain unchanged unless -you deliberately change them within @var{forms}; for example, by calling -@code{select-window} with argument @var{norecord} @code{nil}. - -This macro does not change the order of recently selected windows or -the buffer list. +restores the previously selected window and current buffer. The +ordering of recently selected windows and the buffer list remain +unchanged unless you deliberately change them within @var{forms}; for +example, by calling @code{select-window} with argument @var{norecord} +@code{nil}. Hence, this macro is the preferred way to temporarily work +with @var{window} as the selected window without needlessly running +@code{buffer-list-update-hook}. @end defmac @defun frame-selected-window &optional frame @@ -4566,6 +4591,55 @@ point in the selected window, it's sufficient to write: @end defun +@node Mouse Window Auto-selection +@section Mouse Window Auto-selection +@cindex window auto-selection +@cindex auto-selection of window +The following option allows to automatically select the window under the +mouse pointer. This accomplishes a policy similar to that of window +managers that give focus to a frame (and thus trigger its subsequent +selection) whenever the mouse pointer enters its window-system window +(@pxref{Input Focus}). + +@defvar mouse-autoselect-window +If this variable is non-@code{nil}, Emacs will try to automatically +select the window under the mouse pointer. The following values are +meaningful: + +@table @asis +@item A positive number +This specifies a delay in seconds after which auto-selection triggers. +The window under the mouse pointer is selected after the mouse has +remained in it for the entire duration of the delay. + +@item A negative number +A negative number has a similar effect as a positive number, but selects +the window under the mouse pointer only after the mouse pointer has +remained in it for the entire duration of the absolute value of that +number and in addition has stopped moving. + +@item Other value +Any other non-@code{nil} value means to select a window instantaneously +as soon as the mouse pointer enters it. +@end table + +In either case the mouse pointer must enter the text area of a window in +order to trigger its selection. Dragging the scroll bar slider or the +mode line of a window conceptually should not cause its auto-selection. + +Mouse auto-selection selects the minibuffer window only if it is active, +and never deselects the active minibuffer window. +@end defvar + +Mouse auto-selection can be used to emulate a focus follows mouse policy +for child frames (@pxref{Child Frames}) which usually are not tracked by +the window manager. This requires to set the value of +@code{focus-follows-mouse} (@pxref{Input Focus}) to a non-@code{nil} +value. If the value of @code{focus-follows-mouse} is @code{auto-raise}, +entering a child frame with the mouse will raise it automatically above +all other child frames of that frame's parent frame. + + @node Window Configurations @section Window Configurations @cindex window configurations commit 4e77ff0d45b88cade7836c01344cd8d892adfde8 Author: Damien Cassou Date: Wed Apr 12 07:35:56 2017 +0200 Fix imenu--sort-by-position for non-pairs parameters (bug#26457) * lisp/imenu.el (imenu--sort-by-position): Fix to accept lists beyond pairs. * test/lisp/imenu-tests.el: Add 2 tests for `imenu--sort-by-position`. diff --git a/lisp/imenu.el b/lisp/imenu.el index 0f47a92734..c1fd4005ab 100644 --- a/lisp/imenu.el +++ b/lisp/imenu.el @@ -499,7 +499,12 @@ An item looks like (NAME . POSITION)." (string-lessp (car item1) (car item2))) (defun imenu--sort-by-position (item1 item2) - (< (cdr item1) (cdr item2))) + "Comparison function to sort items depending on their position. +Return non-nil if and only if ITEM1's position is lower than ITEM2's +position." + (if (listp (cdr item1)) + (< (cadr item1) (cadr item2)) + (< (cdr item1) (cdr item2)))) (defun imenu--relative-position (&optional reverse) "Support function to calculate relative position in buffer. diff --git a/test/lisp/imenu-tests.el b/test/lisp/imenu-tests.el index 480368fcbb..9309094713 100644 --- a/test/lisp/imenu-tests.el +++ b/test/lisp/imenu-tests.el @@ -83,6 +83,16 @@ function ABC_D() } " '("a" "b" "c" "ABC_D")) +(ert-deftest imenu--sort-by-position-pairs () + (should (imenu--sort-by-position '("a" . 2) '("a" . 3))) + (should-not (imenu--sort-by-position '("a" . 3) '("a" . 2)))) + +;; Regression test for bug#26457: 25.2; Cannot pass a function to +;; imenu-generic-expression +(ert-deftest imenu--sort-by-position-list () + (should (imenu--sort-by-position '("a" 2 nil) '("a" 3 nil))) + (should-not (imenu--sort-by-position '("a" 3 nil) '("a" 2 nil)))) + (provide 'imenu-tests) ;;; imenu-tests.el ends here