Programming Reference: ODUndo

# Programming Reference

## ODUndo

Class Definition File | Undo.idl
Class C++ Binding | Undo.xh

Class Hierarchy

    SOMObject
       ODObject
          ODUndo

Description

An object of the ODUndo class holds command history information to support the undo capability of OpenDoc. The undo stack gives the user the ability to reverse the effects of recently executed commands.

Your part editor stores undoable actions in, and retrieves them from, the undo object. When a document is opened, the session object creates a single undo object. All parts of that document share the undo object; you can obtain a reference to it by calling the session object's GetUndo method.

The undo object contains an undo stack and a redo stack. When an undoable action is performed, the part involved places action data on the undo stack. Action data is information provided by the part that allows it to reverse the effects of an undoable action. OpenDoc stores the action data in the undo object's action history. The action history is a cumulative set of reversible actions available at any one time. When an action needs to be undone, OpenDoc pops the action data from the undo stack onto the redo stack. At the same time, OpenDoc notifies your part so that your part can undo the recently executed action using the stored action data. When an undone action needs to be redone, OpenDoc pops the action data from the redo stack back onto the undo stack. OpenDoc notifies your part so that your part can redo the recently undone action using the stored action data. The undo and redo stacks can be cleared upon a part's request. When clearing is needed, OpenDoc asks each part to dispose of its action data stored in the stacks. The order of disposal is from newer actions to older actions.

There are times when an action subhistory is useful. An action subhistory, a subset of reversible actions, is available at any one time. For example, you may need a new action context when entering a modal state, that is, when your part displays a modal dialog box. OpenDoc allows marks to be placed on the stacks. If a mark is placed on a stack, the stack may be cleared only to the mark. For example, when the modal dialog box closes, any actions done within the context of the modal dialog box are disposed of; however, all the actions executed before the modal dialog box appeared are preserved in the stacks.

Methods

The methods defined by the ODUndo class include:

- AbortCurrentTransaction
- AddActionToHistory
- ClearActionHistory
- ClearRedoHistory
- MarkActionHistory
- PeekRedoHistory
- PeekUndoHistory
- Redo
- Undo

Overridden Methods | There are no methods overridden by the ODUndo class.

### AbortCurrentTransaction

This method removes the current transaction (any nested transactions) from the action history.

Signature

    void AbortCurrentTransaction ()

Parameters

None.

Returns

None.

Remarks

This method aborts a transaction that is being placed in the undo stack by removing all single actions up to and including the last begin action. If there is a nested transaction in the current transaction, it is entirely removed. This method in turn calls your part's UndoAction method to give your part the opportunity to perform any reverse editing necessary to restore itself to the state it possessed before the transaction began.

Related Methods

- ODPart::UndoAction

### AddActionToHistory

This method pushes the action data and its associated part onto the undo stack.

Signature

    void AddActionToHistory (ODPart *whichPart,
                             ODActionData *actionData,
                             ODActionType actionType,
                             ODName *undoActionLabel,
                             ODName *redoActionLabel)

Parameters

whichPart (ODPart *) - input

  A reference to the part that performed the action.

actionData (ODActionData *) - input

  A byte array whose buffer contains the data needed by the part to allow it to undo the action.

actionType (ODActionType) - input

  The type of undo action. This parameter can be set to one of the following values:

  kODBeginAction | The first action of a multistep action.
  kODEndAction | The last action of a multistep action.
  kODSingleAction | A single action.

undoActionLabel (ODName *) - input

  A user-visible label for the undo command beginning with the word "Undo".

redoActionLabel (ODName *) - input

  A user-visible label for the redo command beginning with the word "Redo".

Returns

None.

Exception Handling

kODErrCannotAddAction | The specified action cannot be added to this undo object; an undo or redo action is in progress.
kODErrOutOfMemory | There is not enough memory to allocate the action information.

### ClearActionHistory

This method clears the undo and redo stacks.

Signature

    void ClearActionHistory (ODRespectMarksChoices respectMarks)

Parameters

respectMarks (ODRespectMarksChoices) - input

  The values for clearing an action history. This parameter can be set to one of the following values:

  kODDontRespectMarks | The stacks are cleared in their entirety.
  kODRespectMarks | The stacks are cleared only down to the specified marks. Only actions within an action subhistory are cleared.

Returns

None.

### ClearRedoHistory

This method clears the redo history.

Signature

    void ClearRedoHistory ()

Parameters

None.

Returns

None.

Remarks OpenDoc calls this method. If the redo stack contains a mark indicating an action subhistory, this method clears only that subhistory. Otherwise, it clears the entire redo stack.

### MarkActionHistory

This method marks the top of the undo and redo stacks.

Signature

    void MarkActionHistory ()

Parameters

None.

Returns

None.

Remarks

The marks are used to indicate the beginning of a new action subhistory in each stack.

Exception Handling

kODErrCannotMarkAction | Failure to start an action subhistory by placing a mark at the beginning of the undo and redo stacks; the undo object was initialized properly.

### PeekRedoHistory

This method indicates whether there is anything on the redo stack and returns the information about the action at the top of the redo stack.

Signature

    ODBoolean PeekRedoHistory (ODPart **part,
                               ODActionData *actionData,
                               ODActionType *actionType,
                               ODName *actionLabel)

Parameters

part (ODPart **) - output

  A reference to the part that performed the action at the top of the redo stack.

actionData (ODActionData *) - output

  A byte array whose buffer is to contain the action data for the action at the top of the redo stack.

actionType (ODActionType *) - output

  The type of undo action. This parameter can be set to one of the following values:

  kODBeginAction | The first action of a multistep action.
  kODEndAction | The last action of a multistep action.
  kODSingleAction | A single action.

actionLabel (ODName *) - output

  A user-visible label for the redo command beginning with the word "Redo".

Returns

rv (ODBoolean) - returns

  A flag indicating whether there is anything on the redo stack.

  kODTrue | There is something on the redo stack.
  kODFalse | The redo stack is empty or the top of the redo stack contains a mark indicating an action subhistory.

Remarks

The document shell or container applications call this method to properly set up the redo item. Your part can also call this method, but it is typically unnecessary.

### PeekUndoHistory

This method indicates whether there is anything on the undo stack and returns information about the action at the top of the undo stack.

Signature

    ODBoolean PeekUndoHistory (ODPart **part,
                               ODActionData *actionData,
                               ODActionType *actionType,
                               ODName *actionLabel)

Parameters

part (ODPart **) - output

  A reference to the part that performed the action at the top of the undo stack.

actionData (ODActionData *) - output

  A byte array whose buffer is to contain the action data for the action at the top of the undo stack.

actionType (ODActionType *) - output

  The values for an undo action. This parameter can be set to one of the following values:

  kODBeginAction | The first action of a multistep action.
  kODEndAction | The last action of a multistep action.
  kODSingleAction | A single action.

actionLabel (ODName *) - output

  The user-visible label for the undo command beginning with the word "Undo".

Returns

rv (ODBoolean) - returns

  A flag indicating whether there is anything on the undo stack.

  kODTrue | There is something on the undo stack.
  kODFalse | The undo stack is empty or the top of the undo stack contains a mark indicating an action subhistory.

Remarks

The document shell or container applications call this method to properly set up the undo item. Your part can also call this method, but it is typically unnecessary.

### Redo

This method is called by the document shell or container application to redo the top action in the redo history.

Signature

    void Redo ()

Parameters

None.

Returns

None.

Exception Handling

kODErrEmptyStack | The redo stack is empty or the undo object was not initialized.

This method may return exceptions returned by the part.

### Undo

This method is called by the document shell or container application to undo the top action in the undo stack.

Signature

    void Undo ()

Parameters

None.

Returns

None.

Exception Handling

kODErrEmptyStack | The undo stack is empty or the undo object was not initialized.

This method may return exceptions returned by the part.

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]