Recording Object States

The state of an object is recorded using an undo filer every time its object properties are about to be modified. This ensures that the system is ready at any time if the undo command is invoked. You must take this into account when developing a custom object.

Note: In some cases, recording the object state is not required. When implementing modification methods of a custom object, there is no need to take this feature into consideration.

The first thing every modification method should do is call the object's assertWriteEnabled() method to ensure it is write-enabled.

void assertWriteEnabled(bool autoUndo = true, bool recordModified = true);

Parameters:

autoUndo — Specifies whether to use automatic undo.
recordModified — Specifies whether graphics are updated and the notifications "openedForModify", "modified" and "modifiedGraphics" are sent.

The assertWriteEnabled() method checks whether the object is open for writing by calling its isWriteEnabled() method. If the object is not write-enabled, assertWriteEnabled() throws the eNotOpenForWrite exception.

Every modification method of an object must record the current state of the object before applying any changes. The simplest way to implement this is using automatic undo. Automatic undo is the optimal way for implementing the undo functionality for most entities. When automatic undo is applied, the complete state of the object is recorded. To enable automatic undo state recording, you only need to set the autoUndo parameter to true for the assertWriteEnabled() method (it is true by default, which allows calling the method without parameters).

If the object uses automatic undo, the state of the object is recorded by calling its dwgOutFields() method.

Note: Automatic undo recording via dwgOutFields()is performed once per transaction. If the complete object state was already saved in the current transaction, automatic undo will not record anything else. Partial undo is written in each call to the set() functions using it even if automatic undo recording already saved the whole object state.

In most cases you can completely rely on automatic undo functionality, but you may want to implement a custom mechanism for recording the object state if:

The volume of data describing the state of the object is big, and
Applied changes affect a small amount of data.

Implementing custom undo recording allows you to save only those parameters of the object that are being changed by the modification method.

See Also