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