Performs an undoable operation.

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

 

Parameters

undoString

[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

command

[in] The lambda function (C++11 function wrapper) that encapsulates the command to be called during the undoable operation.

 

Return Values

NoError

The function has completed with success.

APIERR_UNDOEMPTY

The current action is not undoable.

APIERR_REFUSEDCMD

The current action is not undoable.

APIERR_COMMANDFAILED

The current command threw an exception.

APIERR_NOTMINE

Another add-on has already opened an undoable operation.

 

For other common API errors see the API Errors document.

 

Remarks

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.

 

Example

    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);

 

Requirements

Version: API 19 or later

Header: ACAPinc.h

 

See Also

ACAPI_CallCommand, API Functions