Undo and redo#

Most SAMSON SDK operations that modify the data graph can participate in the undo/redo system.

As a developer, the main question is not whether undo exists, but how to group your own changes into meaningful user-level actions. The SAMSON API uses the concept of a holding for that purpose.

If a function is undoable, its API documentation explicitly says so.

Basic pattern#

Wrap related modifications between SAMSON::beginHolding(...) and SAMSON::endHolding().

Example:

SBCamera* camera = SAMSON::getActiveCamera();   // get the active camera

SAMSON::beginHolding("Change camera name");     // turn the Undo system on
camera->setName("New camera name");             // change the camera name
SAMSON::endHolding();                           // turn the Undo system off

SAMSON::undo();                                 // undo the name change

In that example, the camera rename becomes one undoable action named Change camera name.

Mental model#

Think of a holding as an undo transaction:

changes inside one holding are grouped together
the group appears as one step in the user's history
undo() and redo() replay or revert the grouped action

That means you should group operations according to user intent, not according to low-level implementation details.

When to start a holding#

Start a holding when your extension is about to perform a coherent state change such as:

creating a new object
deleting or replacing nodes
applying a transform to a selection
changing several related properties as one command

If a user presses one button and your code updates ten nodes, that usually belongs in one holding.

Common pitfalls#

Do not forget to call SAMSON::endHolding() after beginHolding(...).
Do not create overly granular undo steps for a single user command.
Do not wrap internal temporary state changes in separate holdings unless the user should actually see them in history.

For advanced cases, SAMSON also provides functions such as SAMSON::disableHolding and SAMSON::enableHolding to control holding behavior.

Practical example#

Suppose an app creates a custom node, assigns several properties, and attaches a visual model.

From the user's perspective, that is one action: "Create custom object". Even if several SDK calls are involved, they should usually be grouped in one holding so a single undo() removes the full result.

Tip

See the User guide: History for the user's representation of the undo and redo mechanism.