3D PLM Enterprise Architecture |
User Interface - Commands |
Managing Command Undo/RedoEnabling the end user to undo and redo the command result |
Use Case |
AbstractThis article shows how to add undo/redo capabilities to a command to enable the end user to undo and redo the command result when the command is completed. |
This use case is intended to show how to manage the command undo/redo, that is how to undo and redo the command effect after the command has completed. It deals with a non transactional document model, that is a document model that doesn't include document object undo/redo by means of the CATIUndoTransaction interface implementation. As a consequence, the document object undo/redo must be coded in the undo/redo methods.
[Top]
The Polyline command is a use case of the CAADialogEngine.edu framework that illustrates the DialogEngine framework capabilities.
[Top]
The Polyline commmand creates a polyline by successively indicating or selecting points, or entering their coordinates using a dialog box. A right click stops the polyline creation and exits the command. When the command is completed, and when other successive commands are also over, the command undo process can sequentially undo the command effects, starting from the last command and going up until the maximum number of undo is reached. Conversely, the polyline undone can be redone.
[Top]
See the section entitled "How to Launch the CAAGeometry Use Case" in the "The CAAGeometry Sample" use case for a detailed description of how this use case should be launched.
Then, in the window where you run the mkrun command, do not type the module name on the command line, but type CNEXT instead. When the application is ready, do the following:
You can create several polylines. Then, clicking undo several times removes the polylines in their creation reverse order, and clicking redo restores them in their cration order.
[Top]
The Polyline command is made of a single class named CAADegCreatePolylineCmd located in the CAADegGeoCommands.m module of the CAADialogEngine.edu framework:
Windows | InstallRootDirectory\CAADialogEngine.edu\CAADegGeoCommands.m\ |
Unix | InstallRootDirectory/CAADialogEngine.edu/CAADegGeoCommands.m/ |
where InstallRootDirectory
is the directory where the CAA CD-ROM
is installed.
[Top]
To create the command undo/redo, there are four steps:
# | Step | Where |
---|---|---|
1 | Declare the command undo/redo methods | Header file |
2 | Create the command undo/redo object | Command member function |
3 | Provide the static undo and redo methods | Command member functions |
4 | Provide the static deallocation method | Command member function |
[Top]
The command undo/redo methods are declared in the command class header file.
... CATCommandGlobalUndo * GetGlobalUndo(); static void DeallocatePolyline(void * iUsefulData); static void UndoCreatePolyline(void * iUsefulData); static void RedoCreatePolyline(void * iUsefulData); ... |
These methods are as follows:
GetGlobalUndo
is a CATCommand redefined method that returns a
CATCommandGlobalUndo object. This object contains pointers to the
deallocation, undo, and redo methods to be accessed when the command itself
is deleted. GetGlobalUndo
is called just before the command
completesDeallocatePolyline
is a command static method that is called
to deallocate the polyline when the maximum number of undo steps is reached.
At this moment, the polyline cannot be redone, and the polyline stored for
redo must be deallocatedUndoCreatePolyline
is a command static method that is called
to undo the command result, that is the created polylineRedoCreatePolyline
is a command static method that is called
to redo the command result.These last three methods are static because they should be accessible when the command has completed and is no more active. The class instance is deleted when the command undo process takes place.
[Top]
The command undo/redo object is created using the GetGlobalUndo
method.
CATCommandGlobalUndo * CAADegCreatePolylineCmd::GetGlobalUndo() { CATCommandGlobalUndo * pCommandUndoRedo = NULL; if ( _EltPolyline ) // The created polyline { pCommandUndoRedo = new CATCommandGlobalUndo( (CATGlobalUndoMethod)& CAADegCreatePolylineCmd::UndoCreatePolyline, (CATGlobalUndoMethod)& CAADegCreatePolylineCmd::RedoCreatePolyline, (void *) _EltPolyline, (CATGlobalUndoMethod)& CAADegCreatePolylineCmd::DeallocatePolyline); } return pCommandUndoRedo; } |
The CATCommandGlobalUndo instance returned by GetGlobalUndo contains pointers to
[Top]
The UndoCreatePolyline
and RedoCreatePolyline
methods have the following signatures.
void CAADegCreatePolylineCmd::UndoCreatePolyline(void *iData) { CAAISysPolyline * Elt = (CAAISysPolyline *) iData; if ( Elt ) { ... // Provide undo code here } } void CAADegCreatePolylineCmd::RedoCreatePolyline(void *iData) { CAAISysPolyline * Elt = (CAAISysPolyline *) iData; if ( Elt ) { ... // Provide redo code here } } |
The pointer to the polyline is passed as a void *. Cast it to the appropriate interface pointer before using it to undo or redo the command result.
[Top]
The DeallocatePolyline
deallocates the created polyline when the
maximum number of undo steps is reached.
void CAADegCreatePolylineCmd::DeallocatePolyline(void * iData) { if (iData) { CAAISysPolyline * Elt = (CAAISysPolyline *) iData; if (Elt) Elt->Release(); } } |
The pointer to the polyline is passed as a void *. Cast it to the appropriate interface pointer before releasing it.
[Top]
This use case shows how to add command undo/redo capabilities to a command using an undo/redo object that remains alive after the command is completed and that holds pointers to the created object, to command static undo and redo methods, and to a command static deallocation method of the created object.
[Top]
[Top] |
Version: 1 [Jan 2000] | Document created |
[Top] |
Copyright © 2000, Dassault Systèmes. All rights reserved.