active---for example, typing @kbd{a} inserts the character @samp{a},
then deactivates the mark. If you enable Delete Selection mode, a
minor mode, then inserting text while the mark is active causes the
-text in the region to be deleted first. To toggle Delete Selection
+text in the region to be deleted first. Also, commands that normally
+delete just one character, such as @kbd{C-d} or @kbd{@key{DEL}}, will
+delete the entire region instead. To toggle Delete Selection
mode on or off, type @kbd{M-x delete-selection-mode}.
@node Mark Ring
@c There is also global-mark-ring-max, but this chapter explicitly
@c does not talk about the global mark.
+@cindex @code{delete-selection}, symbol property
+@findex delete-selection-helper
+@findex delete-selection-pre-hook
+When Delete Selection mode (@pxref{Using Region, Delete Selection, ,
+emacs, The GNU Emacs Manual}) is enabled, commands that operate on the
+active region (a.k.a.@: ``selection'') behave slightly differently.
+This works by adding the function @code{delete-selection-pre-hook} to
+the @code{pre-command-hook} (@pxref{Command Overview}). That function
+calls @code{delete-selection-helper} to delete the selection as
+appropriate for the command. If you want to adapt a command to Delete
+Selection mode, put the @code{delete-selection} property on the
+function's symbol (@pxref{Symbol Plists}); commands that don't have
+this property on their symbol won't delete the selection. This
+property can have one of several values to tailor the behavior to what
+the command is supposed to do; see the doc strings of
+@code{delete-selection-pre-hook} and @code{delete-selection-helper}
+for the details.
+
@node The Region
@section The Region
@c The index entry must be just "region" to make it the first hit
;; the values:
;; `yank'
;; For commands which do a yank; ensures the region about to be
-;; deleted isn't yanked.
+;; deleted isn't immediately yanked back, which would make the
+;; command a no-op.
;; `supersede'
;; Delete the active region and ignore the current command,
-;; i.e. the command will just delete the region.
+;; i.e. the command will just delete the region. This is for
+;; commands that normally delete small amounts of text, like
+;; a single character -- they will instead delete the whole
+;; active region.
+;; `kill'
+;; `kill-region' is used on the selection, rather than
+;; `delete-region'. (Text selected with the mouse will typically
+;; be yankable anyhow.)
;; t
;; The normal case: delete the active region prior to executing
;; the command which will insert replacement text.
-;; <function>
+;; FUNCTION
;; For commands which need to dynamically determine this behavior.
-;; The function should return one of the above values or nil.
+;; FUNCTION should take no argument and return one of the above
+;; values, or nil. In the latter case, FUNCTION should itself
+;; do with the active region whatever is appropriate."
;;; Code:
When Delete Selection mode is enabled, typed text replaces the selection
if the selection is active. Otherwise, typed text is just inserted at
-point regardless of any selection."
+point regardless of any selection. Also, commands that normally delete
+just one character will delete the entire selection instead.
+
+See `delete-selection-helper' and `delete-selection-pre-hook' for
+information on adapting behavior of commands in Delete Selection mode."
:global t :group 'editing-basics
(if (not delete-selection-mode)
(remove-hook 'pre-command-hook 'delete-selection-pre-hook)
"Delete selection according to TYPE:
`yank'
For commands which do a yank; ensures the region about to be
- deleted isn't yanked.
+ deleted isn't immediately yanked back, which would make the
+ command a no-op.
`supersede'
Delete the active region and ignore the current command,
- i.e. the command will just delete the region.
+ i.e. the command will just delete the region. This is for
+ commands that normally delete small amounts of text, like
+ a single character -- they will instead delete the whole
+ active region.
`kill'
`kill-region' is used on the selection, rather than
`delete-region'. (Text selected with the mouse will typically
the command which will insert replacement text.
FUNCTION
For commands which need to dynamically determine this behavior.
- FUNCTION should take no argument and return one of the above values or nil."
+ FUNCTION should take no argument and return one of the above
+ values, or nil. In the latter case, FUNCTION should itself
+ do with the active region whatever is appropriate."
(condition-case data
(cond ((eq type 'kill) ;Deprecated, backward compatibility.
(delete-active-region t)