diff options
author | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:19:15 +0300 |
---|---|---|
committer | Campbell Barton <ideasman42@gmail.com> | 2021-12-07 09:38:48 +0300 |
commit | ffc4c126f5416b04a01653e7a03451797b98aba4 (patch) | |
tree | ac63d70d33aae5ab1666c9c2f62058c9c1eebd5c /source/blender/blenkernel/BKE_undo_system.h | |
parent | f159d49f56cedccd509ee93f5a5fb51f4f39eeb8 (diff) |
Cleanup: move public doc-strings into headers for 'blenkernel'
- Added space below non doc-string comments to make it clear
these aren't comments for the symbols directly below them.
- Use doxy sections for some headers.
- Minor improvements to doc-strings.
Ref T92709
Diffstat (limited to 'source/blender/blenkernel/BKE_undo_system.h')
-rw-r--r-- | source/blender/blenkernel/BKE_undo_system.h | 98 |
1 files changed, 95 insertions, 3 deletions
diff --git a/source/blender/blenkernel/BKE_undo_system.h b/source/blender/blenkernel/BKE_undo_system.h index 2a90211f8e0..bd005af8390 100644 --- a/source/blender/blenkernel/BKE_undo_system.h +++ b/source/blender/blenkernel/BKE_undo_system.h @@ -172,6 +172,10 @@ typedef enum eUndoTypeFlags { } eUndoTypeFlags; /* Expose since we need to perform operations on specific undo types (rarely). */ +/** \name Public Undo Types + * + * Unfortunately we need this for a handful of places. + * \{ */ extern const UndoType *BKE_UNDOSYS_TYPE_IMAGE; extern const UndoType *BKE_UNDOSYS_TYPE_MEMFILE; extern const UndoType *BKE_UNDOSYS_TYPE_PAINTCURVE; @@ -185,11 +189,17 @@ UndoStack *BKE_undosys_stack_create(void); void BKE_undosys_stack_destroy(UndoStack *ustack); void BKE_undosys_stack_clear(UndoStack *ustack); void BKE_undosys_stack_clear_active(UndoStack *ustack); +/* name optional */ bool BKE_undosys_stack_has_undo(const UndoStack *ustack, const char *name); void BKE_undosys_stack_init_from_main(UndoStack *ustack, struct Main *bmain); +/* called after 'BKE_undosys_stack_init_from_main' */ void BKE_undosys_stack_init_from_context(UndoStack *ustack, struct bContext *C); UndoStep *BKE_undosys_stack_active_with_type(UndoStack *ustack, const UndoType *ut); UndoStep *BKE_undosys_stack_init_or_active_with_type(UndoStack *ustack, const UndoType *ut); +/** + * \param steps: Limit the number of undo steps. + * \param memory_limit: Limit the amount of memory used by the undo stack. + */ void BKE_undosys_stack_limit_steps_and_memory(UndoStack *ustack, int steps, size_t memory_limit); #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) @@ -197,13 +207,18 @@ void BKE_undosys_stack_limit_steps_and_memory(UndoStack *ustack, int steps, size void BKE_undosys_stack_group_begin(UndoStack *ustack); void BKE_undosys_stack_group_end(UndoStack *ustack); -/* Only some UndoType's require init. */ +/** + * Only some UndoType's require init. + */ UndoStep *BKE_undosys_step_push_init_with_type(UndoStack *ustack, struct bContext *C, const char *name, const UndoType *ut); UndoStep *BKE_undosys_step_push_init(UndoStack *ustack, struct bContext *C, const char *name); +/** + * \param C: Can be NULL from some callers if their encoding function doesn't need it + */ eUndoPushReturn BKE_undosys_step_push_with_type(UndoStack *ustack, struct bContext *C, const char *name, @@ -216,40 +231,117 @@ UndoStep *BKE_undosys_step_find_by_name_with_type(UndoStack *ustack, UndoStep *BKE_undosys_step_find_by_type(UndoStack *ustack, const UndoType *ut); UndoStep *BKE_undosys_step_find_by_name(UndoStack *ustack, const char *name); +/** + * Return direction of the undo/redo from `us_reference` (or `ustack->step_active` if NULL), and + * `us_target`. + * + * \note If `us_reference` and `us_target` are the same, we consider this is an undo. + * + * \return -1 for undo, 1 for redo, 0 in case of error. + */ eUndoStepDir BKE_undosys_step_calc_direction(const UndoStack *ustack, const UndoStep *us_target, const UndoStep *us_reference); +/** + * Undo/Redo until the given `us_target` step becomes the active (currently loaded) one. + * + * \note Unless `us_target` is a 'skipped' one and `use_skip` is true, `us_target` + * will become the active step. + * + * \note In case `use_skip` is true, the final target will always be **beyond** the given one + * (if the given one has to be skipped). + * + * \param us_reference: If NULL, will be set to current active step in the undo stack. Otherwise, + * it is assumed to match the current state, and will be used as basis for the undo/redo process + * (i.e. all steps in-between `us_reference` and `us_target` will be processed). + */ bool BKE_undosys_step_load_data_ex(UndoStack *ustack, struct bContext *C, UndoStep *us_target, UndoStep *us_reference, const bool use_skip); +/** + * Undo/Redo until the given `us_target` step becomes the active (currently loaded) one. + */ bool BKE_undosys_step_load_data(UndoStack *ustack, struct bContext *C, UndoStep *us_target); +/** + * Undo/Redo until the step matching given `index` in the undo stack becomes the active + * (currently loaded) one. + */ void BKE_undosys_step_load_from_index(UndoStack *ustack, struct bContext *C, const int index); +/** + * Undo until `us_target` step becomes the active (currently loaded) one. + * + * \warning This function assumes that the given target step is _before_ current active one. + * + * \note Unless `us_target` is a 'skipped' one and `use_skip` is true, + * `us_target` will become the active step. + * + * \note In case `use_skip` is true, the final target will always be **before** the given one + * (if the given one has to be skipped). + */ bool BKE_undosys_step_undo_with_data_ex(UndoStack *ustack, struct bContext *C, UndoStep *us, bool use_skip); +/** + * Undo until `us_target` step becomes the active (currently loaded) one. + * + * \note See #BKE_undosys_step_undo_with_data_ex for details. + */ bool BKE_undosys_step_undo_with_data(UndoStack *ustack, struct bContext *C, UndoStep *us_target); +/** + * Undo one step from current active (currently loaded) one. + */ bool BKE_undosys_step_undo(UndoStack *ustack, struct bContext *C); +/** + * Redo until `us_target` step becomes the active (currently loaded) one. + * + * \warning This function assumes that the given target step is _after_ current active one. + * + * \note Unless `us_target` is a 'skipped' one and `use_skip` is true, + * `us_target` will become the active step. + * + * \note In case `use_skip` is true, the final target will always be **after** the given one + * (if the given one has to be skipped). + */ bool BKE_undosys_step_redo_with_data_ex(UndoStack *ustack, struct bContext *C, UndoStep *us, bool use_skip); +/** + * Redo until `us_target` step becomes the active (currently loaded) one. + * + * \note See #BKE_undosys_step_redo_with_data_ex for details. + */ bool BKE_undosys_step_redo_with_data(UndoStack *ustack, struct bContext *C, UndoStep *us_target); +/** + * Redo one step from current active one. + */ bool BKE_undosys_step_redo(UndoStack *ustack, struct bContext *C); +/** + * Useful when we want to diff against previous undo data but can't be sure the types match. + */ UndoStep *BKE_undosys_step_same_type_next(UndoStep *us); +/** + * Useful when we want to diff against previous undo data but can't be sure the types match. + */ UndoStep *BKE_undosys_step_same_type_prev(UndoStep *us); -/* Type System */ +/* Type System. */ + +/** + * Similar to #WM_operatortype_append + */ UndoType *BKE_undosys_type_append(void (*undosys_fn)(UndoType *)); void BKE_undosys_type_free_all(void); -/* ID Accessor */ +/* ID Accessor. */ + #if 0 /* functionality is only used internally for now. */ void BKE_undosys_foreach_ID_ref(UndoStack *ustack, UndoTypeForEachIDRefFn foreach_ID_ref_fn, |