Struct yrs::undo::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<T>(doc: &Doc, scope: &T) -> Self

where T: AsRef<Branch>,

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

pub fn with_options(doc: &Doc, options: Options) -> 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 with_scope_and_options<T>(doc: &Doc, scope: &T, options: Options) -> Self

where T: AsRef<Branch>,

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 observe_item_added<F>(&self, f: F) -> Subscription

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

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.

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

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

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.

Provided key is used to identify the origin of the callback. It can be used to unregister the callback later on.

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

where K: Into<Origin>,

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

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

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.

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

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

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.

Provided key is used to identify the origin of the callback. It can be used to unregister the callback later on.

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

where K: Into<Origin>,

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

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

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.

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

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

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.

Provided key is used to identify the origin of the callback. It can be used to unregister the callback later on.

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

where K: Into<Origin>,

pub fn expand_scope<T>(&mut self, scope: &T)

where T: AsRef<Branch>,

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

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(&mut self) -> Result<(), TransactionAcqError>

Clears all StackItems stored within current UndoManager, effectively resetting its state.

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(&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)

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

pub fn can_redo(&self) -> bool

Are there any redo steps available?

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.

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.