Struct yrs::undo::UndoManager
source · pub struct UndoManager<M>(/* private fields */);
Expand description
Undo manager is a structure used to perform undo/redo operations over the associated shared type(s).
Undo-/redo-able actions (a.k.a. StackItems) are not equivalent to TransactionMut unit of work, but rather a series of updates batched within specified time intervals (see: Options::capture_timeout_millis) and their corresponding origins (see: Doc::transact_mut_with and UndoManager::include_origin).
Individual stack item boundaries can be also specified explicitly by calling UndoManager::reset, which denotes the end of the batch.
In order to revert an operation, call UndoManager::undo, then UndoManager::redo to bring it back.
Users can also subscribe to change notifications observed by undo manager:
- UndoManager::observe_item_added, which is fired every time a new StackItem is created.
- UndoManager::observe_item_updated, which is fired every time when an existing StackItem had been extended due to new document changes arriving before capture timeout for that stack item finished.
- UndoManager::observe_item_popped, which is fired whenever StackItem is being from undo manager as a result of calling either UndoManager::undo or UndoManager::redo method.
Implementations§
source§impl<M> UndoManager<M>where
M: Default + 'static,
impl<M> UndoManager<M>where
M: Default + 'static,
sourcepub fn new<T>(doc: &Doc, scope: &T) -> Self
pub fn new<T>(doc: &Doc, scope: &T) -> Self
Creates a new instance of the UndoManager working in a scope
of a particular shared
type and document. While it’s possible for undo manager to observe multiple shared types
(see: UndoManager::expand_scope), it can only work with a single document at the same time.
pub fn doc(&self) -> &Doc
sourcepub fn with_options<T>(doc: &Doc, scope: &T, options: Options) -> Self
pub fn with_options<T>(doc: &Doc, scope: &T, options: Options) -> Self
Creates a new instance of the UndoManager working in a scope
of a particular shared
type and document. While it’s possible for undo manager to observe multiple shared types
(see: UndoManager::expand_scope), it can only work with a single document at the same time.
sourcepub fn observe_item_added<F>(&self, f: F) -> Subscription
pub fn observe_item_added<F>(&self, f: F) -> Subscription
Registers a callback function to be called every time a new StackItem is created. This usually happens when a new update over an tracked shared type happened after capture timeout threshold from the previous stack item occurence has been reached or UndoManager::reset has been called.
Returns a subscription object which - when dropped - will unregister provided callback.
sourcepub fn observe_item_updated<F>(&self, f: F) -> Subscription
pub fn observe_item_updated<F>(&self, f: F) -> Subscription
Registers a callback function to be called every time an existing StackItem has been extended as a result of updates from tracked types which happened before a capture timeout has passed.
Returns a subscription object which - when dropped - will unregister provided callback.
sourcepub fn observe_item_popped<F>(&self, f: F) -> Subscription
pub fn observe_item_popped<F>(&self, f: F) -> Subscription
Registers a callback function to be called every time an existing StackItem has been removed as a result of UndoManager::undo or UndoManager::redo method.
Returns a subscription object which - when dropped - will unregister provided callback.
sourcepub fn expand_scope<T>(&mut self, scope: &T)
pub fn expand_scope<T>(&mut self, scope: &T)
Extends a list of shared types tracked by current undo manager by a given scope
.
sourcepub fn include_origin<O>(&mut self, origin: O)
pub fn include_origin<O>(&mut self, origin: O)
Extends a list of origins tracked by current undo manager by given origin
. Origin markers
can be assigned to updates executing in a scope of a particular transaction
(see: Doc::transact_mut_with).
sourcepub fn exclude_origin<O>(&mut self, origin: O)
pub fn exclude_origin<O>(&mut self, origin: O)
Removes an origin
from the list of origins tracked by a current undo manager.
sourcepub fn clear(&mut self) -> Result<(), TransactionAcqError>
pub fn clear(&mut self) -> Result<(), TransactionAcqError>
Clears all StackItems stored within current UndoManager, effectively resetting its state.
pub fn as_origin(&self) -> Origin
sourcepub fn reset(&mut self)
pub fn reset(&mut self)
UndoManager merges undo stack items if they were created withing the time gap smaller than Options::capture_timeout_millis. You can call this method so that the next stack item won’t be merged.
Example:
use yrs::{Doc, GetString, Text, Transact, UndoManager};
let doc = Doc::new();
// without UndoManager::stop
let txt = doc.get_or_insert_text("no-stop");
let mut mgr = UndoManager::new(&doc, &txt);
txt.insert(&mut doc.transact_mut(), 0, "a");
txt.insert(&mut doc.transact_mut(), 1, "b");
mgr.undo().unwrap();
txt.get_string(&doc.transact()); // => "" (note that 'ab' was removed)
// with UndoManager::stop
let txt = doc.get_or_insert_text("with-stop");
let mut mgr = UndoManager::new(&doc, &txt);
txt.insert(&mut doc.transact_mut(), 0, "a");
mgr.reset();
txt.insert(&mut doc.transact_mut(), 1, "b");
mgr.undo().unwrap();
txt.get_string(&doc.transact()); // => "a" (note that only 'b' was removed)
sourcepub fn undo(&mut self) -> Result<bool, TransactionAcqError>
pub fn undo(&mut self) -> Result<bool, TransactionAcqError>
Undo last action tracked by current undo manager. Actions (a.k.a. StackItems) are groups of updates performed in a given time range - they also can be separated explicitly by calling UndoManager::reset.
Successful execution returns a boolean value telling if an undo call has performed any changes.
§Errors
This method requires an exclusive access to underlying document store. This means that no other transaction on that same document can be active while calling this method. Otherwise an error will be returned.
sourcepub fn redo(&mut self) -> Result<bool, TransactionAcqError>
pub fn redo(&mut self) -> Result<bool, TransactionAcqError>
Redo’es last action previously undo’ed by current undo manager. Actions (a.k.a. StackItems) are groups of updates performed in a given time range - they also can be separated explicitly by calling UndoManager::reset.
Successful execution returns a boolean value telling if an undo call has performed any changes.
§Errors
This method requires an exclusive access to underlying document store. This means that no other transaction on that same document can be active while calling this method. Otherwise an error will be returned.