Package icyllis.modernui.core

# Class UndoManager

java.lang.Object
icyllis.modernui.core.UndoManager

public class UndoManager extends Object

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final int`
  `MERGE_MODE_ANY`
  Always allow merge with the last undo state, if possible.
  `static final int`
  `MERGE_MODE_NONE`
  Never merge with the last undo state.
  `static final int`
  `MERGE_MODE_UNIQUE`
  Allow merge with the last undo state only if it contains operations with the caller's owner.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `UndoManager()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `addOperation(UndoOperation<?> op, int mergeMode)`
  Add a new UndoOperation to the current update.
  `void`
  `beginUpdate(CharSequence label)`
  Start creating a new undo state.
  `int`
  `commitState(UndoOwner owner)`
  Commit the last finished undo state.
  `int`
  `countRedos(UndoOwner[] owners)`
  Return the number of redo states on the undo stack.
  `int`
  `countUndos(UndoOwner[] owners)`
  Return the number of undo states on the undo stack.
  `void`
  `endUpdate()`
  Finish the creation of an undo state, matching a previous call to `beginUpdate(java.lang.CharSequence)`.
  `int`
  `forgetRedos(UndoOwner[] owners, int count)`
  `int`
  `forgetUndos(UndoOwner[] owners, int count)`
  `int`
  `getHistorySize()`
  Return the current maximum number of undo states.
  `UndoOperation<?>`
  `getLastOperation(int mergeMode)`
  Return the most recent `UndoOperation` that was added to the update.
  `UndoOperation<?>`
  `getLastOperation(UndoOwner owner, int mergeMode)`
  Return the most recent `UndoOperation` that was added to the update and has the given owner.
  `<T extends UndoOperation<?>>
  T`
  `getLastOperation(Class<T> clazz, UndoOwner owner, int mergeMode)`
  Return the most recent `UndoOperation` that was added to the update and has the given owner.
  `UndoOwner`
  `getOwner(String tag, Object data)`
  `CharSequence`
  `getRedoLabel(UndoOwner[] owners)`
  Return the user-visible label for the top redo state on the stack.
  `CharSequence`
  `getUndoLabel(UndoOwner[] owners)`
  Return the user-visible label for the top undo state on the stack.
  `int`
  `getUpdateNestingLevel()`
  Return the number of times `beginUpdate(java.lang.CharSequence)` has been called without a matching `endUpdate()` call.
  `boolean`
  `hasOperation(UndoOwner owner)`
  Check whether there is an `UndoOperation` in the current `beginUpdate(java.lang.CharSequence)` undo state.
  `boolean`
  `isInUndo()`
  Returns true if we are currently inside of an undo/redo operation.
  `boolean`
  `isInUpdate()`
  Returns true if currently inside of a `beginUpdate(java.lang.CharSequence)`.
  `int`
  `redo(UndoOwner[] owners, int count)`
  Perform redo of last/top count undo states in the transient redo stack.
  `void`
  `restoreInstanceState(Parcel p, ClassLoader loader)`
  Restore an undo state previously created with `saveInstanceState(Parcel)`.
  `void`
  `saveInstanceState(Parcel p)`
  Flatten the current undo state into a Parcel object, which can later be restored with `restoreInstanceState(Parcel, java.lang.ClassLoader)`.
  `void`
  `setHistorySize(int size)`
  Set the maximum number of undo states that will be retained.
  `void`
  `setUndoLabel(CharSequence label)`
  Forcibly set a new for the new undo state being built within a `beginUpdate(java.lang.CharSequence)`.
  `void`
  `suggestUndoLabel(CharSequence label)`
  Set a new for the new undo state being built within a `beginUpdate(java.lang.CharSequence)`, but only if there is not a label currently set for it.
  `boolean`
  `uncommitState(int commitId, UndoOwner owner)`
  Attempt to undo a previous call to `commitState(icyllis.modernui.core.UndoOwner)`.
  `int`
  `undo(UndoOwner[] owners, int count)`
  Perform undo of last/top count undo states.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### MERGE_MODE_NONE

    public static final int MERGE_MODE_NONE
    Never merge with the last undo state.
    See Also:
      - Constant Field Values

  - ### MERGE_MODE_UNIQUE

    public static final int MERGE_MODE_UNIQUE
    Allow merge with the last undo state only if it contains operations with the caller's owner.
    See Also:
      - Constant Field Values

  - ### MERGE_MODE_ANY

    public static final int MERGE_MODE_ANY
    Always allow merge with the last undo state, if possible.
    See Also:
      - Constant Field Values

- ## Constructor Details

  - ### UndoManager

    public UndoManager()

- ## Method Details

  - ### getOwner

    public UndoOwner getOwner(String tag, Object data)

  - ### saveInstanceState

    public void saveInstanceState(Parcel p)
    Flatten the current undo state into a Parcel object, which can later be restored with `restoreInstanceState(Parcel, java.lang.ClassLoader)`.

  - ### restoreInstanceState

    public void restoreInstanceState(Parcel p, ClassLoader loader)
    Restore an undo state previously created with `saveInstanceState(Parcel)`. This will restore the UndoManager's state to almost exactly what it was at the point it had been previously saved; the only information not restored is the data object associated with each `UndoOwner`, which requires separate calls to `getOwner(String, Object)` to re-associate the owner with its data.

  - ### setHistorySize

    public void setHistorySize(int size)
    Set the maximum number of undo states that will be retained.

  - ### getHistorySize

    public int getHistorySize()
    Return the current maximum number of undo states.

  - ### undo

    public int undo(UndoOwner[] owners, int count)
    Perform undo of last/top count undo states. The states impacted by this can be limited through owners.
    Parameters:
      `owners` - Optional set of owners that should be impacted. If null, all undo states will be visible and available for undo. If non-null, only those states that contain one of the owners specified here will be visible.
      `count` - Number of undo states to pop.
    Returns:
      Returns the number of undo states that were actually popped.

  - ### redo

    public int redo(UndoOwner[] owners, int count)
    Perform redo of last/top count undo states in the transient redo stack. The states impacted by this can be limited through owners.
    Parameters:
      `owners` - Optional set of owners that should be impacted. If null, all undo states will be visible and available for undo. If non-null, only those states that contain one of the owners specified here will be visible.
      `count` - Number of undo states to pop.
    Returns:
      Returns the number of undo states that were actually redone.

  - ### isInUndo

    public boolean isInUndo()
    Returns true if we are currently inside of an undo/redo operation. This is useful for editors to know whether they should be generating new undo state when they see edit operations happening.

  - ### forgetUndos

    public int forgetUndos(UndoOwner[] owners, int count)

  - ### forgetRedos

    public int forgetRedos(UndoOwner[] owners, int count)

  - ### countUndos

    public int countUndos(UndoOwner[] owners)
    Return the number of undo states on the undo stack.
    Parameters:
      `owners` - If non-null, only those states containing an operation with one of the owners supplied here will be counted.

  - ### countRedos

    public int countRedos(UndoOwner[] owners)
    Return the number of redo states on the undo stack.
    Parameters:
      `owners` - If non-null, only those states containing an operation with one of the owners supplied here will be counted.

  - ### getUndoLabel

    public CharSequence getUndoLabel(UndoOwner[] owners)
    Return the user-visible label for the top undo state on the stack.
    Parameters:
      `owners` - If non-null, will select the top-most undo state containing an operation with one of the owners supplied here.

  - ### getRedoLabel

    public CharSequence getRedoLabel(UndoOwner[] owners)
    Return the user-visible label for the top redo state on the stack.
    Parameters:
      `owners` - If non-null, will select the top-most undo state containing an operation with one of the owners supplied here.

  - ### beginUpdate

    public void beginUpdate(CharSequence label)
    Start creating a new undo state. Multiple calls to this function will nest until they are all matched by a later call to `endUpdate()`.
    Parameters:
      `label` - Optional user-visible label for this new undo state.

  - ### isInUpdate

    public boolean isInUpdate()
    Returns true if currently inside of a `beginUpdate(java.lang.CharSequence)`.

  - ### setUndoLabel

    public void setUndoLabel(CharSequence label)
    Forcibly set a new for the new undo state being built within a `beginUpdate(java.lang.CharSequence)`. Any existing label will be replaced with this one.

  - ### suggestUndoLabel

    public void suggestUndoLabel(CharSequence label)
    Set a new for the new undo state being built within a `beginUpdate(java.lang.CharSequence)`, but only if there is not a label currently set for it.

  - ### getUpdateNestingLevel

    public int getUpdateNestingLevel()
    Return the number of times `beginUpdate(java.lang.CharSequence)` has been called without a matching `endUpdate()` call.

  - ### hasOperation

    public boolean hasOperation(UndoOwner owner)
    Check whether there is an `UndoOperation` in the current `beginUpdate(java.lang.CharSequence)` undo state.
    Parameters:
      `owner` - Optional owner of the operation to look for. If null, will succeed if there is any operation; if non-null, will only succeed if there is an operation with the given owner.
    Returns:
      Returns true if there is a matching operation in the current undo state.

  - ### getLastOperation

    public UndoOperation<?> getLastOperation(int mergeMode)
    Return the most recent `UndoOperation` that was added to the update.
    Parameters:
      `mergeMode` - May be either `MERGE_MODE_NONE` or `MERGE_MODE_ANY`.

  - ### getLastOperation

    public UndoOperation<?> getLastOperation(UndoOwner owner, int mergeMode)
    Return the most recent `UndoOperation` that was added to the update and has the given owner.
    Parameters:
      `owner` - Optional owner of last operation to retrieve. If null, the last operation regardless of owner will be retrieved; if non-null, the last operation matching the given owner will be retrieved.
      `mergeMode` - May be either `MERGE_MODE_NONE`, `MERGE_MODE_UNIQUE`, or `MERGE_MODE_ANY`.

  - ### getLastOperation

    public <T extends UndoOperation<?>> T getLastOperation(Class<T> clazz, UndoOwner owner, int mergeMode)
    Return the most recent `UndoOperation` that was added to the update and has the given owner.
    Parameters:
      `clazz` - Optional class of the last operation to retrieve. If null, the last operation regardless of class will be retrieved; if non-null, the last operation whose class is the same as the given class will be retrieved.
      `owner` - Optional owner of last operation to retrieve. If null, the last operation regardless of owner will be retrieved; if non-null, the last operation matching the given owner will be retrieved.
      `mergeMode` - May be either `MERGE_MODE_NONE`, `MERGE_MODE_UNIQUE`, or `MERGE_MODE_ANY`.

  - ### addOperation

    public void addOperation(UndoOperation<?> op, int mergeMode)
    Add a new UndoOperation to the current update.
    Parameters:
      `op` - The new operation to add.
      `mergeMode` - May be either `MERGE_MODE_NONE`, `MERGE_MODE_UNIQUE`, or `MERGE_MODE_ANY`.

  - ### endUpdate

    public void endUpdate()
    Finish the creation of an undo state, matching a previous call to `beginUpdate(java.lang.CharSequence)`.

  - ### commitState

    public int commitState(UndoOwner owner)
    Commit the last finished undo state. This undo state can no longer be modified with further `MERGE_MODE_UNIQUE` or `MERGE_MODE_ANY` merge modes. If called while inside of an update, this will push any changes in the current update on to the undo stack and result with a fresh undo state, behaving as if `endUpdate()` had been called enough to unwind the current update, then the last state committed, and `beginUpdate(java.lang.CharSequence)` called to restore the update nesting.
    Parameters:
      `owner` - The optional owner to determine whether to perform the commit. If this is non-null, the commit will only execute if the current top undo state contains an operation with the given owner.
    Returns:
      Returns an integer identifier for the committed undo state, which can later be used to try to uncommit the state to perform further edits on it.

  - ### uncommitState

    public boolean uncommitState(int commitId, UndoOwner owner)
    Attempt to undo a previous call to `commitState(icyllis.modernui.core.UndoOwner)`. This will work if the undo state at the top of the stack has the given id, and has not been involved in an undo operation. Otherwise false is returned.
    Parameters:
      `commitId` - The identifier for the state to be uncommitted, as returned by `commitState(icyllis.modernui.core.UndoOwner)`.
      `owner` - Optional owner that must appear in the committed state.
    Returns:
      Returns true if the uncommit is successful, else false.