public class UndoManager extends Object
A single undoable operation is represented by UndoOperation
which
apps implement to define their undo/redo behavior. The UndoManager keeps
a stack of undo states; each state can have one or more undo operations
inside of it.
Updates to the stack must be done inside of a beginUpdate(java.lang.CharSequence)
/endUpdate()
pair. During this time you can add new operations to the stack with
addOperation(android.content.UndoOperation<?>, int)
, retrieve and modify existing operations with
getLastOperation(int)
, control the label shown to the user for this operation
with setUndoLabel(java.lang.CharSequence)
and suggestUndoLabel(java.lang.CharSequence)
, etc.
Every {link UndoOperation} is associated with an UndoOwner
, which identifies
the data it belongs to. The owner is used to indicate how operations are dependent
on each other -- operations with the same owner are dependent on others with the
same owner. For example, you may have a document with multiple embedded objects. If the
document itself and each embedded object use different owners, then you
can provide undo semantics appropriate to the user's context: while within
an embedded object, only edits to that object are seen and the user can
undo/redo them without needing to impact edits in other objects; while
within the larger document, all edits can be seen and the user must
undo/redo them as a single stream.
Modifier and Type | Field and Description |
---|---|
static int |
MERGE_MODE_ANY
Always allow merge with the last undo state, if possible.
|
static int |
MERGE_MODE_NONE
Never merge with the last undo state.
|
static int |
MERGE_MODE_UNIQUE
Allow merge with the last undo state only if it contains
operations with the caller's owner.
|
Constructor and Description |
---|
UndoManager() |
Modifier and Type | Method and 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.
|
<T extends UndoOperation> |
getLastOperation(Class<T> clazz,
UndoOwner owner,
int mergeMode)
Return the most recent
UndoOperation that was added to the update and
has the given owner. |
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. |
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(android.os.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(android.content.UndoOwner) . |
int |
undo(UndoOwner[] owners,
int count)
Perform undo of last/top count undo states.
|
public static final int MERGE_MODE_NONE
public static final int MERGE_MODE_UNIQUE
public static final int MERGE_MODE_ANY
public void saveInstanceState(Parcel p)
restoreInstanceState(android.os.Parcel, java.lang.ClassLoader)
.public void restoreInstanceState(Parcel p, ClassLoader loader)
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.public void setHistorySize(int size)
public int getHistorySize()
public int undo(UndoOwner[] owners, int count)
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.public int redo(UndoOwner[] owners, int count)
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.public boolean isInUndo()
public int forgetUndos(UndoOwner[] owners, int count)
public int forgetRedos(UndoOwner[] owners, int count)
public int countUndos(UndoOwner[] owners)
owners
- If non-null, only those states containing an operation with one of
the owners supplied here will be counted.public int countRedos(UndoOwner[] owners)
owners
- If non-null, only those states containing an operation with one of
the owners supplied here will be counted.public CharSequence getUndoLabel(UndoOwner[] owners)
owners
- If non-null, will select the top-most undo state containing an
operation with one of the owners supplied here.public CharSequence getRedoLabel(UndoOwner[] owners)
owners
- If non-null, will select the top-most undo state containing an
operation with one of the owners supplied here.public void beginUpdate(CharSequence label)
endUpdate()
.label
- Optional user-visible label for this new undo state.public boolean isInUpdate()
beginUpdate(java.lang.CharSequence)
.public void setUndoLabel(CharSequence label)
beginUpdate(java.lang.CharSequence)
.
Any existing label will be replaced with this one.public void suggestUndoLabel(CharSequence label)
beginUpdate(java.lang.CharSequence)
, but
only if there is not a label currently set for it.public int getUpdateNestingLevel()
beginUpdate(java.lang.CharSequence)
has been called without a matching
endUpdate()
call.public boolean hasOperation(UndoOwner owner)
UndoOperation
in the current beginUpdate(java.lang.CharSequence)
undo state.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.public UndoOperation<?> getLastOperation(int mergeMode)
UndoOperation
that was added to the update.mergeMode
- May be either MERGE_MODE_NONE
or MERGE_MODE_ANY
.public UndoOperation<?> getLastOperation(UndoOwner owner, int mergeMode)
UndoOperation
that was added to the update and
has the given owner.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
.public <T extends UndoOperation> T getLastOperation(Class<T> clazz, UndoOwner owner, int mergeMode)
UndoOperation
that was added to the update and
has the given owner.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
.public void addOperation(UndoOperation<?> op, int mergeMode)
op
- The new operation to add.mergeMode
- May be either MERGE_MODE_NONE
, MERGE_MODE_UNIQUE
,
or MERGE_MODE_ANY
.public void endUpdate()
beginUpdate(java.lang.CharSequence)
.public int commitState(UndoOwner owner)
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.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.public boolean uncommitState(int commitId, UndoOwner owner)
commitState(android.content.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.commitId
- The identifier for the state to be uncommitted, as returned
by commitState(android.content.UndoOwner)
.owner
- Optional owner that must appear in the committed state.