commit ff2f35fc478d0047fef4ae3e0b09f43c37961bec (HEAD, refs/remotes/origin/master) Author: Tassilo Horn Date: Fri Aug 21 09:38:01 2015 +0200 Add TeX defaults for prettify-symbol-mode * lisp/textmodes/tex-mode.el (tex--prettify-symbols-alist): Rename from tex-prettify-symbols-alist. (tex--prettify-symbols-compose-p): New function. (tex-common-initialization): Use them as prettify-symbols-alist and prettify-symbols-compose-predicate. diff --git a/lisp/textmodes/tex-mode.el b/lisp/textmodes/tex-mode.el index 5478386..8f68c71 100644 --- a/lisp/textmodes/tex-mode.el +++ b/lisp/textmodes/tex-mode.el @@ -1205,6 +1205,7 @@ Entering SliTeX mode runs the hook `text-mode-hook', then the hook (defvar tildify-space-string) (defvar tildify-foreach-region-function) +(defvar tex--prettify-symbols-alist) (defun tex-common-initialization () ;; Regexp isearch should accept newline and formfeed as whitespace. @@ -1246,7 +1247,7 @@ Entering SliTeX mode runs the hook `text-mode-hook', then the hook (setq-local facemenu-remove-face-function t) (setq-local font-lock-defaults '((tex-font-lock-keywords tex-font-lock-keywords-1 - tex-font-lock-keywords-2 tex-font-lock-keywords-3) + tex-font-lock-keywords-2 tex-font-lock-keywords-3) nil nil nil nil ;; Who ever uses that anyway ??? (font-lock-mark-block-function . mark-paragraph) @@ -1254,6 +1255,8 @@ Entering SliTeX mode runs the hook `text-mode-hook', then the hook . tex-font-lock-syntactic-face-function) (font-lock-unfontify-region-function . tex-font-lock-unfontify-region))) + (setq-local prettify-symbols-alist tex--prettify-symbols-alist) + (setq-local prettify-symbols-compose-predicate #'tex--prettify-symbols-compose-p) (setq-local syntax-propertize-function (syntax-propertize-rules latex-syntax-propertize-rules)) ;; TABs in verbatim environments don't do what you think. @@ -2945,7 +2948,7 @@ There might be text before point." ;;; Prettify Symbols Support -(defvar tex-prettify-symbols-alist +(defvar tex--prettify-symbols-alist '( ;; Lowercase Greek letters. ("\\alpha" . ?α) ("\\beta" . ?β) @@ -3056,6 +3059,8 @@ There might be text before point." ("\\centerdot" . ?·) ("\\checkmark" . ?✓) ("\\chi" . ?χ) + ("\\cdot" . ?⋅) + ("\\cdots" . ?⋯) ("\\circ" . ?∘) ("\\circeq" . ?≗) ("\\circlearrowleft" . ?↺) @@ -3398,6 +3403,17 @@ There might be text before point." ("\\textreferencemark" . ?※)) "A `prettify-symbols-alist' usable for (La)TeX modes.") +(defun tex--prettify-symbols-compose-p (start end _match) + (let* ((after-char (char-after end)) + (after-syntax (char-syntax after-char))) + (not (or + ;; Don't compose \alpha@foo. + (eq after-syntax ?_) + ;; The \alpha in \alpha2 may be composed but of course \alphax may not. + (and (eq after-syntax ?w) + (or (< after-char ?0) + (> after-char ?9))))))) + (run-hooks 'tex-mode-load-hook) (provide 'tex-mode) commit c88063faefdcda6016548fa64c002f4b79281ee3 Author: Tassilo Horn Date: Thu Aug 20 09:58:28 2015 +0200 Generalize prettify-symbols to arbitrary modes * lisp/progmodes/prog-mode.el (prettify-symbols-default-compose-p): New function. (prettify-symbols-compose-predicate): New variable. (prettify-symbols--compose-symbol): Use it. diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el index 994eaaf..b8cd9d9 100644 --- a/lisp/progmodes/prog-mode.el +++ b/lisp/progmodes/prog-mode.el @@ -133,26 +133,41 @@ Each element looks like (SYMBOL . CHARACTER), where the symbol matching SYMBOL (a string, not a regexp) will be shown as CHARACTER instead.") +(defun prettify-symbols-default-compose-p (start end _match) + "Return true iff the symbol MATCH should be composed. +The symbol starts at position START and ends at position END. +This is default `prettify-symbols-compose-predicate' which is +suitable for most programming languages such as C or Lisp." + ;; Check that the chars should really be composed into a symbol. + (let* ((syntaxes-beg (if (memq (char-syntax (char-after start)) '(?w ?_)) + '(?w ?_) '(?. ?\\))) + (syntaxes-end (if (memq (char-syntax (char-before end)) '(?w ?_)) + '(?w ?_) '(?. ?\\)))) + (not (or (memq (char-syntax (or (char-before start) ?\s)) syntaxes-beg) + (memq (char-syntax (or (char-after end) ?\s)) syntaxes-end) + (nth 8 (syntax-ppss)))))) + +(defvar-local prettify-symbols-compose-predicate + #'prettify-symbols-default-compose-p + "A predicate deciding if the currently matched symbol is to be composed. +The matched symbol is the car of one entry in `prettify-symbols-alist'. +The predicate receives the match's start and end position as well +as the match-string as arguments.") + (defun prettify-symbols--compose-symbol (alist) "Compose a sequence of characters into a symbol. Regexp match data 0 points to the chars." ;; Check that the chars should really be composed into a symbol. - (let* ((start (match-beginning 0)) - (end (match-end 0)) - (syntaxes-beg (if (memq (char-syntax (char-after start)) '(?w ?_)) - '(?w ?_) '(?. ?\\))) - (syntaxes-end (if (memq (char-syntax (char-before end)) '(?w ?_)) - '(?w ?_) '(?. ?\\))) - match) - (if (or (memq (char-syntax (or (char-before start) ?\s)) syntaxes-beg) - (memq (char-syntax (or (char-after end) ?\s)) syntaxes-end) - ;; syntax-ppss could modify the match data (bug#14595) - (progn (setq match (match-string 0)) (nth 8 (syntax-ppss)))) - ;; No composition for you. Let's actually remove any composition - ;; we may have added earlier and which is now incorrect. - (remove-text-properties start end '(composition)) - ;; That's a symbol alright, so add the composition. - (compose-region start end (cdr (assoc match alist))))) + (let ((start (match-beginning 0)) + (end (match-end 0)) + (match (match-string 0))) + (if (funcall prettify-symbols-compose-predicate start end match) + ;; That's a symbol alright, so add the composition. + (compose-region start end (cdr (assoc match alist))) + ;; No composition for you. Let's actually remove any + ;; composition we may have added earlier and which is now + ;; incorrect. + (remove-text-properties start end '(composition)))) ;; Return nil because we're not adding any face property. nil) commit 760701ebe1b2061619c91c72d41666d3bd42366f Author: Paul Eggert Date: Thu Aug 20 17:33:48 2015 -0700 Don't quote symbols 'like-this' in docstrings etc. * admin/unidata/uvs.el (uvs-insert-fields-as-bytes): * lisp/allout-widgets.el (allout-widgets-count-buttons-in-region): * lisp/allout.el (allout-add-resumptions, allout-mode): * lisp/calculator.el (calculator-operators): * lisp/cedet/data-debug.el (dd-propertize): * lisp/cedet/ede/proj-prog.el (ede-proj-target-makefile-program): * lisp/cedet/semantic/analyze/debug.el: (semantic-analyzer-debug-global-miss-text): * lisp/cedet/semantic/lex-spp.el: (semantic-lex-spp-replace-or-symbol-or-keyword): * lisp/cedet/semantic/symref.el: (semantic-symref-cleanup-recent-buffers-fcn): * lisp/cedet/semantic/tag.el (semantic-tag-class): * lisp/cedet/srecode/el.el (srecode-semantic-handle-:el-custom): * lisp/gnus/nnmairix.el (nnmairix-propagate-marks-upon-close): * lisp/gnus/pop3.el (pop3-authentication-scheme): * lisp/help-fns.el (describe-function-orig-buffer): * lisp/imenu.el (imenu--history-list): * lisp/mail/feedmail.el (feedmail-confirm-outgoing) (feedmail-display-full-frame, feedmail-deduce-bcc-where) (feedmail-queue-default-file-slug) (feedmail-queue-buffer-file-name): * lisp/net/mairix.el (mairix-searches-mode-map): * lisp/net/newst-backend.el (newsticker-retrieval-method) (newsticker-auto-mark-filter-list): * lisp/obsolete/vi.el (vi-mode): * lisp/progmodes/cc-engine.el (c-literal-type): * lisp/progmodes/cpp.el (cpp-face): * lisp/progmodes/ebrowse.el (ebrowse-electric-list-looper): * lisp/progmodes/elisp-mode.el (elisp--xref-make-xref): * lisp/progmodes/pascal.el (pascal-auto-lineup): * lisp/progmodes/prog-mode.el (prog-widen): * lisp/progmodes/verilog-mode.el (verilog-regexp-words) (verilog-auto-lineup, verilog-auto-reset-widths) (verilog-auto-arg-format, verilog-auto-inst-template-numbers): * lisp/textmodes/flyspell.el (flyspell-maybe-correct-transposition) (flyspell-maybe-correct-doubling): * lisp/textmodes/table.el (table-justify, table-justify-cell) (table-justify-row, table-justify-column, table-insert-sequence) (table--justify-cell-contents): * lisp/url/url-auth.el (url-get-authentication): * lisp/window.el (display-buffer-record-window): * lisp/xml.el (xml-parse-file, xml-parse-region): * src/gfilenotify.c (Fgfile_add_watch): Don't quote symbols with apostrophes in doc strings. Use asymmetric quotes instead. * lisp/cedet/semantic/complete.el (semantic-displayor-show-request): Likewise for symbol in diagnostic. * lisp/image.el (image-extension-data): * lisp/register.el (frame-configuration-to-register): * src/buffer.c (syms_of_buffer): Remove bogus apostrophes after symbols. * lisp/thumbs.el (thumbs-conversion-program): Quote Lisp string values using double-quotes, not apostrophes. diff --git a/admin/unidata/uvs.el b/admin/unidata/uvs.el index a6beac9..8d3ffe2 100644 --- a/admin/unidata/uvs.el +++ b/admin/unidata/uvs.el @@ -114,7 +114,7 @@ The most significant byte comes first." "Insert VALUES for FIELDS as a sequence of bytes to the current buffer. VALUES and FIELDS are lists of integers and field symbols, respectively. Byte length of each value is determined by the -'uvs-field-size' property of the corresponding field." +`uvs-field-size' property of the corresponding field." (while fields (let ((field (car fields)) (value (car values))) diff --git a/lisp/allout-widgets.el b/lisp/allout-widgets.el index c6dba89..578510d 100644 --- a/lisp/allout-widgets.el +++ b/lisp/allout-widgets.el @@ -2372,7 +2372,7 @@ The elements of LIST are not copied, just the list structure itself." (car list))) ;;;_ . allout-widgets-count-buttons-in-region (start end) (defun allout-widgets-count-buttons-in-region (start end) - "Debugging/diagnostic tool - count overlays with 'button' property in region." + "Debugging/diagnostic tool - count overlays with `button' property in region." (interactive "r") (setq start (or start (point-min)) end (or end (point-max))) diff --git a/lisp/allout.el b/lisp/allout.el index 025cb17..5c43f9b 100644 --- a/lisp/allout.el +++ b/lisp/allout.el @@ -1330,11 +1330,11 @@ cdr is the new value: '(some-var some-value)'. The pairs can actually be triples, where the third element qualifies the disposition of the setting, as described further below. -If the optional third element is the symbol 'extend, then the new value +If the optional third element is the symbol `extend', then the new value created by `cons'ing the second element of the pair onto the front of the existing value. -If the optional third element is the symbol 'append, then the new value is +If the optional third element is the symbol `append', then the new value is extended from the existing one by `append'ing a list containing the second element of the pair onto the end of the existing value. @@ -1838,7 +1838,7 @@ M-x outlineify-sticky Activate outline mode for current buffer, buffer with name derived from derived from that of current buffer -- \"*BUFFERNAME exposed*\". \\[allout-flatten-exposed-to-buffer] `allout-flatten-exposed-to-buffer' - Like above 'copy-exposed', but convert topic + Like above `copy-exposed', but convert topic prefixes to section.subsection... numeric format. \\[customize-variable] allout-auto-activation diff --git a/lisp/calculator.el b/lisp/calculator.el index 4027887..55229bc 100644 --- a/lisp/calculator.el +++ b/lisp/calculator.el @@ -311,7 +311,7 @@ user-defined operators, use `calculator-user-operators' instead.") 9 (highest) (optional, defaults to 1); It it possible have a unary prefix version of a binary operator if it -comes later in this list. If the list begins with the symbol 'nobind, +comes later in this list. If the list begins with the symbol `nobind', then no key binding will take place -- this is only useful for predefined keys. diff --git a/lisp/cedet/data-debug.el b/lisp/cedet/data-debug.el index 8a8af4e..300bd04 100644 --- a/lisp/cedet/data-debug.el +++ b/lisp/cedet/data-debug.el @@ -55,7 +55,7 @@ (defalias 'data-debug-overlay-p 'extentp) (if (not (fboundp 'propertize)) (defun dd-propertize (string &rest properties) - "Mimic 'propertize' in from Emacs 23." + "Mimic `propertize' in from Emacs 23." (add-text-properties 0 (length string) properties string) string ) diff --git a/lisp/cedet/ede/proj-prog.el b/lisp/cedet/ede/proj-prog.el index b1b26d4..a59317c 100644 --- a/lisp/cedet/ede/proj-prog.el +++ b/lisp/cedet/ede/proj-prog.el @@ -62,7 +62,7 @@ specified with ldlibs.") "Libraries, such as \"m\" or \"Xt\" which this program depends on. The linker flag \"-l\" is automatically prepended. Do not include a \"lib\" prefix, or a \".so\" suffix. -Use the 'ldflags' slot to specify where in-project libraries might be. +Use the `ldflags' slot to specify where in-project libraries might be. Note: Currently only used for Automake projects." ) diff --git a/lisp/cedet/semantic/analyze/debug.el b/lisp/cedet/semantic/analyze/debug.el index 9f9270f..d0ab7c82 100644 --- a/lisp/cedet/semantic/analyze/debug.el +++ b/lisp/cedet/semantic/analyze/debug.el @@ -512,7 +512,7 @@ Optional argument CLASSCONSTRAINT says to output to tags of that class." ) (defun semantic-analyzer-debug-global-miss-text (name-in) - "Use 'princ' to show text describing not finding symbol NAME-IN. + "Use `princ' to show text describing not finding symbol NAME-IN. NAME is the name of the unfound symbol." (let ((name (cond ((stringp name-in) name-in) diff --git a/lisp/cedet/semantic/complete.el b/lisp/cedet/semantic/complete.el index 1e12190..509f802 100644 --- a/lisp/cedet/semantic/complete.el +++ b/lisp/cedet/semantic/complete.el @@ -1665,7 +1665,7 @@ Display mechanism using tooltip for a list of possible completions.") (when (>= (oref obj typing-count) 5) (oset obj mode 'standard) (setq mode 'standard) - (message "Resetting inline-mode to 'standard'.")) + (message "Resetting inline-mode to ‘standard’.")) (when (and (> numcompl max-tags) (< (oref obj typing-count) 2)) ;; Discretely hint at completion availability. diff --git a/lisp/cedet/semantic/lex-spp.el b/lisp/cedet/semantic/lex-spp.el index 0aa2f95..761cc1a 100644 --- a/lisp/cedet/semantic/lex-spp.el +++ b/lisp/cedet/semantic/lex-spp.el @@ -919,7 +919,7 @@ STR occurs in the current buffer between BEG and END." )) (define-lex-regex-analyzer semantic-lex-spp-replace-or-symbol-or-keyword - "Like 'semantic-lex-symbol-or-keyword' plus preprocessor macro replacement." + "Like `semantic-lex-symbol-or-keyword' plus preprocessor macro replacement." "\\(\\sw\\|\\s_\\)+" (let ((str (match-string 0)) (beg (match-beginning 0)) diff --git a/lisp/cedet/semantic/symref.el b/lisp/cedet/semantic/symref.el index ca5dd7d..89e8b40 100644 --- a/lisp/cedet/semantic/symref.el +++ b/lisp/cedet/semantic/symref.el @@ -337,7 +337,7 @@ Use the `semantic-symref-hit-tags' method to get this list.") "List of buffers opened by `semantic-symref-result-get-tags'.") (defun semantic-symref-cleanup-recent-buffers-fcn () - "Hook function to be used in 'post-command-hook' to cleanup buffers. + "Hook function to be used in `post-command-hook' to cleanup buffers. Buffers collected during symref can result in some files being opened multiple times for one operation. This will keep buffers open until the next command is executed." diff --git a/lisp/cedet/semantic/tag.el b/lisp/cedet/semantic/tag.el index 545ca91..6c6616d 100644 --- a/lisp/cedet/semantic/tag.el +++ b/lisp/cedet/semantic/tag.el @@ -95,7 +95,7 @@ print statement." (defsubst semantic-tag-class (tag) "Return the class of TAG. -That is, the symbol 'variable, 'function, 'type, or other. +This is a symbol like `variable', `function', or `type'. There is no limit to the symbols that may represent the class of a tag. Each parser generates tags with classes defined by it. diff --git a/lisp/cedet/srecode/el.el b/lisp/cedet/srecode/el.el index 2bdf804..7e91a61 100644 --- a/lisp/cedet/srecode/el.el +++ b/lisp/cedet/srecode/el.el @@ -50,7 +50,7 @@ Adds the following: (defun srecode-semantic-handle-:el-custom (dict) "Add macros into the dictionary DICT based on the current Emacs Lisp file. Adds the following: - GROUP - The 'defgroup' name we guess you want for variables. + GROUP - The `defgroup' name we guess you want for variables. FACEGROUP - The `defgroup' name you might want for faces." (require 'semantic/db-find) (let ((groups (semanticdb-strip-find-results diff --git a/lisp/gnus/nnmairix.el b/lisp/gnus/nnmairix.el index 96b40e5..0a4dbff 100644 --- a/lisp/gnus/nnmairix.el +++ b/lisp/gnus/nnmairix.el @@ -311,7 +311,7 @@ The default chooses the largest window in the current frame." The default of this variable is t. If set to 'ask, the user will be asked if the flags should be propagated when the group is closed. If set to nil, the user will have to manually -call 'nnmairix-propagate-marks'." +call `nnmairix-propagate-marks'." :version "23.1" :type '(choice (const :tag "always" t) (const :tag "ask" ask) diff --git a/lisp/gnus/pop3.el b/lisp/gnus/pop3.el index 4d9dfda..696c6e4 100644 --- a/lisp/gnus/pop3.el +++ b/lisp/gnus/pop3.el @@ -82,7 +82,7 @@ (defcustom pop3-authentication-scheme 'pass "*POP3 authentication scheme. Defaults to `pass', for the standard USER/PASS authentication. The other -valid value is 'apop'." +valid value is `apop'." :type '(choice (const :tag "Normal user/password" pass) (const :tag "APOP" apop)) :version "22.1" ;; Oort Gnus diff --git a/lisp/help-fns.el b/lisp/help-fns.el index 71bcdb6..8ed9a47 100644 --- a/lisp/help-fns.el +++ b/lisp/help-fns.el @@ -44,7 +44,7 @@ The functions will receive the function name as argument.") ;; Functions (defvar describe-function-orig-buffer nil - "Buffer that was current when 'describe-function' was invoked. + "Buffer that was current when `describe-function' was invoked. Functions on 'help-fns-describe-function-functions' can use this to get buffer-local values.") diff --git a/lisp/image.el b/lisp/image.el index 1c268c4..99a65e3 100644 --- a/lisp/image.el +++ b/lisp/image.el @@ -357,7 +357,7 @@ Optional DATA-P non-nil means SOURCE is a string containing image data." (if (fboundp 'image-metadata) ; eg not --without-x (define-obsolete-function-alias 'image-extension-data - 'image-metadata' "24.1")) + 'image-metadata "24.1")) (define-obsolete-variable-alias 'image-library-alist diff --git a/lisp/imenu.el b/lisp/imenu.el index 3a856b8..158718b 100644 --- a/lisp/imenu.el +++ b/lisp/imenu.el @@ -476,7 +476,7 @@ element recalculates the buffer's index alist.") (defvar imenu--history-list nil ;; Making this buffer local caused it not to work! - "History list for 'jump-to-function-in-buffer'.") + "History list for `jump-to-function-in-buffer'.") ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;; ;;; diff --git a/lisp/mail/feedmail.el b/lisp/mail/feedmail.el index 7f27599..857cfcc 100644 --- a/lisp/mail/feedmail.el +++ b/lisp/mail/feedmail.el @@ -399,10 +399,10 @@ "If non-nil, give a y-or-n confirmation prompt before sending mail. This is done after the message is completely prepped, and you'll be looking at the top of the message in a buffer when you get the prompt. -If set to the symbol 'queued, give the confirmation prompt only while +If set to the symbol `queued', give the confirmation prompt only while running the queue (however, the prompt is always suppressed if you are processing the queue via `feedmail-run-the-queue-no-prompts'). If set -to the symbol 'immediate, give the confirmation prompt only when +to the symbol `immediate', give the confirmation prompt only when sending immediately. For any other non-nil value, prompt in both cases. You can give a timeout for the prompt; see variable `feedmail-confirm-outgoing-timeout'." @@ -418,9 +418,9 @@ cases. You can give a timeout for the prompt; see variable If nil, the prepped message will be shown, for confirmation or otherwise, in some window in the current frame without resizing anything. That may or may not display enough of the message to -distinguish it from others. If set to the symbol 'queued, take +distinguish it from others. If set to the symbol ‘queued’, take this action only when running the queue. If set to the symbol -'immediate, take this action only when sending immediately. For +‘immediate’, take this action only when sending immediately. For any other non-nil value, take the action in both cases. Even if you're not confirming the sending of immediate or queued messages, it can still be interesting to see a lot about them as they are @@ -471,9 +471,9 @@ Addresses for the message envelope are deduced by examining appropriate address headers in the message. Generally, they will show up in the list of deduced addresses in the order that the headers happen to appear (duplicate addresses are eliminated in any case). -This variable can be set to the symbol 'first, in which case the +This variable can be set to the symbol ‘first’, in which case the Bcc:/Resent-Bcc: addresses will appear at the beginning in the list; -or, it can be set to the symbol 'last, in which case they will appear +or, it can be set to the symbol ‘last’, in which case they will appear at the end of the list. Why should you care? Well, maybe you don't, and certainly the same @@ -484,7 +484,7 @@ addresses are not handled first, there can be substantial delays in seeing the message again. Some configurations of sendmail, for example, seem to try to deliver to each addressee at least once, immediately and serially, so slow SMTP conversations can add up to a delay. There -is an option for either 'first or 'last because you might have a +is an option for either ‘first’ or ‘last’ because you might have a delivery agent that processes the addresses backwards." :group 'feedmail-headers :type '(choice (const nil) @@ -1231,7 +1231,7 @@ If a string, it is used directly. If a function, it is called with no arguments from the buffer containing the raw text of the message. It must return a string (which may be empty). -If the symbol 'ask, you will be prompted for a string in the mini-buffer. +If the symbol `ask', you will be prompted for a string in the mini-buffer. Filename completion is available so that you can inspect what's already been used, but feedmail will do further manipulation on the string you return, so it's not expected to be a complete filename." @@ -1301,27 +1301,27 @@ the fact in the messages buffer." (defvar feedmail-queue-buffer-file-name nil - "If non-nil, has the value normally expected of 'buffer-file-name'. + "If non-nil, has the value normally expected of `buffer-file-name'. You are not intended to set this to something in your configuration. Rather, you might programmatically set it to something via a hook or function advice or whatever. You might like to do this if you are using a mail -composition program that eventually uses sendmail.el's 'mail-send' +composition program that eventually uses sendmail.el's `mail-send' function to process the message. If there is a filename associated -with the message buffer, 'mail-send' will ask you for confirmation. +with the message buffer, `mail-send' will ask you for confirmation. There's no trivial way to avoid it. It's unwise to just set the value -of 'buffer-file-name' to nil because that will defeat feedmail's file +of `buffer-file-name' to nil because that will defeat feedmail's file management features. Instead, arrange for this variable to be set to -the value of 'buffer-file-name' before setting that to nil. An easy way -to do that would be with defadvice on 'mail-send' \(undoing the +the value of `buffer-file-name' before setting that to nil. An easy way +to do that would be with defadvice on `mail-send' \(undoing the assignments in a later advice\). -feedmail will pretend that 'buffer-file-name', if nil, has the value -assigned of 'feedmail-queue-buffer-file-name' and carry out its normal +feedmail will pretend that `buffer-file-name', if nil, has the value +assigned of `feedmail-queue-buffer-file-name' and carry out its normal activities. feedmail does not restore the non-nil value of -'buffer-file-name'. For safe bookkeeping, the user should insure that +`buffer-file-name'. For safe bookkeeping, the user should insure that feedmail-queue-buffer-file-name is restored to nil. -Example 'defadvice' for mail-send: +Example `defadvice' for mail-send: (defadvice mail-send (before feedmail-mail-send-before-advice activate) (setq feedmail-queue-buffer-file-name buffer-file-name) diff --git a/lisp/net/mairix.el b/lisp/net/mairix.el index 087ae43..2d7d46b 100644 --- a/lisp/net/mairix.el +++ b/lisp/net/mairix.el @@ -762,7 +762,7 @@ VALUES may contain values for editable fields from current article." (define-key map [(d)] 'mairix-select-delete) (define-key map [(s)] 'mairix-select-save) map) - "'mairix-searches-mode' keymap.") + "`mairix-searches-mode' keymap.") (defvar mairix-searches-mode-font-lock-keywords '(("^\\([0-9]+\\)" diff --git a/lisp/net/newst-backend.el b/lisp/net/newst-backend.el index 5db04eb..435851c 100644 --- a/lisp/net/newst-backend.el +++ b/lisp/net/newst-backend.el @@ -235,7 +235,7 @@ which apply for this feed only, overriding the value of 'intern "Method for retrieving news from the web, either `intern' or `extern'. Default value `intern' uses Emacs' built-in asynchronous download -capabilities ('url-retrieve'). If set to `extern' the external +capabilities (`url-retrieve'). If set to `extern' the external program wget is used, see `newsticker-wget-name'." :type '(choice :tag "Method" (const :tag "Intern" intern) @@ -332,9 +332,9 @@ deleted at the next retrieval." This is an alist of the form (FEED-NAME PATTERN-LIST). I.e. each element consists of a FEED-NAME a PATTERN-LIST. Each element of the pattern-list has the form (AGE TITLE-OR-DESCRIPTION REGEXP). -AGE must be one of the symbols 'old or 'immortal. -TITLE-OR-DESCRIPTION must be on of the symbols 'title, -'description, or 'all. REGEXP is a regular expression, i.e. a +AGE must be one of the symbols `old' or `immortal'. +TITLE-OR-DESCRIPTION must be one of the symbols `title', +`description', or `all'. REGEXP is a regular expression, i.e., a string. This filter is checked after a new headline has been retrieved. diff --git a/lisp/obsolete/vi.el b/lisp/obsolete/vi.el index c5dc0ef..40d2e22 100644 --- a/lisp/obsolete/vi.el +++ b/lisp/obsolete/vi.el @@ -444,11 +444,11 @@ Major differences between this mode and real vi : * Extensions - Some standard (or modified) Emacs commands were integrated, such as incremental search, query replace, transpose objects, and keyboard macros. - - In command state, ^X links to the 'ctl-x-map', and ESC can be linked to + - In command state, ^X links to the `ctl-x-map', and ESC can be linked to esc-map or set undefined. These can give you the full power of Emacs. - See vi-com-map for those keys that are extensions to standard vi, e.g. `vi-name-last-change-or-macro', `vi-verify-spelling', `vi-locate-def', - `vi-mark-region', and 'vi-quote-words'. Some of them are quite handy. + `vi-mark-region', and `vi-quote-words'. Some of them are quite handy. - Use \\[vi-switch-mode] to switch among different modes quickly. Syntax table and abbrevs while in vi mode remain as they were in Emacs." diff --git a/lisp/progmodes/cc-engine.el b/lisp/progmodes/cc-engine.el index 520b7e5..a0f44a2 100644 --- a/lisp/progmodes/cc-engine.el +++ b/lisp/progmodes/cc-engine.el @@ -4616,7 +4616,7 @@ comment at the start of cc-engine.el for more info." (defun c-literal-type (range) "Convenience function that given the result of `c-literal-limits', returns nil or the type of literal that the range surrounds, one -of the symbols 'c, 'c++ or 'string. It's much faster than using +of the symbols `c', `c++' or `string'. It's much faster than using `c-in-literal' and is intended to be used when you need both the type of a literal and its limits. diff --git a/lisp/progmodes/cpp.el b/lisp/progmodes/cpp.el index 0a51add..685bb21 100644 --- a/lisp/progmodes/cpp.el +++ b/lisp/progmodes/cpp.el @@ -57,7 +57,7 @@ :group 'cpp) (define-widget 'cpp-face 'lazy - "Either a face or the special symbol 'invisible'." + "Either a face or the special symbol `invisible'." :type '(choice (const invisible) (face))) (defcustom cpp-known-face 'invisible diff --git a/lisp/progmodes/ebrowse.el b/lisp/progmodes/ebrowse.el index 8d7c8aa..7c785d4 100644 --- a/lisp/progmodes/ebrowse.el +++ b/lisp/progmodes/ebrowse.el @@ -2015,7 +2015,7 @@ COLLAPSE non-nil means collapse the branch." (defun ebrowse-electric-list-looper (state condition) "Prevent cursor from moving beyond the buffer end. Don't let it move into the title lines. -See 'Electric-command-loop' for a description of STATE and CONDITION." +See `Electric-command-loop' for a description of STATE and CONDITION." (cond ((and condition (not (memq (car condition) '(buffer-read-only end-of-buffer diff --git a/lisp/progmodes/elisp-mode.el b/lisp/progmodes/elisp-mode.el index 6ad803d..a96fca1 100644 --- a/lisp/progmodes/elisp-mode.el +++ b/lisp/progmodes/elisp-mode.el @@ -624,7 +624,7 @@ It can be quoted, or be inside a quoted form." (defun elisp--xref-make-xref (type symbol file &optional summary) "Return an xref for TYPE SYMBOL in FILE. -TYPE must be a type in 'find-function-regexp-alist' (use nil for +TYPE must be a type in `find-function-regexp-alist' (use nil for 'defun). If SUMMARY is non-nil, use it for the summary; otherwise build the summary from TYPE and SYMBOL." (xref-make (or summary diff --git a/lisp/progmodes/pascal.el b/lisp/progmodes/pascal.el index c05bda5..454367c 100644 --- a/lisp/progmodes/pascal.el +++ b/lisp/progmodes/pascal.el @@ -234,9 +234,9 @@ The name of the function or case is included between the braces." (defcustom pascal-auto-lineup '(all) "List of contexts where auto lineup of :'s or ='s should be done. -Elements can be of type: 'paramlist', 'declaration' or 'case', which will +Elements can be of type: `paramlist', `declaration' or `case', which will do auto lineup in parameterlist, declarations or case-statements -respectively. The word 'all' will do all lineups. '(case paramlist) for +respectively. The word `all' will do all lineups. '(case paramlist) for instance will do lineup in case-statements and parameterlist, while '(all) will do all lineups." :type '(set :extra-offset 8 diff --git a/lisp/progmodes/prog-mode.el b/lisp/progmodes/prog-mode.el index cb8aaad..994eaaf 100644 --- a/lisp/progmodes/prog-mode.el +++ b/lisp/progmodes/prog-mode.el @@ -116,7 +116,7 @@ This function can be used instead of `widen' in any function used by the indentation engine to make it respect the value `prog-indentation-context'. -This function (like 'widen') is useful inside a +This function (like `widen') is useful inside a `save-restriction' to make the indentation correctly work when narrowing is in effect." (let ((chunk (cadr prog-indentation-context))) diff --git a/lisp/progmodes/verilog-mode.el b/lisp/progmodes/verilog-mode.el index 3ce185f..3244805 100644 --- a/lisp/progmodes/verilog-mode.el +++ b/lisp/progmodes/verilog-mode.el @@ -346,10 +346,10 @@ wherever possible, since it is slow." (eval-when-compile (defun verilog-regexp-words (a) - "Call 'regexp-opt' with word delimiters for the words A." + "Call `regexp-opt' with word delimiters for the words A." (concat "\\<" (verilog-regexp-opt a t) "\\>"))) (defun verilog-regexp-words (a) - "Call 'regexp-opt' with word delimiters for the words A." + "Call `regexp-opt' with word delimiters for the words A." ;; The FAQ references this function, so user LISP sometimes calls it (concat "\\<" (verilog-regexp-opt a t) "\\>")) @@ -541,9 +541,9 @@ entry \"Fontify Buffer\"). XEmacs: turn off and on font locking." (defcustom verilog-auto-lineup 'declarations "Type of statements to lineup across multiple lines. -If 'all' is selected, then all line ups described below are done. +If `all' is selected, then all line ups described below are done. -If 'declarations', then just declarations are lined up with any +If `declarations', then just declarations are lined up with any preceding declarations, taking into account widths and the like, so or example the code: reg [31:0] a; @@ -552,7 +552,7 @@ would become reg [31:0] a; reg b; -If 'assignment', then assignments are lined up with any preceding +If `assignment', then assignments are lined up with any preceding assignments, so for example the code a_long_variable <= b + c; d = e + f; @@ -1054,7 +1054,7 @@ the MSB or LSB of a signal inside an AUTORESET. If nil, AUTORESET uses \"0\" as the constant. -If 'unbased', AUTORESET used the unbased unsized literal \"'0\" +If `unbased', AUTORESET used the unbased unsized literal \"'0\" as the constant. This setting is strongly recommended for SystemVerilog designs." :type 'boolean @@ -1070,10 +1070,10 @@ SystemVerilog designs." (defcustom verilog-auto-arg-format 'packed "Formatting to use for AUTOARG signal names. -If 'packed', then as many inputs and outputs that fit within +If `packed', then as many inputs and outputs that fit within `fill-column' will be put onto one line. -If 'single', then a single input or output will be put onto each +If `single', then a single input or output will be put onto each line." :version "25.1" :type '(radio (const :tag "Line up Assignments and Declarations" packed) @@ -1172,7 +1172,7 @@ was used for that port declaration. This setting is suggested only for debugging use, as regular use may cause a large numbers of merge conflicts. -If 'lhs', the comment will show the left hand side of the +If `lhs', the comment will show the left hand side of the AUTO_TEMPLATE rule that is matched. This is less precise than numbering (t) when multiple rules have the same pin name, but won't merge conflict." diff --git a/lisp/register.el b/lisp/register.el index 7afbc06..110c36f 100644 --- a/lisp/register.el +++ b/lisp/register.el @@ -220,7 +220,7 @@ Interactively, reads the register using `register-read-with-preview'." (set-advertised-calling-convention 'frame-configuration-to-register '(register) "24.4") -(make-obsolete 'frame-configuration-to-register 'frameset-to-register' "24.4") +(make-obsolete 'frame-configuration-to-register 'frameset-to-register "24.4") (defalias 'register-to-point 'jump-to-register) (defun jump-to-register (register &optional delete) diff --git a/lisp/textmodes/flyspell.el b/lisp/textmodes/flyspell.el index 64aa3de1..14f8744 100644 --- a/lisp/textmodes/flyspell.el +++ b/lisp/textmodes/flyspell.el @@ -2326,7 +2326,7 @@ If the text between BEG and END is equal to a correction suggested by Ispell, after transposing two adjacent characters, correct the text, and return t. -The third arg POSS is either the symbol 'doublon' or a list of +The third arg POSS is either the symbol `doublon' or a list of possible corrections as returned by `ispell-parse-output'. This function is meant to be added to `flyspell-incorrect-hook'." @@ -2356,7 +2356,7 @@ If the text between BEG and END is equal to a correction suggested by Ispell, after removing a pair of doubled characters, correct the text, and return t. -The third arg POSS is either the symbol 'doublon' or a list of +The third arg POSS is either the symbol `doublon' or a list of possible corrections as returned by `ispell-parse-output'. This function is meant to be added to `flyspell-incorrect-hook'." diff --git a/lisp/textmodes/table.el b/lisp/textmodes/table.el index fa9f0fa..93b31d5 100644 --- a/lisp/textmodes/table.el +++ b/lisp/textmodes/table.el @@ -2806,8 +2806,8 @@ ORIENTATION is a symbol either horizontally or vertically." ;;;###autoload (defun table-justify (what justify) "Justify contents of a cell, a row of cells or a column of cells. -WHAT is a symbol 'cell, 'row or 'column. JUSTIFY is a symbol 'left, -'center, 'right, 'top, 'middle, 'bottom or 'none." +WHAT is a symbol ‘cell’, ‘row’ or ‘column’. JUSTIFY is a symbol +‘left’, ‘center’, ‘right’, ‘top’, ‘middle’, ‘bottom’ or ‘none’." (interactive (list (let* ((_ (barf-if-buffer-read-only)) (completion-ignore-case t) @@ -2822,8 +2822,8 @@ WHAT is a symbol 'cell, 'row or 'column. JUSTIFY is a symbol 'left, ;;;###autoload (defun table-justify-cell (justify &optional paragraph) "Justify cell contents. -JUSTIFY is a symbol 'left, 'center or 'right for horizontal, or 'top, -'middle, 'bottom or 'none for vertical. When optional PARAGRAPH is +JUSTIFY is a symbol ‘left’, ‘center’ or ‘right’ for horizontal, or ‘top’, +‘middle’, ‘bottom’ or ‘none’ for vertical. When optional PARAGRAPH is non-nil the justify operation is limited to the current paragraph, otherwise the entire cell contents is justified." (interactive @@ -2835,8 +2835,8 @@ otherwise the entire cell contents is justified." ;;;###autoload (defun table-justify-row (justify) "Justify cells of a row. -JUSTIFY is a symbol 'left, 'center or 'right for horizontal, or top, -'middle, 'bottom or 'none for vertical." +JUSTIFY is a symbol ‘left’, ‘center’ or ‘right’ for horizontal, +or ‘top’, ‘middle’, ‘bottom’ or ‘none’ for vertical." (interactive (list (table--query-justification))) (let((cell-list (table--horizontal-cell-list nil nil 'top))) @@ -2852,8 +2852,8 @@ JUSTIFY is a symbol 'left, 'center or 'right for horizontal, or top, ;;;###autoload (defun table-justify-column (justify) "Justify cells of a column. -JUSTIFY is a symbol 'left, 'center or 'right for horizontal, or top, -'middle, 'bottom or 'none for vertical." +JUSTIFY is a symbol ‘left’, ‘center’ or ‘right’ for horizontal, +or ‘top’, ‘middle’, ‘bottom’ or ‘none’ for vertical." (interactive (list (table--query-justification))) (let((cell-list (table--vertical-cell-list nil nil 'left))) @@ -3341,8 +3341,8 @@ INTERVAL is the number of cells to travel between sequence element insertion which is normally 1. When zero or less is given for INTERVAL it is interpreted as number of cells per row so that sequence is placed straight down vertically as long as the table's cell -structure is uniform. JUSTIFY is one of the symbol 'left, 'center or -'right, that specifies justification of the inserted string. +structure is uniform. JUSTIFY is a symbol ‘left’, ‘center’ or +‘right’ that specifies justification of the inserted string. Example: @@ -4461,8 +4461,8 @@ looking at the appearance of the CELL contents." (defun table--justify-cell-contents (justify &optional paragraph) "Justify the current cell contents. -JUSTIFY is a symbol 'left, 'center or 'right for horizontal, or 'top, -'middle, 'bottom or 'none for vertical. When PARAGRAPH is non-nil the +JUSTIFY is a symbol ‘left’, ‘center’ or ‘right’ for horizontal, or ‘top’, +‘middle’, ‘bottom’ or ‘none’ for vertical. When PARAGRAPH is non-nil the justify operation is limited to the current paragraph." (table-with-cache-buffer (let ((beg (point-min)) diff --git a/lisp/thumbs.el b/lisp/thumbs.el index d8bb8cb..409ba7c 100644 --- a/lisp/thumbs.el +++ b/lisp/thumbs.el @@ -102,7 +102,7 @@ When it reaches that size (in bytes), a warning is sent." (or (executable-find "convert") "/usr/X11R6/bin/convert")) "Name of conversion program for thumbnails generation. -It must be 'convert'." +It must be \"convert\"." :type 'string :group 'thumbs) diff --git a/lisp/url/url-auth.el b/lisp/url/url-auth.el index 58bf45b..64f56f0 100644 --- a/lisp/url/url-auth.el +++ b/lisp/url/url-auth.el @@ -262,12 +262,12 @@ URL is the url you are requesting authorization to. This can be either a string representing the URL, or the parsed representation returned by `url-generic-parse-url' REALM is the realm at a specific site we are looking for. This should be a - string specifying the exact realm, or nil or the symbol 'any' to + string specifying the exact realm, or nil or the symbol `any' to specify that the filename portion of the URL should be used as the realm TYPE is the type of authentication to be returned. This is either a string - representing the type (basic, digest, etc), or nil or the symbol 'any' - to specify that any authentication is acceptable. If requesting 'any' + representing the type (basic, digest, etc), or nil or the symbol `any' + to specify that any authentication is acceptable. If requesting `any' the strongest matching authentication will be returned. If this is wrong, it's no big deal, the error from the server will specify exactly what type of auth to use diff --git a/lisp/window.el b/lisp/window.el index ebe7054..c783b0d 100644 --- a/lisp/window.el +++ b/lisp/window.el @@ -5596,18 +5596,18 @@ windows can get as small as `window-safe-min-height' and (defun display-buffer-record-window (type window buffer) "Record information for window used by `display-buffer'. TYPE specifies the type of the calling operation and must be one -of the symbols 'reuse (when WINDOW existed already and was -reused for displaying BUFFER), 'window (when WINDOW was created -on an already existing frame), or 'frame (when WINDOW was +of the symbols `reuse' (when WINDOW existed already and was +reused for displaying BUFFER), `window' (when WINDOW was created +on an already existing frame), or `frame' (when WINDOW was created on a new frame). WINDOW is the window used for or created by the `display-buffer' routines. BUFFER is the buffer that shall be displayed. This function installs or updates the quit-restore parameter of WINDOW. The quit-restore parameter is a list of four elements: -The first element is one of the symbols 'window, 'frame, 'same or -'other. The second element is either one of the symbols 'window -or 'frame or a list whose elements are the buffer previously +The first element is one of the symbols `window', `frame', `same' or +`other'. The second element is either one of the symbols `window' +or `frame' or a list whose elements are the buffer previously shown in the window, that buffer's window start and window point, and the window's height. The third element is the window selected at the time the parameter was created. The fourth diff --git a/lisp/xml.el b/lisp/xml.el index b3dce41..f5a9a3f 100644 --- a/lisp/xml.el +++ b/lisp/xml.el @@ -326,8 +326,8 @@ URIs, and expanded names will be returned as a cons If PARSE-NS is an alist, it will be used as the mapping from namespace to URIs instead. -If it is the symbol 'symbol-qnames, expanded names will be -returned as a plain symbol 'namespace:foo instead of a cons. +If it is the symbol `symbol-qnames', expanded names will be +returned as a plain symbol `namespace:foo' instead of a cons. Both features can be combined by providing a cons cell @@ -356,8 +356,8 @@ URIs, and expanded names will be returned as a cons If PARSE-NS is an alist, it will be used as the mapping from namespace to URIs instead. -If it is the symbol 'symbol-qnames, expanded names will be -returned as a plain symbol 'namespace:foo instead of a cons. +If it is the symbol `symbol-qnames', expanded names will be +returned as a plain symbol `namespace:foo' instead of a cons. Both features can be combined by providing a cons cell diff --git a/src/buffer.c b/src/buffer.c index bd7c82c..fb1502a 100644 --- a/src/buffer.c +++ b/src/buffer.c @@ -5540,12 +5540,12 @@ This is the same as (default-value 'indicate-buffer-boundaries). */); DEFVAR_BUFFER_DEFAULTS ("default-fringe-indicator-alist", fringe_indicator_alist, doc: /* Default value of `fringe-indicator-alist' for buffers that don't override it. -This is the same as (default-value 'fringe-indicator-alist'). */); +This is the same as (default-value 'fringe-indicator-alist). */); DEFVAR_BUFFER_DEFAULTS ("default-fringe-cursor-alist", fringe_cursor_alist, doc: /* Default value of `fringe-cursor-alist' for buffers that don't override it. -This is the same as (default-value 'fringe-cursor-alist'). */); +This is the same as (default-value 'fringe-cursor-alist). */); DEFVAR_BUFFER_DEFAULTS ("default-scroll-up-aggressively", scroll_up_aggressively, diff --git a/src/gfilenotify.c b/src/gfilenotify.c index 08713a8..5488fa3 100644 --- a/src/gfilenotify.c +++ b/src/gfilenotify.c @@ -119,9 +119,9 @@ watched for some reason, this function signals a `file-notify-error' error. FLAGS is a list of conditions to set what will be watched for. It can include the following symbols: - 'watch-mounts' -- watch for mount events - 'send-moved' -- pair 'deleted' and 'created' events caused by file - renames and send a single 'renamed' event instead + `watch-mounts' -- watch for mount events + `send-moved' -- pair `deleted' and `created' events caused by file + renames and send a single `renamed' event instead When any event happens, Emacs will call the CALLBACK function passing it a single argument EVENT, which is of the form @@ -132,18 +132,18 @@ DESCRIPTOR is the same object as the one returned by this function. ACTION is the description of the event. It could be any one of the following: - 'changed' -- FILE has changed - 'changes-done-hint' -- a hint that this was probably the last change + `changed' -- FILE has changed + `changes-done-hint' -- a hint that this was probably the last change in a set of changes - 'deleted' -- FILE was deleted - 'created' -- FILE was created - 'attribute-changed' -- a FILE attribute was changed - 'pre-unmount' -- the FILE location will soon be unmounted - 'unmounted' -- the FILE location was unmounted - 'moved' -- FILE was moved to FILE1 + `deleted' -- FILE was deleted + `created' -- FILE was created + `attribute-changed' -- a FILE attribute was changed + `pre-unmount' -- the FILE location will soon be unmounted + `unmounted' -- the FILE location was unmounted + `moved' -- FILE was moved to FILE1 FILE is the name of the file whose event is being reported. FILE1 -will be reported only in case of the 'moved' event. */) +will be reported only in case of the `moved' event. */) (Lisp_Object file, Lisp_Object flags, Lisp_Object callback) { Lisp_Object watch_object; commit daf390b5e927ef87d6d3ccad793cc3fb389acd30 Author: Martin Rudalics Date: Thu Aug 20 18:30:07 2015 +0200 ; * etc/NEWS: Mention frame geometry related changes and additions. diff --git a/etc/NEWS b/etc/NEWS index 6058f22..3a654c8 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -1123,6 +1123,29 @@ Horizontal scroll bars are turned off by default. `scroll-bar-height'. +++ +** New functions `x-frame-geometry' and `frame-edges' give access to a +frame's geometry. + ++++ +** New functions `x-mouse-absolute-pixel-position' and +`x-set-mouse-absolute-pixel-position' get/set screen coordinates of the +mouse cursor. + ++++ +** The function `window-edges' now accepts three additional arguments to +retrieve body, absolute and pixel edges of the window. + ++++ +** The functions `window-inside-edges', `window-inside-pixel-edges' and +`window-inside-absolute-pixel-edges' have been renamed to respectively +`window-body-edges', `window-body-pixel-edges' and +`window-absolute-body-pixel-edges'. The old names are kept as aliases. + ++++ +** New function `window-absolute-pixel-position' to get the screen +coordinates of a visible buffer position. + ++++ ** The height of a frame's menu and tool bar are no longer counted in the frame's text height. This means that the text height stands only for the height of the frame's root window plus that of the echo area (if commit e68d43eb8734b4ec466c489b43b26fe732e02dfd Author: Martin Rudalics Date: Thu Aug 20 18:09:24 2015 +0200 Describe frame geometry and related functions in Elisp manual * doc/lispref/display.texi (Size of Displayed Text, Line Height) (Showing Images): Update references. * doc/lispref/elisp.texi (Top): Update node listing. * doc/lispref/frames.texi (Frame Geometry): New node. Move `Size and Position' section here. (Size Parameters): Update references. (Mouse Position): Update references and nomenclature. Describe new functions `x-mouse-absolute-pixel-position' and `x-set-mouse-absolute-pixel-position'. * doc/lispref/windows.texi (Window Sizes): Update references. (Resizing Windows): Update references. Move description of `fit-frame-to-buffer' here. (Coordinates and Windows): Update nomenclature and references. Describe new arguments of `window-edges'. Comment out descriptions of `window-left-column', `window-top-line', `window-pixel-left' and `window-pixel-top'. Describe `window-absolute-pixel-position'. diff --git a/doc/lispref/display.texi b/doc/lispref/display.texi index 9e9f8e3..ae59bbb 100644 --- a/doc/lispref/display.texi +++ b/doc/lispref/display.texi @@ -1897,9 +1897,9 @@ to or less than the display width of @var{ellipsis}. If The following function returns the size in pixels of text as if it were displayed in a given window. This function is used by -@code{fit-window-to-buffer} (@pxref{Resizing Windows}) and -@code{fit-frame-to-buffer} (@pxref{Size and Position}) to make a window -exactly as large as the text it contains. +@code{fit-window-to-buffer} and @code{fit-frame-to-buffer} +(@pxref{Resizing Windows}) to make a window exactly as large as the text +it contains. @defun window-text-pixel-size &optional window from to x-limit y-limit mode-and-header-line This function returns the size of the text of @var{window}'s buffer in @@ -1952,12 +1952,12 @@ height of both, if present, in the return value. contents of the line, plus optional additional vertical line spacing above or below the display line. - The height of the line contents is the maximum height of any -character or image on that display line, including the final newline -if there is one. (A display line that is continued doesn't include a -final newline.) That is the default line height, if you do nothing to -specify a greater height. (In the most common case, this equals the -height of the default frame font.) + The height of the line contents is the maximum height of any character +or image on that display line, including the final newline if there is +one. (A display line that is continued doesn't include a final +newline.) That is the default line height, if you do nothing to specify +a greater height. (In the most common case, this equals the height of +the corresponding frame's default font, see @ref{Frame Font}.) There are several ways to explicitly specify a larger line height, either by specifying an absolute height for the display line, or by @@ -5406,12 +5406,11 @@ This removes only images that were put into @var{buffer} the way @cindex size of image This function returns the size of an image as a pair @w{@code{(@var{width} . @var{height})}}. @var{spec} is an image -specification. @var{pixels} non-@code{nil} means return sizes -measured in pixels, otherwise return sizes measured in canonical -character units (fractions of the width/height of the frame's default -font). @var{frame} is the frame on which the image will be displayed. -@var{frame} null or omitted means use the selected frame (@pxref{Input -Focus}). +specification. @var{pixels} non-@code{nil} means return sizes measured +in pixels, otherwise return sizes measured in the default character size +of @var{frame} (@pxref{Frame Font}). @var{frame} is the frame on which +the image will be displayed. @var{frame} null or omitted means use the +selected frame (@pxref{Input Focus}). @end defun @defvar max-image-size diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index a32c69c..9044fba 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -1041,6 +1041,7 @@ Frames * Creating Frames:: Creating additional frames. * Multiple Terminals:: Displaying on several different devices. +* Frame Geometry:: Geometric properties of frames. * Frame Parameters:: Controlling frame size, position, font, etc. * Terminal Parameters:: Parameters common for all frames on terminal. * Frame Titles:: Automatic updating of frame titles. @@ -1064,12 +1065,18 @@ Frames * Resources:: Getting resource values from the server. * Display Feature Testing:: Determining the features of a terminal. +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. +* Implied Frame Resizing:: Implied resizing of frames and how to prevent it. + Frame Parameters * Parameter Access:: How to change a frame's parameters. * Initial Parameters:: Specifying frame parameters when you make a frame. * Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. * Geometry:: Parsing geometry specifications. Window Frame Parameters diff --git a/doc/lispref/frames.texi b/doc/lispref/frames.texi index 79b5172..28e6fbd 100644 --- a/doc/lispref/frames.texi +++ b/doc/lispref/frames.texi @@ -80,6 +80,7 @@ for @code{framep} above. @menu * Creating Frames:: Creating additional frames. * Multiple Terminals:: Displaying on several different devices. +* Frame Geometry:: Geometric properties of frames. * Frame Parameters:: Controlling frame size, position, font, etc. * Terminal Parameters:: Parameters common for all frames on terminal. * Frame Titles:: Automatic updating of frame titles. @@ -416,6 +417,545 @@ This function returns the attributes of the physical monitor dominating (see above) @var{frame}, which defaults to the selected frame. @end defun + +@node Frame Geometry +@section Frame Geometry +@cindex frame geometry +@cindex frame position +@cindex position of frame +@cindex frame size +@cindex size of frame + +The geometry of a frame depends on the toolkit that was used to build +this instance of Emacs and the terminal that displays the frame. This +chapter describes these dependencies and some of the functions to deal +with them. Note that the @var{frame} argument of all of these functions +has to specify a live frame (@pxref{Deleting Frames}). If omitted or +@code{nil}, it specifies the selected frame (@pxref{Input Focus}). + +@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. +* Implied Frame Resizing:: Implied resizing of frames and how to prevent it. +@end menu + + +@node Frame Layout +@subsection Frame Layout +@cindex frame layout +@cindex layout of frame + +The drawing below sketches the layout of a frame on a graphical +terminal: +@smallexample +@group + + <------------ Outer Frame Width -----------> + ___________________________________________ + ^(0) ___________ External Border __________ | + | | |_____________ Title Bar ______________| | + | | (1)_____________ Menu Bar ______________| | ^ + | | (2)_____________ Tool Bar ______________| | ^ + | | (3) _________ Internal Border ________ | | ^ + | | | | ^ | | | | + | | | | | | | | | +Outer | | | Inner | | | Native +Frame | | | Frame | | | Frame +Height | | | Height | | | Height + | | | | | | | | | + | | | |<--+--- Inner Frame Width ------->| | | | + | | | | | | | | | + | | | |___v______________________________| | | | + | | |___________ Internal Border __________| | v + v |______________ External 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: + +@table @samp +@item Outer Frame +@cindex outer frame +@cindex outer edges +@cindex outer width +@cindex outer height +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. + +@cindex outer position +The upper left corner of the outer frame (indicated by ``(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}). + +@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. + +@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. + +@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, +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}). + +@item Tool Bar +@cindex internal tool bar +@cindex external tool bar +Like the menu bar, the tool bar (@pxref{Tool Bar}) can be either +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. + +@item Native Frame +@cindex native frame +@cindex native edges +@cindex native width +@cindex native height +@cindex display area +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. + +@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: + +@itemize @w +@item (1) non-toolkit and terminal frames + +@item (2) Lucid, Motif and Windows frames + +@item (3) GTK+ and NS frames +@end itemize + +Accordingly, the native height of a frame includes 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 +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}). + +@item Internal Border +The internal border (@pxref{Layout Parameters}) is a border drawn by +Emacs around the inner frame (see below). + +@item Inner Frame +@cindex inner frame +@cindex inner edges +@cindex inner width +@cindex inner height +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. + +@cindex non-minibuffer frame +@cindex minibuffer-only frame +As a rule, the inner frame is subdivided into the frame's root window +(@pxref{Windows and Frames}) and the frame's minibuffer window +(@pxref{Minibuffer Windows}). There are two notable exceptions to this +rule: A @dfn{non-minibuffer frame} contains a root window only and does +not contain a minibuffer window. A @dfn{minibuffer-only frame} contains +only a minibuffer window which also serves as that frame's root window. +See @ref{Initial Parameters} for how to create such frame +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}. +@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. + + For a frame on a graphical terminal the following function returns the +sizes of the areas described above: + +@defun x-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. + +@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. + +@item outer-size +A cons of the outer width and height of @var{frame}. + +@item external-border-size +A cons of the horizontal and vertical width of @var{frame}'s external +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 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 +zero, the frame has no title bar. If only the width is zero, Emacs was +not able to retrieve the width information. + +@item menu-bar-external +If non-@code{nil}, this means the menu bar is external (not part of the +native frame of @var{frame}). + +@item menu-bar-size +A cons of the width and height of the menu bar of @var{frame}. + +@item tool-bar-external +If non-@code{nil}, this means the tool bar is external (not part of the +native frame of @var{frame}). + +@item tool-bar-position +This tells on which side the tool bar on @var{frame} is and can be one +of @code{left}, @code{top}, @code{right} or @code{bottom}. The only +toolkit that currently supports a value other than @code{top} is GTK+. + +@item tool-bar-size +A cons of the width and height of the tool bar of @var{frame}. + +@item internal-border-width +The width of the internal border of @var{frame}. +@end table +@end defun + +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} +@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. + +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. + +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. +@end defun + + +@node Frame Font +@subsection Frame Font +@cindex default font +@cindex default character size +@cindex default character width +@cindex default width of character +@cindex default character height +@cindex default height of character +Each frame has a @dfn{default font} which specifies the default +character size for that frame. This size is meant when retrieving or +changing the size of a frame in terms of ``columns'' or ``lines'' +(@pxref{Size Parameters}). It is also used when resizing (@pxref{Window +Sizes}) or splitting (@pxref{Splitting Windows}) windows. + +@cindex line height +@cindex column width +The term @dfn{line height} is sometimes used instead of ``default +character height''. Similarly, the term @dfn{column width} is used as +shorthand for ``default character width''. + +@defun frame-char-height &optional frame +@defunx frame-char-width &optional frame +These functions return the default height and width of a character in +@var{frame}, measured in pixels. Together, these values establish the +size of the default font on @var{frame}. The values depend on the +choice of font for @var{frame}, see @ref{Font and Color Parameters}. +@end defun + +The default font can be also set directly with the following function: + +@deffn Command set-frame-font font &optional keep-size frames +This sets the default font to @var{font}. When called interactively, it +prompts for the name of a font, and uses that font on the selected +frame. When called from Lisp, @var{font} should be a font name (a +string), a font object, font entity, or a font spec. + +If the optional argument @var{keep-size} is @code{nil}, this keeps the +number of frame lines and columns fixed. (If non-@code{nil}, the option +@code{frame-inhibit-implied-resize} described in the next section will +override this.) If @var{keep-size} is non-@code{nil} (or with a prefix +argument), it tries to keep the size of the display area of the current +frame fixed by adjusting the number of lines and columns. + +If the optional argument @var{frames} is @code{nil}, this applies the +font to the selected frame only. If @var{frames} is non-@code{nil}, it +should be a list of frames to act upon, or @code{t} meaning all existing +graphical frames. +@end deffn + + +@node Size and Position +@subsection Size and Position +@cindex frame size +@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. + +@defun frame-position &optional Lisp_Object &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. +@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. + +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. + +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 + +@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 +@defunx frame-width &optional frame +These functions return the height and width of the text area of +@var{frame}, measured in units of the default font height and width of +@var{frame} (@pxref{Frame Font}). These functions are plain shorthands +for writing @code{(frame-parameter frame 'height)} and +@code{(frame-parameter frame 'width)}. + +If the text area of @var{frame} measured in pixels is not a multiple of +its default font size, the values returned by these functions are +rounded down to the number of characters of the default font that fully +fit into the text area. +@end defun + +@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. + +Setting this variable usually causes the next resize operation to pass +the corresponding size hints to the window manager. This means that +this variable should be set only in a user's initial file; applications +should never bind it temporarily. + +The precise meaning of a value of @code{nil} for this option depends on +the toolkit used. Dragging the external border with the mouse is done +character-wise provided the window manager is willing to process the +corresponding size hints. Calling @code{set-frame-size} (see below) +with arguments that do not specify the frame size as an integer multiple +of its character size, however, may: be ignored, cause a rounding +(GTK+), or be accepted (Lucid, Motif, MS-Windows). + +With some window managers you may have to set this to non-@code{nil} in +order to make a frame appear truly ``maximized'' or ``fullscreen''. +@end defopt + +@defun set-frame-size frame width height pixelwise +This function sets the size of the text area of @var{frame}, measured in +terms of the canonical height and width of a character on @var{frame} +(@pxref{Frame Font}). + +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 +to a multiple of its character size. +@end defun + +@defun set-frame-height frame height &optional pretend pixelwise +This function resizes the text area of @var{frame} to a height of +@var{height} lines. The sizes of existing windows in @var{frame} are +altered proportionally to fit. + +If @var{pretend} is non-@code{nil}, then Emacs displays @var{height} +lines of output in @var{frame}, but does not change its value for the +actual height of the frame. This is only useful on text terminals. +Using a smaller height than the terminal actually implements may be +useful to reproduce behavior observed on a smaller screen, or if the +terminal malfunctions when using its whole screen. Setting the frame +height ``for real'' does not always work, because knowing the correct +actual size may be necessary for correct cursor positioning on +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. +@end defun + +@defun set-frame-width frame width &optional pretend pixelwise +This function sets the width of the text area of @var{frame}, measured +in characters. The argument @var{pretend} has the same meaning as in +@code{set-frame-height}. + +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. +@end defun + +None of these three functions will make a frame smaller than needed to +display all of its windows together with their scroll bars, fringes, +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. + + +@node Implied Frame Resizing +@subsection Implied Frame Resizing +@cindex implied frame resizing +@cindex implied resizing of frame + +By default, Emacs tries to keep the number of lines and columns of a +frame's text area unaltered when, for example, adding or removing the +menu bar, changing the default font or setting the width of the frame's +scroll bars. This means, however, that in such case Emacs must ask the +window manager to resize the outer frame in order to accommodate the +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 +example, when the frame is maximized or made fullscreen (where it's +turned off by default). In other cases you can disable implied resizing +with the following option: + +@defopt frame-inhibit-implied-resize +If this option is @code{nil}, changing font, menu bar, tool bar, +internal borders, fringes or scroll bars of a specific frame may +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 +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}, +@code{internal-border-width}, @code{menu-bar-lines} and +@code{tool-bar-lines}. + +Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height}, +@code{vertical-scroll-bars}, @code{horizontal-scroll-bars}, +@code{left-fringe} and @code{right-fringe} frame parameters is handled +as if the frame contained just one live window. This means, for +example, that removing vertical scroll bars on a frame containing +several side by side windows will shrink the outer frame width by the +width of one scroll bar provided this option is @code{nil} and keep it +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 +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 +(which means the outer frame size never changes implicitly when there's +no window system support). + +Note that when a frame is not large enough to accommodate a change of +any of the parameters listed above, Emacs may try to enlarge the frame +even if this option is non-@code{nil}. +@end defopt + + @node Frame Parameters @section Frame Parameters @cindex frame parameters @@ -438,7 +978,6 @@ frame transparency, the parameter @code{alpha} is also meaningful. * Parameter Access:: How to change a frame's parameters. * Initial Parameters:: Specifying frame parameters when you make a frame. * Window Frame Parameters:: List of frame parameters for window systems. -* Size and Position:: Changing the size and position of a frame. * Geometry:: Parsing geometry specifications. @end menu @@ -723,12 +1262,12 @@ 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{Size and Position}), in +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{Size and Position}), in +The width of the frame's text area (@pxref{Frame Geometry}), in characters. @vindex user-size, a frame parameter @@ -1183,309 +1722,6 @@ equivalent to the @code{:background} attribute of the @end table -@node Size and Position -@subsection Frame Size and Position -@cindex size of frame -@cindex screen size -@cindex frame size -@cindex resize frame - -You can read or change the size and position of a frame using the frame -parameters @code{left}, @code{top}, @code{height}, and @code{width}. -Whatever geometry parameters you don't specify are chosen by the window -manager in its usual fashion. - - Here are some special features for working with sizes and positions. -Most of the functions described below use a @var{frame} argument which -has to specify a live frame. If omitted or @code{nil}, it specifies the -selected frame, see @ref{Input Focus}. - -@defun set-frame-position frame left top -This function sets the position of the top left corner of @var{frame} to -@var{left} and @var{top}. These arguments are measured in pixels, and -normally count from the top left corner of the screen to the top left -corner of the rectangle allotted to the frame by the window manager. - -Negative parameter values position the bottom edge of that rectangle up -from the bottom edge of the screen, or the right rectangle edge to the -left of the right edge of the screen. It would probably be better if -the values were always counted from the left and top, so that negative -arguments would position the frame partly off the top or left edge of -the screen, but it seems inadvisable to change that now. -@end defun - -@cindex frame default font -@cindex default font of a frame -Each frame has a @dfn{default font} which specifies the canonical height -and width of a character on that frame. The default font is used when -retrieving or changing the size of a frame in terms of columns or lines. -It is also used when resizing (@pxref{Window Sizes}) or splitting -(@pxref{Splitting Windows}) windows. - -@defun frame-char-height &optional frame -@defunx frame-char-width &optional frame -These functions return the canonical height and width of a character in -@var{frame}, measured in pixels. Together, these values establish the -size of the default font on @var{frame}. The values depend on the -choice of font for @var{frame}, see @ref{Font and Color Parameters}. -@end defun - -The default font can be also set directly with the following function: - -@deffn Command set-frame-font font &optional keep-size frames -This sets the default font to @var{font}. When called interactively, it -prompts for the name of a font, and uses that font on the selected -frame. When called from Lisp, @var{font} should be a font name (a -string), a font object, font entity, or a font spec. - -If the optional argument @var{keep-size} is @code{nil}, this keeps the -number of frame lines and columns fixed. (If non-@code{nil}, the option -@code{frame-inhibit-implied-resize} described below will override this.) -If @var{keep-size} is non-@code{nil} (or with a prefix argument), it -tries to keep the size of the display area of the current frame fixed by -adjusting the number of lines and columns. - -If the optional argument @var{frames} is @code{nil}, this applies the -font to the selected frame only. If @var{frames} is non-@code{nil}, it -should be a list of frames to act upon, or @code{t} meaning all existing -graphical frames. -@end deffn - -@cindex frame display area -@cindex display area of a frame -The @dfn{display area} of a frame is a rectangular area within the area -allotted to the frame by the window manager. The display area neither -includes the title bar (@pxref{Frame Titles}) nor any other decorations -provided by the window manager (like an external border used for -resizing frames via mouse dragging). - - The actual height of the display area depends on the window-system -and toolkit in use. With GTK+, the display area does not include any -tool bar or menu bar. With the Motif or Lucid toolkits and with -Windows, the display area includes the tool bar but not the menu bar. -In a graphical version with no toolkit, it includes both the tool bar -and menu bar. On a text terminal, the display area includes the menu -bar. - -@defun frame-pixel-height &optional frame -@defunx frame-pixel-width &optional frame - These functions return the height and width of the display area of -@var{frame}, measured in pixels. For a text terminal, the results are -in characters rather than pixels. -@end defun - -@cindex frame text area -@cindex text area of a frame - The @dfn{text area} of a frame is a concept implicitly used by all -functions that change a frame's height or width. It is a rectangle -located within the display area. Its size is obtained from that of the -display area by subtracting the sizes of any tool or menu bars that are -part of the display area, 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}. - -@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}, 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 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 -@defunx frame-width &optional frame -These functions return the height and width of the text area of -@var{frame}, measured in units of the default font height and width of -@var{frame}. These functions are plain shorthands for writing -@code{(frame-parameter frame 'height)} and @code{(frame-parameter frame -'width)}. - -If the text area of @var{frame} measured in pixles is not a multiple of -its default font size, the values returned by this functions are rounded -down to the number of characters of the default font that fully fit into -the text area. -@end defun - -@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}. If this is non-@code{nil}, no rounding -occurs, hence frame sizes can increase/decrease by one pixel. - -Setting this causes the next resize operation to pass the corresponding -size hints to the window manager. This means that this variable should -be set only in a user's initial file; applications should never bind it -temporarily. - -The precise meaning of a value of @code{nil} for this option depends -on the toolkit used. Dragging the frame border with the mouse is usually -done character-wise. Calling @code{set-frame-size} (see below) -with arguments that do not specify the frame size as an integer multiple -of its character size, however, may: be ignored, cause a -rounding (GTK+), or be accepted (Lucid, Motif, MS-Windows). - -With some window managers you may have to set this to non-@code{nil} in -order to make a frame appear truly ``maximized'' or ``fullscreen''. -@end defopt - -@defun set-frame-size frame width height pixelwise -This function sets the size of the text area of @var{frame}, measured in -characters; @var{width} and @var{height} specify the new width in -columns and the new height in lines. - -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 -to a multiple of its character size. -@end defun - -@defun set-frame-height frame height &optional pretend pixelwise -This function resizes the text area of @var{frame} to a height of -@var{height} lines. The sizes of existing windows in @var{frame} are -altered proportionally to fit. - -If @var{pretend} is non-@code{nil}, then Emacs displays @var{height} -lines of output in @var{frame}, but does not change its value for the -actual height of the frame. This is only useful on text terminals. -Using a smaller height than the terminal actually implements may be -useful to reproduce behavior observed on a smaller screen, or if the -terminal malfunctions when using its whole screen. Setting the frame -height ``for real'' does not always work, because knowing the correct -actual size may be necessary for correct cursor positioning on -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. -@end defun - -@defun set-frame-width frame width &optional pretend pixelwise -This function sets the width of the text area of @var{frame}, measured -in characters. The argument @var{pretend} has the same meaning as in -@code{set-frame-height}. - -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. -@end defun - -None of these three functions will make a frame smaller than needed to -display all of its windows together with their scroll bars, fringes, -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. - - By default, Emacs tries to keep the number of lines and columns of a -frame's text area unaltered when, for example, adding or removing a menu -bar, changing the default font or setting the width of the frame's -scroll bars. This means, however, that in such case Emacs must ask the -window manager to resize the display area of the frame in order to -accommodate the size change. Note that wrapping a menu or tool bar -usually does not resize the frame's display area, hence this will alter -the number of displayed lines. - - Occasionally, such implied resizing of the display area may be -unwanted, for example, when the frame is maximized or made fullscreen -where it's turned off by default. In other cases you can disable -implied resizing with the following option: - -@defopt frame-inhibit-implied-resize -If this option is @code{nil}, changing font, menu bar, tool bar, -internal borders, fringes or scroll bars of a specific frame may -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 -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}, -@code{internal-border-width}, @code{menu-bar-lines} and -@code{tool-bar-lines}. - -Changing any of the @code{scroll-bar-width}, @code{scroll-bar-height}, -@code{vertical-scroll-bars}, @code{horizontal-scroll-bars}, -@code{left-fringe} and @code{right-fringe} frame parameters is handled -as if the frame contained just one live window. This means, for -example, that removing vertical scroll bars on a frame containing -several side by side windows will shrink the frame width by the width of -one scroll bar provided this option is @code{nil} and keep it 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 -change the 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 frame), and @code{t} otherwise (which -means the frame size never changes implicitly when there's no window -system support). - -Note that when a frame is not large enough to accommodate a change of -any of the parameters listed above, Emacs may try to enlarge the frame -even if this option is non-@code{nil}. -@end defopt - -@c FIXME? Belongs more in Emacs manual than here? -@c But, e.g., fit-window-to-buffer is in this manual. -If you have a frame that displays only one window, you can fit that -frame to its buffer using the command @code{fit-frame-to-buffer}. - -@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only -This command adjusts the size of @var{frame} to display the contents of -its buffer exactly. @var{frame} can be any live frame and defaults to -the selected one. Fitting is done only if @var{frame}'s root window is -live. The arguments @var{max-height}, @var{min-height}, @var{max-width} -and @var{min-width} specify bounds on the new total size of -@var{frame}'s root window. @var{min-height} and @var{min-width} default -to the values of @code{window-min-height} and @code{window-min-width} -respectively. - -If the optional argument @var{only} is @code{vertically}, this function -may resize the frame vertically only. If @var{only} is -@code{horizontally}, it may resize the frame horizontally only. -@end deffn - -The behavior of @code{fit-frame-to-buffer} can be controlled with the -help of the two options listed next. - -@defopt fit-frame-to-buffer-margins -This option can be used to specify margins around frames to be fit by -@code{fit-frame-to-buffer}. Such margins can be useful to avoid, for -example, that such frames overlap the taskbar. - -It specifies the numbers of pixels to be left free on the left, above, -the right, and below a frame that shall be fit. The default specifies -@code{nil} for each which means to use no margins. The value specified -here can be overridden for a specific frame by that frame's -@code{fit-frame-to-buffer-margins} parameter, if present. -@end defopt - -@defopt fit-frame-to-buffer-sizes -This option specifies size boundaries for @code{fit-frame-to-buffer}. -It specifies the total maximum and minimum lines and maximum and minimum -columns of the root window of any frame that shall be fit to its buffer. -If any of these values is non-@code{nil}, it overrides the corresponding -argument of @code{fit-frame-to-buffer}. -@end defopt - - @node Geometry @subsection Geometry @@ -2088,8 +2324,10 @@ give access to the current position of the mouse. @defun mouse-position This function returns a description of the position of the mouse. The value looks like @code{(@var{frame} @var{x} . @var{y})}, where @var{x} -and @var{y} are integers giving the position in characters relative to -the top left corner of the inside of @var{frame}. +and @var{y} are integers giving the (possibly rounded) position in +multiples of the default character size of @var{frame} (@pxref{Frame +Font}) relative to the native position of @var{frame} (@pxref{Frame +Geometry}). @end defun @defvar mouse-position-function @@ -2105,9 +2343,13 @@ This abnormal hook exists for the benefit of packages like @defun set-mouse-position frame x y This function @dfn{warps the mouse} to position @var{x}, @var{y} in frame @var{frame}. The arguments @var{x} and @var{y} are integers, -giving the position in characters relative to the top left corner of the -inside of @var{frame}. If @var{frame} is not visible, this function -does nothing. The return value is not significant. +giving the position in multiples of the default character size of +@var{frame} (@pxref{Frame Font}) relative to the native position of +@var{frame} (@pxref{Frame Geometry}). + +The resulting mouse position is constrained to the native frame of +@var{frame}. If @var{frame} is not visible, this function does nothing. +The return value is not significant. @end defun @defun mouse-pixel-position @@ -2118,12 +2360,31 @@ coordinates in units of pixels rather than units of characters. @defun set-mouse-pixel-position frame x y This function warps the mouse like @code{set-mouse-position} except that @var{x} and @var{y} are in units of pixels rather than units of -characters. These coordinates are not required to be within the frame. +characters. -If @var{frame} is not visible, this function does nothing. The return -value is not significant. +The resulting mouse position is not constrained to the native frame of +@var{frame}. If @var{frame} is not visible, this function does nothing. +The return value is not significant. @end defun +On a graphical terminal the following two functions allow to retrieve +and set the absolute position of the mouse cursor. + +@defun x-mouse-absolute-pixel-position +This function returns a cons cell (@var{x} . @var{y}) of the coordinates +of the mouse cursor position in pixels, relative to a position (0, 0) of +the selected frame's display. +@end defun + +@defun x-set-mouse-absolute-pixel-position x y +This function moves the mouse cursor to the position (@var{x}, @var{y}). +The coordinates @var{x} and @var{y} are interpreted in pixels relative +to a position (0, 0) of the selected frame's display. +@end defun + +The following function can tell whether the mouse cursor is currently +visible on a frame: + @defun frame-pointer-visible-p &optional frame This predicate function returns non-@code{nil} if the mouse pointer displayed on @var{frame} is visible; otherwise it returns @code{nil}. diff --git a/doc/lispref/windows.texi b/doc/lispref/windows.texi index ccfe7ff..b55a139 100644 --- a/doc/lispref/windows.texi +++ b/doc/lispref/windows.texi @@ -432,8 +432,8 @@ specified either in units of pixels or in units of lines and columns. On a graphical display, the latter actually correspond to the height and width of a ``default'' character specified by the frame's default font as returned by @code{frame-char-height} and @code{frame-char-width} -(@pxref{Size and Position}). Thus, if a window is displaying text with -a different font or size, the reported line height and column width for +(@pxref{Frame Font}). Thus, if a window is displaying text with a +different font or size, the reported line height and column width for that window may differ from the actual number of text lines or columns displayed within it. @@ -791,8 +791,8 @@ If the value of this option is non-@code{nil}, Emacs resizes windows in units of pixels. This currently affects functions like @code{split-window} (@pxref{Splitting Windows}), @code{maximize-window}, @code{minimize-window}, @code{fit-window-to-buffer}, -@code{shrink-window-if-larger-than-buffer} (all listed below) and -@code{fit-frame-to-buffer} (@pxref{Size and Position}). +@code{fit-frame-to-buffer} and +@code{shrink-window-if-larger-than-buffer} (all listed below). Note that when a frame's pixel size is not a multiple of its character size, at least one window may get resized pixelwise even if this @@ -836,8 +836,7 @@ resize operations (@pxref{Preserving Window Sizes}). If the option @code{fit-frame-to-buffer} (see below) is non-@code{nil}, this function will try to resize the frame of @var{window} to fit its -contents by calling @code{fit-frame-to-buffer} (@pxref{Size and -Position}). +contents by calling @code{fit-frame-to-buffer} (see below). @end deffn @defopt fit-window-to-buffer-horizontally @@ -858,6 +857,47 @@ live window and this option is non-@code{nil}. If this is non-@code{nil} value means frames can be resized in both dimensions. @end defopt +If you have a frame that displays only one window, you can fit that +frame to its buffer using the command @code{fit-frame-to-buffer}. + +@deffn Command fit-frame-to-buffer &optional frame max-height min-height max-width min-width only +This command adjusts the size of @var{frame} to display the contents of +its buffer exactly. @var{frame} can be any live frame and defaults to +the selected one. Fitting is done only if @var{frame}'s root window is +live. The arguments @var{max-height}, @var{min-height}, @var{max-width} +and @var{min-width} specify bounds on the new total size of +@var{frame}'s root window. @var{min-height} and @var{min-width} default +to the values of @code{window-min-height} and @code{window-min-width} +respectively. + +If the optional argument @var{only} is @code{vertically}, this function +may resize the frame vertically only. If @var{only} is +@code{horizontally}, it may resize the frame horizontally only. +@end deffn + +The behavior of @code{fit-frame-to-buffer} can be controlled with the +help of the two options listed next. + +@defopt fit-frame-to-buffer-margins +This option can be used to specify margins around frames to be fit by +@code{fit-frame-to-buffer}. Such margins can be useful to avoid, for +example, that such frames overlap the taskbar. + +It specifies the numbers of pixels to be left free on the left, above, +the right, and below a frame that shall be fit. The default specifies +@code{nil} for each which means to use no margins. The value specified +here can be overridden for a specific frame by that frame's +@code{fit-frame-to-buffer-margins} parameter, if present. +@end defopt + +@defopt fit-frame-to-buffer-sizes +This option specifies size boundaries for @code{fit-frame-to-buffer}. +It specifies the total maximum and minimum lines and maximum and minimum +columns of the root window of any frame that shall be fit to its buffer. +If any of these values is non-@code{nil}, it overrides the corresponding +argument of @code{fit-frame-to-buffer}. +@end defopt + @deffn Command shrink-window-if-larger-than-buffer &optional window This command attempts to reduce @var{window}'s height as much as possible while still showing its full buffer, but no less than @@ -3622,33 +3662,28 @@ is off the screen due to horizontal scrolling: @end group @end example + @node Coordinates and Windows @section Coordinates and Windows @cindex frame-relative coordinate @cindex coordinate, relative to frame @cindex window position - This section describes functions that report the position of a -window. Most of these functions report positions relative to the -window's frame. In this case, the coordinate origin @samp{(0,0)} lies -near the upper left corner of the frame. For technical reasons, on -graphical displays the origin is not located at the exact corner of -the graphical window as it appears on the screen. If Emacs is built -with the GTK+ toolkit, the origin is at the upper left corner of the -frame area used for displaying Emacs windows, below the title-bar, -GTK+ menu bar, and tool bar (since these are drawn by the window -manager and/or GTK+, not by Emacs). But if Emacs is not built with -GTK+, the origin is at the upper left corner of the tool bar (since in -this case Emacs itself draws the tool bar). In both cases, the X and -Y coordinates increase rightward and downward respectively. - - Except where noted, X and Y coordinates are reported in integer -character units, i.e., numbers of lines and columns respectively. On a -graphical display, each ``line'' and ``column'' corresponds to the -height and width of a default character specified by the frame's -default font. - -@defun window-edges &optional window +This section describes functions that report the position of a window. +Most of these functions report positions relative to an origin at the +native position of the window's frame (@pxref{Frame Geometry}). Some +functions report positions relative to the origin of the display of the +window's frame. In any case, the origin has the coordinates (0, 0) and +X and Y coordinates increase ``rightward'' and ``downward'' +respectively. + + For the following functions, X and Y coordinates are reported in +integer character units, i.e., numbers of lines and columns +respectively. On a graphical display, each ``line'' and ``column'' +corresponds to the height and width of a default character specified by +the frame's default font (@pxref{Frame Font}). + +@defun window-edges &optional window body absolute pixelwise This function returns a list of the edge coordinates of @var{window}. If @var{window} is omitted or @code{nil}, it defaults to the selected window. @@ -3665,44 +3700,73 @@ header line, mode line, scroll bar, fringes, window divider and display margins. On a text terminal, if the window has a neighbor on its right, its right edge includes the separator line between the window and its neighbor. -@end defun -@defun window-inside-edges &optional window -This function is similar to @code{window-edges}, but the returned edge -values are for the text area of the window. They exclude any header -line, mode line, scroll bar, fringes, window divider, display margins, -and vertical separator. +If the optional argument @var{body} is @code{nil}, this means to +return the edges corresponding to the total size of @var{window}. +@var{body} non-@code{nil} means to return the edges of @var{window}'s +body (aka text area). If @var{body} is non-@code{nil}, @var{window} +must specify a live window. + +If the optional argument @var{absolute} is @code{nil}, this means to +return edges relative to the native position of @var{window}'s frame. +@var{absolute} non-@code{nil} means to return coordinates relative to +the origin (0, 0) of @var{window}'s display. On non-graphical systems +this argument has no effect. + +If the optional argument @var{pixelwise} is @code{nil}, this means to +return the coordinates in terms of the default character width and +height of @var{window}'s frame (@pxref{Frame Font}), rounded if +necessary. @var{pixelwise} non-@code{nil} means to return the +coordinates in pixels. Note that the pixel specified by @var{right} and +@var{bottom} is immediately outside of these edges. If @var{absolute} +is non-@code{nil}, @var{pixelwise} is implicitly non-@code{nil} too. @end defun -@defun window-top-line &optional window -This function returns the Y coordinate of the topmost row of -@var{window}, equivalent to the @var{top} entry in the list returned -by @code{window-edges}. +@defun window-body-edges &optional window +This function returns the edges of @var{window}'s body (@pxref{Window +Sizes}). Calling @code{(window-body-edges window)} is equivalent to +calling @code{(window-edges window t)}, see above. @end defun +@comment The following two functions are confusing and hardly used. +@ignore @defun window-left-column &optional window -This function returns the X coordinate of the leftmost column of -@var{window}, equivalent to the @var{left} entry in the list returned -by @code{window-edges}. +This function returns the leftmost column of @var{window}. This value +equals the @var{left} entry in the list returned by @code{(window-edges +window)} minus the number of columns occupied by the internal border of +@var{window}'s frame. @end defun +@defun window-top-line &optional window +This function returns the topmost row of @var{window}. This value is +equal to the @var{top} entry in the list returned by @code{(window-edges +window)} minus the number of lines occupied by the internal border of +@var{window}'s frame. +@end defun +@end ignore + The following functions can be used to relate a set of frame-relative coordinates to a window: @defun window-at x y &optional frame -This function returns the live window at the frame-relative -coordinates @var{x} and @var{y}, on frame @var{frame}. If there is no -window at that position, the return value is @code{nil}. If -@var{frame} is omitted or @code{nil}, it defaults to the selected +This function returns the live window at the coordinates @var{x} and +@var{y} given in default character sizes (@pxref{Frame Font}) relative +to the native position of @var{frame} (@pxref{Frame Geometry}). + +If there is no window at that position, the return value is @code{nil}. +If @var{frame} is omitted or @code{nil}, it defaults to the selected frame. @end defun @defun coordinates-in-window-p coordinates window -This function checks whether a window @var{window} occupies the -frame-relative coordinates @var{coordinates}, and if so, which part of -the window that is. @var{window} should be a live window. +This function checks whether a window @var{window} occupies the frame +relative coordinates @var{coordinates}, and if so, which part of the +window that is. @var{window} should be a live window. + @var{coordinates} should be a cons cell of the form @code{(@var{x} -. @var{y})}, where @var{x} and @var{y} are frame-relative coordinates. +. @var{y})}, where @var{x} and @var{y} are given in default character +sizes (@pxref{Frame Font}) relative to the native position of +@var{window}'s frame (@pxref{Frame Geometry}). If there is no window at the specified position, the return value is @code{nil} . Otherwise, the return value is one of the following: @@ -3757,46 +3821,96 @@ each text character is taken to be ``one pixel''. @defun window-pixel-edges &optional window This function returns a list of pixel coordinates for the edges of -@var{window}. If @var{window} is omitted or @code{nil}, it defaults -to the selected window. +@var{window}. Calling @code{(window-pixel-edges window)} is equivalent +to calling @code{(window-edges window nil nil t)}, see above. +@end defun -The return value has the form @code{(@var{left} @var{top} @var{right} -@var{bottom})}. The list elements are, respectively, the X pixel -coordinate of the left window edge, the Y pixel coordinate of the top -edge, one more than the X pixel coordinate of the right edge, and one -more than the Y pixel coordinate of the bottom edge. +@comment The following two functions are confusing and hardly used. +@ignore +@defun window-pixel-left &optional window +This function returns the left pixel edge of window @var{window}. This +value equals the @var{left} entry in the list returned by +@code{(window-pixel-edges window)} minus the number of pixels occupied +by the internal border of @var{window}'s frame. @var{window} must be a +valid window and defaults to the selected one. @end defun -@defun window-inside-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the pixel coordinates for the edges of the window's text area, -rather than the pixel coordinates for the edges of the window itself. -@var{window} must specify a live window. +@defun window-pixel-top &optional window +This function returns the top pixel edge of window @var{window}. This +value is equal to the @var{top} entry in the list returned by +@code{(window-pixel-edges window)} minus the number of pixels occupied +by the internal border of @var{window}'s frame. @var{window} must be a +valid window and defaults to the selected one. +@end defun +@end ignore + +@defun window-body-pixel-edges &optional window +This function returns the pixel edges of @var{window}'s body. Calling +@code{(window-body-pixel-edges window)} is equivalent to calling +@code{(window-edges window t nil t)}, see above. @end defun - The following functions return window positions in pixels, relative -to the display screen rather than the frame: + The following functions return window positions in pixels, relative to +the origin of the display screen rather than that of the frame: @defun window-absolute-pixel-edges &optional window -This function is like @code{window-pixel-edges}, except that it -returns the edge pixel coordinates relative to the top left corner of -the display screen. +This function returns the pixel coordinates of @var{WINDOW} relative to +an origin at (0, 0) of the display of @var{window}'s frame. Calling +@code{(window-absolute-pixel-edges)} is equivalent to calling +@code{(window-edges window nil t t)}, see above. @end defun -@defun window-inside-absolute-pixel-edges &optional window -This function is like @code{window-inside-pixel-edges}, except that it -returns the edge pixel coordinates relative to the top left corner of -the display screen. @var{window} must specify a live window. -@end defun +@defun window-absolute-body-pixel-edges &optional window +This function returns the pixel coordinates of @var{WINDOW}'s body +relative to an origin at (0, 0) of the display of @var{window}'s frame. +Calling @code{(window-absolute-body-pixel-edges window)} is equivalent +to calling @code{(window-edges window t t t)}, see above. -@defun window-pixel-left &optional window -This function returns the left pixel edge of window @var{window}. -@var{window} must be a valid window and defaults to the selected one. +Combined with @code{x-set-mouse-absolute-pixel-position}, this function +can be used to move the mouse pointer to an arbitrary buffer position +visible in some window: + +@example +@group +(let ((edges (window-absolute-body-pixel-edges)) + (position (pos-visible-in-window-p nil nil t))) + (x-set-mouse-absolute-pixel-position + (+ (nth 0 edges) (nth 0 position)) + (+ (nth 1 edges) (nth 1 position)))) +@end group +@end example + +On a graphical terminal this form ``warps'' the mouse cursor to the +upper left corner of the glyph at the selected window's point. A +position calculated this way can be also used to show a tooltip window +there. @end defun -@defun window-pixel-top &optional window -This function returns the top pixel edge of window @var{window}. -@var{window} must be a valid window and defaults to the selected one. +The following function returns the screen coordinates of a buffer +position visible in a window: + +@defun window-absolute-pixel-position &optional position window +If the buffer position @var{position} is visible in window @var{window}, +this function returns the display coordinates of the upper/left corner +of the glyph at @var{position}. The return value is a cons of the X- +and Y-coordinates of that corner, relative to an origin at (0, 0) of +@var{window}'s display. It returns @code{nil} if @var{position} is not +visible in @var{window}. + +@var{window} must be a live window and defaults to the selected +window. @var{position} defaults to the value of @code{window-point} +of @var{window}. + +This means that in order to move the mouse pointer to the position of +point in the selected window, it's sufficient to write: + +@example +@group +(let ((position (window-absolute-pixel-position))) + (x-set-mouse-absolute-pixel-position + (car position) (cdr position))) +@end group +@end example @end defun commit d13dc271e52c7d977aee6f32c3d40b8b15b04c6c Author: Alan Mackenzie Date: Thu Aug 20 10:37:24 2015 +0000 Handling of `c-parse-state'. Fix low level bug. progmodes/cc-engine.el (c-remove-stale-state-cache-backwards): Add "CASE 3.5" to handle `cache-pos' being only slightly before `here'. diff --git a/lisp/progmodes/cc-engine.el b/lisp/progmodes/cc-engine.el index f5285a6..520b7e5 100644 --- a/lisp/progmodes/cc-engine.el +++ b/lisp/progmodes/cc-engine.el @@ -3135,16 +3135,20 @@ comment at the start of cc-engine.el for more info." nil)) ; for the cond ((save-restriction - (narrow-to-region too-far-back (point-max)) - (setq ren (c-safe (c-sc-scan-lists pos -1 -1)))) - + (narrow-to-region too-far-back (point-max)) + (setq ren (c-safe (c-sc-scan-lists pos -1 -1)))) ;; CASE 3: After a }/)/] before `here''s BOL. (list (1+ ren) (and dropped-cons pos) nil)) ; Return value + ((progn (setq good-pos (c-state-lit-beg (c-point 'bopl here-bol))) + (>= cache-pos good-pos)) + ;; CASE 3.5: Just after an existing entry in `c-state-cache' on `here''s + ;; line or the previous line. + (list cache-pos nil nil)) + (t ;; CASE 4; Best of a bad job: BOL before `here-bol', or beginning of ;; literal containing it. - (setq good-pos (c-state-lit-beg (c-point 'bopl here-bol))) (list good-pos (and dropped-cons good-pos) nil)))))