From: Eli Zaretskii Date: Sat, 19 Dec 2015 14:14:11 +0000 (+0200) Subject: Document new features of Font Lock X-Git-Tag: emacs-25.0.90~435 X-Git-Url: https://code.delx.au/gnu-emacs/commitdiff_plain/277d7efd24082f989c72a1a91df6ded8546bfbfb Document new features of Font Lock * doc/lispref/modes.texi (Other Font Lock Variables): Document 'font-lock-flush-function' and 'font-lock-ensure-function'. (Font Lock Basics): Document the basic fontification functions referenced in "Other Font Lock Variables". * lisp/font-lock.el (font-lock-flush, font-lock-ensure): Doc fix. --- diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index a1747707d1..3b8550e13b 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -2509,6 +2509,53 @@ Search-based fontification happens second. @node Font Lock Basics @subsection Font Lock Basics + The Font Lock functionality is based on several basic functions. +Each of these calls the function specified by the corresponding +variable. This indirection allows major modes to modify the way +fontification works in the buffers of that mode, and even use the Font +Lock mechanisms for features that have nothing to do with +fontification. (This is why the description below says ``should'' +when it describes what the functions do: the major mode can customize +the values of the corresponding variables to do something entirely +different.) The variables mentioned below are described in @ref{Other +Font Lock Variables}. + +@ftable @code +@item font-lock-fontify-buffer +This function should fontify the current buffer's accessible portion, +by calling the function specified by +@code{font-lock-fontify-buffer-function}. + +@item font-lock-unfontify-buffer +Used when turning Font Lock off to remove the fontification. Calls +the function specified by @code{font-lock-unfontify-buffer-function}. + +@item font-lock-fontify-region beg end &optional loudly +Should fontify the region between @var{beg} and @var{end}. If +@var{loudly} is non-@code{nil}, should display status messages while +fontifying. Calls the function specified by +@code{font-lock-fontify-region-function}. + +@item font-lock-unfontify-region beg end +Should remove fontification from the region between @var{beg} and +@var{end}. Calls the function specified by +@code{font-lock-unfontify-region-function}. + +@item font-lock-flush &optional beg end +This function should mark the fontification of the region between +@var{beg} and @var{end} as outdated. If not specified or @code{nil}, +@var{beg} and @var{end} default to the beginning and end of the +buffer's accessible portion. Calls the function specified by +@code{font-lock-flush-function}. + +@item font-lock-ensure &optional beg end +This function should make sure the region between @var{beg} and +@var{end} has been fontified. The optional arguments @var{beg} and +@var{end} default to the beginning and the end of the buffer's +accessible portion. Calls the function specified by +@code{font-lock-ensure-function}. +@end ftable + There are several variables that control how Font Lock mode highlights text. But major modes should not set any of these variables directly. Instead, they should set @code{font-lock-defaults} as a buffer-local @@ -2936,6 +2983,22 @@ arguments, the beginning and end of the region. The default value is @code{font-lock-default-unfontify-region}. @end defvar +@defvar font-lock-flush-function +Function to use for declaring that a region's fontification is out of +date. It takes two arguments, the beginning and end of the region. +The default value of this variable is +@code{font-lock-after-change-function}. +@end defvar + +@defvar font-lock-ensure-function +Function to use for making sure a region of the current buffer has +been fontified. It is called with two arguments, the beginning and +end of the region. The default value of this variable is a function +that calls @code{font-lock-default-fontify-buffer} if the buffer is +not fontified; the effect is to make sure the entire accessible +portion of the buffer is fontified. +@end defvar + @defun jit-lock-register function &optional contextual This function tells Font Lock mode to run the Lisp function @var{function} any time it has to fontify or refontify part of the diff --git a/etc/NEWS b/etc/NEWS index 3a219851ff..5f19c40972 100644 --- a/etc/NEWS +++ b/etc/NEWS @@ -642,8 +642,10 @@ respectively, `show-paren-when-point-inside-paren' or *** C-x C-x in rectangle-mark-mode now cycles through the four corners. *** `string-rectangle' provides on-the-fly preview of the result. -** New font-lock functions font-lock-ensure and font-lock-flush, which -should be used instead of font-lock-fontify-buffer when called from Elisp. ++++ +** New font-lock functions `font-lock-ensure' and `font-lock-flush'. +These should be used in preference to `font-lock-fontify-buffer' when +called from Lisp. ** Macro `minibuffer-with-setup-hook' takes (:append FUN) to mean appending FUN to `minibuffer-setup-hook'. diff --git a/lisp/font-lock.el b/lisp/font-lock.el index 762720d5ba..93d677c67e 100644 --- a/lisp/font-lock.el +++ b/lisp/font-lock.el @@ -1065,7 +1065,8 @@ Called with two arguments BEG and END.") (defun font-lock-flush (&optional beg end) "Declare the region BEG...END's fontification as out-of-date. -If the region is not specified, it defaults to the whole buffer." +If the region is not specified, it defaults to the entire +accessible portion of the current buffer." (and font-lock-mode font-lock-fontified (funcall font-lock-flush-function @@ -1079,7 +1080,8 @@ Called with two arguments BEG and END.") (defun font-lock-ensure (&optional beg end) "Make sure the region BEG...END has been fontified. -If the region is not specified, it defaults to the whole buffer." +If the region is not specified, it defaults to the entire accessible +portion of the buffer." (font-lock-set-defaults) (funcall font-lock-ensure-function (or beg (point-min)) (or end (point-max))))