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.

QuickInfo

  Windows NT: Use version 4.0 or later. New for OC96.
  Windows: Use Windows 95 or later. New for OC96.
  Windows CE: Unsupported.
  Header: Declared in ocidl.h.

IOleParentUndoUnit

When to Implement

When to Use

Methods in VTable Order

QuickInfo

See Also