devel-docs/undo.txt

   1 A quick overview of the undo system
   2 -----------------------------------
   3
   4 Actions on the image by the user are pushed onto an undo stack.  Each
   5 action object includes all the information needed to undo or redo an
   6 operation, plus an UndoType.  The type can be converted to text to
   7 show to the user.  Actions may be run forwards (UndoState == REDO) or
   8 backwards (UndoState == UNDO).  As the action is run, it swaps the
   9 image's current state and the recorded state.  A run action is moved
  10 from the undo stack to the redo stack (or vice-versa if UndoState ==
  11 REDO).  Pushing something onto the undo stack causes the redo stack to
  12 be cleared, since the actions on the redo stack may depend on the
  13 image being in a particular state (eg consider: layer add, rename,
  14 undo rename, layer delete.  If the redo stack weren't cleared on undo,
  15 then there would still be a "rename" operation on the redo stack which
  16 could be run on a non-existent layer.  Bad news.)
  17
  18 Undo groups
  19 -----------
  20 In order to group many basic operations together into a more useful
  21 whole, code can push group start and end markers.  A group is treated
  22 as a single action for the purposes of the undo and redo user
  23 commands.  It is legal to nest groups, in which case the outermost
  24 group is the only user-visible one.
  25
  26 Groups boundaries used to be implemented by pushing a NULL pointer on
  27 the undo (or redo) stack.  Now they are a special action which has the
  28 "group_boundary" bit set.  This allows the group boundaries to include
  29 the undo type associated with the whole group.  The individual actions
  30 need to preserve their own undo type since the undo_free_* functions
  31 sometimes need to know which action is being freed.
  32
  33 Undo events
  34 -----------
  35 Images emit UNDO_EVENT signals, to say that the user has performed an
  36 undo or redo action on that image.  This allows interested parties to
  37 track image mutation actions.  So far, only the undo history dialog
  38 uses this feature.  The other way to discover the undo status of an
  39 image is to use the iterator functions undo_map_over_undo_stack() and
  40 undo_map_over_redo_stack().  These call your function on each action
  41 (or group) on the stack.  There is also undo_get_undo_name() and
  42 undo_get_redo_name() to peek at the top items on each stack.  This
  43 could be used (eg) to change the undo/redo menu strings to something
  44 more meaningful, but currently lack synchronisation.
  45
  46 Dirtying images
  47 ---------------
  48 NOTE about the gimage->dirty counter:
  49   If 0, then the image is clean (ie, copy on disk is the same as the one
  50       in memory).
  51   If positive, then that's the number of dirtying operations done
  52       on the image since the last save.
  53   If negative, then user has hit undo and gone back in time prior
  54       to the saved copy.  Hitting redo will eventually come back to
  55       the saved copy.
  56   The image is dirty (ie, needs saving) if counter is non-zero.
  57   If the counter is around 10000, this is due to undo-ing back
  58   before a saved version, then mutating the image (thus destroying
  59   the redo stack).  Once this has happened, it's impossible to get
  60   the image back to the state on disk, since the redo info has been
  61   freed.  See undo.c for the gorey details.
  62
  63 NEVER CALL gimp_image_dirty() directly!
  64
  65 If your code has just dirtied the image, push an undo instead.
  66 Failing that, push the trivial undo which tells the user the
  67 command is not undoable: undo_push_cantundo() (But really, it would
  68 be best to push a proper undo).  If you just dirty the image
  69 without pushing an undo then the dirty count is increased, but
  70 popping that many undo actions won't lead to a clean image.
  71
  72 Austin
  73