IOleParentUndoUnit
The IOleParentUndoUnit
interface enables undo units to contain child undo units. For example, a
complex action can be presented to the end user as a single undo action even
though a number of separate actions are involved. All the subordinate undo
actions are contained within the top-level, parent undo unit.
A parent undo
unit is initially created using the IOleUndoManager::Open method. Then,
to add another parent unit nested within an existing parent unit, you call IOleParentUndoUnit::Open.
While a parent unit is open, the undo manager adds undo units to it by calling IOleParentUndoUnit::Add.
When the undo manager closes a top-level parent, the entire undo unit with its
nested subordinates is placed on top of the undo stack.
This
interface is derived from IOleUndoUnit and supports all the methods on
that interface.
If an object
needs to create a parent unit, there are several cases to consider:
To create an enabling parent
unit, the object calls IOleUndoManager::GetOpenParentState on the undo
manager and checks the return value. If the value is S_FALSE, then the object
creates the enabling parent and opens it. If the return value is S_OK, then there
is a parent already open. If the open parent is blocked (UAS_BLOCKED bit set),
or an enabling parent (UAS_BLOCKED and UAS_NOPARENTENABLE bits not set), then
there is no need to create the enabling parent. If the currently open parent is
a disabling parent (UAS_NOPARENTENABLE bit set), then the enabling parent
should be created and opened to re-enable adding undo units. Note that
UAS_NORMAL has a value of zero, which means it is the absence of all other bits
and is not a bit flag that can be set. If comparing *pdwState against
UAS_NORMAL, mask out unused bits from *pdwState with UAS_MASK to allow
for future expansion.
To create a blocked parent, the
object calls IOleUndoManager::GetOpenParentState and checks for an open
parent that is already blocked. If one exists, then there is no need to create
the new blocking parent. Otherwise, the object creates it and opens it on the
stack.
To create a disabling parent,
the object calls IOleUndoManager::GetOpenParentState and checks for an
open parent that is blocked or disabling. If either one exists it is
unnecessary to create the new parent. Otherwise, the object creates the parent
and opens it on the stack.
In the event
that both the UAS_NOPARENTENABLE and UAS_BLOCKED flags are set, the flag that
is most relevant to the caller should be used with UAS_NOPARENTENABLE taking
precedence. For example, if an object is creating a simple undo unit, it should
pay attention to the UAS_NOPARENTENABLE flag and clear the undo stack. If it is
creating an enabling parent unit, then it should pay attention to the
UAS_BLOCKED flag and skip the creation.
When the
parent undo unit is marked blocked, it discards any undo units it receives.
When to Implement
An undo unit
that is capable of containing child undo units implements this interface in
addition to IOleUndoUnit.
When to Use
The undo
manager calls the methods in this interface to add child undo units.
Methods in VTable Order
IUnknown Methods |
Description |
QueryInterface |
Returns a
pointer to a specified interface. |
AddRef |
Increments
the reference count. |
Release |
Decrements
the reference count. |
IOleUndoUnit Methods |
Description |
Do |
Instructs
the undo unit to carry out its action. |
GetDescription |
Returns a
string that describes the undo unit and can be used in the undo or redo user
interface. |
GetUnitType |
Returns the
CLSID and a type identifier for the undo unit. |
OnNextAdd |
Notifies
the last undo unit in the collection that a new unit has been added. |
IOleParentUndoUnit
Methods |
Description |
Open |
Opens a new
parent undo unit, which becomes part of the containing unit s undo stack. |
Close |
Closes the
most recently opened parent undo unit. |
Add |
Adds a
simple undo unit to the collection. |
FindUnit |
Indicates
if the specified unit is a child of this undo unit or one of its children,
that is if the specified unit is part of the hierarchy in this parent unit. |
GetParentState |
Returns
state information about the innermost open parent undo unit. |
See Also