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->type 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.type = API_ZombieElemID;
if (ClickAnElem ("Click an element to set toolbox mode", API_ZombieElemID, nullptr, &tboxInfo.type, &guid, nullptr)) {
    if (tboxInfo.type == API_ObjectID || tboxInfo.type == API_LampID ||
        tboxInfo.type == API_WindowID || tboxInfo.type == API_DoorID)
    {
        BNZeroMemory (&element, sizeof (API_Element));
        element.header.type.typeID   = tboxInfo.type.typeID;
        element.header.guid          = guid;
        err = ACAPI_Element_Get (&element);
        if (err == NoError)
            tboxInfo.type.variationID = element.header.type.variationID;
    }
}

err = ACAPI_Environment (APIEnv_SetToolBoxModeID, &tboxInfo, nullptr, nullptr);
if (err == NoError) {
    if (tboxInfo.type == API_ZombieElemID)
        WriteReport ("Current toolbox mode: Arrow");
    else {
        if (tboxInfo.type.variationID == APIVarId_Generic) {
            WriteReport ("Current toolbox mode: %s", ElemID_To_Name (tboxInfo.type));
        } else {
            char *p = (char *) &tboxInfo.type.variationID;
            WriteReport ("Current toolbox mode: %s  External \"%c%c%c%c\"", ElemID_To_Name (tboxInfo.type), 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