Undo System: support for grouping steps with begin/end calls

This adds support for treating multiple undo steps as a single step
from the user perspective.

This is needed for outliner mode switching and `object.switch_object`
operator which change active object and mode in a single action.

source/blender/blenkernel/BKE_undo_system.h

@@ -70,6 +70,12 @@ typedef struct UndoStack {
    * That is done once end is called.
    */
   struct UndoStep *step_init;
+
+  /**
+   * Keep track of nested group begin/end calls,
+   * within which all but the last undo-step is marked for skipping.
+   */
+  int group_level;
 } UndoStack;
 
 typedef struct UndoStep {
@@ -156,6 +162,9 @@ void BKE_undosys_stack_limit_steps_and_memory(UndoStack *ustack, int steps, size
 #define BKE_undosys_stack_limit_steps_and_memory_defaults(ustack) \
   BKE_undosys_stack_limit_steps_and_memory(ustack, U.undosteps, (size_t)U.undomemory * 1024 * 1024)
 
+void BKE_undosys_stack_group_begin(UndoStack *ustack);
+void BKE_undosys_stack_group_end(UndoStack *ustack);
+
 /* Only some UndoType's require init. */
 UndoStep *BKE_undosys_step_push_init_with_type(UndoStack *ustack,
                                                struct bContext *C,

source/blender/blenkernel/intern/undo_system.c

@@ -580,6 +580,12 @@ bool BKE_undosys_step_push_with_type(UndoStack *ustack,
     }
   }
 
+  if (ustack->group_level > 0) {
+    /* Temporarily set skip for the active step.
+     * This is an invalid state which must be corrected once the last group ends. */
+    ustack->step_active->skip = true;
+  }
+
   undosys_stack_validate(ustack, true);
   return true;
 }
@@ -848,6 +854,45 @@ void BKE_undosys_type_free_all(void)
 
 /** \} */
 
+/* -------------------------------------------------------------------- */
+/** \name Undo Stack Grouping
+ *
+ * This enables skip while group-level is set.
+ * In general it's not allowed that #UndoStack.step_active have 'skip' enabled.
+ *
+ * This rule is relaxed for grouping, however it's important each call to
+ * #BKE_undosys_stack_group_begin has a matching #BKE_undosys_stack_group_end.
+ *
+ * - Levels are used so nesting is supported, where the last call to #BKE_undosys_stack_group_end
+ *   will set the active undo step that should not be skipped.
+ *
+ * - Correct begin/end is checked by an assert since any errors here will cause undo
+ *   to consider all steps part of one large group.
+ *
+ * - Calls to begin/end with no undo steps being pushed is supported and does nothing.
+ *
+ * \{ */
+
+void BKE_undosys_stack_group_begin(UndoStack *ustack)
+{
+  BLI_assert(ustack->group_level >= 0);
+  ustack->group_level += 1;
+}
+
+void BKE_undosys_stack_group_end(UndoStack *ustack)
+{
+  ustack->group_level -= 1;
+  BLI_assert(ustack->group_level >= 0);
+
+  if (ustack->group_level == 0) {
+    if (LIKELY(ustack->step_active != NULL)) {
+      ustack->step_active->skip = false;
+    }
+  }
+}
+
+/** \} */
+
 /* -------------------------------------------------------------------- */
 /** \name ID Reference Utilities
  *

source/blender/editors/include/ED_undo.h

@@ -36,6 +36,9 @@ struct wmOperator;
 struct wmOperatorType;
 
 /* undo.c */
+bool ED_undo_is_state_valid(struct bContext *C);
+void ED_undo_group_begin(struct bContext *C);
+void ED_undo_group_end(struct bContext *C);
 void ED_undo_push(struct bContext *C, const char *str);
 void ED_undo_push_op(struct bContext *C, struct wmOperator *op);
 void ED_undo_grouped_push(struct bContext *C, const char *str);

source/blender/editors/undo/ed_undo.c

@@ -76,6 +76,44 @@ static CLG_LogRef LOG = {"ed.undo"};
  * Non-operator undo editor functions.
  * \{ */
 
+/**
+ * Run from the main event loop, basic checks that undo is left in a correct state.
+ */
+bool ED_undo_is_state_valid(bContext *C)
+{
+  wmWindowManager *wm = CTX_wm_manager(C);
+
+  /* Currently only checks matching begin/end calls. */
+  if (wm->undo_stack == NULL) {
+    /* No undo stack is valid, nothing to do. */
+    return true;
+  }
+  if (wm->undo_stack->group_level != 0) {
+    /* If this fails #ED_undo_grouped_begin, #ED_undo_grouped_end calls don't match. */
+    return false;
+  }
+  if (wm->undo_stack->step_active != NULL) {
+    if (wm->undo_stack->step_active->skip == true) {
+      /* Skip is only allowed between begin/end calls,
+       * a state that should never happen in main event loop. */
+      return false;
+    }
+  }
+  return true;
+}
+
+void ED_undo_group_begin(bContext *C)
+{
+  wmWindowManager *wm = CTX_wm_manager(C);
+  BKE_undosys_stack_group_begin(wm->undo_stack);
+}
+
+void ED_undo_group_end(bContext *C)
+{
+  wmWindowManager *wm = CTX_wm_manager(C);
+  BKE_undosys_stack_group_end(wm->undo_stack);
+}
+
 void ED_undo_push(bContext *C, const char *str)
 {
   CLOG_INFO(&LOG, 1, "name='%s'", str);

source/blender/windowmanager/intern/wm_event_system.c

@@ -3159,6 +3159,7 @@ static void wm_event_free_and_remove_from_queue_if_valid(wmEvent *event)
 void wm_event_do_handlers(bContext *C)
 {
   wmWindowManager *wm = CTX_wm_manager(C);
+  BLI_assert(ED_undo_is_state_valid(C));
 
   /* Update key configuration before handling events. */
   WM_keyconfig_update(wm);