APIEnv_​SetToolBoxModeID

Sets the actual toolbox mode.

    GSErrCode ACAPI_Environment (
        APIEnv_SetToolBoxModeID,
        API_ToolBoxItem*     toolBoxItem
    );

 

Parameters

toolBoxItem
[in] Toolbox mode to be set.

 

Return Values

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

For other common API errors see the API Errors document.

 

Remarks

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.

 

Example


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

 

Requirements

Version: API 2.1 or later
Header: APIdefs_Environment.h

 

See Also

API_ToolBoxItem,
APIEnv_GetToolBoxModeID,
ACAPI_Environment, API Functions