---

16.3 Undoing commands

Function: save-for-undo name method &optional cleanup method-undo buffer ¶

This saves information to undo a command. Name is a string to display when prompting the user for confirmation when he invokes the Undo command (for example, "kill" or "Fill Paragraph"). Method is the function to invoke to undo the effect of the command. Method-undo is a function that undoes the undo function, or effectively re-establishes the state immediately after invoking the command. If there is any existing undo information, this invokes the cleanup function; typically method closes over or uses permanent marks into a buffer, and the cleanup function should delete such references. Buffer defaults to the current-buffer, and the Undo command only invokes undo methods when they were saved for the buffer that is current when the user invokes Undo.

Function: make-region-undo kind name region &optional mark-or-region ¶

This handles three common cases that commands fall into when setting up undo methods, including cleanup and method-undo functions (see save-for-undo). These cases are indicated by the kind argument:

:twiddle

Use this kind when a command modifies a region, and the undo information indicates how to swap between two regions — the one before any modification occurs and the resulting region. Region is the resulting region, and it has permanent marks into the buffer. Mark-or-region is a region without marks into the buffer (for example, the result of copy-region). As a result of calling this, a first invocation of Undo deletes region, saving it, and inserts mark-or-region where region used to be. The undo method sets up for a second invocation of Undo that will undo the effect of the undo; that is, after two calls, the buffer is exactly as it was after invoking the command. This activity is repeatable any number of times. This establishes a cleanup method that deletes the two permanent marks into the buffer used to locate the modified region.

:insert

Use this kind when a command has deleted a region, and the undo information indicates how to re-insert the region. Region is the deleted and saved region, and it does not contain marks into any buffer. Mark-or-region is a permanent mark into the buffer where the undo method should insert region. As a result of calling this, a first invocation of Undo inserts region at mark-or-region and forms a region around the inserted text with permanent marks into the buffer. This allows a second invocation of Undo to undo the effect of the undo; that is, after two calls, the buffer is exactly as it was after invoking the command. This activity is repeatable any number of times. This establishes a cleanup method that deletes either the permanent mark into the buffer or the two permanent marks of the region, depending on how many times the user used Undo.

:delete

Use this kind when a command has inserted a block of text, and the undo information indicates how to delete the region. Region has permanent marks into the buffer and surrounds the inserted text. Leave Mark-or-region unspecified. As a result of calling this, a first invocation of Undo deletes region, saving it, and establishes a permanent mark into the buffer to remember where the region was. This allows a second invocation of Undo to undo the effect of the undo; that is, after two calls, the buffer is exactly as it was after invoking the command. This activity is repeatable any number of times. This establishes a cleanup method that deletes either the permanent mark into the buffer or the two permanent marks of the region, depending on how many times the user used Undo.

Name in all cases is an appropriate string indicating what the command did. This is used by Undo when prompting the user for confirmation before calling the undo method. The string used by Undo alternates between this argument and something to indicate that the user is undoing an undo.