ACAPI_LibPart_GetHotspots

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 or hotspots parameter is nullptr, or invalid libInd has been passed
APIERR_BADINDEX: Invalid instanceElemGuid for the element type that libInd 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:

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

Parameters

Return Values

Remarks

Example

Requirements

See Also