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=>AREA_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.
The 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 an area, we need to specify a list of border points. This is done by filling sub-table BORDER_POINTS. The line type of this table is VBI_S_OBJ_GEOPOS. The field XPOS of this structure holds the longitude and YPOS the latitude value of the location. The ZPOS as height is currently not supported.
If the area 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=>AREA_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 fill color (FILL_COLOR) and a 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=>AREA_TAB. This table is than given to the GeoMap service provider by calling method UPDATE_SCENE_OBJECTS as parameter IT_AREAS.
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_AREA is an easy example on how to create a spot object:
The result may look like this (here with more points inserted than in the above sample code):