Struct UndoManager 

pub struct UndoManager<M> { /* private fields */ }

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

impl<M> UndoManager<M>

where M: Meta + 'static,

pub fn new() -> 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 with_options(options: Options<M>) -> Self

Creates a new instance of the UndoManager working in a context of a given document, but without any pre-initialize scope. 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 expand_scope<T>(&mut self, doc: &Doc, scope: &T)

where T: AsRef<Branch>,

Extends a list of shared types tracked by current undo manager by a given scope.

pub fn docs(&self) -> impl Iterator<Item = &Doc>

pub fn observe_item_added<F>(&mut self, f: F) -> Subscription

where F: FnMut(&TransactionMut<'_>, &mut Event<M>) + 'static,

Registers a callback to be called every time a new StackItem is created.

pub fn observe_item_added_with<K, F>(&mut self, key: K, f: F)

where K: Into<Origin>, F: FnMut(&TransactionMut<'_>, &mut Event<M>) + 'static,

pub fn unobserve_item_added<K>(&mut self, key: K) -> bool

where K: Into<Origin>,

pub fn observe_item_updated<F>(&mut self, f: F) -> Subscription

where F: FnMut(&TransactionMut<'_>, &mut Event<M>) + 'static,

Registers a callback to be called every time an existing StackItem is extended.

pub fn observe_item_updated_with<K, F>(&mut self, key: K, f: F)

where K: Into<Origin>, F: FnMut(&TransactionMut<'_>, &mut Event<M>) + 'static,

pub fn unobserve_item_updated<K>(&mut self, key: K) -> bool

where K: Into<Origin>,

pub fn observe_item_popped<F>(&mut self, f: F) -> Subscription

where F: FnMut(&TransactionMut<'_>, &mut Event<M>) + 'static,

Registers a callback to be called every time a StackItem is popped via UndoManager::undo or UndoManager::redo.

pub fn observe_item_popped_with<K, F>(&mut self, key: K, f: F)

where K: Into<Origin>, F: FnMut(&TransactionMut<'_>, &mut Event<M>) + 'static,

pub fn unobserve_item_popped<K>(&mut self, key: K) -> bool

where K: Into<Origin>,

pub fn observe_stack_cleared<F>(&mut self, f: F) -> Subscription

where F: FnMut(&StackClearedEvent) + 'static,

Registers a callback to be called every time undo/redo stacks are cleared. The callback receives two booleans: (undo_stack_cleared, redo_stack_cleared).

pub fn observe_stack_cleared_with<K, F>(&mut self, key: K, f: F)

where K: Into<Origin>, F: FnMut(&StackClearedEvent) + 'static,

pub fn unobserve_stack_cleared<K>(&mut self, key: K) -> bool

where K: Into<Origin>,

pub fn include_origin<O>(&mut self, origin: O)

where O: Into<Origin>,

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

pub fn exclude_origin<O>(&mut self, origin: O)

where O: Into<Origin>,

Removes an origin from the list of origins tracked by a current undo manager.

pub fn clear_all(&mut self)

Clears all StackItems stored within current UndoManager undo AND redo stacks, effectively resetting its state.

Deadlocks

In order to perform its function, this method must guarantee that underlying document store is not being modified by another running TransactionMut. It does so by acquiring a read-only transaction itself. If transaction couldn’t be acquired (because another read-write transaction is in progress), it will hold current thread until, acquisition is available.

pub fn clear_undo(&mut self)

Clears all StackItems stored within current UndoManager undo stack alone, leaving redo stack untouched.

Deadlocks

In order to perform its function, this method must guarantee that underlying document store is not being modified by another running TransactionMut. It does so by acquiring a read-only transaction itself. If transaction couldn’t be acquired (because another read-write transaction is in progress), it will hold current thread until, acquisition is available.

pub fn clear_redo(&mut self)

Clears all StackItems stored within current UndoManager redo stack alone, leaving undo stack untouched.

Deadlocks

In order to perform its function, this method must guarantee that underlying document store is not being modified by another running TransactionMut. It does so by acquiring a read-only transaction itself. If transaction couldn’t be acquired (because another read-write transaction is in progress), it will hold current thread until, acquisition is available.

pub fn as_origin(&self) -> Origin

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();
mgr.expand_scope(&doc, &txt);
txt.insert(&mut doc.transact_mut(), 0, "a");
txt.insert(&mut doc.transact_mut(), 1, "b");
mgr.undo_blocking();
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();
mgr.expand_scope(&doc, &txt);
txt.insert(&mut doc.transact_mut(), 0, "a");
mgr.reset();
txt.insert(&mut doc.transact_mut(), 1, "b");
mgr.undo_blocking();
txt.get_string(&doc.transact()); // => "a" (note that only 'b' was removed)

pub fn can_undo(&self) -> bool

Are there any undo steps available?

pub fn undo_stack(&self) -> &[StackItem<M>]

Returns a list of StackItems stored within current undo manager responsible for performing potential undo operations.

pub fn redo_stack(&self) -> &[StackItem<M>]

Returns a list of StackItems stored within current undo manager responsible for performing potential redo operations.

pub async fn undo(&mut self) -> bool

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.

Deadlocks

This method requires exclusive access to underlying document store. This means that no other transaction on that same document can be active while calling this method. Otherwise, it may cause a deadlock.

See also: [UndoManager::try_undo] and UndoManager::undo_blocking.

pub fn undo_blocking(&mut self) -> bool

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.

Deadlocks

This method requires exclusive access to underlying document store. This means that no other transaction on that same document can be active while calling this method. Otherwise, it may cause a deadlock.

See also: [UndoManager::try_undo] and UndoManager::undo.

pub fn can_redo(&self) -> bool

Are there any redo steps available?

pub async fn redo(&mut self) -> bool

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.

Deadlocks

This method requires exclusive access to underlying document store. This means that no other transaction on that same document can be active while calling this method. Otherwise, it may cause a deadlock.

See also: [UndoManager::try_redo] and UndoManager::redo_blocking.

pub fn redo_blocking(&mut self) -> bool

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.

Deadlocks

This method requires exclusive access to underlying document store. This means that no other transaction on that same document can be active while calling this method. Otherwise, it may cause a deadlock.

See also: [UndoManager::try_redo] and UndoManager::redo_blocking.

Trait Implementations

impl<M: Debug> Debug for UndoManager<M>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<M> Drop for UndoManager<M>

fn drop(&mut self)

Executes the destructor for this type.

fn pin_drop(self: Pin<&mut Self>)

🔬This is a nightly-only experimental API. (pin_ergonomics)

Execute the destructor for this type, but different to Drop::drop, it requires self to be pinned.