IMcUndoStackPush Method

Sub Push ( 
	Undoable As Object,
	Optional Operation As Integer = 0,
	<OptionalAttribute> Context As Object,
	<OptionalAttribute> Owner As Object,
	Optional Description As String = "",
	<OptionalAttribute> AlreadyBackedUp As Object
)

Parameters

Undoable

Type: SystemObject
LPDISPATCH : pointer to an object that exposes the IMcUndoable interface. If the optional AlreadyBackedUp argument is not supplied, the IMcUndoable.Backup method will be called on this interface to capture the current state of the object for saving on the Undo stack.

Operation (Optional)

Type: SystemInt32
long : A set of flags describing the operation. These flags are supplied to the IMcUndoable.Backup method and may be modified by it before saving it on the undo stack. These flags may be examined for the operation on the top of the Undo stack as the UndoTopStateOperation property and for the top operation on the Redo stack as the RedoTopStateOperation property. The special mcCommonUndoStackOperationFlags flag mccusofUndoWithNextPush, indicates that the current push is to be joined with the subsequent one as a single Undo state. For such joined states, when Undo is called all joined Push states will be restored in reverse order to that in which they were Push'ed. The final joined state should be pushed without the mccusofUndoWithNextPush flag set (See Example 2). When examined, the top state will have the mccusofJoinedToPrevious flag set if it is the head of a joined state (the mccusofJoinedToPrevious flag is set automatically in the flags; it cannot be set directly by the caller). For saving McImage objects, this may be one or more mcImageUndoOperationFlags OR'ed together (see examples). For saving McFeatures-derived objects (IMcRegions2, IMcLines or IMcPoints) and for McGraphOverlay objects, this argument is unused (unless the mccusofUndoWithNextPush flag needs to be set, as in Example 2).

Context (Optional)

Type: SystemObject
VARIANT : An optional argument, giving any information deemed useful for the undoable to be able to properly perform Backup and Restore. This variant is supplied to the IMcUndoable.Backup method and may be modified by it before saving it on the undo stack. This variant may be examined for the operation on the top of the Undo stack as the UndoTopStateContext property and for the top operation on the Redo stack as the RedoTopStateContext property. For saving McImage objects, this may be a source rectangle for the section of the image to be saved, given as a LONGRECT UDT or as an array of 4 numeric values in the order left, top, right, bottom. For saving McFeatures-derived objects (IMcRegions2, IMcLines or IMcPoints) or for McGraphOverlay objects, this argument is unused and should be left empty or missing.

Owner (Optional)

Type: SystemObject
VARIANT : A convenience for the caller. This optional argument is stored with the undo information on the stack and may be accessed for the top element of the Undo or Redo stacks by calling UndoTopStateOwner or RedoTopStateOwner, respectively. This value is not passed to the IMcUndoable.Backup method, and will be stored on the stack unchanged.

Description (Optional)

Type: SystemString
BSTR : Description of the operation that the Undo of this Push will restore. This description is stored with the undo information on the stack and may be accessed for the top element of the Undo or Redo stacks by calling UndoTopStateDescription or RedoTopStateDescription, respectively. This value is not passed to the IMcUndoable.Backup method, and will be stored on the stack unchanged. For joined states, only the final pushed state (the one without the mccusofUndoWithNextPush flag set) can usefully have a non-empty description (see Example 2).

AlreadyBackedUp (Optional)

Type: SystemObject
VARIANT : If given, then no call to McUndoable.Backup is made, but instead this argument is pushed on the undo stack. It must be the BackupTo argument of an McUndoable.Backup call. You use this argument, when it is necessary to capture the undo state at some time prior to when the actual McUndoStack.Push call needs to be made. This can occur whenever a cancelable operation is to be made undoable, since you don't want to push undo information until you know that the operation will not be canceled, but by the time you know that, it is too late to capture the pre-operation state.

Reference