add-undo

Adds an undoer procedure to the editor's undo stack. If an undo is currently being performed, the undoer is added to the editor's redo stack. The undoer is called by the system when it is undoing (or redoing) changes to a editor, and when this undoer is the first item on the undo (or redo) stack.

The system automatically installs undo records to undo built-in editor operations, such as inserts, deletes, and font changes. Install an undoer only when it is necessary to maintain state or handle operations that are not built-in. For example, in a program where the user can assign labels to snips in a pasteboard, the program should install an undoer to revert a label change. Thus, when a user changes a snip's label and then selects Undo (from a standard menu bar), the snip's label will revert as expected. In contrast, there is no need to install an undoer when the user moves a snip by dragging it, because the system installs an appropriate undoer automatically.

After an undoer returns, the undoer is popped off the editor's undo (or redo) stack; if the return value is true, then the next undoer is also executed as part of the same undo (or redo) step. The undoer should return true if the action being undone was originally performed as part of a begin-edit-sequence and end-edit-sequence sequence. The return value should also be true if the undone action was implicitly part of a sequence. To extend the previous example, if a label change is paired with a move to realign the snip, then the label-change undoer should be added to the editor after the call to move, and it should return #t when it is called. As a result, the move will be undone immediately after the label change is undone. (If the opposite order is needed, use begin-edit-sequence and end-edit-sequence to create an explicit sequence.)

The system adds undoers to an editor (in response to other method calls) without calling this method.

• (send an-editor add-undo undoer) -> void
      undoer : procedure of zero arguments