Creates a new Navigator viewpoint root, group or leaf node in the Project Map.

    GSErrCode ACAPI_Navigator (
        APINavigator_CreateNavigatorVPItemID,
        API_NavigatorAddOnViewPointData*     viewPointData
    );

 

Parameters

viewPointData

[in/out] Details of the viewpoint root, group or leaf node to be created. The guid member will be filled out on return.

 

Return Values

NoError

The function has completed with success.

APIERR_BADPARS

viewPointData was nullptr.

viewPointData.itemType was API_NavigatorAddOnViewPointUndefinedID.

APIERR_BADID

viewPointData.guid is already used, i.e. an object already exists with the same GUID. Note: if viewPointData.guid was set to APINULLGuid, a GUID is generated for the Navigator root group or group to be created, and this error can never come.

viewPointData.parentGuid does not designate an already existing viewpoint group.

APIERR_NOACCESSRIGHT

The function was called in teamwork mode, and a root or group was to be created.

For other common API errors see the API Errors document.

 

Example

This example creates a root group, a group and a leaf node, and then verifies, that the created leaf node has the expected content.

    // create a root group

API_NavigatorAddOnViewPointData rootVP;                    // Do not memset! This is not a POD type.
rootVP.itemType    = API_NavigatorAddOnViewPointRootID;
rootVP.displayName = "My AddOn's Root";
DBVERIFY (ACAPI_Navigator (APINavigator_CreateNavigatorVPItemID, &rootVP) == NoError);

    // create a group

API_NavigatorAddOnViewPointData groupVP;
groupVP.parentGuid  = rootVP.guid;
groupVP.itemType    = API_NavigatorAddOnViewPointGroupID;
groupVP.displayName = "Group Name";
DBVERIFY (ACAPI_Navigator (APINavigator_CreateNavigatorVPItemID, &groupVP) == NoError);

    // create a leaf node

API_NavigatorAddOnViewPointData nodeVP;
nodeVP.parentGuid        = groupVP.guid;
nodeVP.itemType          = API_NavigatorAddOnViewPointNodeID;
nodeVP.displayId         = "1";
nodeVP.displayName       = "Node Name";
nodeVP.viewSettingsFlags = API_NavgatorViewSettingsLayerAttributeID | API_NavgatorViewSettingsScaleAttributeID;
nodeVP.data              = BMhAll (13);
strcpy (*nodeVP.data, "Hello World!");
DBVERIFY (ACAPI_Navigator (APINavigator_CreateNavigatorVPItemID, &nodeVP) == NoError);

    // query

API_NavigatorAddOnViewPointData nodeVP2;
nodeVP2.guid = nodeVP.guid;
DBVERIFY (ACAPI_Navigator (APINavigator_GetNavigatorVPItemID, &nodeVP2) == NoError);
DBASSERT (nodeVP2.displayId         == nodeVP.displayId);
DBASSERT (nodeVP2.displayName       == nodeVP.displayName);
DBASSERT (nodeVP2.itemType          == nodeVP.itemType);
DBASSERT (nodeVP2.guid              == nodeVP.guid);
DBASSERT (nodeVP2.parentGuid        == nodeVP.parentGuid);
DBASSERT (nodeVP2.viewSettingsFlags == nodeVP.viewSettingsFlags);
DBASSERT (CHEqualCStrings (*nodeVP2.data, *nodeVP.data));

// API_NavigatorAddOnViewPointData's destructor will free nodeVP.data and nodeVP2.data

 

Remarks

Creating a root group

Set viewPointData.itemType to API_NavigatorAddOnViewPointRootID.

When creating a root group, viewPointData.parentGuid and viewPointData.viewSettingsFlags is ignored.

If viewPointData.guid was provided on input, the function creates a root group with the given GUID. If an object with the same GUID already exists, the function returns APIERR_BADID.

Creating a group

Set viewPointData.itemType to API_NavigatorAddOnViewPointGroupID.

When creating a group, viewPointData.viewSettingsFlags is ignored.

If viewPointData.guid was provided on input, the function creates a group with the given GUID. If an object with the same GUID already exists, the function returns APIERR_BADID.

Creating a leaf node

Set viewPointData.itemType to API_NavigatorAddOnViewPointNodeID.

viewPointData.guid is ignored. A leaf node is always created with an internally generated GUID.

Note: In teamwork mode you cannot create, change or delete viewpoint roots or groups.

 

Requirements

Version: API 22 or later

Header: APIdefs_Navigator.h

 

See Also

APINavigator_GetNavigatorVPItemID,
ACAPI_Navigator,
API Functions