native.newMapView()

Type Function
Library native.*
Return value Map
Revision Release 2022.3683
Keywords maps, map view, map object
See also mapAddress
mapLocation
mapMarker

Overview

Renders a map view within the specified boundaries and returns a display object wrapper. On the map view, touch events are available when you add a mapLocation event listener.

Gotchas

General

  • This feature is only supported on Android and iOS.

  • Native map views are not part of the OpenGL canvas and do not obey the display object hierarchy, so they will always appear in front of normal display objects including images, text, and vector objects.

Android

Google now requires you to provide an API key to use maps on Android. You can get an API key here.

On Android, you must add the INTERNET permission to the build.settings file in order to display a map. You may optionally add location permissions in order to display the current location in a map.

settings =
{
    android =
    {
        usesPermissions =
        {
            "android.permission.INTERNET",

            --optional permission used to display current location via the GPS
            "android.permission.ACCESS_FINE_LOCATION",

            --optional permission used to display current location via WiFi or cellular service
            "android.permission.ACCESS_COARSE_LOCATION",
        },
        usesFeatures =
        {
            -- If you set permissions "ACCESS_FINE_LOCATION" and "ACCESS_COARSE_LOCATION" above,
            -- you may want to set up your app to not require location services as follows.
            -- Otherwise, devices that do not have location sevices (such as a GPS) will be unable
            -- to purchase this app in the app store.
            { name = "android.hardware.location", required = false },
            { name = "android.hardware.location.gps", required = false },
            { name = "android.hardware.location.network", required = false }
        },
    },
}

In addition, you will need to add your API key to your config.lua:

application =
{
    license =
    {
        google =
        {
            mapsKey = "YOUR_MAPS_API_KEY",
        },
    },
}

iOS

On iOS, you must include the following keys/descriptions in the plist table of build.settings. When the system prompts the user to allow access, the associated description is displayed as part of the alert. Note that these descriptions can be customized to your preference and they can even be localized (guide).

settings =
{
    iphone =
    {
        plist =
        {
            NSLocationAlwaysUsageDescription = "This app would like to use location services.",
            NSLocationWhenInUseUsageDescription = "This app would like to use location services.",
        },
    },
}

Syntax

native.newMapView( x, y, width, height )
x (required)

Number. The x coordinate that corresponds to the center of the map view object.

y (required)

Number. The y coordinate that corresponds to the center of the map view object.

width (required)

Number. Width of the map view object.

height (required)

Number. Height of the map view object.

Properties / Methods

See the Map documentation for a list of methods and properties.

Events

See the mapAddress, mapLocation, and mapMarker event documentation for properties related to various Map object events.

Example

-- Create a native map view
local myMap = native.newMapView( 20, 20, 280, 360 )
myMap.x = display.contentCenterX
myMap.y = display.contentCenterY

-- Display map as vector drawings of streets (other options are "satellite" and "hybrid")
myMap.mapType = "standard"

-- Initialize map to a real location
myMap:setCenter( 37.331692, -122.030456 )