Sets the actual toolbox mode.

    GSErrCode ACAPI_Environment (
        API_ToolBoxItem*     toolBoxItem



[in] Toolbox mode to be set.


Return Values

The function completed with success.
The variationID of the library part type does not match to the toolbox mode type
toolBoxItem->typeID contains invalid data

For other common API errors see the API Errors document.



This function is used to change the current toolbox mode. The mode is specified by the element type ID. For those types which can have more toolbox modes (ID_Wind, ID_Door, ID_Symb, ID_Light), the variationID of the tool should also be supplied. For API_ZombieElemID or an invalid element type ID specification the arrow mode will be set.

Note that the function does not switch the toolbox immediately, but posts an event into the application queue. The command will be executed only when the application events are processed.

To get the active toolbox mode use the APIEnv_GetToolBoxModeID function.



API_Guid        guid;
API_Element     element;
API_ToolBoxItem tboxInfo;
GSErrCode       err;

BNZeroMemory (&tboxInfo, sizeof (API_ToolBoxItem));
tboxInfo.typeID = API_ZombieElemID;
tboxInfo.variationID = APIVarId_Generic;
if (ClickAnElem ("Click an element to set toolbox mode", API_ZombieElemID, nullptr, &tboxInfo.typeID, &guid, nullptr)) {
    if (tboxInfo.typeID == API_ObjectID || tboxInfo.typeID == API_LampID ||
        tboxInfo.typeID == API_WindowID || tboxInfo.typeID == API_DoorID)
        BNZeroMemory (&element, sizeof (API_Element));
        element.header.typeID   = tboxInfo.typeID;
        element.header.guid     = guid;
        err = ACAPI_Element_Get (&element);
        if (err == NoError)
            tboxInfo.variationID = element.header.variationID;

err = ACAPI_Environment (APIEnv_SetToolBoxModeID, &tboxInfo, nullptr, nullptr);
if (err == NoError) {
    if (tboxInfo.typeID == API_ZombieElemID)
        WriteReport ("Current toolbox mode: Arrow");
    else {
        if (tboxInfo.variationID == APIVarId_Generic) {
            WriteReport ("Current toolbox mode: %s", ElemID_To_Name (tboxInfo.typeID));
        } else {
            char *p = (char *) &tboxInfo.variationID;
            WriteReport ("Current toolbox mode: %s  External \"%c%c%c%c\"", ElemID_To_Name (tboxInfo.typeID), p[0], p[1], p[2], p[3]);



Version: API 2.1 or later
Header: APIdefs_Environment.h


See Also

ACAPI_Environment, API Functions