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
wasnullptr
.viewPointData.itemType
wasAPI_NavigatorAddOnViewPointUndefinedID
.APIERR_BADID
viewPointData.guid
is already used, i.e. an object already exists with the same GUID. Note: ifviewPointData.guid
was set toAPINULLGuid
, 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
toAPI_NavigatorAddOnViewPointRootID
. - When creating a root group,
viewPointData.parentGuid
andviewPointData.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 returnsAPIERR_BADID
. - Creating a group
- Set
viewPointData.itemType
toAPI_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 returnsAPIERR_BADID
. - Creating a leaf node
- Set
viewPointData.itemType
toAPI_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