3D PLM Enterprise Architecture

What You Will Learn With This Use Case

This use case is intended to show how to fit out you command with input and action undo/redo capabilities. 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 Use Case

The Polyline command is a use case of the CAADialogEngine.edu framework that illustrates the DialogEngine framework capabilities.

[Top]

What Does the Polyline Command Do

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. During the polyline creation process, the Undo and Redo commands are available to undo each point and line segment creation, possibly up to the first point created, and to redo each point and line segment creation from this first point to the last one. Undoing the first point creation, that is undoing the first input, exits the command.

The Polyline command is a state dialog command that creates a polyline according to the following UML statechart diagram [1].

Each end user input and associated action can be undone and redone, as shown by the scenario below:

	The end user has already created a polyline with four points and thus three line segments. The fifth point is not yet clicked, but a rubber line segment joins the fourth point and the mouse location. The dialog loops onto the RepeatState.
	The end user has clicked Undo. The rubber segment has disappeared, the fourth point and the third line segment are erased from the document.
	The end user has clicked Undo again. The third point and the second line segment are erased from the document.
	The end user has clicked Redo. The third point and the second line segment are recreated.

Any created point and line segment of the polyline can be undone as long as the command is active. This is a sequential process that enables the end user to go back to a previous state by successively going through the states from the current one. Redo is the process that recreates what was undone in the undo reverse order. This is input undo and action undo, because it is dedicated to undo the end user input, and the possible associated action.

[Top]

How to Launch the Polyline Command

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:

• Select File->New
• In the New box, select CAAGeometry and click OK
• Select Insert->Multi Lines->Polyline
• Click to create the points that make up the polyline, and right click to end.

[Top]

Where to Find the Polyline Command Code

The Polyline command is made of a single class named CAADegCreatePolylineCmd located in the CAADegGeoCommands.m module of the CAADialogEngine.edu framework:

where InstallRootDirectory is the directory where the CAA CD-ROM is installed.

[Top]

Step-by-Step

To create the CreatePoint, there are three steps:

[Top]

Providing an Undo Behavior to the Dialog Agents

The dialog agent undo behavior is set where they are instantiated, that is in the BuildGraph method. For example, for the _daEditor agent:

void CAADegCreatePolylineCmd::BuildGraph()
{
  ...
  _daEditor = new CATDialogAgent("PointEditorId");
  _daEditor->SetBehavior(CATDlgEngRepeat | CATDlgEngWithUndoStep); 
  ...	

The character string PointEditorId defined as the argument of the CATDialogAgent constructor is the dialog agent identifier. This identifier can be used to assign undo/redo prompts replacing the Undo and Redo items in the Edit menu.

For example, the active state is the target state of a transition triggered by a point indication that can be undone from this state to reach the previous state. In addition, this active state is the source state of a transition that triggers when the point editor dialog box sends an OK notification and is used to create the point using the entered coordinates.

The dialog agent behavior is set to CATDlgEngWithUndoStep to record an undo step when the dialog agent is valued. This enables this valuation step to be undone. This behavior is the default, that is, if CATDlgEngWithUndoStep were omitted in the SetBehavior method, an undo step were recorded anyway.

Changing CATDlgEngWithUndoStep to CATDlgEngWithUndo doesn't record an undo step for the dialog agent. This means that clicking Undo in the state that follows the one to which the dialog agent is plugged undoes the actions up until a state to which a dialog agent with a CATDlgEngWithUndoStep behavior is associated is met, and exits the command if none is found.

[Top]

Creating the Transition with Undo and Redo Methods

The transition are created in the BuildGraph method.

  ...
  CATDialogTransition *pRepeatTransitionBox = AddTransition
  (
    stRepeatState,
    stRepeatState,
    AndCondition(IsLastModifiedAgentCondition(_daEditor),
                 Condition((ConditionMethod) & CAADegCreatePolylineCmd::CheckPointByBox)),
    Action(
           (ActionMethod) & CAADegCreatePolylineCmd::CreateLineByBox,
           (ActionMethod) & CAADegCreatePolylineCmd::UndoCreateLine,
           (ActionMethod) & CAADegCreatePolylineCmd::RedoCreateLine 
          )
  ); 
  ...

The second and third parameters of the Action method are the undo and redo method declarations respectively. These methods are usually member functions of the state dialog command class, as shown here. The UndoCreateLine method undoes the line segment craeted by CreateLineByBox, and the RedoCreateLine redoes this line segment creation.

[Top]

Providing the Undo and Redo Methods

The UndoCreateLine and RedoCreateLine methods have the following signatures.

...
CATBoolean CAADegCreatePolylineCmd::UndoCreateLine(void *iUsefulData)
{
  ... // Provide ubdo code here  
}

CATBoolean CAADegCreatePolylineCmd::RedoCreateLine(void *iUsefulData)
{
  ... // Provide redo code here
}
...

[Top]

In Short

This use case shows how to include input and action undo/redo capabilities to a command. Input undo/redo is for dialog agents and set using the dialog agent behavior. Action undo/redo is added to transitions to undo and redo what action methods do when transition fire.

[Top]

References

History

Copyright © 2000, Dassault Systèmes. All rights reserved.