Command Scopes

Functions related to the Command Scopes of Archicad. They provide a way to post Undoable and NotUndoable commands to the message loop. More...

Classes
class	ACAPI::ModifierBase
	Base class of every Modifier classes used in ExecuteUndoableScope/ExecuteNotUndoableScope/CallDefaultModifier function. More...

Functions
ACAPI::Result< void > ARCHICADAPI_EXPORT	ACAPI::CallUndoableCommand (const std::function< GSErrCode()> &callback, const API_Token &token, const GS::UniString &undoString)
	It executes the given callback function in an Undoable scope.
GSErrCode __ACENV_CALL	ACAPI_Command_GetHttpConnectionPort (UShort *portNumber)
	Returns the HTTP port number, on which Archicad is expecting requests.
GSErrCode __ACENV_CALL	ACAPI_CallUndoableCommand (const GS::UniString &undoString, const std::function< GSErrCode()> &command)
	Performs an undoable operation.
GSErrCode __ACENV_CALL	ACAPI_CallCommand (const GS::UniString &commandName, const std::function< GSErrCode()> &command)
	Performs an operation without opening an undoable session.

Detailed Description

Functions related to the Command Scopes of Archicad. They provide a way to post Undoable and NotUndoable commands to the message loop.

Command Overview

Archicad uses the command concept to represent and execute a user operation. All data structure modifications (except IO processes) should be performed during command execution. In case of element change notifications, the command is started, executed and managed by Archicad. Add-ons also can start and execute commands.

In case of undoable operations all modifications should be done in a lambda function which is executed by ACAPI_CallUndoableCommand.
Undoable commands can be executed only from the main thread. Use ACAPI_AddOnAddOnCommunication_CallFromEventLoop mechanism to pass the control to the main thread.

There are two possibilities to modify non-undoable data structures:

• in order to execute several modification functions as a single command, group them with an ACAPI_CallCommand call
• call every function as in the past. In this case every command will be treated as a separate command by Archicad, which means that all necessary derived data calculations, screen refresh, etc. will be performed after each function call.

Nested command execution is forbidden: you cannot start a new command execution when an existing command is still running.

Complete operations (i.e. opening a plan) cannot be called during command execution, as they may execute several commands themselves.

Because of the command concept, new rules are introduced for API functions. The API functions are divided into four groups:

• Functions that don't modify data structures - there are no special rules for them.
• Undoable data structure modifier functions (i.e. elem operations) - these functions can only be called during undoable commands (started by Archicad or an add-on)
• Non-undoable data structure modifier functions (i.e. attributes, environment functions) - these functions can be called from a batch operation using ACAPI_CallCommand, and also can be called standalone.
• Complete operations - these functions perform complete operations, so they cannot be called neither during undoable operations nor during non-undoable commands.

Function Documentation

ACAPI_CallCommand()

GSErrCode __ACENV_CALL ACAPI_CallCommand	(	const GS::UniString &	commandName,
		const std::function< GSErrCode()> &	command
	)

Performs an operation without opening an undoable session.

Parameters

commandName	[in] Reserved for further use, this string won't appear anywhere.
command	[in] The lambda function (C++11 function wrapper) that encapsulates all the operations.

Returns

• NoError - The function has completed with success.
• APIERR_REFUSEDCMD - An operation has already opened, or the current command is undoable.
• APIERR_COMMANDFAILED - The current command threw an exception.

Remarks

This function is used to execute more not-undoable data structure modifier functions in a single command.

ACAPI_CallUndoableCommand()

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

Performs an undoable operation.

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.

Returns

• 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.

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

ACAPI_Command_GetHttpConnectionPort()

GSErrCode __ACENV_CALL ACAPI_Command_GetHttpConnectionPort

(

UShort *

portNumber

)

Returns the HTTP port number, on which Archicad is expecting requests.

Parameters

portNumber

[out] HTTP port number.

Returns

• NoError - The function has completed with success.
• APIERR_BADPARS - the portNumber parameter is nullptr.
• APIERR_GENERAL - there is an internal error and the HTTP server could not be started.

Remarks

This function is used to get the HTTP port on which the Add-On commands, registered via ACAPI_AddOnAddOnCommunication_InstallAddOnCommandHandler, can be accessed.

CallUndoableCommand()

ACAPI::Result< void > ARCHICADAPI_EXPORT ACAPI::CallUndoableCommand	(	const std::function< GSErrCode()> &	callback,
		const API_Token &	token,
		const GS::UniString &	undoString
	)

It executes the given callback function in an Undoable scope.

Parameters

callback	The function that will be executed inside the Undoable scope.
token	The token of the add-on that is calling the command.
undoString	The string that will be displayed in the Undo/Redo menu.

Returns

The return type is ACAPI::Result<void>.