When running a script within UndoMode.AUTO_UNDO, ID will add the script's undo to the previous undo item on the undo stack. If there is no previous undo item on the stack, it appears that you will not be able to undo your script's action.
For example, after you manually create a new rectangle, Edit > Undo displays "Undo Add New Item".
If you then run script (while in auto undo mode) that turns off the visibiltiy of a layer, Edit > Undo will still display "Undo Add New Item"--even after your script has run.
If you do the Edit > Undo ("Undo Add New Item") after your script has run, not only will the creation of the new rectangle be undone, so will your layer settings. The undo for the layer settings will happen along with the previously created undo.
Here's a script that you can run after you create a new rectangle (or whatever) and see how it does not affect the top item of the undo stack after it is run. After running the script below, you will see that the script's changes are undone with along with the previous undo.
I hope this helps!
Jim, thank you!
It's clear now, albeit seems quite a strange feature to have. Can't realy think of a usefull thing to to with it.
Anyway, thank you.
The feature is nice when you want a script to do something extra at the end of some built-in command.
For example, automatically adding a script label to a page item when it is moved. With the auto-undo mode, the user won't see "Undo Set Scripting Tag" in the Undo menu after the item is moved—the Undo menu will only display the original "Undo Move Item" item. And choosing this item will undo the move and the script label you added.