"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
the uninterpreted source code file.
1 A quick overview of the undo system
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.)
18 Undo groups
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.
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.
33 Undo events
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.
46 Dirtying images
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.
63 NEVER CALL gimp_image_dirty() directly!
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.