Commands

To modify the data of a document, it is recommended to use the Application Framework command mechanism, which provides the following advantages:

• Undo/Redo mechanism - The Undo, Redo, and Repeat actions are automatically processed, as well as their state.

• The modification state of a document is automatically managed. Adding a command to an unmodified document will mark the document as modified (a star will appear in the title of the frames that contain views associated with this document). Similarly, undoing this command will restore the unmodified state of the document (and will remove the star from the title of the same frames).

• Keeps a log of all modifications made to the document.

Consider the following document class:

class MyDocument

: public IlvDvDocument

{

...

void setX(int x) { _x = x; }

int getX() const { return _x; }

protected:

int _x;

};

To modify the X property of the document while processing either a document view event/action or a document action, it is not recommended to call directly the setX method of the document. It is more appropriate to implement a command class (called ChangeXPropertyCommand in this example) that will modify this property:

class ChangeXPropertyCommand

: public IlvDvCommand

{

ChangeXPropertyCommand(MyDocument* document, int newX)

: _document(document),

_newX(newX)

{

_oldX = document->getX();

}

virtual void doIt() { setX(_newX); }

virtual void undo() { setX(_oldX); }

void setX(int x) { _document->setX(x); }

protected:

MyDocument* _document;

int _newX;

int _oldX;

};

Therefore, the implementation of a view or the document itself should invoke the following code to change the X property (instead of calling directly the setX method of the document):

document->doCommand(new ChangeXPropertyCommand(document, newX));

This code will execute the ChangeXPropertyCommand command by calling its doIt method, and will store it within a command history internally managed by the document.

Use the following method of the IlvDvDocument class to manage commands:

void doCommand(IlvDvCommand* cmd,

IlBoolean updateUI = IlTrue,

IlBoolean bSetModified = IlTrue);

This method is called to add the command object cmd to the history of internal commands. Then, the command is executed by calling its doIt method. The updateUI parameter specifies that the UI of the Undo, Redo, and Repeat commands must be updated. The bSetModified parameter specifies whether the modification flag of the document must be set to true.