README.UNDO

   1 Some notes on supporting Undo/Redo when implementing new commands
   2 -----------------------------------------------------------------
   3
   4   All the editor commands that modify something in the HTML document
   5 must support undo and redo.  Otherwise, it will break undo/redo for
   6 all the other commands too, as undo/redo operations assume that the
   7 document is in exactly the same state as it was before the action was
   8 done/undone.
   9
  10   First of all, make sure the function implementing the action calls
  11 the following function before doing any modifications to the document:
  12
  13         html_undo_discard_redo (engine->undo);
  14
  15 This will destroy the redo list, and is necessary because a "redo"
  16 makes sense only if the previous modifying operation was an "undo"; as
  17 the editor has no way to know whether the command will modify the
  18 document or not, you have to do this yourself when needed.
  19
  20   Then, you have to make sure you provide an undo action after the
  21 operation is done.  Undo actions are defined by the `HTMLUndoAction'
  22 object, which is created through the function `html_undo_action_new()'
  23 defined in `htmlundo-action.h':
  24
  25         typedef void (* HTMLUndoActionFunction) (HTMLEngine *engine,
  26                                                  gpointer closure);
  27         typedef void (* HTMLUndoActionClosureDestroyFunction)
  28                                                 (gpointer closure);
  29
  30
  31         HTMLUndoAction *
  32         html_undo_action_new (const gchar *description,
  33                               HTMLUndoActionFunction undo_function,
  34                               HTMLUndoActionClosureDestroyFunction
  35                                       closure_destroy_function,
  36                               gpointer closure,
  37                               gint position);
  38
  39 The meaning of the parameters is as follows:
  40
  41     - The `undo_function' is the function that will physically perform
  42       the action.
  43
  44     - The `closure' is an arbitrary pointer that will be passed to
  45       this function as the second parameter.
  46
  47     - The `closure_destroy_function' is a function that will be called
  48       when the action is destroyed: the purpose is to let you free the
  49       information associated with the action when the action itself is
  50       freed.
  51
  52     - `position' is the absolute cursor position to restore before
  53       calling the `undo_function'.  Normally you will want to use the
  54       value returned by `html_cursor_get_position (engine->cursor)'.
  55
  56   After creating a suitable `HTMLUndo' object, you can add it to the
  57 undo list by using the following function, defined in `htmlundo.h':
  58
  59         void html_undo_add_undo_action (HTMLUndo *undo,
  60                                         HTMLUndoAction *action);
  61
  62   The `HTMLUndo' object associated with the editor can be retrieved
  63 from the `HTMLEngine' struct: it's simply called `undo'.  So, the
  64 normal way to add an undo action is:
  65
  66         html_undo_add_undo_action (engine->undo, action);
  67
  68   Before returning from the `undo_function', you must also add a
  69 corresponding redo action to the redo list.  The redo action should
  70 undo what the undo function has done, and is defined by the same
  71 `HTMLUndo' object that defines undo actions.  In order to add the
  72 action to the redo list instead of the undo list, use
  73 `html_undo_add_redo_action()' instead of
  74 `html_undo_add_undo_action()':
  75
  76         html_undo_add_redo_action (engine->undo, action);
  77