Undo and Redo
=============

Scintilla has multiple level undo and redo. It will continue to collect undoable
actions until memory runs out. Scintilla saves actions that change the document.
Scintilla does not save caret and selection movements, view scrolling and the
like. Sequences of typing or deleting are compressed into single transactions to
make it easier to undo and redo at a sensible level of detail. Sequences of
actions can be combined into transactions that are undone as a unit. These
sequences occur between :meth:`~gtkscintilla.Scintilla.begin_undo_action` and :meth:`~gtkscintilla.Scintilla.end_undo_action` methods.
These transactions can be nested and only the top-level sequences are undone as
units.

.. method:: gtkscintilla.Scintilla.undo()

.. method:: gtkscintilla.Scintilla.can_undo()

:meth:`~gtkscintilla.Scintilla.undo` undoes one action, or if the undo buffer has
reached a :meth:`~gtkscintilla.Scintilla.end_undo_action` point, all the actions back to the corresponding
:meth:`~gtkscintilla.Scintilla.begin_undo_action`.

:meth:`~gtkscintilla.Scintilla.can_undo` returns *False* if there is nothing to undo, and *True* if there is. You would
typically use the result of this message to enable/disable the Edit menu Undo
command.

.. method:: gtkscintilla.Scintilla.redo()

undoes the effect of the last :meth:`~gtkscintilla.Scintilla.undo` operation.

.. method:: gtkscintilla.Scintilla.can_redo()

:returns *False* if there is no action to redo and *True* if there are undo
actions to redo. You could typically use the result of this message to
enable/disable the Edit menu Redo command.

.. method:: gtkscintilla.Scintilla.empty_undo_buffer()

This command tells Scintilla to forget any saved undo or
redo history. It also sets the save point to the start of the undo buffer, so
the document will appear to be unmodified. This does not cause the
*save-point-reached* notification to be sent to the container.

See also: :meth:`~gtkscintilla.Scintilla.set_save_point`

.. method:: gtkscintilla.Scintilla.set_undo_collection(collectUndo) 

.. method:: gtkscintilla.Scintilla.get_undo_collection() 

You can control whether Scintilla collects undo information with :meth:`~gtkscintilla.Scintilla.set_undo_collection`. Pass in True to collect information and False to stop collecting. If you stop
collection, you should also use :meth:`~gtkscintilla.Scintilla.empty_undo_buffer`
to avoid the undo buffer
being unsynchronized with the data in the buffer.

You might wish to turn off saving undo information if you use the Scintilla to
store text generated by a program (a Log view) or in a display window where text
is often deleted and regenerated.

.. method:: gtkscintilla.Scintilla.begin_undo_action()

.. method:: gtkscintilla.Scintilla.end_undo_action()

Send these two messages to Scintilla to
mark the beginning and end of a set of operations that you want to undo all as
one operation but that you have to generate as several operations.
Alternatively, you can use these to mark a set of operations that you do not
want to have combined with the preceding or following operations if they are
undone. 

.. method:: gtkscintilla.Scintilla.add_undo_action(token, flags) 

The container can add its own actions
into the undo stack by calling :meth:`~gtkscintilla.Scintilla.add_undo_action` and an *modified*
notification will be sent to the container with the SC_MOD_CONTAINER flag when
it is time to undo (SC_PERFORMED_UNDO) or redo (SC_PERFORMED_REDO) the action.
The token argument supplied is returned in the token field of the notification.

For example, if the container wanted to allow undo and redo of a 'toggle
bookmark' command then it could call :meth:`~gtkscintilla.Scintilla.add_undo_action` (line, 0) each time the
command is performed. Then when it receives a notification to undo or redo it
toggles a bookmark on the line given by the token field. If there are different
types of commands or parameters that need to be stored into the undo stack then
the container should maintain a stack of its own for the document and use the
current position in that stack as the argument to :meth:`~gtkscintilla.Scintilla.add_undo_action` (line).
:meth:`~gtkscintilla.Scintilla.add_undo_action` commands are not combined together into a single undo
transaction unless grouped with :meth:`~gtkscintilla.Scintilla.begin_undo_action` and :meth:`~gtkscintilla.Scintilla.end_undo_action`.

The flags argument can be UNDO_MAY_COALESCE (1) if the container action may be
coalesced along with any insertion and deletion actions into a single compound
action, otherwise 0. Coalescing treats coalescible container actions as
transparent so will still only group together insertions that look like typing
or deletions that look like multiple uses of the Backspace or Delete keys.