In order to show a link on the map we need to add an object to the scene. The use of the API is independent from the actual UI technology the VB control is used with. However, there might be also specific API wrappers in certain integrations, e.g. in the FPM integration.
First you need to fill a structure of type IF_VBI_SERVICE_PROVIDER=>LINK_ENTRY. You need to fill field ID and optionally GUID. In case the later is left empty, the Scene Manager will assign a GUID internally.
Important NoticeThe GUID will be the primary key of the object and is also given in the event data in order to specify the event source. Thus we recommend to assign the GUID on application level. You may create a suitable GUID on your own with method CL_VBI_SCENE_MANAGER=>GET_NEW_OBJECT_GUID().
Since our object should be a link, we need to specify at least the location of the start and destination point. This is done by filling sub-structures LINK_START-POSITION and LINK_DEST-POSITION. The field XPOS holds the longitude and YPOS the latitude value of the location. The ZPOS as height is currently not supported. Optionally you can also assign spot objects to the start and destination of the link by providing the GUID of the spots as LINK_START-
REFERENCE_SPOT_GUID and LINK_DEST-REFERENCE_SPOT_GUID.
If the link object should have a tooltip you can fill sub-table DESCRIPTION. This table allows you to have multi-line tooltips. This table can also store data to be shown in a detail window. The purpose of an entry is determined by field CATEGORY. The available values are defined in IF_VBI_CONST=>GC_DESCR_CATEGORY.
Structure IF_VBI_SERVICE_PROVIDER=>LINK_ENTRY provides also a set of flags:
- HIGHLIGHTED: allows you to highlight the object by using a different pin image (by default with a yellow pin border).
- FLY_TO: indicates that you want an animated zoom to the object location.
- SELECTED: Indicates the object as selected (by default with a grey pin border).
- FIXED: Protects the object against easy deletion.
Further you can provide a line color (FILL_COLOR) and line border color (BORDER_COLOR) in RGB(A) or HLS(A) notation.
Info on color notationThe RGB(A) notation provides the values for Red, Green, Blue, and optionally the transparency (Alpha channel), separated by semicolon. You can provide the values in decimal (0 - 255) format. Example: RGBA(107;152;202;180). Alternatively also the HLS(A) notation with Hue, Lightness, Saturation, and optionally the transparency (Alpha channel) is supported.
Finally you can assign one or more roles to the object by adding them to sub-table ROLES. The role may influence also the color of the link. The pre-defined roles are defined in constants interface IF_VBI_GEOMAP_CONST structure attribute GC_OBJECT_ROLE.
In order to send the new object to the GeoMap the structure is added to a table of type IF_VBI_SERVICE_PROVIDER=>LINK_TAB. This table is than given to the GeoMap service provider by calling method UPDATE_SCENE_OBJECTS as parameter IT_LINKS.
After this you may add further object to the scene. Once your are done you need to trigger the update of the frontend control by raising event IF_VBI_CONST=>GC_EVENT-DISPLAY_SCENE on the scene manager (method HANDLE_EVENT).
The following code snipped from local class LCL_APPLICATION (inheriting from CL_VBI_GEOMAP_APPLICATION) of program VBI_GUI_TEST method ADD_LINK is an easy example on how to create a spot object:
The result looks like this:
Of course it is also possible to define links with intermediate points, which, in the end, allows you to display a detailed route. In that case you have to fill sub-table ROUTE_POINTS in addition to setting LINK_START end LINK_DEST. The start and destination position are part of table ROUTE_POINTS as well!
Here again a code snipped from class LCL_APPLICATION method SHOW_ROUTE (from the sample program VBI_GUI_TEST):
The resulting route could look like this: