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