Inspecting NSUndoManager's undo stack

I had trouble understanding NSUndoManager and its retain policy so I wrote some code, and then I was enlightened :) There's a great article on that explains the concepts, so I won't go into detail - check the code out.

Two methods and their retain behaviours

When doing an undoable action, you register in NSUndoManager a method than undoes what you just did. It will be called when undoing. Depending on your method's arguments, call one of these :

  • registerUndoWithTarget registers a call with one ObjC object as parameter
  • prepareWithInvocationTarget registers a call with multiple parameters, even non ObjC objects like NSPoint

If you set a value from 4 to 5, register in the undomanager a call to set the value to 4, then set it to 5. If you add an object with addObject:, register a call to removeObject:. That's really all there is to it.

prepareWithInvocationTarget and registerUndoWithTarget both retain their arguments. Each undoable change ups the retain count. So when moving an object around, the retain count will go up at each position change. Don't worry if an object reaches a retain count of 30. Clearing the undo stack gets the retain count back to its initial value.

Peering through NSUndoManager

NSUndoManager does not offer any public way to view its undo and redo stacks. Thanks to F-Script, we can see that it has an undocumented _undoStack method, but nothing for the redo stack. NSUndoManager's header file shows 2 instance variables _redoStack and _undoStack. We'll fetch these with object_getInstanceVariable and call description on them, which dumps their contents.

Undoing adding and removing of objects in an NSArray

Storing objects in an array ups their retain count. Create an object (count=1), add it in an array (count=2). If you don't release the object (count=1) after adding it to the array, NSUndoManager will restore the object to its original retain count (1) when disposing of it, thus it will never be released. This is fine if you overload your objects' release method and plan on pooling them. If not, release your objects after adding them to the array or they will stick around forever.

Sample code

Image:iconZip.png Undo

Florent Pillet
2008 06 23

An alternate (quick and easy) way of accessing private ivars is to use KVC, in particular -valueForKey: and -setValue:forKey: . Although some classes may trap this, most don't and it's a very useful technique that I use often (actually I used it too while in gdb console to inspect NSUndoManager stacks).

Patrick Geiller
2008 06 23

Just tried NSUndoManager's valueForKey:@"_undoStack" and it works like a charm. Great tip, merci bien !

Follow me on Twitter
Planet Cocoa

2011 02 22Distance field
2010 07 202Binding through NSApp
2010 05 122Forwarding invocations
2010 02 272Core Image black fringes
2010 02 21Quickest Way to Shell
2010 02 08Who's calling ?
2009 09 2138 ways to use Blocks in Snow Leopard
2009 08 182Bracket Mess
2009 08 124Taming JavascriptCore within and without WebView
2009 04 15Debugging with Activity Monitor
2009 03 25How Core Image Color Tracking works
2009 03 1510Custom NSThemeFrame
2009 03 10Which framework is running ?
2009 03 074CoreUI can paint pretty big
2009 02 18Localization with functions
2009 01 30Did you forget to nest alloc and init?
2009 01 16JSCocoa on the iPhone
2009 01 11Mixing WebView and JavascriptCore
2009 01 09Badge overflow
2009 01 09Find your Garbage Collection leaks with Instruments

Powered by MediaWiki