"Fossies" - the Fresh Open Source Software Archive

Member "gimp-2.10.28/devel-docs/undo.txt" (14 Sep 2021, 3602 Bytes) of package /linux/misc/gimp-2.10.28.tar.bz2:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    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