Undo System Manual

About

The undo system of Cinema 4D allows to store changes of elements so that these changes can be undone and redone. An undo action can contain multiple changes to multiple elements - all these changes will be undone in a single step when the undo action is applied. These undo actions are stored in an undo buffer and are created in a BaseDocument.

  • The undo system will create copies of the changed elements. This means that NodeData::Init(), NodeData::CopyTo() etc. of plugin classes will be called multiple times.
  • No undos should be created in expressions or generators etc. Undos should be created when the user interacts with the scene.
  • Using CallCommand() will create its own undo step (since it behaves like pressing the associated button in the GUI).
  • To start and end an undo based on some interaction in a GeDialog the messages BFM_INTERACTSTART and BFM_INTERACTEND can be used.

The Undo System

Creating Undos

Undo actions are added to the BaseDocument using these functions:

// This example creates a cube object and adds it to the document with an undo step.
if (!cube)
return false;
doc->StartUndo();
doc->InsertObject(cube, nullptr, nullptr);
doc->AddUndo(UNDOTYPE_NEW, cube);
doc->EndUndo();

The undo types are:

  • UNDOTYPE_CHANGE: Any change to an object, including hierarchy modifications; modification in positioning (e.g. object has been moved from A to B), substructures etc. Needs to be called BEFORE the change.
  • UNDOTYPE_CHANGE_NOCHILDREN: Same as UNDOTYPE_CHANGE, but without child modifications. Needs to be called BEFORE the change.
  • UNDOTYPE_CHANGE_SMALL: Change to local data only (e.g. data container). No substructures (e.g. no tags on an object) and no children. Needs to be called BEFORE the change.
// This example changes the radius of the given sphere object.
sphere->SetParameter(DescID(PRIM_SPHERE_RAD), 200.0, DESCFLAGS_SET_0);

UNDOTYPE_CHANGE_SELECTION: Change to point/poly/edge selection only. Needs to be called BEFORE the change.

// This example clears the point selection of the given PolygonObject.
PolygonObject* polygonObject = ToPoly(polyObject);
doc->AddUndo(UNDOTYPE_CHANGE_SELECTION, polygonObject);
BaseSelect* pSelect = polygonObject->GetPointS();
pSelect->DeselectAll();

UNDOTYPE_NEW: New object/material/tag etc. was created. Needs to be called AFTER the insertion.

// This example adds a new object to the scene.
if (cube)
{
doc->InsertObject(cube, nullptr, nullptr);
doc->AddUndo(UNDOTYPE_NEW, cube);
}

UNDOTYPE_DELETE: Object/node/tag etc. to be deleted. Needs to be called BEFORE removal.

// This example removes the given BaseObject.
doc->AddUndo(UNDOTYPE_DELETE, torus);
torus->Remove();

UNDOTYPE_BITS: Change to object bits, e.g. selection status. Needs to be called BEFORE the change.

// This example disables a video post effect.
doc->AddUndo(UNDOTYPE_BITS, videoPost);
videoPost->SetBit(BIT_VPDISABLED);

UNDOTYPE_HIERARCHY_PSR: Change in hierarchical placement and PSR values. Needs to be called BEFORE the change.

// This example moves the object "child" under the object "parent".
child->Remove();
doc->InsertObject(child, parent, nullptr);

Handle Undos

Undo actions can be applied using these functions:

// This example adds a new undo action.
// If something went wrong during the operation the last actions are undone.
Bool success = true;
doc->StartUndo();
// do something
doc->AddUndo(UNDOTYPE_CHANGE_SMALL, sphereObject);
sphereObject->SetParameter(DescID(PRIM_SPHERE_RAD), 200.0, DESCFLAGS_SET_0);
// let's assume something went wrong, could not be done or the user aborted the action
success = false;
const Bool hasundo = doc->GetUndoPtr() != nullptr;
// end the undo step and check for success
if (doc->EndUndo())
{
// if something went wrong, undo all actions
if (!success && hasundo)
doc->DoUndo();
}

User Interaction

If the user changes a parameter value in the Attribute Manager, Cinema 4D will create the proper undos. NodeData based plugins will receive a message to add custom operations to the automatically created undo action.

{
DescriptionInitUndo* uData = static_cast<DescriptionInitUndo*>(data);
// check if data and BaseDocument can be accessed
if (!uData || !uData->doc)
break;
// add undo for dependent entities
BaseDocument* doc = uData->doc;
return true;
}

Further Reading