APIIo_GetPolyID |

Performs polygon input.

    GSErrCode ACAPI_Interface (
        APIIo_GetPolyID,
        API_GetPolyType*             polyInfo,
        API_RubberPolyCallbacks*     rubberPolyCallbacks
    );

Parameters

polyInfo: [in/out] Parameters of the polygon input operation.
rubberPolyCallbacks: [in] Callback functions for custom feedback drawing. Optional, can be nullptr.

Return Values

NoError: The function has completed with success.
APIERR_BADPARS: polyInfo is nullptr or one of the rubber callback function pointers in rubberProcs is nullptr
APIERR_BADPLANE: Invalid plane definition in polyInfo
APIERR_BADWINDOW: The operation cannot be performed in the current front window of the application
APIERR_CANCEL: The input was canceled by the user

For other common API errors see the API Errors document.

Remarks

This function is used to let the user input a polygon graphically.

If the input process has failed, the function returns APIERR_CANCEL. Otherwise the result is returned in the coords, parcs, nCoords, nArcs and polylineWas fields of polyInfo. The returned polygon consists of at least 2 points. The polygon’s coordinates start from index 1, and the polygon is closed if polyInfo->polylineWas is false, meaning that the last point is equal to the first. Do not forget to dispose the coords and parcs handle with BMKillHandle.

If changePlane has not been set for the input, the z coordinates of the polygon nodes can be also retrieved in the zCoords handle by passing true in the getZCoords member of API_GetPolyType. In this case the add-on should dispose this handle when it is not needed any more.

The start point of the polyline can be defined directly, or entered graphically with the APIIo_GetPointID interface function.

The prompt string displayed in the control box can contain instructions about the action. You can control the cursor shapes, set the input plane and the specify the polygon input method. From API v3.1 it is possible to draw your own graphical feedback during the input, as it is provided in the APIIo_GetPointID, APIIo_GetLineID, APIIo_GetArcID functions. For more details on the utilization refer to the documentation of the API_GetPolyType structure.

Do not invoke any input operation while there are modal dialogs open.

Example


API_GetPointType    pointInfo;
API_GetPolyType     polyInfo;
Int32               ind;
char                buffer [256];
GSErrCode           err;

BNZeroMemory (&pointInfo, sizeof (API_GetPointType));
BNZeroMemory (&polyInfo, sizeof (API_GetPolyType));

CHCopyC ("Click the first node of the polygon", pointInfo.prompt);

err = ACAPI_Interface (APIIo_GetPointID, &pointInfo, nullptr);

if (err == NoError) {
    CHCopyC ("Enter the polygon nodes", polyInfo.prompt);
    polyInfo.startCoord = pointInfo.pos;                  /* polygon starts with the clicked point */
    polyInfo.method = APIPolyGetMethod_General;

    err = ACAPI_Interface (APIIo_GetPolyID, &polyInfo, nullptr);
}

if (err == NoError) {
    ACAPI_WriteReport ("Polygon Coordinates:", false);
    for (ind = 1; ind <= polyInfo.nCoords; ind++) {
        sprintf (buffer, "[%2d]  (%Lf, %Lf)", ind, (*polyInfo.pos) [ind].x, (*polyInfo.pos) [ind].y);
        ACAPI_WriteReport (buffer, false, false);
    }
} else if (err == APIERR_CANCEL)
    ACAPI_WriteReport ("Input was interrupted", true);

See also the Interface_Functions example project of APIDevKit.

Requirements

Version: API 3.1 or later

Header: APIdefs_Interface.h

Parameters

Return Values

Remarks

Example

Requirements

See Also