Performs an undoable operation.

    GSErrCode  ACAPI_CallUndoableCommand (
        const GS::UniString&                undoString
        const std::function<GSErrCode ()>&  command



[in] This string will appear after “Undo ” in the Edit menu. Should be localizable. When left empty:
  • “Paste” appears for merging and drag’n’drop operations
  • the name of the command will be shown after “Undo ” when the user chooses normal menu driven commands
[in] The lambda function (C++11 function wrapper) that encapsulates the command to be called during the undoable operation.


Return Values

The function has completed with success.
The current action is not undoable.
The current action is not undoable.
The current command threw an exception.
Another add-on has already opened an undoable operation.

For other common API errors see the API Errors document.



This function encapsulates a (series of) undoable steps (e.g. element creation). All the database modification operations check whether they are performed within an undoable command scope (a database transaction).

For some add-on types (e.g. I/O type add-ons) this function doesn’t have to be called, as it doesn’t make any sense to ‘undo’ opening a file.

Add-ons may not call this function from their element database event handler callback, because those notifications are sent from within an existing database transaction.

An add-on can perform more than one undoable command during one call. Just be aware that if the user completes an action in one step, it wouldn’t be too convenient for her/him to restore the previous state (perform an “undo”) in more than one step.



    GSErrCode err = ACAPI_CallUndoableCommand ("Create text",
        [&] () -> GSErrCode {
            return ACAPI_Element_Create (&element, &memo);

    if (err != NoError)
        ErrorBeep ("ACAPI_Element_Create (text)", err);

    ACAPI_DisposeElemMemoHdls (&memo);



Version: API 19 or later
Header: ACAPinc.h


See Also

ACAPI_CallCommand, API Functions