Export (0) Print
Expand All

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. The addition of undo units should always be done through the undo manager. The IOleParentUndoUnit::Open and IOleParentUndoUnit::Close methods on parent units will end up being called by the undo manager. Having parent units call back into the undo manager will cause infinite recursion.

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.

An enabling parent is required to be open on the stack before any other undo units can be added. If one isn't open, the stack should be cleared instead. This is to ensure that undo units only get added as a result of user actions and not programmatic actions. For example, if your application wants to make clicking a certain button undoable, but that same action is also exposed through the object model. That action should be undoable through the user interface but not the object model because you cannot restore the state of the user's script code. Because the same code implements the change in both cases, the UI code that handles the button click should open an enabling parent on the stack, call the appropriate code, and then close the parent unit. The object model code would not open a parent unit, causing the undo stack to be cleared.

A blocking parent is used when you do not want your code to call other code that you know may try to add undo units to the stack. For example, you should use a blocking parent if you call code that creates undo units, that your outer code has already created that will fully undo all the desired behavior.

A non-enabling parent is used when you fire an event in response to a user action. The stack would be cleared only if the event handler did something that tried to create an undo unit, but if no handler exists then the undo stack would be preserved.

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.

Members

The IOleParentUndoUnit interface inherits from IOleUndoUnit. IOleParentUndoUnit also has these types of members:

Methods

The IOleParentUndoUnit interface has these methods.

MethodDescription
Add

Adds a simple undo unit to the collection.

Close

Closes the specified parent undo unit.

FindUnit

Indicates whether 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

Retrieves state information about the innermost open parent undo unit.

Open

Opens a new parent undo unit, which becomes part of the containing unit's undo stack.

 

Requirements

Minimum supported client

Windows 2000 Professional [desktop apps only]

Minimum supported server

Windows 2000 Server [desktop apps only]

Header

OCIdl.h

IDL

OCIdl.idl

IID

IID_IOleParentUndoUnit is defined as A1FAF330-EF97-11CE-9BC9-00AA00608E01

See also

IOleUndoManager
IOleUndoUnit

 

 

Community Additions

ADD
Show:
© 2014 Microsoft