GNU Info

(readline.info)Allowing Undoing

---

Next: Redisplay Prev: Associating Function Names and Bindings Up: Readline Convenience Functions

---

Enter node , (file) or (file)node

Allowing Undoing
----------------

   Supporting the undo command is a painless thing, and makes your
functions much more useful.  It is certainly easy to try something if
you know you can undo it.

   If your function simply inserts text once, or deletes text once, and
uses `rl_insert_text()' or `rl_delete_text()' to do it, then undoing is
already done for you automatically.

   If you do multiple insertions or multiple deletions, or any
combination of these operations, you should group them together into
one operation.  This is done with `rl_begin_undo_group()' and
`rl_end_undo_group()'.

   The types of events that can be undone are:

     enum undo_code { UNDO_DELETE, UNDO_INSERT, UNDO_BEGIN, UNDO_END };

   Notice that `UNDO_DELETE' means to insert some text, and
`UNDO_INSERT' means to delete some text.  That is, the undo code tells
what to undo, not how to undo it.  `UNDO_BEGIN' and `UNDO_END' are tags
added by `rl_begin_undo_group()' and `rl_end_undo_group()'.

 - Function: int rl_begin_undo_group (void)
     Begins saving undo information in a group construct.  The undo
     information usually comes from calls to `rl_insert_text()' and
     `rl_delete_text()', but could be the result of calls to
     `rl_add_undo()'.

 - Function: int rl_end_undo_group (void)
     Closes the current undo group started with `rl_begin_undo_group
     ()'.  There should be one call to `rl_end_undo_group()' for each
     call to `rl_begin_undo_group()'.

 - Function: void rl_add_undo (enum undo_code what, int start, int end,
          char *text)
     Remember how to undo an event (according to WHAT).  The affected
     text runs from START to END, and encompasses TEXT.

 - Function: void rl_free_undo_list (void)
     Free the existing undo list.

 - Function: int rl_do_undo (void)
     Undo the first thing on the undo list.  Returns `0' if there was
     nothing to undo, non-zero if something was undone.

   Finally, if you neither insert nor delete text, but directly modify
the existing text (e.g., change its case), call `rl_modifying()' once,
just before you modify the text.  You must supply the indices of the
text range that you are going to modify.

 - Function: int rl_modifying (int start, int end)
     Tell Readline to save the text between START and END as a single
     undo unit.  It is assumed that you will subsequently modify that
     text.