21. Undoing operations

The sgml widget keeps track of changes to the widget contents and records the necessry information to revert these changes. More specifically, the following operations can be reverted:

• Insertion of characters, elements and entities.
• Deletions of characters, elements and entites.
• Removal of elements.
• Modifications of attribute values.
• Changes to the global display status of tags and attributes.

The sgml widget maintains a list of the most recent operations that have occurred in the widget. When an operation should be undone, the newest entry in this list is examined and the operation that is described by this entry is reverted. After the operation has been undone, the corresponding entry is removed from the undo list and discarded.

The undo widget command

undo
	Reverts the modifications caused by the most recent change to the widget contents to their previous state.
undo type
	Returns the type of the topmost entry in the undo list.
undo max ?newmax?
	Returns or modifies the maximum size of the undo list to newmax. Supplying a value 0 for newmax turns recording of undo information of. If newmax hast been omitted, the command returns the current maximum size of the undo list.
undo size
	Returns the current number of entries available in the undo list.
undo clear
	Removes all entries from the undo list.
undo begin ?name?
	Starts a new undo transaction. All undo information will be added to this transaction until the next pcrmundo end command is encountered. If name is provided, it will be used to describe the transaction. If name is omitted, the default actions will be used.
undo end
	Terminates the current set of undo operations.
changed ?count?
	Retrieve or set the number of changes for the current document. If count has been omitted, the number of changes to the contents of the sgml widget is returned. If count is supplied, the number of changes is set to this value.

21.1 Reverting the last operation

The simplest form of the pcrmundo widget command is

pathname undo

where pathname is the name of the sgml widget which should process the pcrmundo command.

This form of the command reverts the last changes made to the content of the sgml widget and removes the corresponding information from the undo list.

If an pcrmundo begin operation (see section  for details) is in progress (or has just been terminated with an pcrmundo end command and no other undo-able operations have occurred since then), all operations belonging to the current transaction are undone.

Notification commands (see chapter ) will be invoked during undo operation. For example, if an element is deleted and later re-inserted by an undo operation, the undo operation will invoke the insert notification command with a reference to the re-inserted element.

The widget sets the global variable TkSGML(undo) to the value 1 while it is performing an undo operation; it resets this variable to 0 after the undo operation has been completed. This behaviour can be exploited in notification commands, e.g. to determine if a new element is created or if an element is re-inserted by the pcrmundo command.

21.2 Grouping undo information

It is sometimes convenient to revert the effects of several consecutive commands in one step. An example for this situation is the key binding for normal characters that will erase the current selection (first operation) and insert the character at the location of the selection (second operation).

Invoking the undo function immediately after these operations should remove the newly inserted character and restore the previous selection and the selected text.

To achieve this effect, the sgml widget allows to combine the undo information for several successive commands into a single undo operation. We use the term transaction (borrowed from database terminology) for a combination of this kind.

A transaction is collection of undo information for an arbitrary number of operations. Each transaction forms single entry in the undo list. Invoking the pcrmundo command reverts all operations that are stored in the transaction.

Transactions are started with the pcrmundo begin command which has the following syntax:

pathname undo begin ?name?

The command takes an optional parameter name that is used to describe the transaction and that will be returned by the pcrmundo type command when the transaction is at the top of the undo list.

After a transaction has been started by the pcrmundo begin command, all operations that occur up to the next pcrmundo end command will be added to the undo transaction. If the pcrmundo command is invoked, all operations in the transcation will be reverted and the transaction will be removed from the undo list.

An undo transaction is terminated by the command pcrmundo end which has the following syntax:

pathname undo end

Any undo information that will be added after an pcrmundo end command will again be added directly to the undo list. If no actions have occurred between the pcrmundo begin and pcrmundo end commands, the transaction will be discarded.

Undo transactions ignore the maximum size setting for the undo list; i.e. an undo transaction can contain any number of operations. The transaction itself is counted as a single entry in the undo list.

The following example procedure inserts a new element ename into the sgml widget w. It accepts a list of attriute-value pairs in args and sets each attribute to the corresponding value. The procedures reverts all modifications if any of these steps fails.

The procedure shown above starts an undo transaction before it performs any manipulations of the widget contents. If any errors are encountered by the procedure, it issues an pcrmundo command to revert all changes so far. If no errors occur, the procedure terminates the undo transaction so that a later invocation of the pcrmundo command will remove the newly inserted element.^21.1

It is important to notice that the procedure terminates the undo transaction before it reports an error. Failing to terminate the transaction would add all subsequent actions to the still-open undo transaction. If an pcrmundo command is issued later, it would revert all changes that have occured since the invocation of the procedure.

The maximum number of entries in the list can be defined Whenever one of the operations

To undo the last operation that has been performed, the pcrmundo command can be used.

Undo functionality is limited to operations that affect the widget contents. Annotation or configuration commands can not be undone.

Footnotes

... element.^21.1

A procedure of this kind can be useful in customized environments where attribute values are known in advance for newly inserted elements.