Retrieves the hotspots of a registered Library Part.
GSErrCode ACAPI_LibPart_GetHotspots ( Int32 libInd, const API_Guid& instanceElemGuid, Int32* nHotspots, API_PrimHotspot*** hotspots );
Parameters
- libInd
- [in] Index of the library part
- instanceElemGuid
- [in] Instance element GUID; if APINULLGuid, then the drawing parameters will be the default parameters of the library part (with no transformation, etc.), otherwise they are taken from the instance of the library part defined by this GUID.
- nHotspots
- [out] Numbers of hotspots.
- hotspots
- [out] Handle that contains the hotspot data on return.
Return Values
NoError
- The function has completed with success.
APIERR_BADPARS
nHotspots
orhotspots
parameter isnullptr
, or invalidlibInd
has been passedAPIERR_BADINDEX
- Invalid
instanceElemGuid
for the element type thatlibInd
implies
Remarks
This function is used to retrieve the hotspots of the Libpart Part.
The library part is identified the same way as ACAPI_LibPart_ShapePrims does.
The hotspots return in an array of API_PrimHotspot structures. The coordinate values in the loc
field are interpreted in the local coordinate system of the library part, however if the referred element instance has been resized, the coordinates follow the scale.
If you would like to get the actual position of a hotspot of the specified element instance, use the neig
field to convert the coordinates.
Do not forget to dispose the hotspots
handle after the operation.
The function works only on Library Parts that can be placed onto the floor plan. Applicable type of Library Parts are:
- APILib_WindowID
- APILib_DoorID
- APILib_ObjectID
- APILib_LampID
- APILib_RoomID (zone stamp)
- APILib_LabelID (symbol label)
Example
API_PrimHotspot** hotspots = nullptr; Int32 nHotspots = 0; Int32 libInd = 1990; /* a given library part index */ API_Guid instanceElemGuid = element.header.guid; /* GUID of an element placed on the floorplan with the corresponding libpart reference */ GSErrCode err = ACAPI_LibPart_GetHotspots (libInd, instanceElemGuid, &nHotspots, &hotspots); if (err == NoError && hotspots != nullptr) { API_Element element; BNZeroMemory (&element, sizeof (API_Element)); element.header.typeID = API_HotspotID; err = ACAPI_Element_GetDefaults (&element, nullptr); if (err == NoError) { short ind; for (ind = 0; ind < nHotspots; ind++) { // draw hotspots in local coordinates element.hotspot.pen = ind; element.hotspot.pos = (*hotspots)[ind].loc; ACAPI_Element_Create (&element, nullptr); } for (ind = 0; ind < nHotspots; ind++) { // draw hotspots according to the neigs element.hotspot.pen = ind; err = ACAPI_Goodies (APIAny_NeigToCoordID, &(*hotspots)[ind].neig, &element.hotspot.pos); if (err == NoError) ACAPI_Element_Create (&element, nullptr); } } } BMKillHandle ((GSHandle*) &hotspots);
Requirements
- Version: API 5.2 or later
- Header: ACAPinc.h
See Also
API_LibTypeID
ACAPI_LibPart_ShapePrims
ACAPI_Element_ShapePrims
LibPart Manager
API Functions