Function: prepare-change-group

prepare-change-group is a byte-compiled function defined in subr.el.gz.

Signature

(prepare-change-group &optional BUFFER)

Documentation

Return a handle for the current buffer's state, for a change group.

If you specify BUFFER, make a handle for BUFFER's state instead.

Pass the handle to activate-change-group afterward to initiate the actual changes of the change group.

To finish the change group, call either accept-change-group or cancel-change-group passing the same handle as argument. Call accept-change-group to accept the changes in the group as final; call cancel-change-group to undo them all. You should use unwind-protect to make sure the group is always finished. The call to activate-change-group should be inside the unwind-protect. Once you finish the group, don't use the handle again--don't try to finish the same group twice. For a simple example of correct use, see the source code of atomic-change-group.

As long as this handle is still in use, do not call functions which edit the undo list: if it no longer contains its current value, Emacs will not be able to cancel the change group. This includes any "amalgamating" commands, such as delete-char, which call undo-auto-amalgamate.

The handle records only the specified buffer. To make a multibuffer change group, call this function once for each buffer you want to cover, then use nconc to combine the returned values, like this:

  (nconc (prepare-change-group buffer-1)
         (prepare-change-group buffer-2))

You can then activate that multibuffer change group with a single call to activate-change-group and finish it with a single call to accept-change-group or cancel-change-group.

View in manual

Probably introduced at or before Emacs version 22.1.

Source Code

;; Defined in /usr/src/emacs/lisp/subr.el.gz
(defun prepare-change-group (&optional buffer)
  "Return a handle for the current buffer's state, for a change group.
If you specify BUFFER, make a handle for BUFFER's state instead.

Pass the handle to `activate-change-group' afterward to initiate
the actual changes of the change group.

To finish the change group, call either `accept-change-group' or
`cancel-change-group' passing the same handle as argument.  Call
`accept-change-group' to accept the changes in the group as final;
call `cancel-change-group' to undo them all.  You should use
`unwind-protect' to make sure the group is always finished.  The call
to `activate-change-group' should be inside the `unwind-protect'.
Once you finish the group, don't use the handle again--don't try to
finish the same group twice.  For a simple example of correct use, see
the source code of `atomic-change-group'.

As long as this handle is still in use, do not call functions
which edit the undo list: if it no longer contains its current
value, Emacs will not be able to cancel the change group.  This
includes any \"amalgamating\" commands, such as `delete-char',
which call `undo-auto-amalgamate'.

The handle records only the specified buffer.  To make a multibuffer
change group, call this function once for each buffer you want to
cover, then use `nconc' to combine the returned values, like this:

  (nconc (prepare-change-group buffer-1)
         (prepare-change-group buffer-2))

You can then activate that multibuffer change group with a single
call to `activate-change-group' and finish it with a single call
to `accept-change-group' or `cancel-change-group'."

  (if buffer
      (list (cons buffer (with-current-buffer buffer buffer-undo-list)))
    (list (cons (current-buffer) buffer-undo-list))))