Copyright and License information Home

__ A B C D E F G H I L M P R S T U V W

### wxStyledTextCtrl - Undo

- BeginUndoAction
- CanUndo
- CanRedo
- EmptyUndoBuffer
- EndUndoAction
- GetUndoCollection
- Redo
- SetUndoCollection
- Undo

Summary:

The STC has a very flexible undo/redo facility. Here's a somewhat simplified explanation about its workings.

Each Document is a CellBuffer, which actually holds the textual content and styling information. Two methods of CellBuffer, InsertString and DeleteChars, are where all text modifications occur. These methods collect information on the type of action (insertAction or removeAction), the position of the changes and the characters added or deleted. Note that styling information is not preserved for undo. After each action, a startAction action is used to separate one action from the next. Each action is sent to the undo history class instance for storage.

The undo history will combine groups of contiguous insertions or single-character deletions from the same position (but not combinations of insertions and deletions) into one action, as long as the current action isn't a savepoint. In Scintilla terminology, this is called coalescing. If insertions or deletions are being coalesced, then the startAction at the undo pointer is overwritten with the insertAction or removeAction followed by a new startAction, as shown in the following example. For more information, examine the Scintilla source code file CellBuffer.cxx and look at UndoHistory::AppendAction().

The BeginUndoAction method increments an internal sequence-depth variable and adds a new non-coalesceable startAction action into the undo history; ending any possible coalescing for the current user operation. The matching EndUndoAction method decrements the sequence-depth. These two methods nest so that you can have undo 'levels'. Furthermore, ALL inserts and deletes when the sequence-depth is nonzero (when inside a BeginUndoAction/EndUndoAction pair) are coalesced within that level. In other words, every time you use BeginUndoAction, all the actions are coalesced into one group until you do EndUndoAction or another BeginUndoAction.

Sounds a little confusing, doesn't it? Here's a quote from the source code that may help: "As each action is performed, it is recorded in the undo history. The action may either become part of the current user operation or may start a new user operation. If it is to be part of the current operation, then it overwrites the current last action. If it is to be part of a new operation, it is appended after the current last action. After writing the new action, a new start action is appended at the end of the history. The decision of whether to start a new user operation is based upon two factors. If a compound operation has been explicitly started by calling BeginUndoAction and no matching EndUndoAction (these calls nest) has been called, then the action is coalesced into the current operation. If there is no outstanding BeginUndoAction call then a new operation is started unless it looks as if the new action is caused by the user typing or deleting a stream of text. Sequences that look like typing or deletion are coalesced into a single user operation."

CanUndo indicates whether there's any undo information to use at all (useful to enable a menu item or toolbar button) and CanRedo indicate whether or not there's been something undone so that redo can be performed. CanRedo is also useful for GUI element enabling.

BeginUndoAction()

Begins a nested group of coalesced actions: actions undone or redone as a unit. If the current action isn't a startAction, creates a new startAction and increments the sequence-depth variable. All insert and delete actions within a nested set of BeginUndoAction and EndUndoAction calls are coalesced into one action. Returns None.

top

CanUndo()

Returns 1 if the document isn't read only and there are actions recorded in the undo history.

top

CanRedo()

Returns 1 if there has been some undo operations performed with no intervening Actions recorded. For example, if you delete a few characters, then perform an undo, CanRedo would return 1. If you type a few more characters, then try CanRedo again, you'd get a return value of 0 since Redo is no longer possible.

top

EmptyUndoBuffer()

This method deletes the undo history, if any. It destroys all stored Actions, then initializes the undo history instance with a startAction. Returns None.

top

EndUndoAction()

Ends a nested group of coalesced actions. Returns None. See BeginUndoAction

top

GetUndoCollection()

Returns 1 if undo information is being recorded or 0 if it is not.

top

Redo()

Redo a previously-undone operation from the undo history. Has protection against recursion. Returns None. Will usually cause a MODIFIED event to be emitted if you have executed a EVT_STC_MODIFIED statement. May also cause a SAVEPOINTREACHED or SAVEPOINTLEFT event if you have executed EVT_STC_SAVEPOINTREACHED or EVT_STC_SAVEPOINTLEFT statements, respectively.

top

SetUndoCollection(collectUndo)

This method is used to activate (collectUndo = 1) or deactivate (collectUndo = 0) the collection of undoable actions. Returns None. Has the side effect of cancelling all nested undo sequences that might have been initiated by BeginUndoAction. This side effect occurs regardless of the state of the collectUndo argument.

top

Undo()

Undoes previously performed actions recorded in the undo history. Has protection against recursion. Returns None. Will usually cause a MODIFIED event to be emitted if you have executed a EVT_STC_MODIFIED statement. May also cause a SAVEPOINTREACHED or SAVEPOINTLEFT event if you have executed EVT_STC_SAVEPOINTREACHED or EVT_STC_SAVEPOINTLEFT statements, respectively.

top