Map Methods
The Map widget has the following methods associated with it:
addCircle Method
This method is used to add a circle to the map widget with the given location data.
Syntax
addCircle(circleData)
Parameters
circleData
Specifies the location data for which the circle is drawn on the map. Parameters of the circleData are:
id [String] [Mandatory]: Specifies the unique identifier to represent the circle. If a circle already exists with the same identifier, then it gets replaced by the new id.
centerLocation [JSObject] [Mandatory]: Specifies the center location for circle. This property takes the same keys of locationData property of map. Center location of the map is represented with the Map pin.
radius [Number] [Mandatory]: Specifies the radius in meters.
- navigateAndZoom [Boolean] [Optional]: Decides whether the navigation to first pin should take place. It is available on Android, Windows, and iOS. The default value of this parameter is true.
Here is an example of how to enable this property.
locationData: [{
lat: "17.445775",
lon: "78.3731",
name: "Campus 1",
desc: "My Office Campus",
navigateAndZoom: true
}]
};
```
> * **showCenterPin** \[Boolean\] \[Optional\]: Indicates whether to show pin image for Circle center location. Default value is true.
> * **circleConfig** \[JSObject\] \[Optional\]: Specifies an object with predefined configuration keys. These configuration keys can hold platform specific keys as well. The following is the list configuration keys:
>
> * **lineColor** \[String\] \[All\]: Specifies the color of the circle border line in RBGA hex format. Default line color in RGBA is FF0000FF (RED). For example, 0xFF0000FF and FF0000FF, both formats are valid for Red color. The RGBA format followed is of standard RGBA format; it is not same as the RGBA color code generated by Volt MX Iris IDE for skins. If the lineColor is not specified in proper format, it falls back to the default behavior.
> * **fillColor** \[String\] \[All\]: Specifies the color that circle area is filled with in RBGA hex format. The format could be 0xRGBA or RGBA. No fill color is applied by default. For example, 0xFF0000FF and FF0000FF, both formats are valid for Red color. The RGBA format followed is of standard RGBA format; it is not same as the RGBA color code generated by Volt MX Iris IDE for skins. If the fillColor is not specified in proper format, it falls back to the default behavior.
> * **lineWidth** \[Number\] \[All\]: Specifies the width of the circle in screen independent pixels. Default line width is 3 dp.
> * **lineDashPattern** \[Array\] \[iOS\]:An array of numbers specifying the dash pattern to use for the path.
>
> * **zIndex**\[Number\] \[Optional\]: Applicable for Android and iOS platforms.
> Specifies the stack order of circles added in the Map widget. In Android platform, you can set a Double or Integer value (including negative value) as `zIndex`. In iOS platform, you cannot set a negative value to this parameter. When a circle(or any shape like polyline, polygon etc.) is added to the Map widget with a higher `zIndex`, it will be placed in front of the other circles (or other shapes) with lower zIndices. The default value of this parameter is zero.
>
> > **_Note:_** In Android platform, in a map the z-index value stack of the pins are different from the z-index stack of the shapes. The pins are drawn on top of the shapes based on their z-index values. Also, when the pins and shapes (such as circle and polyline) are placed on the map on top of each other, the click event of the pins have a higher priority than the click events of the shapes.
>
Return Values
None
### Exceptions
None
### Remarks
The `image` parameter inside the `locationData` property can accept the pin image as a name string or as a JavaScript pin object. The pin object contains the following keys.
| Key | Description |
| --- | --- |
| source | Specifies the source of the image. It could be an image name, an image path, or a URL. |
| sourceType | Contains a value from the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgTyp)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Type Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not given for the sourceType, the default value of PIN\_IMG\_SRC\_TYPE\_RESOURCES is used. |
| anchor | Optional. A constant that defines how the pin image should be anchored to the location point. Its value should be one of the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgAnc)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Anchor Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not specified, the default value of PIN\_IMG\_ANACHOR\_BOTTOM\_CENTER is used. |
### Example
//Sample code to invoke addCircle method var testdata = { id: "circleId", centerLocation: { lat: "17.4442897", lon: "78.3839277" }, navigatetoZoom: true, radius: 1, circleConfig: { lineColor: "0x7D664DFF", lineWidth: 5 }, showCenterPin: false, zIndex: 1 }; frmMapCircle2.Map1.addCircle(testdata);
### Platform Availability
* iOS, and Android
* * *
</details>
<details close markdown="block"><summary>addPin Method</summary>
* * *
Adds or appends a single pin to the map.
### Syntax
addPin(pinData)
### Parameters
pinData
`pinData` consists of the following key-value pairs.
* **id**\[String\] \[Mandatory\]: Specifies the unique identifier that represents the pin. If a pin already exists with the same identifier, then the id will be replaced by a new id.
* **lat** \[String\] \[Mandatory\]: Specifies the latitude of the location.
* **lon** \[String\] \[Mandatory\]: Specifies the longitude of the location.
* **name** \[String\] \[Mandatory\]: Specifies a short description for the location.
* **desc** \[String\] \[Mandatory\]: Specifies a long description for the location.
* **image** \[String or Image Object\] \[Mandatory\]: Specifies the map pin image that overrides the [defaultPinImage](Map_Properties.md#defaultP).Refer the **Remarks** section for more information.
* **navigateAndZoom** \[Boolean\] \[Optional\]: Decides whether the navigation to first pin should take place. It is available on Android, Windows, and iOS. The default value of this parameter is true.
Here is an example of how to enable this property.
locationData: [{
lat: "17.445775",
lon: "78.3731",
name: "Campus 1",
desc: "My Office Campus",
navigateAndZoom: true
}]
};
* **showcallout** \[Boolean\] \[Optional\]: Shows the callout pop-up. The default value is _true_.
* **calloutData** \[JSObject\] \[Optional\]: Specifies the widget data for a given template for a particular location. The value should be a in the form of key-value pairs. The data can have one of the standard keys called `template` that accepts a reference, to provide location-specific template. This template will override the template provided in the [calloutTemplate](Map_Properties.md#calloutT).
> **_Note:_** The widget-data map for a template must be provided in the "[widgetDataMapForCallout](#widgetDa)" property.
* **meta** \[JSObject\] \[Optional\]: Specifies the platform-specific metadata.
* **color**\[String\] \[Optional\]: Specifies the color for the pop-up. (Supported on Mobile Web and SPA.)
* **label** \[String\] \[Optional\]: Specifies the text for the pop-up. (Supported on Mobile Web and SPA.)
* **zIndex**\[Number\] \[Optional\]: Applicable for Android platform only.
Specifies the stack order of pins in the Map widget. You can set a Double or Integer value (including negative value) as `zIndex`. When a pin is added to the Map widget with a higher `zIndex`, it will be placed in front of other pins with lower zIndices. If multiple pins are placed at the same co-ordinates, then the [onPinClick](Map_Events.md#onPinCli) event is first triggered for the pin with a higher `zIndex`. The `onPinClick` event is then triggered for the rest of the pins in a descending order of `zIndex` on consecutive clicks. The default value of this parameter is zero.
> **_Note:_** In Android platform, in a map the z-index value stack of the pins are different from the z-index stack of the shapes. The pins are drawn on top of the shapes based on their z-index values. Also, when the pins and shapes (such as circle and polyline) are placed on the map on top of each other, the click event of the pins have a higher priority than the click events of the shapes.
### Return Values
None
### Remarks
The `image` parameter inside the `locationData` property can accept the pin image as a name string or as a JavaScript pin object. The pin object contains the following keys.
| Key | Description |
| --- | --- |
| source | Specifies the source of the image. It could be an image name, an image path, or a URL. |
| sourceType | Contains a value from the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgTyp)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Type Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not given for the sourceType, the default value of PIN\_IMG\_SRC\_TYPE\_RESOURCES is used. |
| anchor | Optional. A constant that defines how the pin image should be anchored to the location point. Its value should be one of the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgAnc)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Anchor Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not specified, the default value of PIN\_IMG\_ANACHOR\_BOTTOM\_CENTER is used. |
### Example
// Sample code to invoke addPin method in MainMap Map widget 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, zIndex: 2, meta: { color: "green", label: "A" }
}; //Adding pins function addThePin() { frmMapNew.MainMap.addPin(pin1); }
### Platform Availability
* iOS, Android, and Windows
* * *
</details>
<details close markdown="block"><summary>addPins Method</summary>
* * *
Adds or appends multiple pins to the map.
### Syntax
addPins(pin)
### Parameters
pinData \[Array\]\[Mandatory\]
`pinData` consists of the following key-value pairs.
* **id**\[String\] \[Mandatory\]: Specifies the unique identifier that represents the pin. If a pin already exists with the same identifier, then the id will be replaced by a new id.
* **lat** \[String\] \[Mandatory\]: Specifies the latitude of the location.
* **lon** \[String\] \[Mandatory\]: Specifies the longitude of the location.
* **name** \[String\] \[Mandatory\]: Specifies a short description for the location.
* **desc** \[String\] \[Mandatory\]: Specifies a long description for the location.
* **image** \[String or Image Object\] \[Mandatory\]: Specifies the map pin image that overrides the [defaultPinImage](Map_Properties.md#defaultP).Refer the **Remarks** section for more information.
* **navigateAndZoom** \[Boolean\] \[Optional\]: Decides whether the navigation to first pin should take place. It is available on Android, Windows, and iOS. The default value of this parameter is true.
Here is an example of how to enable this property.
locationData: [{
lat: "17.445775",
lon: "78.3731",
name: "Campus 1",
desc: "My Office Campus",
navigateAndZoom: true
}]
};
* **showcallout** \[Boolean\] \[Optional\]: Shows the callout pop-up. The default value is _true_.
* **calloutData** \[JSObject\] \[Optional\]: Specifies the widget data for a given template for a particular location. The value should be a in the form of key-value pairs. The data can have one of the standard keys called `template` that accepts a reference, to provide location-specific template. This template will override the template provided in the [calloutTemplate](Map_Properties.md#calloutT).
* > **_Note:_** The widget-data map for a template must be provided in the "[widgetDataMapForCallout](#widgetDa)" property.
* **meta** \[JSObject\] \[Optional\]: Specifies the platform-specific metadata.
* **color**\[String\] \[Optional\]: Specifies the color for the pop-up. (Supported on Mobile Web and SPA.)
* **label** \[String\] \[Optional\]: Specifies the text for the pop-up. (Supported on Mobile Web and SPA.)
* **zIndex**\[Number\] \[Optional\]: Applicable for Android platform only.
Specifies the stack order of pins in the Map widget. You can set a Double or Integer value (including negative value) as `zIndex`. When a pin is added to the Map widget with a higher `zIndex`, it will be placed in front of other pins with lower zIndices. If multiple pins are placed at the same co-ordinates, then the [onPinClick](Map_Events.md#onPinCli) event is first triggered for the pin with a higher `zIndex`. The `onPinClick` event is then triggered for the rest of the pins in a descending order of `zIndex` on consecutive clicks. The default value of this parameter is zero.
> **_Note:_** In Android platform, in a map the z-index value stack of the pins are different from the z-index stack of the shapes. The pins are drawn on top of the shapes based on their z-index values. Also, when the pins and shapes (such as circle and polyline) are placed on the map on top of each other, the click event of the pins have a higher priority than the click events of the shapes.
### Return Values
None
### Remarks
The `image` parameter inside the `locationData` property can accept the pin image as a name string or as a JavaScript pin object. The pin object contains the following keys.
| Key | Description |
| --- | --- |
| source | Specifies the source of the image. It could be an image name, an image path, or a URL. |
| sourceType | Contains a value from the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgTyp)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Type Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not given for the sourceType, the default value of PIN\_IMG\_SRC\_TYPE\_RESOURCES is used. |
| anchor | Optional. A constant that defines how the pin image should be anchored to the location point. Its value should be one of the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgAnc)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Anchor Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not specified, the default value of PIN\_IMG\_ANACHOR\_BOTTOM\_CENTER is used. |
### Example
/ Sample code to invoke addPins method in MainMap Map widget to add pin1 and pin2 to the map./ // id is mandatory for every pin in dictionary
pin1 = { id: "id1", // id is mandatory for every pin in dictionary 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, zIndex: 2, meta: { color: "green", label: "A" } };
pin2 = { id: "id2", // id is mandatory for every pin in dictionary 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, zIndex: 4, meta: { color: "green", label: "B" } };
//Adding pins function addThePins() { frmMapNew.MainMap.addPins([pin1, pin2]); }
### Platform Availability
* iOS, Android, and Windows
* * *
</details>
<details close markdown="block"><summary>addGestureRecognizer Method</summary>
* * *
This API allows you to set a gesture recognizer for a specified gesture for a specified widget.
### Syntax
addGestureRecognizer(gestureType, gestureConfigParams, onGestureClosure)
### Parameters
_gestureType_
\[Number\] - Mandatory
Indicates the type of gesture to be detected on the widget.
See Remarks for possible values.
_gestureConfigParams_
\[object\] - Mandatory
The parameter specifies a table that has the required configuration parameters to setup a gesture recognizer.
The configuration parameters vary based on the type of the gesture.
See Remarks for possible values.
_onGestureClosure_
\[function\] - Mandatory
Specifies the function that needs to be executed when a gesture is recognized.
This function will be raised asynchronously
See Remarks for the syntax of this function.
### Return Values
String - Reference to the gesture is returned.
### Remarks
The values for the _gestureType_parameter are:
\[Number\] - Mandatory
Indicates the type of gesture to be detected on the widget. The following are possible values:
* 1 – constants.GESTURE\_TYPE\_TAP
* 2 - constants.GESTURE\_TYPE\_SWIPE
* 3 – constants.GESTURE\_TYPE\_LONGPRESS
* 4 – constants.GESTURE\_TYPE\_PAN
* 5 – constants.GESTURE\_TYPE\_ROTATION
* 6 - constants.GESTURE\_TYPE\_PINCH
* 7 - constants.GESTURE\_TYPE\_RIGHTTAP
The values for the _gestureConfigParams_parameter are:
\[object\] - Mandatory
The parameter specifies a table that has the required configuration parameters to setup a gesture recognizer. The configuration parameters vary based on the type of the gesture.
This parameter supports the following key-value pairs:
Gesture Type:TAP
* fingers \[Number\] - specifies the maximum number of fingers that must be respected for a gesture. Possible values are: 1. Default value is 1.
* taps \[Number\] - specifies the maximum number of taps that must be respected for a gesture. Possible values are: 1 or 2. Default value is 1.
### For example:
{fingers:1,taps:1}
Gesture Type:SWIPE
* fingers \[Number\] - specifies the maximum number of fingers that must be respected for a gesture. Possible values are: 1. Default value is 1.
### For example:
{fingers: 1}
Gesture Type:LONGPRESS
* pressDuration \[Number\] - specifies the minimum time interval (in seconds) after which the gesture is recognized as a LONGPRESS. For example, if pressDuration is 2 seconds, any continued press is recognized as LONGPRESS only if it lasts for at least 2 seconds. Default value is 1. This is not applicable to Windows.
### For example:
{pressDuration=1}.
Gesture Type: PAN
* fingers \[number\] specifies the minimum number of fingers needed to recognize this gesture. Default value is 1.
* continuousEvents \[Boolean\] indicates if callback should be called continuously for every change beginning from the time the gesture is recognized to the time it ends.
Gesture Type: ROTATION
* Rotation gesture involves only two fingers.
* continuousEvents \[Boolean\] indicates if callback must be called continuously for every change beginning from the time the gesture is recognized to the time it ends.
Gesture Type:PINCH
* Pinch gesture invloves two fingures.
* continuousEvents \[Boolean\] indicates if callback should be called continuously every change beginning from the time the gesture is recognized to the time it ends.
The syntax for the _onGestureClosure_callback function are:
\[function\] - Mandatory
Specifies the function that needs to be executed when a gesture is recognized.
This function will be raised asynchronously and has the following Syntax:
onGestureClosure(widgetRef, gestureInfo, context)
* widgetRef - specifies the handle to the widget on which the gesture was recognized.
* gestureInfo - Table with information about the gesture. The contents of this table vary based on the gesture type.
* context - Table with SegmentedUI row details.
gestureInfo table has the following key-value pairs:
* gestureType \[number\] – indicates the gesture type; 1 for TAP, 2 for SWIPE, and 3 for LONGPRESS,4 for PAN, 5 for ROTATION, 6 for PINCH and 7 for RIGHTTAP
* gesturesetUpParams \[object\] – specifies the set up parameters passed while adding the gesture recognizer
* gesturePosition \[number\] – indicates the position where the gesture was recognized. Possible values are: 1 for TOPLEFT, 2 for TOPCENTER, 3 for TOPRIGHT, 4 for MIDDLELEFT, 5 for MIDDLECENTER, 6 for MIDDLERIGHT, 7 for BOTTOMLEFT, 8 for BOTTOMCENTER, 9 for BOTTOMRIGHT, 10 for CENTER
* swipeDirection \[number\] –indicates the direction of swipe. This parameter is applicable only if the gesture type is SWIPE. Possible values are: 1 for LEFT, 2 for RIGHT, 3 for TOP, 4 for BOTTOM. Direction is w.r.t the view and not device orientation.
* gestureX \[number\] – specifies the X coordinate of the point (in pixels) where the gesture has occurred. The coordinate is relative to the widget coordinate system.
* gestureY \[number\] – specifies the Y coordinate of the point (in pixels) where the gesture has occurred. The coordinate is relative to the widget coordinate system.
* widgetWidth \[number\] – specifies the width of the widget (in pixels)
* widgetHeight \[number\] – specifies the height of the widget (in pixels)
* gestureState\[number\] – indicates the gesture state as below
* 1 – gesture state begin
* 2 - gesture state changed
* 3 – gesture state ended.
* \* gestureState is applicable only for continuous gestures like PAN, ROTATION and PINCH.
* rotation \[number\] rotation of the gesture in degrees since its last change.( Applicable only when gesture type is ROTATION
* velocityX and velocityY : horizontal and vertical component of velocity expressed in points per second. (Applicable only for PAN gesture type)
* velocity \[number\]: velocity of pinch in scale per second (Applicable for Pinch gesture)
* scale \[number\]:scale factor relative to the points of the two touches in screen coordinates
* touchType\[number\]:(windows only)
* 0 - constants.TOUCHTYPE\_FINGER
* 1 - constants.TOUCHTYPE\_PEN
* 2 - constants.TOUCHTYPE\_MOUSE
* translationX and translationY \[number\] : cumulative distance as number. (Applicable only for PAN gesture type)
context table has the following key-value pairs:
* rowIndex \[number\] : row index of the segui where gesture was recognised. (Applicable to gestures added to segUI rows)
* sectionIndex \[number\] : section index of the segui where gesture was recognised. (Applicable to gestures added to segUI rows)
It is not recommend to define gestures for widgets that have a default behavior associated with it.
If you click (tap) a button (any clickable widget), the default behavior is to trigger an onClick event. If you define a Tap gesture on such widgets, the gesture closure is executed in addition to the onClick event.
If you swipe a larger form, the default behavior is to scroll up and down depending on the direction in which you swipe. If you define a SWIPE gesture on such forms, the gesture closure gets executed in addition to scrolling the form.
If you swipe a Segmented UI with huge number of rows, the default behavior is to scroll the Segmented UI. If you define a SWIPE gesture on such segments, the gesture closure gets executed in addition to scrolling the form.
Gestures can be added only for the following widgets:
* Flex Container
* Flex Scroll Container.
In the android platform, the top and bottom gestures work only when the scrolling is disabled for Form and parent scrolling containers. By default, the scrolling is enabled for the Form and scrolling containers.
* RIGHTTAP applicable only to Windows 10
* ROTATION is not supported on android.
### Example
//Sample code to add Gestures to the frmGestures FlexForm. //Code to add DOUBLE TAP gesture to the frmGestures, FlexForm. var doubletp = { fingers: 1, taps: 2 }; frmGestures.addGestureRecognizer(1, doubletp, onGestureFunction); //Code to add SINGLE TAP gesture to the frmGestures FlexForm. var singleTp = { fingers: 1, taps: 1 }; frmGestures.addGestureRecognizer(1, singleTp, onGestureFunction); //Code to add SWIPE gesture to the frmGestures FlexForm. var swipeForm = { fingers: 1, swipedistance: 50, swipevelocity: 75 }; frmGestures.addGestureRecognizer(2, swipeForm, onGestureFunction); //Code to add LONGPRESS gesture to the frmGestures FlexForm. var longPressForm = { pressDuration: 2 }; frmGestures.addGestureRecognizer(3, longPressForm, onGestureFunction);
function onGestureFunction(commonWidget, gestureInfo) { voltmx.print("The Gesture type is:" + gestureInfo.gestureType);
}
### Platform Availability
* iOS, Windows
* * *
</details>
<details close markdown="block"><summary>addPolygon Method</summary>
* * *
This method is used to add a polygon to the map widget with the given location data.
### Syntax
addPolygon(polygonData)
### Parameters
polygonData
Specifies the location data for which the polygon is drawn on the map. Parameters of the polygonData are:
* **id** \[String\] \[Mandatory\]: Specifies the unique identifier to represent the polygon. If a polygon already exists with the same identifier, then it gets replaced by the new id.
* **locations** \[Array\] \[Mandatory\]: Specifies the list of all the locations as an array. Each location object accepts "lat" and "lon" keys and other keys are ignored. First and last location in the list are connected even if they are not same.
* **navigateAndZoom** \[Boolean\] \[Optional\]: Decides whether the navigation to first pin should take place. It is available on Android, Windows, and iOS. The default value of this parameter is true.
Here is an example of how to enable this property.
locationData: [{
lat: "17.445775",
lon: "78.3731",
name: "Campus 1",
desc: "My Office Campus",
navigateAndZoom: true
}]
};
* **polygonConfig** \[JSObject\] \[Optional\]: Specifies an object with predefined configuration keys. These configuration keys can hold platform specific keys as well. The following is the list configuration keys:
* **lineColor** \[String\] \[All\]: Specifies the color of the polygon border line in RBGA hex format. Default line color in RGBA is FF0000FF (RED) . For example, 0xFF0000FF and FF0000FF, both formats are valid for Red color. The RGBA format followed is of standard RGBA format; it is not same as the RGBA color code generated by Volt MX Iris IDE for skins. If the lineColor is not specified in proper format, it falls back to the default behavior.
* **fillColor** \[String\] \[All\]: Specifies the color that polygon area is filled with in RBGA hex format. The format could be 0xRGBA or RGBA. No fill color is applied by default. For example, 0xFF0000FF and FF0000FF, both formats are valid for Red color. The RGBA format followed is of standard RGBA format; it is not same as the RGBA color code generated by Volt MX Iris IDE for skins. If the fillColor is not specified in proper format, it falls back to the default behavior.
* **lineWidth** \[Number\] \[All\]: Specifies the width of the polygon in screen independent pixels. Default line width is 3 dp.
* **innerPolygons** \[Array\] \[Android, iOS\]: Specifies the list of all the locations as an array to draw inner polygon without fill color. Each location object accepts "lat" and "lon" keys and other keys are ignored. First and last location in the list are connected even if they are not same. If the inner polygons falls beyond outer polygon region, the behavior of the outer and inner polygon may vary in underlying platforms. In Android, fill color of the outer polygon may be not applied properly and in iOS, inner polygons may be applied the fill color.
* **lineDashPattern** \[Array\] \[iOS\]:An array of numbers specifying the dash pattern to use for the path. The array contains one or more numbers that indicate the lengths (in dp) of the line segments and gaps in the pattern. The values in the array alternate, starting with the first line segment length, followed by the first gap length, followed by the second line segment length, and so on.
* **isDashedLine** \[Boolean\] \[ Windows\] - Boolean property to indicate whether to draw border line in dashed format
* **zIndex**\[Number\] \[Optional\]: Applicable for Android and iOS platforms.
Specifies the stack order of the polygons drawn on the Map widget. In Android platform, you can set a Double or Integer value (including negative value) as `zIndex`. In iOS platform, you cannot set a negative value to this parameter. When a polygon is added to the Map widget with a higher `zIndex`, it will be placed in front of the other polygons (or any shape like polyline, circle, etc.)with lower zIndices. The default value of this property is zero.
> **_Note:_** In Android platform, in a map the z-index value stack of the pins are different from the z-index stack of the shapes. The pins are drawn on top of the shapes based on their z-index values. Also, when the pins and shapes (such as circle and polyline) are placed on the map on top of each other, the click event of the pins have a higher priority than the click events of the shapes.
### Return Values
None
### Exceptions
None
### Example
//Sample code to invoke addPolygon method using MainMap Map widget. var polyData = { id: "polyId1", locations: [{ lat: "51.507351", lon: "-0.127758" }, { lat: "18.921936", lon: "72.834573" }, { lat: "56.130366", lon: "-106.346771" }, { lat: "-33.924869", lon: "18.424055" }], navigateAndZoom: true, zIndex: 2, polygonConfig: { fillColor: "0xFFCC99FF", lineWidth: 5 } }; frmMapPolygon1.MainMap.addPolygon(polyData);
### Platform Availability
* iOS, and Android
* * *
</details>
<details close markdown="block"><summary>addPolyline Method</summary>
* * *
This method is used to add a polyline to the map widget with the given location data. You can add multiple polylines to the map widget using this method.
### Syntax
addPolyline(locationData)
### Parameters
locationData
Specifies the location data for which the polyline is drawn on the map. Parameters of the locationdata are:
* **id** \[String\] \[Mandatory\]: Specifies the unique identifier to represent the polyline. If a polyline already exists with the same identifier, then it gets replaced by the new id.
* **startLocation** \[String\] \[Optional\]: Specifies the location data for the start point of the polyline. The values should be provided as specified in [locationData](Map_Properties.md#location) property. The start point of the polyline is represented with a map pin.
* **endLocation** \[String\] \[Optional\]: Specifies the location data for the end point of the polyline. The values should be provided as specified in [locationData](Map_Properties.md#location) property. The start point of the polyline is represented with a map pin.
* **navigateAndZoom** \[Boolean\] \[Optional\]: Decides whether the navigation to first pin should take place. It is available on Android, Windows, and iOS. The default value of this parameter is true.
Here is an example of how to enable this property.
locationData: [{
lat: "17.445775",
lon: "78.3731",
name: "Campus 1",
desc: "My Office Campus",
navigateAndZoom: true
}]
};
* **locations** \[JSObject\] \[Optional\]: Specifies the list of all the locations as an array including start and end points. Each location object accepts "lat" and "lon" keys and other keys are ignored.
* **polylineConfig** \[JSObject\] \[Optional\]: Specifies an object with predefined configuration keys. These configuration keys can hold platform specific keys as well. The following is the list configuration keys:
* **lineColor** \[String\]: Specifies the color of the polyline in #RBGA hex format. If the line color property is not specified, by default, Red color is selected.
For example, 0xFF0000FF and FF0000FF, both formats are valid for Red color.
> **_Note:_** RGBA format followed is of standard RGBA format; it is not same as the RGBA color code generated by Volt MX Iris IDE for skins.
> **_Note:_** If the lineColor is not specified in proper format, the default color (Red) is selected.
* **lineWidth** \[Number\]: Specifies the width of the polyline in screen independent pixels.
* **zIndex**\[Number\] \[Optional\]: Applicable for Android and iOS platforms.
Specifies the stack order of the polylines drawn on the Map widget. In Android platform, you can set a Double or Integer value (including negative value) as `zIndex`. In iOS platform, you cannot set a negative value to this parameter.When a polyline is added to the Map widget with a higher `zIndex`, it will be placed in front of the other polylines (or any shape like circle, polygon, etc.)with lower zIndices. The default value of this parameter is zero.
> **_Note:_** In Android platform, in a map the z-index value stack of the pins are different from the z-index stack of the shapes. The pins are drawn on top of the shapes based on their z-index values. Also, when the pins and shapes (such as circle and polyline) are placed on the map on top of each other, the click event of the pins have a higher priority than the click events of the shapes.
### Return Values
None
### Exceptions
WidgetError, Error
### Remarks
The image property of the start and end locations can accept the pin image as a name string or as a JavaScript pin object. The pin object contains the following keys.
| Key | Description |
| --- | --- |
| source | Specifies the source of the image. It could be an image name, an image path, or a URL. |
| sourceType | Contains a value from the [Pin Image Type Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not given for the sourceType, the default value of PIN\_IMG\_SRC\_TYPE\_RESOURCES is used. |
| anchor | Optional. A constant that defines how the pin image should be anchored to the location point. Its value should be one of the [Pin Image Anchor Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not specified, the value PIN\_IMG\_ANCHOR\_BOTTOM\_CENTER is used. |
### Example
//Sample code to invoke addPolyline method using mapref Map widget frmMap.mapref.addPolyline({ id: "polyid1", startLocation: { lat: "43.47591", lon: "80.53964", name: "Campus 1", desc: "My College Campus", image: "marker.png", meta: { color: "green", label: "C" } }, endLocation: { lat: "43.47621", lon: "-80.54034", name: "Campus 2", desc: "My School Campus", image: "ymarker.png", meta: { color: "red", label: "A" } }, locations: [{ lat: "43.47591", lon: "-80.53964" }, { lat: "44.47593", lon: "-81.53964" }, { lat: "43.47621", lon: "-80.54034" }], polylineConfig: { lineColor: "0x0000ffff", lineWidth: "2" }, zIndex: 1 });
### Platform Availability
* iOS, and Android
* * *
</details>
<details close markdown="block"><summary>animate Method</summary>
* * *
Applies an animation to the widget.
### Syntax
animate (animationObj, animateConfig, animationCallbacks)
### Parameters
_animationObj_
An `animation` object created using [voltmx.ui.createAnimation](../../../Iris/iris_api_dev_guide/content/voltmx.ui_functions.md#createAn?TocPath=References|voltmx.ui_Namespace|Functions|_____5) function.
_animationConfig_
As defined in widget level animation section.
_animationCallbacks_
A JavaScript dictionary that contains key-value pairs. The following keys are supported.
| Key | Description |
| --- | --- |
| animationEnd | A JavaScript function that is invoked with the animation ends. For more information, see the **Remarks** section below. |
| animationStart | A JavaScript function that is invoked with the animation starts. For more information, see the **Remarks** section below. |
### Return Values
Returns a platform-specific handle to the animation. This handle currently not used, but is returned for possible future requirements use.
### Remarks
The callback for the `animationStart` key in the JavaScript object passed in this method's _animationCallbacks_ parameter has the following signature.
animationStart(source, animationHandle, elapsedTime);
where `source` is the widget being animated, `animationHandle` is the handle returned by the `applyAnimation` method, and `elapsedTime` is the amount of time the animation has been running in seconds, when this event is fired..
This event occurs at the start of the animation. If there is 'animation-delay' configured then this event will fire only after the delay period. This event gets called asynchronously.
The callback for the `animationEnd` key in the JavaScript object passed in this method's _animationCallbacks_ parameter has the following signature.
animationEnd(source, animationHandle, elapsedTime);
where source is the widget being animated, animationHandle is the handle returned by the applyAnimation method, and elapsedTime is the amount of time the animation has been running in seconds, when this event is fired.
This event occurs at the end of the animation. This event gets called asynchronously.
The `animate` method throws an Invalid Animation Definition Exception if animation definition, does not follow the dictionary structure expected. This method is ignored if it is called on a widget whose immediate parent is not FlexContainer or a FlexScrollContainer.
If the widget is not part of the currently visible view hierarchy, calling this method does nothing. Because this method is asynchronous and immediately returns, it does not wait for the animation to start or complete.
### Example
//Sample code of animation function AnimateBoth() { var getFuncName = frm1.listbox18.selectedKey; if (getFuncName == "BothLT") { frm1.textbox26.animate(myAnimDefinition(), animConfiguration(), {}); } else if (getFuncName == "BothTBL") { frm1.textbox26.animate(myAnimDefinitionsc1(), animConfiguration(), {}); } }
### Platform Availability
* iOS, Android, Windows, and SPA
* * *
</details>
<details close markdown="block"><summary>clear Method</summary>
* * *
This method is used to clear all the data associated with a map widget, including locationData and polylines.
### Syntax
clear()
### Parameters
None
### Return Values
None
### Exceptions
None
### Example
//clear method call mapref.clear();
### Platform Availability
* iOS and Android
* * *
</details>
<details close markdown="block"><summary>clone Method</summary>
* * *
When this method is used on a container widget, then all the widgets inside the container are cloned. This method takes an optional parameter. If the widgetid is not passed then the cloned copy will have the same ID as original widget.
If the widget ID is passed as a parameter then it will be prefixed to the existing ID and will assign it to cloned copy of the container. For all other widgets of the container and its child widgets.
For example, if the widget ID is "fc1" and the widget ID passed to clone API is "ref1", then the cloned widget ID will be "ref1fc1". For a child widget placed in a container with widget ID as "wid1", the cloned copy will have the widget ID as "ref1wid1".
Exceptions are not displayed if widget ID parameter is not unique. Instead when the cloned copy is added to the same form as of original container then it may lead to unexpected behaviors. So it is your responsibility to provide unique widget ID.
### Syntax
clone()
### Parameters
widgetId \[String\]
Optional. Reference of the name of the widget.
### Return Values
Cloned copy of the widget.
### Exceptions
None
### Remarks
* This method is not supported on SegmentedUI2 widget.
* Gestures for the FlexContainer are not cloned. You have to reapply the gestures on the cloned object.
* In Android platform, cloned Map widget will not work if prefix is not passed as parameter to the API.
* To apply focusSkin for dynamically created widgets or cloned widgets, assign focusSkin dynamically after adding the widget to the form hierarchy. This is applicable for SPA and Desktop web platforms.
formid.widgetid.focusSkin = "skinname";
* To apply hoverSkin for dynamically created widgets or cloned widgets, assign hoverSkin dynamically after adding the widget to the form hierarchy. This is applicable for the Desktop web platform.
formid.widgetid.hoverSkin = "skinname";
### Example
//This is a generic method that is applicable for various widgets.
//Here, we have shown how to use the clone Method for a FlexContainer widget.
//You need to make a corresponding call of the clone method for other applicable widgets.
var flex2 = frmFlex.flexContainer1.clone();
//Here, flexContainer1 is a FlexContainer widget that is already present in frmFlex FlexForm.
frmFlex.add(flex2);
//For instance, the corresponding clone method call on the Label widget is as follows:
var myLabel=frmFlex.lbl1.clone();
### Platform Availability
* iOS, Android, Windows, and SPA
* * *
</details>
<details close markdown="block"><summary>convertPointFromWidget Method</summary>
* * *
This method allows you to convert the coordinate system from a widget to a point (receiver's coordinate system).
### Syntax
convertPointFromWidget(point, fromWidget)
### Parameters
_point_
\[JSObject\]- Mandatory
You can specify an object with keys as x and y. You can specify the values in all (dp, px and %) units of measurement.
_fromWidget_
\[widgetref\]- Mandatory
This parameter is the handle to the widget instance. Based on this parameter, the coordinate system is converted from the widget to a point (receiver's coordinate system).
### Example
Form1.widget1.convertPointFromWidget({ x: "10dp", y: "20dp" }, widget2);
### Platform Availability
* iOS, Android, Windows, and SPA
* * *
</details>
<details close markdown="block"><summary>convertPointToWidget Method</summary>
* * *
Using the convertPointToWidget method, you can modify the co-ordinate system. You can convert the receiver's co-ordinate system from a **point** to a **Widget**.
### Syntax
convertPointToWidget(point, toWidget)
### Parameters
_point_
\[JSObject\]- Mandatory. You can specify an object with keys as x and y. You can specify the values in all (dp, px and %) units of measurement.
_toWidget_
\[widgetref\] - Mandatory. This parameter is the handle to the widget instance. Based on this parameter, the coordinate system is converted from a point to a widget.
### Example
Form1.widget2.convertPointToWidget({ x: "20dp", y: "30dp" }, widget1);
### Platform Availability
* iOS, Android, Windows, and SPA
* * *
</details>
<details close markdown="block"><summary>dismissCallout Method</summary>
* * *
This method is used to dismiss the custom callout for a given location. This method is ignored if the callout is already is in dismissed state, or location argument is invalid or non-existing.
### Syntax
dismissCallout(location)
### Parameters
locationData
Specifies the location data of a single location following the data format of the "locationData" property on the map widget. It should support both hash and array format.
### Return Values
None
### Exceptions
WidgetError
### Example
//Sample code to invoke dismissCallout method by using a Map widget.
frmMap.myMap.dismissCallout();
### Platform Availability
Available on all platforms
* * *
</details>
<details close markdown="block"><summary>fitToBounds Method</summary>
* * *
This API helps to fit the given locationdata on to the map.
### Signature
fitToBounds(config)
### Parameters
config \[JSDictionary\]: config is a mandatory argument that is a JSDictionary with the following properties:
* locations \[JSObject\] -Mandatory. Specifies the list of all the locations as an array. Each location is a JSDictionary that accepts "lat" and "lon" keys and ignores the other keys.
* animate \[bool\] - Optional. This is a Boolean value that indicates whether the map should be navigated to the area with animation or without animation. Its default value is true for all platforms. And when the value is true, the navigations take place with animation.
> **_Note:_** Map navigates to provided latitude-longitude dictionaries, animate only decides whether the navigation occurs with or without animation.
### Return Values
None
### Remarks
1. You should call the fitToBounds and setBounds methods for onMapLoaded callback.
2. If you call both fitToBounds and setBounds (fitToBounds, setBounds) before navigating to the form that contains the map, the fitToBounds method takes precedence.
### Example
var data = { locations: [{ lat: "17.469157", lon: "78.322256" }, { lat: "17.520893", lon: "78.463018" }, { lat: "17.458677", lon: "78.682402" }, { lat: "17.251575", lon: "78.685148" }, { lat: "17.245673", lon: "78.455809" }], animate: true }; formInstance.mapObj.fitToBounds(data);
### Platform Availability
* iOS, Android, and Windows
* * *
</details>
<details close markdown="block"><summary>getBounds Method</summary>
* * *
This method returns the currently visible map boundaries as an object. The predefined keys for the object are:
* center\[JSObject\]: Specifies the latitude and longitude keys and associated values.
* northeast \[JSObject\]: Specifies the latitude and longitude keys and associated values.
* southwest \[JSObject\]: Specifies the latitude and longitude keys and associated values.
* latspan \[number\]: Specifies the spanning latitudes in degrees.
* lonspan \[number\]: Specifies the spanning longitude in degrees.
* zoom \[JS number\]: 6
* viewingAngle \[JS number\]: 30
* orientation \[JS number\]: 270
> **_Note:_** This method returns nil if the map is not initialized.
### Syntax
getBounds()
### Parameters
None
### Return Values
None
### Exceptions
WidgetError, Error
### Example
//getBounds method call var bounds = mapref.getBounds(); voltmx.print(bounds.center);
### Platform Availability
* iOS, Android, and Windows
* * *
</details>
<details close markdown="block"><summary>getBadge Method</summary>
* * *
This API enables you to read the badge value (if any) attached to the specified widget. If the specified widget does not have a badge attached to it, it returns an empty string.
### Syntax
getBadge()
Optional Parameter
uniqueIdentifier
Unique identifier of a widget which is a handle to the widget.
### Return Values
Returns a string containing the badge value applied to the specified widget. If the specified widget has no badge value attached to it, it returns an empty string.
### Remarks
When a badge is removed, the widgets are re-formatted to accommodate the cleared badge values.
On the iOS platform, this method is applicable on Label, Button, Image, TextBox, and TextArea widgets only.
### Example
//This is a generic method that is applicable for various widgets. //Here, we have shown how to use the getBadge Method for button widget. //You need to make a corresponding call of the getBadge method for other applicable widgets. function getBadge() { //To get a badge value on a Button with ID btn1 placed on a form frm1, use the following snippet: var badgeVal = frm1.btn1.getBadge(); alert("badge value is::" + badgeVal);
//For instance, the corresponding getBadge method call on the Label widget is as follows:
frm1.lbl1.getBadge();
}
### Platform Availability
* iOS
* * *
</details>
<details close markdown="block"><summary>navigateTo Method</summary>
* * *
This helps to navigate from one index to other index in the given list of locations shown on the map view.
### Syntax
navigateTo(index,showcallout)
### Parameters
Index
Specifies the index of the pin to which the map should navigate to. Index is calculated based on the order of the locations that are passed to the map widget initially.
showCallout
Indicates whether to show the call out on the pin after navigating to the pin at the given index.
### Return Values
None
### Exceptions
WidgetError
### Example
//Sample code to invoke navigateTo method by using a Map widget.
frmMap.myMap.navigateTo(2, true);
### Platform Availability
Available on all platforms
* * *
</details>
<details close markdown="block"><summary>navigateToLocation Method</summary>
* * *
This method allows you to navigate programmatically to the specified location. Based on the parameters passed it also displays the dropPin and callout.
### Syntax
navigateToLocation(locationData,showcallout,dropPin)
### Parameters
locationData
Specifies the location data of a single location following the data format of the "locationdata" property on the map widget. It support both hash and array formats.
showcallout
Indicates whether to show the callout on the pin after navigating to the pin at the given index. The showcallout set in this API takes priority over the following:
> 1\. showcallout defined as a part of locationdata sent to this method.
> 2\. showcallout defined as a part of the locationData that is set at the map widget level for a matching location.
dropPin
Indicates whether to drop the pin at the given location or not. If true, a pin is displayed at the given location. Drop Pin is effective only when you navigate to a location which doesn't exist as a part of the locationData set at the map widget level.
> > **_Note:_** If navigated to same location again and again by toggling dropPin property, pin is toggled.
### Return Values
None
### Exceptions
WidgetError
### Remarks
All the values specified in this method invocation are respected only for the invocation and does not change the original state of the map, I.e locationData that is set at the map widget level. When this method is called in sequence, the map is navigated to the latest location and there wont be trace of the old locations which were navigated earlier through this method on the map.
### Example
//Sample code to invoke navigateToLocation method by using a Map widget.
var locationData = {
lat: "17.433451",
lon: "78.432061",
name: "Kids Park",
desc: "Kids Park Near My Home"
};
frmMap.myMap.navigateToLocation(locationData, true, true);
### Platform Availability
Available on all platforms
* * *
</details>
<details close markdown="block"><summary>registerForPeekandPop Method</summary>
* * *
This method registers a widget to enable 3D Touch peek and pop gestures.
### Syntax
registerForPeekandPop(onPeekCallback, onPopCallback)
### Parameters
onPeekCallback
A callback function that is invoked when the user slightly presses (soft press) the widget.
Callback Syntax
onPeekCallback(widget)
Callback Input Parameters
_widget_
A widget reference that is registered for peek and pop.
### Callback Return Values
A PreviewInfoTable. See the Remarks section for a description of this table.
### Callback Example
function onPeekCallback(widget) { var previewInfoTable = { "peekForm": frmSecond, "focusRect": [0, 0, 200, 200], "contentSize": [320, 480] }; return previewInfoTable; }
onPopCallback (Optional)
A callback function that is invoked when the user further presses (hard press) the preview that is displayed for the widget.
Callback Syntax
onPopCallback(widget,peekForm)
Callback Input Parameters
_widget_
A widget reference that is registered for peek and pop.
_peekForm_
A form reference that is displayed as preview/peek.
### Callback Return Values
A form reference.
### Callback Remarks
Use this callback to set the content for pop. The form handle returned by this callback is used for pop content. In general, the form that is used for preview is used for pop content also. If the pop callback is not implemented, peek disappears and the app returns to its previous state.
### Callback Example
function onPopCallback(widget, peekForm) { // preview form used for pop also return peekForm; }
### Remarks
A PreviewInfoTable has the following format.
**Name:** peekForm
**Description:** The form reference that will be displayed as preview. If an invalid form reference is given, the preview will not be shown.
**Type:** form reference
**Name:** focusRect (Optional)
**Description:** An array representing a rectangle in widgets view coordinates. If provided, this rectangle will be focused while its surrounding area will be blurred, indicating a preview is available for the widget. If not provided, entire view area of the widget will be focused. If either the width or height is zero, the widget's view width/height is used. The values are supported in percentage(with regard to widget bounds), dp, or pixels. The values are strings. If a string value is given without any format specifier, it defaults to dp. If an array of numbers is given, it is assumed they are dp values.
**Type:** Array \[x, y, width, height\]
Example: \[“0dp”, “0dp”, “200dp”, “300dp”\], \[“10%”, “10%”, “75%”, “50%”\], \[“10px”, “10px”, “200px”, “480px”\]
**Name:** contentSize (Optional)
**Description:** An array representing the preferred content size of the preview. This allows the user to adjust the preferred width/height dimensions of the preview. If not provided, the preview is shown with default values. If either the width or height is zero, the default preview width/height is used. It is recommended that one of the width/height values be zero for proper adjustment of the other value. For example, if width = 0, the height is adjustable and vice versa. Providing positive values simultaneously for both width and height will result in distorted appearance of preview. The values are supported in dp, pixels, and percentage(with regard to screen bounds). The actual width/height of the preview may vary slightly due to resizing per aspect ratio. The values are strings. If a string value is given without any format specifier, it defaults to dp. If array of numbers is given, it is assumed they are dp values.
**Type:** Array \[width, height\]
Example: \[“0dp”, “100dp”\], \[“100%”, “0%”\], \[“0px”, “240px”\]
### Example of a PreviewInfoTable:
var previewInfoTable = { "peekForm": frmSecond, "focusRect": [0, 0, 200, 200], "contentSize": [320, 480] };
### Return Values
None.
### Platform Availability
* iOS 9.0 and later
* * *
</details>
<details close markdown="block"><summary>removeCircle Method</summary>
* * *
This method is used to remove a Circle from the map.
### Syntax
removeCircle(circleId)
### Parameters
circleId
Specifies the id of the circle to remove. This method is ignored if the given id is incorrect or not found.
### Return Values
None
### Exceptions
WidgetError, Error
### Example
var testdata = { id: "circleId", centerLocation: { lat: "17.4442897", lon: "78.3839277" }, navigatetoZoom: true, radius: 1, circleConfig: { lineColor: "0x7D664DFF", lineWidth: 5 }, showCenterPin: false }; frmMapCircle2.Map1.addCircle(testdata); //After processing the data frmMapCircle2.Map1.removeCircle();
* * *
</details>
<details close markdown="block"><summary>removeFromParent Method</summary>
* * *
This method allows you to remove a child widget from a parent widget.
### Syntax
removeFromParent()
### Read/Write
Yes - (Read and Write)
### Example
//This is a generic method that is applicable for various widgets. //Here, we have shown how to use the removeFromParent Method for a Calendar widget. //You need to make a corresponding call of the removeFromParent method for other applicable widgets.
Form1.calendar.removeFromParent();
### Platform Availability
* iOS, Android , Windows, SPA, and Desktop Web
* * *
</details>
<details close markdown="block"><summary>removeGestureRecognizer Method</summary>
* * *
This method allows you to remove the specified gesture recognizer for the specified widget.
### Syntax
removeGestureRecognizer(gestureHandle)
### Parameters
gestureHandle - Mandatory
Specifies the handle to the gesture returned by addGestureRecognizer call.
### Example
//Sample code to remove Double tap gesture from frmGestures FlexForm.
frmGestures.removeGestureRecognizer(doubletp);
### Platform Availability
* Available on all platforms except Desktop Web and Android.
* * *
</details>
<details close markdown="block"><summary>removePolygon Method</summary>
* * *
This method is used to remove a polygon from the map.
### Syntax
removePolygon(polygonId)
### Parameters
polygonId
Specifies the id of the polygon to remove. This method is ignored if the given id is incorrect or not found.
### Return Values
None
### Exceptions
WidgetError, Error
### Example
//removePolygon method call mapref.removePolygon("polyid1");
### Platform Availability
* iOS and Android
* * *
</details>
<details close markdown="block"><summary>removePin Method</summary>
* * *
Removes a single pin from the map.
### Syntax
removePin(pin)
### Parameters
pin
`pinData` consists of the following key-value pairs.
* **id**\[String\] \[Mandatory\]: Specifies the unique identifier that represents the pin. If a pin already exists with the same identifier, then the id will be replaced by a new id.
* **lat** \[String\] \[Mandatory\]: Specifies the latitude of the location.
* **lon** \[String\] \[Mandatory\]: Specifies the longitude of the location.
* **name** \[String\] \[Mandatory\]: Specifies a short description for the location.
* **desc** \[String\] \[Mandatory\]: Specifies a long description for the location.
* **image** \[String or Image Object\] \[Mandatory\]: Specifies the map pin image that overrides the [defaultPinImage](Map_Properties.md#defaultP).Refer the **Remarks** section for more information.
* **navigateAndZoom** \[Boolean\] \[Optional\]: Decides whether the navigation to first pin should take place. It is available on Android, Windows, and iOS. The default value of this parameter is true.
Here is an example of how to enable this property.
locationData: [{
lat: "17.445775",
lon: "78.3731",
name: "Campus 1",
desc: "My Office Campus",
navigateAndZoom: true
}]
};
* **showcallout** \[Boolean\] \[Optional\]: Shows the callout pop-up. The default value is _true_.
* **calloutData** \[JSObject\] \[Optional\]: Specifies the widget data for a given template for a particular location. The value should be a in the form of key-value pairs. The data can have one of the standard keys called `template` that accepts a reference, to provide location-specific template. This template will override the template provided in the [calloutTemplate](Map_Properties.md#calloutT).
> **_Note:_** The widget-data map for a template must be provided in the "[widgetDataMapForCallout](#widgetDa)" property.
* **meta** \[JSObject\] \[Optional\]: Specifies the platform-specific metadata.
* **color**\[String\] \[Optional\]: Specifies the color for the pop-up. (Supported on Mobile Web and SPA.)
* **label** \[String\] \[Optional\]: Specifies the text for the pop-up. (Supported on Mobile Web and SPA.)
### Return Values
None
### Exceptions
None
### Remarks
The `image` parameter inside the `locationData` property can accept the pin image as a name string or as a JavaScript pin object. The pin object contains the following keys.
| Key | Description |
| --- | --- |
| source | Specifies the source of the image. It could be an image name, an image path, or a URL. |
| sourceType | Contains a value from the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgTyp)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Type Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not given for the sourceType, the default value of PIN\_IMG\_SRC\_TYPE\_RESOURCES is used. |
| anchor | Optional. A constant that defines how the pin image should be anchored to the location point. Its value should be one of the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgAnc)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Anchor Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not specified, the default value of PIN\_IMG\_ANACHOR\_BOTTOM\_CENTER is used. |
### Example
function removeThePin() { frmMapNew.MainMap.removePin(pin1); }
### Platform Availability
* iOS, Android, and Windows
* * *
</details>
<details close markdown="block"><summary>removePins Method</summary>
* * *
Removes several pins from the map.
### Syntax
removePins(pin)
### Parameters
pin
`pinData` consists of the following key-value pairs.
* **id**\[String\] \[Mandatory\]:Specifies the unique identifier that represents the pin. If a pin already exists with the same identifier, then the id will be replaced by a new id.
* **lat** \[String\] \[Mandatory\]: Specifies the latitude of the location.
* **lon** \[String\] \[Mandatory\]: Specifies the longitude of the location.
* **name** \[String\] \[Mandatory\]: Specifies a short description for the location.
* **desc** \[String\] \[Mandatory\]: Specifies a long description for the location.
* **image** \[String or Image Object\] \[Mandatory\]: Specifies the map pin image that overrides the [defaultPinImage](Map_Properties.md#defaultP).Refer the **Remarks** section for more information.
* **navigateAndZoom** \[Boolean\] \[Optional\]: Decides whether the navigation to first pin should take place. It is available on Android, Windows, and iOS. The default value of this parameter is true.
Here is an example of how to enable this property.
locationData: [{
lat: "17.445775",
lon: "78.3731",
name: "Campus 1",
desc: "My Office Campus",
navigateAndZoom: true
}]
};
* **showcallout** \[Boolean\] \[Optional\]: Shows the callout pop-up. The default value is _true_.
* **calloutData** \[JSObject\] \[Optional\]: Specifies the widget data for a given template for a particular location. The value should be a in the form of key-value pairs. The data can have one of the standard keys called `template` that accepts a reference, to provide location-specific template. This template will override the template provided in the [calloutTemplate](Map_Properties.md#calloutT).
> **_Note:_** The widget-data map for a template must be provided in the "[widgetDataMapForCallout](#widgetDa)" property.
* **meta** \[JSObject\] \[Optional\]: Specifies the platform-specific metadata.
* **color**\[String\] \[Optional\]: Specifies the color for the pop-up. (Supported on Mobile Web and SPA.)
* **label** \[String\] \[Optional\]: Specifies the text for the pop-up. (Supported on Mobile Web and SPA.)
### Return Values
None
### Exceptions
None
### Remarks
The `image` parameter inside the `locationData` property can accept the pin image as a name string or as a JavaScript pin object. The pin object contains the following keys.
| Key | Description |
| --- | --- |
| source | Specifies the source of the image. It could be an image name, an image path, or a URL. |
| sourceType | Contains a value from the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgTyp)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Type Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not given for the sourceType, the default value of PIN\_IMG\_SRC\_TYPE\_RESOURCES is used. |
| anchor | Optional. A constant that defines how the pin image should be anchored to the location point. Its value should be one of the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgAnc)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Anchor Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not specified, the default value of PIN\_IMG\_ANACHOR\_BOTTOM\_CENTER is used. |
### Example
frmMapNew.MainMap.removePins([pin2, pin3]);
### Platform Availability
* iOS, Android, and Windows
* * *
</details>
<details close markdown="block"><summary>removePolyline Method</summary>
* * *
This method is used to remove a polyline from the map.
### Syntax
removePolyline(polylineId)
### Parameters
polylineId
Specifies the id of the polyline to remove. This method is ignored if the given id is incorrect or not found.
### Return Values
None
### Exceptions
WidgetError, Error
### Example
//removePolyline method call mapref.removePolyline("polyid1");
### Platform Availability
* iOS and Android
* * *
</details>
<details close markdown="block"><summary>setBadge Method</summary>
* * *
This method enables you to set the badge value to the given widget at the upper, right corner of the widget.
### Syntax
setBadge(badgeText)
### Parameters
badgeText \[String\] - Mandatory
Specifies the Text value that appears within the badge. If the length of the badgeText is greater than 1, the badge is a rounded rectangle. For example, if you specify the text of the badge as 88, the number appears in a rounded rectangular badge. If the length of the badge text is 1, the badge is always a circle. The badge can occupy up to 70% of the width of the parent widget. For example, on a button with a width of 100 pixels, a badge with about 100 characters will occupy only 70 pixels of the button width. The badge text is truncated and shows about 30 characters followed by three dots.
skin \[String\] - Optional
The parameter specifies the background color for the badge. The default color is red.
### Return Values
None
### Exceptions
Error
### Remarks
The color for the badge can be defined using a skin. The default color for the badge is red with white lettering.
If you pass an empty string as a parameter, the badge applied to the widget is cleared.
A Badge can be applied only to the FlexContainer Widget. To apply badge to other widgets, place the corresponding widget inside the FlexContainer, then apply Badge to the FlexContainer Widget. Also make sure that the clipBounds property of the FlexContainer are set to false.
If the badge value is a single character (a character or a number), the badge shape is a circle.
If the badge value contains multiple characters, the badge shape is a rectangle with rounded corners and borders.
The badge can occupy a maximum of 70% width of the parent widget (widget on which badge is applied). For example, on a button with a width of 100 pixels, a badge with about 100 characters will occupy only 70 pixels of the button width. The badge value is truncated and about 30 characters followed by three dots.
When a badge is set, the widgets are re-arranged to accommodate the badge.
For iOS platform, this method is applicable on Box, Label, and Image widgets only.
For Android platform, this method is applicable on Button and Image widgets only.
### Example
//This is a generic method that is applicable for various widgets. //Here, we have shown how to use the setBadge Method for button widget. //You need to make a corresponding call of the setBadge method for other applicable widgets. function setBadge() { /To set a badge value with skin "badgeSkin" on a button btn1 placed on a form frm1, use the following code: / frm1.btn1.setBadge("2", "badgeSkin"); } //For instance, the corresponding setEnabled method call on the Label widget is as follows: form.lbl1.setBadge("4", "badgeSkin");
### Platform Availability
* iOS
For more information about the badge APIs refer the _API Reference Document_.
* * *
</details>
<details close markdown="block"><summary>setBounds Method</summary>
* * *
This API helps to fit the map to the provided center, zoom, viewingAngle, and orientation values at one go.
bounds is the dictionary config returned by [getBounds](#getBound).
### Signature
setBounds(config)
### Parameters
config \[JSDictionary\]: config is a mandatory argument that is a JSDictionary with the following properties:
* center\[JSObject\] -Mandatory. Specifies the latitude and longitude key.
* zoom \[JSNumber\] - Mandatory. The zoom level of the camera determines the scale of the map. For Android, float values are accepted. The desired zoom level is in the range of 2.0 to 21.0. Values below this range are set to 2.0 and values above it are set to 21.0. Increase the value to zoom in. Not all areas have tiles at the largest zoom levels. For Windows also, float values are accepted. The desired zoom level is in the range of 1.0 to 20.0.
* viewingAngle \[JSNumber\] - Mandatory. The viewing angle of the camera, measured in degrees from the current viewer's view point and the intial view point directly facing the Earth. For Android, viewingAngle defines the camera's position on an arc between directly over the map's center position and the surface of the Earth, measured in degrees from the nadir (the direction pointing directly below the camera). The possible value range for this property is restricted depending on the zoom level of the camera. For Windows, viewingAngle is not considered, thus only the default 2-D view is taken into account. So, viewingAngle = 0 is set by default. For iOS and Android,
* For zoom levels less than 10, the maximum viewingAngle value is 30.
* For zoom levels from 10 to 14, the maximum viewingAngle value increases linearly from 30 to 45 (for example, at zoom level 12, the maximum is 37.5).
* For zoom levels from 14 to 15.5, the maximum viewingAngle value increases linearly from 45 to 67.5.
* For zoom levels greater than 15.5, the maximum viewingAngle value is 67.5.
* The minimum is always 0 (directly down). If you specify a value outside this range and try to move the camera to this camera position it will be restricted to within these bounds.
* orientation\[JSNumber\] - Mandatory. Specifies the direction at which the camera is pointing, in degrees clockwise from north. For iOS, this is available from iOS 7 onwards. For Windows, the direction at which the camera is pointing, in degrees clockwise from north, where 0 or 360 means North and 90 means East.
* northeast \[JSObject\] - Specifies the latitude and longitude keys and associated values. For Windows, it is an optional value and it is not respected.
* southwest \[JSObject\] - Specifies the latitude and longitude keys and associated values. For Windows, it is an optional value and it is not respected.
* latspan \[number\] - Specifies the spanning latitude in degrees. For Windows, it is an optional value and it is not respected.
* lonspan \[number\] - Specifies the spanning longitude in degrees. For Windows, it is an optional value and it is not respected.
### Return Values
None
### Remarks
1. You should call the fitToBounds and setBounds methods for onMapLoaded callback.
2. Before using the setBounds method, you must use the getBounds method to retrieve the current map bounds.
3. If you call both fitToBounds and setBounds (fitToBounds, setBounds) before navigating to the form that contains the map, the fitToBounds method takes precedence.
### Example
/Sample code to invoke setBounds method for myMap Map widget in frmMap form./ var bounds = frmMap.myMap.getBounds(); bounds.center = { lat: "17.3850", lon: "78.4867", }; bounds.zoom = 6; bounds.viewAngle = 30; bounds.orientation = 270; frmMap.myMap.setBounds(bounds);
### Platform Availability
* iOS, Android, and Windows
* * *
</details>
<details close markdown="block"><summary>setCalloutVisibility Method</summary>
* * *
This method is used to show or hide callouts in Google Maps.
Consider a banking application where you want to search for bank branches or ATMs. The bank branches and ATMs are represented is represented as pins in the Maps. When you click on any pin corresponding to branches, you can show the callout with the information such as address and working hours using the `setCalloutVisibility` method. If you want to hide the information corresponding to the ATMs, you can use the `setCalloutVisibility` method to hide it.
### Syntax
setCalloutVisibility(visible, pin)
### Parameters
visible
Boolean. Required.
pin
Dictionary. Required.
### Return Values
None
### Exceptions
None
### Remarks
`setCalloutVisibility` method does not work when the Map widget corresponding to the pins, is not visible.
### Example
var pin1 = { id: "id1", // id is mandatory for every pin lat: "17.447412", lon: "78.376230", name: "Hitec city", image: "defaultImage.png", focusImage: "focusImage.png", //focus image will be shown while map pin selected desc: "Office", showCallout: true, meta: { color: "green", label: "A" } }; frmMapNew.mainMap.setCalloutVisibility(true, pin1);
### Platform Availability
* iOS, Android, Windows, and Desktop Web
* * *
</details>
<details close markdown="block"><summary>setEnabled Method</summary>
* * *
This method specifies the widget that must be enabled or disabled.
### Syntax
setEnabled(enabled)
### Parameters
_enabled_
\[Boolean\] - Mandatory
true -Indicates widget is enabled.
false - Indicates widget is disabled.
### Return Values
None
### Exceptions
Error
### Remarks
Browser widget does not support this method in SPA.
This method is not applicable in Map widget.
### Example
//This is a generic method that is applicable for various widgets. //Here, we have shown how to use the setEnabled Method for button widget. //You need to make a corresponding call of the setEnabled method for other applicable widgets.
form1.myButton.setEnabled(false);
### Platform Availability
Available on all platforms except SPA.
* * *
</details>
<details close markdown="block"><summary>setFocus Method</summary>
* * *
This method specifies the widget on which there must be focus.
**Default :** true
### Syntax
setFocus(focus)
### Parameters
_focus_ \[Boolean\]- Mandatory
true -Indicates focus is set on a widget.
false - Indicates focus is not set on a widget.
### Return Values
None
### Exceptions
Error
### Remarks
You should not call this method in **preShow** of a form as it is not respected by all platforms. In android platform, this method is not respected in **preShow** of a form. You can give focus to a particular widget only after it is rendered on the screen, hence it should be called in postShow of a form.
This method is not applicable in Form widget.
### Example
//This is a generic method that is applicable for various widgets. //Here, we have shown how to use the setFocus Method for button widget. //You need to make a corresponding call of the setFocus method for other applicable widgets.
form1.myButton.setFocus(true);
### Platform Availability
Available on all platforms.
* * *
</details>
<details close markdown="block"><summary>setGestureRecognizer Method</summary>
* * *
This method allows you to set a gesture recognizer for a specified gesture for a specified widget. You can set a Gesture recognizer only for a FlexForm, a FlexContainer, and a FlexScrollContainer. The setGestureRecognizer method is deprecated and should not be used in new software. However, Swipe Distance and Swipe Velocity parameters are not deprecated. So if you want to use the Swipe Distance and Swipe velocity parameters, use the setGestureRecognizer method. To use all other parameters, you must use the addGestureRecognizer method.
### Syntax
setGestureRecognizer (gestureType,setupParams,gestureHandler)
### Parameters
_gestureType_
\[Number\] - Mandatory
Specifies the type of gesture that needs to be detected on the widget. The following are possible values:
* 1 for TAP
* 2 for SWIPE
* 3 for LONGPRESS
_setupParams_
\[array of arrays\] - Mandatory
The parameter specifies an object that has the configuration parameters to setup a gesture recognizer. See Remarks for the values for this parameter.
gestureHandler
\[function\] - Mandatory
The parameter specifies the function that needs to be executed when a gesture is recognized. See Remarks for the functions syntax.
onGesturefunction(widgetRef,gestureInfo)
* _widgetRef_ - This parameter specifies the handle to the widget on which the gesture was recognized.
* _gestureInfo_ - This parameter specifies an array that provides information about the gesture. The contents of this array vary based on the gesture type.
Volt MX Iris populates the details in the _gestureInfo_ array. This array has the following key-value pairs:
* _gestureType_ \[number\] - indicates the gesture type; **1** for TAP, **2** for SWIPE, and **3** for LONGPRESS.
* _gesturesetUpParams_ \[object\] - this array is the set up parameters passed while adding the gesture recognizer.
* _gesturePosition_ \[number\] - indicates the position where the gesture was recognized. Possible values are: **1** for TOPLEFT, **2** for TOPCENTER, **3** for TOPRIGHT, **4** for MIDDLELEFT, **5** for MIDDLECENTER, **6** for MIDDLERIGHT, **7** for BOTTOMLEFT, **8** for BOTTOMCENTER, **9** for BOTTOMRIGHT, **10** for CENTER. This parameter is applicable only on iPhone.
* _swipeDirection_ \[number\] -indicates the direction of swipe. This parameter is applicable only if the gesture type is SWIPE. Possible values are: **1** for LEFT, **2** for RIGHT, **3** for TOP, **4** for BOTTOM.
* _gestureX_ \[number\] - specifies the X coordinate of the point (in pixels) where the gesture has occurred. The coordinate is relative to the widget coordinate system. This parameter is applicable only on iPhone.
* _gestureY_ \[number\] - specifies the Y coordinate of the point (in pixels) where the gesture has occurred. The coordinate is relative to the widget coordinate system. This parameter is applicable only on iPhone.
* _widgetWidth_ \[number\] - specifies the width of the widget (in pixels). This parameter is applicable only on iPhone.
* _widgetHeight_ \[number\] - specifies the height of the widget (in pixels). This parameter is applicable only on iPhone.
### Return Values
String - Reference(uniqueidentifier) to the gesture is returned.
### Exceptions
Error
### Remarks
This method is applicable on Form, Box, and ScrollBox widgets only.
Configuration of setupParams
The configuration parameters vary based on the type of the gesture.
Gesture Type:TAP
* fingers \[number\] - This parameter specifies the maximum number of fingers that must be respected for a gesture. Possible values are: 1. Default value is 1.
* taps \[number\] - This parameter specifies the maximum number of taps that must be respected for a gesture. Possible values are: 1 or 2. Default value is 1.
### For example:
{fingers:1,taps:1}
Gesture Type:SWIPE
* fingers \[number\] - This parameter specifies the maximum number of fingers that must be respected for a gesture. Possible values are: 1. Default value is 1.
* swipedistance \[number\] - This parameter specifies the distance between the pixel from where the swipe started to the pixel where the swipe stopped (finger is moved up or removed). The default value is 50 pixels. This parameter is applicable only on android. This parameter is applicable only if the gesture type is SWIPE.
* swipevelocity \[number\] - This parameter specifies the velocity of the swipe measured in pixels per second. The default value is 75. This parameter is applicable only on android. This parameter is applicable only if the gesture type is SWIPE.
### For example:
{fingers:1,swipedistance:50,swipevelocity:75}
Gesture Type:LONGPRESS
* pressDuration \[number\] - This parameter specifies the minimum time interval (in seconds) after which the gesture is recognized as a LONGPRESS. For example, if the _pressDuration_ is 2 seconds, any continued press is recognized as LONGPRESS only if it lasts for at least 2 seconds. Default value is 1. This parameter is not customizable on android platform. The default value on android platform is 500 ms. Any value you pass to this parameter is ignored and the default value is used.
### For example:
{pressDuration:1}
Function syntax for the _GestureHandler_ parameter
The parameter specifies the function that needs to be executed when a gesture is recognized. This function has the following Syntax:
onGesturefunction(widgetRef,gestureInfo)
* _widgetRef_ - This parameter specifies the handle to the widget on which the gesture was recognized.
* _gestureInfo_ - This parameter specifies an array that provides information about the gesture. The contents of this array vary based on the gesture type.
Volt MX Iris populates the details in the _gestureInfo_ array. This array has the following key-value pairs:
* _gestureType_ \[number\] - indicates the gesture type; **1** for TAP, **2** for SWIPE, and **3** for LONGPRESS.
* _gesturesetUpParams_ \[object\] - this array is the set up parameters passed while adding the gesture recognizer.
* _gesturePosition_ \[number\] - indicates the position where the gesture was recognized. Possible values are: **1** for TOPLEFT, **2** for TOPCENTER, **3** for TOPRIGHT, **4** for MIDDLELEFT, **5** for MIDDLECENTER, **6** for MIDDLERIGHT, **7** for BOTTOMLEFT, **8** for BOTTOMCENTER, **9** for BOTTOMRIGHT, **10** for CENTER. This parameter is applicable only on iPhone.
* _swipeDirection_ \[number\] -indicates the direction of swipe. This parameter is applicable only if the gesture type is SWIPE. Possible values are: **1** for LEFT, **2** for RIGHT, **3** for TOP, **4** for BOTTOM.
* _gestureX_ \[number\] - specifies the X coordinate of the point (in pixels) where the gesture has occurred. The coordinate is relative to the widget coordinate system. This parameter is applicable only on iPhone.
* _gestureY_ \[number\] - specifies the Y coordinate of the point (in pixels) where the gesture has occurred. The coordinate is relative to the widget coordinate system. This parameter is applicable only on iPhone.
* _widgetWidth_ \[number\] - specifies the width of the widget (in pixels). This parameter is applicable only on iPhone.
* _widgetHeight_ \[number\] - specifies the height of the widget (in pixels). This parameter is applicable only on iPhone.
### Example
//The below function will get invoked when a gesture is recognized. function myTap(myWidget, gestureInfo) { alert(" Tap Gesture detected"); alert("gestureType :" + gestureInfo.gestureType); alert("gesturePosition :" + gestureInfo.gesturePosition); //write any further logic here }
//Setting Gesture configuration. var setupTblTap = { fingers: 1, taps: 2 }; //double tap gesture
//To add a TAP gesture recognizer on a hbox with ID hbx1 placed on a form frm1 var tapGesture = frm1.hbx1.setGgestureRecognizer(1, setupTblTap, myTap);
### Platform Availability
* iOS, Windows, and SPA
* * *
</details>
<details close markdown="block"><summary>setOnPeek Method</summary>
* * *
This method sets and overrides the existing onPeekCallback for the widget.
### Syntax
setOnPeek(onPeekCallback)
### Parameters
onPeekCallback
A callback function that is invoked when the user slightly presses (soft press) the widget.
Callback Syntax
onPeekCallback(widget)
Callback Parameters
_widget_
A widget reference that is registered for peek and pop.
### Callback Return Values
PreviewInfoTable. See the Remarks section for a description of this table.
### Callback Example
function onPeekCallback(widget, contextInfo) { var previewInfoTable = { "peekForm": frmSecond, "focusRect": [0, 0, 200, 200], "contentSize": [320, 480] }; return previewInfoTable; }
### Return Values
None.
### Remarks
A PreviewInfoTable has the following format.
**Name:** peekForm
**Description:** The form reference that will be displayed as preview. If an invalid form reference is given, the preview will not be shown.
**Type:** form reference
**Name:** focusRect (Optional)
**Description:** An array representing a rectangle in widgets view coordinates. If provided, this rectangle will be focused while its surrounding area will be blurred, indicating a preview is available for the widget. If not provided, entire view area of the widget will be focused. If either the width or height is zero, the widget's view width/height is used. The values are supported in percentage(with regard to widget bounds), dp, or pixels. The values are strings. If a string value is given without any format specifier, it defaults to dp. If an array of numbers is given, it is assumed they are dp values.
**Type:**Array \[x, y, width, height\]
Example: \[“0dp”, “0dp”, “200dp”, “300dp”\], \[“10%”, “10%”, “75%”, “50%”\], \[“10px”, “10px”, “200px”, “480px”\]
**Name:**contentSize (Optional)
**Description:**An array representing the preferred content size of the preview. This allows the user to adjust the preferred width/height dimensions of the preview. If not provided, the preview is shown with default values. If either the width or height is zero, the default preview width/height is used. It is recommended that one of the width/height values be zero for proper adjustment of the other value. For example, if width = 0, the height is adjustable and vice versa. Providing positive values simultaneously for both width and height will result in distorted appearance of preview. The values are supported in dp, pixels, and percentage(with regard to screen bounds). The actual width/height of the preview may vary slightly due to resizing per aspect ratio. The values are strings. If a string value is given without any format specifier, it defaults to dp. If array of numbers is given, it is assumed they are dp values.
**Type:**Array \[width, height\]
Example: \[“0dp”, “100dp”\], \[“100%”, “0%”\], \[“0px”, “240px”\]
### Example of a PreviewInfoTable:
var previewInfoTable = { "peekForm": frmSecond, "focusRect": [0, 0, 200, 200], "contentSize": [320, 480] };
### Example
function settingPeek() { Form1.setOnPeek(onMyPeekcallback); }
function onMyPeekcallback(widgetref, contextInfo) { if (typeof(contextInfo) === undefined) { return null; }
var previewInfoTable = {
"peekForm": frmSecond,
"focusRect": [0, 0, 200, 200],
"contentSize": [320, 480]
};
return previewInfoTable;
}
### Platform Availability
* iOS 9.0 and later
* * *
</details>
<details close markdown="block"><summary>setOnPop Method</summary>
* * *
This method overrides the existing onPopCallback for the widget.
### Syntax
setOnPop(onPopCallback)
### Parameters
onPopCallback
A callback function that is invoked when the user slightly presses (soft press) the widget.
Callback Syntax
onPopCallback(widget,peekForm)
Callback Parameters
_widget_
A widget reference that is registered for peek and pop.
_peekForm_
A form reference that is displayed as preview/peek.
### Callback Return Values
A form reference.
### Callback Remarks
Use this callback to set the content for pop. The form handle returned by this callback is used for pop content. In general, the form that is used for preview is used for pop content also. If the pop callback is not implemented, peek disappears and the app returns to its previous state.
### Callback Example
function onPopCallback(widget, peekForm) { // preview form used for pop also return peekForm; }
### Return Values
None.
### Example
function settingPop() { Form1.setOnPop(myonPopcallback); }
function myonPopcallback(widgetref, peekForm) { // preview form used for pop also return peekForm; }
### Platform Availability
* iOS 9.0 and later
* * *
</details>
<details close markdown="block"><summary>setVisibility Method</summary>
* * *
Use this method to set the visibility of the widget.
**Default :** true
### Syntax
setVisibility(visible)
### Parameters
_visible_
\[Boolean\] - Mandatory
true -Indicates visibility is true.
false - Indicates visibility is false.
_animationConfig_
\[JSObject\] - Optional. The parameter specifies the animation configuration of the object. This is not supported in SPA and Desktop Web platforms.
Following are the parameters of the JSObject:
_animEffect_
Optional. The parameter specifies the animation effect. Following are the available options of animation effect:
* constants.ANIMATION\_EFFECT\_EXPAND: This is applicable when the visibility is turned on. Specifies the widget must expand gradually by increasing the height of the widget.
* constants.ANIMATION\_EFFECT\_COLLAPSE: This is applicable when the visibility is turned off. Specifies the widget must collapse gradually by decreasing the height of the widget.
* constants.ANIMATION\_EFFECT\_REVEAL: This is applicable when the visibility is turned on. Specifies the widget must appear gradually by decreasing the transparency of the widget.
* constants.ANIMATION\_EFFECT\_FADE: This is applicable when the visibility is turned off. Specifies the widget must disappear gradually by increasing the transparency of the widget.
* constants.ANIMATION\_EFFECT\_NONE: This is the default option. Specifies animation should not be applied to the widget. However the layout animations are applied on the Form.
_animDuration_
Optional. The parameter specifies the duration of the animation effect in seconds. The default value is 1 second. The negative values are ignored and defaulted to 1 second.
_animDelay_
Optional. This parameter specifies the delay of the animation effect in seconds. The default value is 0 second. The negative values are ignored and defaulted to 0 second.
_animCurve_
Optional. The parameter specifies the animation curve to be applied while playing the animation. An animation curve defines the speed of the animations at different intervals of the animation duration. Following are the available options of animation curve:
* constants.ANIMATION\_CURVE\_EASEIN: Specifies the animation effect to start slow in the beginning.
* constants.ANIMATION\_CURVE\_EASEOUT: Specifies the animation effect to slowdown towards the end.
* constants.ANIMATION\_CURVE\_EASEINOUT: Specifies the animation effect to start slow and slowdown towards the end.
* constants.ANIMATION\_CURVE\_LINEAR: This is the default value. Specifies the animation effect to continue with the same speed from start to end.
animCallBacks - Optional
It is a JS dictionary containing the events invoked by the platform during the animation life cycle. Following are the available events:
* **animStarted**: Invoked at the beginning of the animation without any parameters. Following is the Syntax of the event: function animStarted()
* **animEnded**: Invoked at the end of the animation without any parameters. Following is the Syntax of the event: function animEnded()
### Return Values
None
### Exceptions
Error
### Remarks
This method is not applicable on Form, Popup, and Alert. It is also not applicable if the widget is placed in a [Segment](Segment.md). When the widget is placed in a Segment, the default _Visibility_ is set to _true_. If you want to change the value to _false_, you can do so by using [Segment](Segment_Methods.md#segmentedui-methods) methods.
Passing an invalid type other than the above events lead to run time exceptions/ crashes.
This method is not supported on the widgets FlexForm, FlexContainer, and FlexScrollContainer.
### Example
//This is a generic method that is applicable for various widgets. //Here, we have shown how to invoke the setVisibility Method for a button widget with animation. //You need to make a corresponding call of the setVisibility method for other applicable widgets.
form1.myButton.setVisibility( false, { "animEffect": constants.ANIMATION_EFFECT_COLLAPSE, "animDuration": 1, "animDelay": 0, "animCurve": constants.ANIMATION_CURVE_LINEAR, "animCallBacks": { "animStarted": startCallBackFunc, "animEnded": endCallBackFunc } }); //Sample code to invoke setVisibility Method for button widget without animation. form1.myButton.setVisibility(false);
### Platform Availability
Available on all platforms.
* * *
</details>
<details close markdown="block"><summary>unregisterForPeekandPop Method</summary>
* * *
This method unregisters a widget from 3D Touch peek and pop gestures.
### Syntax
unregisterForPeekandPop()
### Parameters
None.
### Return Values
None.
### Example
Form1.unregisterForPeekAndPop();
### Platform Availability
* iOS 9.0 and later
* * *
</details>
<details close markdown="block"><summary>updatePin Method</summary>
* * *
Updates a single pin on the map.
### Syntax
updatePin(pinData)
### Parameters
pinData
`pinData` consists of the following key-value pairs.
* **id**\[String\] \[Mandatory\]: Specifies the unique identifier that represents the pin. If a pin already exists with the same identifier, then the id will be replaced by a new id.
* **lat** \[String\] \[Mandatory\]: Specifies the latitude of the location.
* **lon** \[String\] \[Mandatory\]: Specifies the longitude of the location.
* **name** \[String\] \[Mandatory\]: Specifies a short description for the location.
* **desc** \[String\] \[Mandatory\]: Specifies a long description for the location.
* **image** \[String or Image Object\] \[Mandatory\]: Specifies the map pin image that overrides the [defaultPinImage](Map_Properties.md#defaultP).Refer the **Remarks** section for more information.
* **navigateAndZoom** \[Boolean\] \[Optional\]: Decides whether the navigation to first pin should take place. It is available on Android, Windows, and iOS. The default value of this parameter is true.
Here is an example of how to enable this property.
locationData: [{
lat: "17.445775",
lon: "78.3731",
name: "Campus 1",
desc: "My Office Campus",
navigateAndZoom: true
}]
};
* **showcallout** \[Boolean\] \[Optional\]: Shows the callout pop-up. The default value is _true_.
* **calloutData** \[JSObject\] \[Optional\]: Specifies the widget data for a given template for a particular location. The value should be a in the form of key-value pairs. The data can have one of the standard keys called `template` that accepts a reference, to provide location-specific template. This template will override the template provided in the [calloutTemplate](Map_Properties.md#calloutT).
> **_Note:_** The widget-data map for a template must be provided in the "[widgetDataMapForCallout](#widgetDa)" property.
* **meta** \[JSObject\] \[Optional\]: Specifies the platform-specific metadata.
* **color**\[String\] \[Optional\]: Specifies the color for the pop-up. (Supported on Mobile Web and SPA.)
* **label** \[String\] \[Optional\]: Specifies the text for the pop-up. (Supported on Mobile Web and SPA.)
* **zIndex**\[Number\] \[Optional\]: Applicable for Android platform only.
Specifies the stack order of pins in the Map widget. You can set a Double or Integer value (including negative value) as `zIndex`. When a pin is added to the Map widget with a higher `zIndex`, it will be placed in front of other pins with lower zIndices. If multiple pins are placed at the same co-ordinates, then the [onPinClick](Map_Events.md#onPinCli) event is first triggered for the pin with a higher `zIndex`. The `onPinClick` event is then triggered for the rest of the pins in a descending order of `zIndex` on consecutive clicks. The default value of this parameter is zero.
> **_Note:_** In Android platform, in a map the z-index value stack of the pins are different from the z-index stack of the shapes. The pins are drawn on top of the shapes based on their z-index values. Also, when the pins and shapes (such as circle and polyline) are placed on the map on top of each other, the click event of the pins have a higher priority than the click events of the shapes.
### Return Values
None
### Remarks
The `image` parameter inside the `locationData` property can accept the pin image as a name string or as a JavaScript pin object. The pin object contains the following keys.
| Key | Description |
| --- | --- |
| source | Specifies the source of the image. It could be an image name, an image path, or a URL. |
| sourceType | Contains a value from the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgTyp)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Type Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not given for the sourceType, the default value of PIN\_IMG\_SRC\_TYPE\_RESOURCES is used. |
| anchor | Optional. A constant that defines how the pin image should be anchored to the location point. Its value should be one of the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgAnc)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Anchor Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not specified, the default value of PIN\_IMG\_ANACHOR\_BOTTOM\_CENTER is used. |
### Example
// id is mandatory for every pin function updatePin() { pinTemp = { id: "id1", name: "Kukatpally Housing Board", }; frmMapNew.MainMap.updatePin(pinTemp); frmMapNew.lblUpdate.text = "updated the name of added pin"; }
### Platform Availability
* iOS, Android, and Windows
* * *
</details>
<details close markdown="block"><summary>updatePins Method</summary>
* * *
Updates several pins on the map.
### Syntax
updatePins(pinData)
### Parameters
pinData
`pinData` consists of the following key-value pairs.
* **id**\[String\] \[Mandatory\]: Specifies the unique identifier that represents the pin. If a pin already exists with the same identifier, then the id will be replaced by a new id.
* **lat** \[String\] \[Mandatory\]: Specifies the latitude of the location.
* **lon** \[String\] \[Mandatory\]: Specifies the longitude of the location.
* **name** \[String\] \[Mandatory\]: Specifies a short description for the location.
* **desc** \[String\] \[Mandatory\]: Specifies a long description for the location.
* **image** \[String or Image Object\] \[Mandatory\]: Specifies the map pin image that overrides the [defaultPinImage](Map_Properties.md#defaultP).Refer the **Remarks** section for more information.
* **navigateAndZoom** \[Boolean\] \[Optional\]: Decides whether the navigation to first pin should take place. It is available on Android, Windows, and iOS. The default value of this parameter is true.
Here is an example of how to enable this property.
locationData: [{
lat: "17.445775",
lon: "78.3731",
name: "Campus 1",
desc: "My Office Campus",
navigateAndZoom: true
}]
};
* **showcallout** \[Boolean\] \[Optional\]: Shows the callout pop-up. The default value is _true_.
* **calloutData** \[JSObject\] \[Optional\]: Specifies the widget data for a given template for a particular location. The value should be a in the form of key-value pairs. The data can have one of the standard keys called `template` that accepts a reference, to provide location-specific template. This template will override the template provided in the [calloutTemplate](Map_Properties.md#calloutT).
> **_Note:_** The widget-data map for a template must be provided in the "[widgetDataMapForCallout](#widgetDa)" property.
* **meta** \[JSObject\] \[Optional\]: Specifies the platform-specific metadata.
* **color**\[String\] \[Optional\]: Specifies the color for the pop-up. (Supported on Mobile Web and SPA.)
* **label** \[String\] \[Optional\]: Specifies the text for the pop-up. (Supported on Mobile Web and SPA.)
* **zIndex**\[Number\] \[Optional\]: Applicable for Android platform only.
Specifies the stack order of pins in the Map widget. You can set a Double or Integer value (including negative value) as `zIndex`. When a pin is added to the Map widget with a higher `zIndex`, it will be placed in front of other pins with lower zIndices. If multiple pins are placed at the same co-ordinates, then the [onPinClick](Map_Events.md#onPinCli) event is first triggered for the pin with a higher `zIndex`. The `onPinClick` event is then triggered for the rest of the pins in a descending order of `zIndex` on consecutive clicks. The default value of this parameter is zero.
> **_Note:_** In Android platform, in a map the z-index value stack of the pins are different from the z-index stack of the shapes. The pins are drawn on top of the shapes based on their z-index values. Also, when the pins and shapes (such as circle and polyline) are placed on the map on top of each other, the click event of the pins have a higher priority than the click events of the shapes.
### Return Values
None
### Remarks
The `image` parameter inside the `locationData` property can accept the pin image as a name string or as a JavaScript pin object. The pin object contains the following keys.
| Key | Description |
| --- | --- |
| source | Specifies the source of the image. It could be an image name, an image path, or a URL. |
| sourceType | Contains a value from the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgTyp)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Type Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not given for the sourceType, the default value of PIN\_IMG\_SRC\_TYPE\_RESOURCES is used. |
| anchor | Optional. A constant that defines how the pin image should be anchored to the location point. Its value should be one of the [](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md#PnImgAnc)[](../../../Iris/iris_api_dev_guide/content/voltmx_map_constants.md)[Pin Image Anchor Constants](../../../Iris/iris_api_dev_guide/content/introduction.md). If a value is not specified, the default value of PIN\_IMG\_ANACHOR\_BOTTOM\_CENTER is used. |
### Example
// id is mandatory for every pin function updatePins() { pinTemp = { id: "id1", name: "Kukatpally Housing Board", }; pinTemp1 = { id: "id2", name: "Four Minarets", }; frmMapNew.MainMap.updatePins([pinTemp, pinTemp1]); frmMapNew.lblUpdate.text = "updated the names of Pins"; } ```
Platform Availability
- iOS, Android, and Windows