COUndoTrack class documentation
COUndoTrack : NSObject <COTrack>Overview
For a commit done in an editing context, an undo track can be passed using -[COEditingContext commitWithIdentifier:metadata:undoTrack:error:] or similar commit methods. When the commit is saved, the editing context records the commit as a command using -recordCommand: . At this point, the undo track saves the command on disk.
Commits that contain object graph context changes result in new revisions in the store. For other commits that just contain store structure changes:
- branch creation
- branch deletion
- branch undeletion
- branch switch
- branch revision change
- branch metadata editing (e.g. branch renaming)
- persistent root creation
- persistent root deletion
- persistent root undeletion
no new revisions is created. The store doesn't record them in any way.
However an undo track can track both:- store structure history (represented as custom commands e.g. COCommandDeleteBranch etc.)
- branch history (new revisions represented as COCommandSetVersionForBranch)
Undo tracks can track all these changes or a subset per application or per use cases, and provide undo/redo support. For undo/redo menu actions, never manipulate the branch history directly, but use an undo track.
You can navigate the command sequence to change the editing context state using -undo , -redo and -setCurrentNode: . COUndoTrack supports the same history navigation protocol than COBranch. Note that the COUndoTrack implementation (of these COTrack methods) can perform an editing context commit automatically.
You shouldn't subclass COUndoTrack.
Track Access and Creation
- + (COUndoTrack *) trackForName: (NSString *)aName withEditingContext: (COEditingContext *)aContext
Returns the persistent track bound to the given name, or creates it in case it doesn't exist yet.
See -editingContext .
- + (COUndoTrack *) trackForPattern: (NSString *)aPattern withEditingContext: (COEditingContext *)aContext
Returns a non-recordable track that provides a union view over all persistent tracks that match the given pattern.
The returned track must not be passed to commit methods e.g. -[COEditingContext commmitWithIdentitifer:metadata:undoTrack:error:] , otherwise the commit raises an exception.
See -editingContext .
Basic Properties
- - (COEditingContext *) editingContext
The editing context that is changed if -undo , -redo or -setCurrentNode: are called.
- - (NSDictionary *) customRevisionMetadata
If set, COUndoTrack will add these keys/values to the revision metadata when it commits a revision in response to -undo/-redo, or -undoNode:/-redoNode:.
For example, use this if you want to record the user's name in revisions they commit using the undo track.
- - (void) setCustomRevisionMetadata: (NSDictionary *)customRevisionMetadata
If set, COUndoTrack will add these keys/values to the revision metadata when it commits a revision in response to -undo/-redo, or -undoNode:/-redoNode:.
For example, use this if you want to record the user's name in revisions they commit using the undo track.
Clearing and Coalescing Commands
- - (void) beginCoalescing
Tells the receiver to put the next recorded commands in the same command group until -endCoalescing is called.
For the next commits, the track won't create a command group per commit.
By bracketing multiple commits with -beginCoalescing and -endCoalescing , these multiple commits can be recorded as a single one (i.e. a single COCommandGroup) on the track.
Calling -beginCoalescing doesn't change the rules for the branch revision creation on commit.
See also -endCoalescing .
- - (void) endCoalescing
Tells the receiver to group the next recorded commands per commit.
For the next commits, the track will create a command group per commit.
See also -beginCoalescing .
Convenience
- - (NSString *) undoMenuItemTitle
Returns a localized menu item title describing the command to undo.
- - (NSString *) redoMenuItemTitle
Returns a localized menu item title describing the command to redo.
Divergent Commands
- - (NSArray *) childrenOfNode: (id <COTrackNode>)aNode
Returns all commands that are children of the given node (the order is undefined).
Framework Private
- - (void) recordCommand: (COCommandGroup *)aCommand
This method is only exposed to be used internally by CoreObject.
Saves the command on disk and remembers it as the current command.
See also -currentCommand .
- - (COUndoTrackStore *) store
This method is only exposed to be used internally by CoreObject.
Returns the undo track store used by this track.
- - (COCommandGroup *) commandForUUID: (ETUUID *)aUUID
This method is only exposed to be used internally by CoreObject.
Returns a cached command group, or attempts to load it from the store if not present in memory.
