Commit eea4e919 authored by Eli Zaretskii's avatar Eli Zaretskii

Improve documentation of self-insert-uses-region-functions

* lisp/simple.el (self-insert-uses-region-functions): Clarify the
doc string.
* lisp/delsel.el (delete-selection-uses-region-p): Mention
'self-insert-command' in the doc string.  (Bug#29373)

* doc/lispref/text.texi (Commands for Insertion): Mention
'self-insert-uses-region-functions'.
* doc/lispref/modes.texi (Keymaps and Minor Modes): Add a
cross-reference to "Commands for Insertion".
parent e6e41dac
......@@ -1490,10 +1490,11 @@ alist @code{minor-mode-map-alist}. @xref{Definition of minor-mode-map-alist}.
One use of minor mode keymaps is to modify the behavior of certain
self-inserting characters so that they do something else as well as
self-insert. (Another way to customize @code{self-insert-command} is
through @code{post-self-insert-hook}. Apart from this, the facilities
for customizing @code{self-insert-command} are limited to special cases,
designed for abbrevs and Auto Fill mode. Do not try substituting your
own definition of @code{self-insert-command} for the standard one. The
through @code{post-self-insert-hook}, see @ref{Commands for
Insertion}. Apart from this, the facilities for customizing
@code{self-insert-command} are limited to special cases, designed for
abbrevs and Auto Fill mode. Do not try substituting your own
definition of @code{self-insert-command} for the standard one. The
editor command loop handles this function specially.)
Minor modes may bind commands to key sequences consisting of @kbd{C-c}
......
......@@ -525,9 +525,17 @@ responsible for calling @code{blink-paren-function} when the inserted
character has close parenthesis syntax (@pxref{Blinking}).
@vindex post-self-insert-hook
@vindex self-insert-uses-region-functions
The final thing this command does is to run the hook
@code{post-self-insert-hook}. You could use this to automatically
reindent text as it is typed, for example.
reindent text as it is typed, for example. If any function on this
hook needs to act on the region (@pxref{The Region}), it should make
sure Delete Selection mode (@pxref{Using Region, Delete Selection, ,
emacs, The GNU Emacs Manual}) doesn't delete the region before
@code{post-self-insert-hook} functions are invoked. The way to do so
is to add a function that returns @code{nil} to
@code{self-insert-uses-region-functions}, a special hook that tells
Delete Selection mode it should not delete the region.
Do not try substituting your own definition of
@code{self-insert-command} for the standard one. The editor command
......
......@@ -256,12 +256,18 @@ See `delete-selection-helper'."
(get this-command 'delete-selection)))))
(defun delete-selection-uses-region-p ()
"Return t when the current command will be using the region
rather than having `delete-selection' delete it, nil otherwise.
"Return t when `delete-selection-mode' should not delete the region.
The `self-insert-command' could be the current command or may be
called by the current command. If this function returns nil,
then `delete-selection' is allowed to delete the region.
This function is intended for use as the value of the
`delete-selection' property of a command, and shouldn't be used
for anything else."
for anything else. In particular, `self-insert-command' has this
function as its `delete-selection' property, so that \"electric\"
self-insert commands that act on the region could adapt themselves
to `delete-selection-mode'."
(not (run-hook-with-args-until-success
'self-insert-uses-region-functions)))
......
......@@ -401,9 +401,18 @@ Other major modes are defined by comparison with this one."
(defvar self-insert-uses-region-functions nil
"Special hook to tell if `self-insert-command' will use the region.
It must be called via `run-hook-with-args-until-success' with no arguments.
Any `post-self-insert-command' which consumes the region should
register a function on this hook so that things like `delete-selection-mode'
can refrain from consuming the region.")
If any function on this hook returns a non-nil value, `delete-selection-mode'
will act on that value (see `delete-selection-helper'), and will
usually delete the region. If all the functions on this hook return
nil, it is an indiction that `self-insert-command' needs the region
untouched by `delete-selection-mode', and will itself do whatever is
appropriate with the region.
Any function on `post-self-insert-hook' which act on the region should
add a function to this hook so that `delete-selection-mode' could
refrain from deleting the region before `post-self-insert-hook'
functions are called.
This hook is run by `delete-selection-uses-region-p', which see.")
(defvar hard-newline (propertize "\n" 'hard t 'rear-nonsticky '(hard))
"Propertized string representing a hard newline character.")
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment