Adding upstream version 2.10.34.upstream/2.10.34upstream

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 73 insertions, 0 deletions

diff --git a/devel-docs/undo.txt b/devel-docs/undo.txt
new file mode 100644
index 0000000..03457a3
--- /dev/null
+++ b/devel-docs/undo.txt
@@ -0,0 +1,73 @@
+A quick overview of the undo system
+-----------------------------------
+
+Actions on the image by the user are pushed onto an undo stack.  Each
+action object includes all the information needed to undo or redo an
+operation, plus an UndoType.  The type can be converted to text to
+show to the user.  Actions may be run forwards (UndoState == REDO) or
+backwards (UndoState == UNDO).  As the action is run, it swaps the
+image's current state and the recorded state.  A run action is moved
+from the undo stack to the redo stack (or vice-versa if UndoState ==
+REDO).  Pushing something onto the undo stack causes the redo stack to
+be cleared, since the actions on the redo stack may depend on the
+image being in a particular state (eg consider: layer add, rename,
+undo rename, layer delete.  If the redo stack weren't cleared on undo,
+then there would still be a "rename" operation on the redo stack which
+could be run on a non-existent layer.  Bad news.)
+
+Undo groups
+-----------
+In order to group many basic operations together into a more useful
+whole, code can push group start and end markers.  A group is treated
+as a single action for the purposes of the undo and redo user
+commands.  It is legal to nest groups, in which case the outermost
+group is the only user-visible one.
+
+Groups boundaries used to be implemented by pushing a NULL pointer on
+the undo (or redo) stack.  Now they are a special action which has the
+"group_boundary" bit set.  This allows the group boundaries to include
+the undo type associated with the whole group.  The individual actions
+need to preserve their own undo type since the undo_free_* functions
+sometimes need to know which action is being freed.
+
+Undo events
+-----------
+Images emit UNDO_EVENT signals, to say that the user has performed an
+undo or redo action on that image.  This allows interested parties to
+track image mutation actions.  So far, only the undo history dialog
+uses this feature.  The other way to discover the undo status of an
+image is to use the iterator functions undo_map_over_undo_stack() and
+undo_map_over_redo_stack().  These call your function on each action
+(or group) on the stack.  There is also undo_get_undo_name() and
+undo_get_redo_name() to peek at the top items on each stack.  This
+could be used (eg) to change the undo/redo menu strings to something
+more meaningful, but currently lack synchronisation.
+
+Dirtying images
+---------------
+NOTE about the gimage->dirty counter:
+  If 0, then the image is clean (ie, copy on disk is the same as the one 
+      in memory).
+  If positive, then that's the number of dirtying operations done
+      on the image since the last save.
+  If negative, then user has hit undo and gone back in time prior
+      to the saved copy.  Hitting redo will eventually come back to
+      the saved copy.
+  The image is dirty (ie, needs saving) if counter is non-zero.
+  If the counter is around 10000, this is due to undo-ing back
+  before a saved version, then mutating the image (thus destroying
+  the redo stack).  Once this has happened, it's impossible to get
+  the image back to the state on disk, since the redo info has been
+  freed.  See undo.c for the gorey details.
+
+NEVER CALL gimp_image_dirty() directly!
+
+If your code has just dirtied the image, push an undo instead.
+Failing that, push the trivial undo which tells the user the
+command is not undoable: undo_push_cantundo() (But really, it would
+be best to push a proper undo).  If you just dirty the image
+without pushing an undo then the dirty count is increased, but
+popping that many undo actions won't lead to a clean image.
+
+Austin
+