2.4.5 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.