You are here: Flex Container Support

Map Widget

If you want to display certain geographical locations on a map as part of your application, you should use a Map widget. The Map widget uses native maps such as Google Maps to display the relevant points. Map widgets also have callouts and annotations such as pins and label to display the information related to each coordinate.

Here are some use cases in which you can use a Map widget, instead of calling the Maps app such as Google apps:

• To display the location of branches and ATMs of banks.
• To track the transit of a package delivery/flight.
• To provide the information to a Field Service agent as to where the service needs to be provided.
• To show a route to an outlet location, such as a restaurant or a gym.

You can also use Map widgets to overlay the map with various shapes such as circle, polyline, and polygon; encode or decode the maps; add pins to the map; and customize information that needs to be displayed for each pin (by using callout). In addition, you can use a Map widget to determine the distance between two geographical coordinates.

A Map widget provides you the capability to display pre-defined locations (latitude and longitude) on an onscreen map. Platforms like iPhone (above 3.0), and Android provide a native map widget that can be displayed as part of the application.

On platforms where a native map widget is not available, the Map widget integrates with Google Maps and displays the static image with zoom and pan controls. You can customize the map view if you do not want to use the default view.

Widgets are normally added to your application using Volt MX Iris, but can also be added from code. For general information on using widgets in Volt MX Iris, see Designing an Application in the Iris User Guide.

For general information on the Map widget see the Map topic in the Volt MX Iris User Guide.

For a more hands-on approach on the functions of Map widget and features provided by the Map API, import and preview the Map Feature sample app by using Volt MX Iris.

The Map widget capabilities can be broadly categorized into the following:

• Layout
• Animations
• Data Management
• Gestures
• 3D Touch
• UI Appearance
• Enabling RTL
• Miscellaneous
• Configurations Common To All Widgets

Layout

Animations

Data Management

3D Touch

User Input Handling

UI Appearance

Enabling RTL

Miscellaneous

Configurations Common To All Widgets

Map Widget Basics

With the Map widget, your app can display a specific location, overlay it with circles, polygons, and polylines, and add highly customizable pins. With these capabilities, you app can, for instance, show the user a circular or rectangular area in which the app will search for certain types of businesses.

In addition, your app can search for possible routes between a source and a destination location and show them on the map by drawing a polyline.

Note: On Android platform, Map widget does not work in Popup.

Flex Container Support

When designing and developing your app, you can place a Map widget inside a flex container such as a FlexForm, a FlexContainer, or a FlexScrollContainer. You can also apply flex templates to Map widgets to aid in customizing their appearance. However, flex templates cannot be applied to Map widgets that are placed inside a box container such as an HBox or VBox. Flex templates can only be used on Map widgets that you have placed inside a flex container. In addition, you can use flex containers and flex templates for your pin callouts.

When used within a flex container, callouts behave in ways that are different from most widgets. For example, the Map widget does not use the flex container positional properties for callouts because it always displays callouts at the pin location. Because the Map widget itself is not derived from a flex container, the implicit calculations that normally occur with flex dimensional parameters are not performed with a Map widget’s callouts. If the callout does not have an explicit width and height specified, the flex container default width and height are applied. When you apply callout templates to callounts in the Map widget, the Map widget ignores the calloutWidth property entirely.

Since a Flex container has the width and height properties, the calloutWidth property of a Map is ignored when using a Flex callout template.

Positional parameters of Flex containers are not respected since callouts are always displayed at the pin location rather than positions specified. Implicit calculations of flex dimensional values are not supported as its parent (the Map widget) is not a Flex container. If the widget does not have explicit width and height specified, Flex container default width and height are applicable.

Mapping Services

The Map widget renders a map using the mapping service provided by the platform. The following table shows the list of platforms and the available mapping services:

To generate and configure Android Google Map APIs click here.

Creating a Map Using a Constructor: voltmx.ui.Map

var mymap = new voltmx.ui.Map(basicConf, layoutConf, pspConf);

• basicConf is an object with basic properties.
• layoutConf is an object with layout properties.
• pspConf is an object with platform specific properties.

Note: The configuration properties should be passed only in the respective configuration objects otherwise they are ignored

Map Examples

Example 1: Creating a Map Dynamically

//The below function is the callback function for onPinClick event.
function onPinClickCallBck(map) {
    alert("onPinClick event triggered");
}

//Defining the map properties
var mapBasicConf = {
    id: "map1",
    provider: constants.MAP_PROVIDER_GOOGLE,
    mapKey: "0z5UtaSPUYj42f5qX0VAwmDGLX39Qxgbtcra0TA", //Provide your own Google map key.
    defaultPinImage: "kmpin.png",
    isVisible: true,
    onPinClick: onPinClickCallBck
};

var mapLayoutConf = {
    margin: [20, 40, 50, 20],
    containerWeight: 100,
    widgetAlignment: constants.WIDGET_ALIGN_BOTTOM_LEFT,
    padding: [10, 10, 10, 10],
    hExpand: false,
    vExpand: false
};

var mapPSPConf = {
    mode: constants.MAP_VIEW_MODE_HYBRID,
    showCurrentLocation: constants.MAP_VIEW_SHOW_CURRENT_LOCATION_AS_PIN
};
//Creating the map with the properties defined above.
var map = new voltmx.ui.Map(mapBasicConf, mapLayoutConf, mapPSPConf);

Example 2: Using Flex Containers in Maps

var lbl1 = new voltmx.ui.Label({
    "height": "26dp",
    "id": "lbl1",
    "left": "1dp",
    "top": "85dp",
    "width": "100dp",
    "zIndex": 1….
}, {….
}, {….
});

flexTemp1 = new voltmx.ui.FlexContainer({
    "bottom": "50dp",
    "clipBounds": true,
    "id": "flexTemp1",
    "isVisible": true,
    "layoutType": voltmx.flex.FREE_FORM,
    "left": "0dp",
    "Location": "[0,0]",
    "right": "200dp",
    "skin": "flexskin1",
    "top": "0dp",
    "zIndex": 1
}, {
    "padding": [0, 0, 0, 0]
}, {});;

flexTemp1.add(lbl1);
mapWidget.calloutTemplate = flexTemp1;
frmMap1.map1.widgetDataMapForCallout = {
    "lbl1": "lbl1"
};
frmMap1.map1.locationData = [{
    lat: "17.377513",
    lon: "78.475895",
    name: "HCL",
    desc: "Hyderabad,Telangana",
    showCallout: true,
    calloutData: {
        lbl1: "HCL"
    }
}]		

Managing Map Pins

The following example shows how to add, delete and update map pins.

/******************************************************************
 *	Name    : mapPins
 *	Author  : HCL
 *	Purpose : To add pins corresponding to location data.
 *******************************************************************/
function mapPins() {
    frmMapNew.MainMap.locationData = [{
        lat: "17.447326",
        lon: "78.371358",
        name: "HCL(new)",
        desc: "Phoenix infocity, Gachibowli"
    }, {
        lat: "17.441839",
        lon: "78.380928",
        name: "HCL",
        desc: "HCL",
        image: "pin.png",
        meta: {
            color: "red",
            label: "A"
        }
    }, {
        lat: "17.450378",
        lon: "78.388398",
        name: "House",
        desc: "Madhapur, Hyderabad, Andhra Pradesh",
        image: "pin.png",
        meta: {
            color: "yellow",
            label: "B"
        }
    }, ];

    //   frmMapNew.MainMap.addPin(pin1);
}

// Creating Pins 
pin1 = {
    id: "id1", // id is mandatory for every pin
    lat: "17.4947934",
    lon: "78.3996441",
    name: "KPHB",
    image: "defaultImage.png",
    focusImage: ”focusImage.png ",  //focus image will be shown while map pin selected
	desc: "Kukatpally ",
	showCallout : true,
	meta: {
		color: "green ",
		label: "A "
	}
};
  
pin2 = {
	id : "id2 ", // id is mandatory for every pin
	lat : "17.3616 ",
	lon : "78.4747 ",
	name : "Charminar ",
	image : "defaultImage.png ",
	focusImage:"focusImage.png", //focus image will be shown while map pin selected
    desc: "In Hyderabad",
    showCallout: true,
    meta: {
        color: "green",
        label: "B"
    }
};

pin3 = {
    id: "id3", // id is mandatory for every pin
    lat: "17.2543",
    lon: "78.6808",
    name: "Ramoji",
    image: "defaultImage.png",
    focusImage: ”focusImage.png ",  //focus image will be shown while map pin selected
	desc : "Film City in Hyderabad ",
	showCallout : true,
	meta: {
		color: "green ",
		label: "C "
	} 
};
/******************************************************************
*	Name    : addPin
*	Author  : HCL
*	Purpose : To Dynamically add pin to the Map widget.
*******************************************************************/
function addPin ()
{
	frmMapNew.MainMap.addPin(pin1);
}

/******************************************************************
*	Name    : addPins
*	Author  : HCL
*	Purpose : To Dynamically add pins to the Map widget.
*******************************************************************/
function addPins()
{ 
	frmMapNew.MainMap.addPins([pin2,pin3]);
}

/******************************************************************
*	Name    : deletePin
*	Author  : HCL
*	Purpose : To Dynamically delete pin from the Map widget.
*******************************************************************/
function deletePin()
{
	frmMapNew.MainMap.removePin(pin1);
}

/******************************************************************
*	Name    : deletePins
*	Author  : HCL
*	Purpose : To Dynamically delete pins from the Map widget.
*******************************************************************/
function deletePins()
{
	frmMapNew.MainMap.removePins([pin2,pin3]);
}

/******************************************************************
*	Name    : updatePin
*	Author  : HCL
*	Purpose : To Dynamically update pin of a Map widget.
*******************************************************************/
function updatePin()
{
	pinTemp = {
		id : "id1 ",  // id is mandatory for every pin
		name : "Kukatpally Housing Board ",
	};
	frmMapNew.MainMap.updatePin(pinTemp);
	frmMapNew.lblUpdate.text = "
    updated the name of added pin ";
}

/******************************************************************
*	Name    : updatePins
*	Author  : HCL
*	Purpose : To Dynamically update pins of a Map widget.
*******************************************************************/

function updatePins()
{
	pinTemp = {
		id : "id1 ",  // id is mandatory for every pin
		name : "Kukatpally Housing Board ",
	};
  
	pinTemp1 = {
		id : "id2 ",  // id is mandatory for every pin
		name : "Four Minarets ",
	};
	frmMapNew.MainMap.updatePins([pinTemp,pinTemp1]);
	frmMapNew.lblUpdate.text = "updated the names of Pins ";
}

Important Considerations

If there are multiple pins at the same location, click events will behave in the following way:

• iOS: Click events will be sent to the topmost pin and callout.
• Android:  Click events will be sent to the bottommost pin and callout.

Note: Preview of map widget is not supported on SPA and Desktop Web platforms.

Android Limitations

On Android, if your app creates a Map widget V1 programmatically, follow either of the procedures below:

Procedure1:

1. From the Applications View, right-click on the project and select Properties.
2. Select Native App tab and select Android.
3. Under Manifest Properties, select Tags tab.
4. Add the below line of code in **Child tag entries under tag:**.

<uses-library Android:name="com.google.Android.maps"></uses-library>

Procedure2: (works only with Volt MX Iris IDE plugin version IDE GA-V5.0.10 )

1. From the Applications View, right-click on the project and select Properties.
2. Under Application tab, add map key in Android map widget key textbox.

On Android if you want to use the Map widget V2, follow the below steps:

1. From the Applications View, right-click on the project and select Properties.

2. Navigate to the Properties->Application tab. In the Map Widget section, add the key generated above in the Android map widget key 2 field.

   

Click here to read more about Generating and Configuring Map API Keys.

If you have downloaded Google Play Services v13 in Android SDK manager, follow either of the options below:

To support Android v2.2 and above devices, do the following:

1. Download Google Play services for Froyo from the Android SDK manager. The Google Play services for Froyo will be available for download only after checking Obsolete option in Android SDK manager.
2. Rename the folder “google_play_services_froyo” to “google_play_services”, in the Android SDK path: ..\Android-sdk-windows\extras\google\.

To use the latest Google Play libraries (Rev 13 and above which support only Android v2.3 and above devices), do the following:

1. In Volt MX Iris, On the Project menu, click Settings.
2. Click the Native tab, and then click the Android sub-tab.
3. Scroll down in the dialog box, and under Manifest Properties, click the Tags tab.

4. In the Child tag entries under tag text box, add the following tag:

   .

Note: Google Map V2 does not work on emulator. On Android devices it works only with Android Version 2.2 and above. It requires OpenGL ES version 2 to load.

Note: On Android platform, Multiple Map Widgets in a single form is not supported for Google Map V1. It is supported for Google Map V2.

Note: Clickable/Interactive widgets inside a Map callout template will become non-clickable when Android Map V2 version is used. This the limitation of native Android Map V2 callout. As callouts are displayed as static image snapshot of callout template and only the entire callout is clickable. Map onSelection callback is invoked when a callout is clicked.

Customizing Map Pin Images

The Map widget provides you with the ability to set the map pin image from different possible sources. The map pin image takes the name of the pin image that is bundled with the application. This feature allows the developer to set the pin image from different sources. If the platforms fail to extract the image out of source, then default pin image is used. You can set the pin image from the following sources.

• A bundled image. If you have bundled an image with the app, you can set the pin image source to the name of the bundled image to display it.
• An image in the file system. Images in the file system of the device or app can be used for the pin image. You must provide the full path name to the image. Note that Android allows only PNG images.
• A Base64 String. You can provide an image that is stored in a base64 encoded format. Apps must decode the image from the base64 string to create a pin icon and set it as the pin image.
• An Image object. The Map widget lets you provide your bitmaps as Image widgets.

Note: Windows, Desktop Web, and SPA support only bundled images.

Searching Routes

Your app can search for routes between the source and destination locations using the voltmx.map.searchRoutes function, which is documented in the API Developer’s Guide.