Learn how to display the current device location on a map or scene.
You can display the device location on a map or scene. This is important for workflows that require the user's current location, such as finding nearby businesses, navigating from the current location, or identifying and collecting geospatial information.
By default, location display uses the device's location provider. Your app can also process input from other location providers, such as an external GPS receiver or a provider that returns a simulated location. For more information, see the Show device location topic.
Prerequisites
The following are required for this tutorial:
An ArcGIS account to access your API keys. If you don't have an account, sign up for free.
To start this tutorial, complete the Display a map tutorial, or download and unzip the Display a map solution into a new folder.
Open the build.gradle file as a project in IntelliJ IDEA.
If you downloaded the solution project, set your API key.
An API Key enables access to services, web maps, and web scenes hosted in ArcGIS Online.
Go to your developer dashboard to get your API key.
For these tutorials, use your default API key. It is scoped to include all of the services demonstrated in the tutorials.
In the IntelliJ IDEA's Project tool window, open src/main/java/com.example.app and double-click App.
In the start() method, set the API key property on the ArcGISRuntimeEnvironment with your API key. Replace YOUR_API_KEY with your actual API Key. Be sure to surround your API Key with quotes, because the parameter passed to setApiKey is a string.
App.java
Use dark colors for code blocks
Change lineChange lineChange lineChange line
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
@Overridepublicvoidstart(Stage stage){
// set the title and size of the stage and show it stage.setTitle("Display a map tutorial");
stage.setWidth(800);
stage.setHeight(700);
stage.show();
// create a JavaFX scene with a stack pane as the root node, and add it to the scene StackPane stackPane = new StackPane();
Scene scene = new Scene(stackPane);
stage.setScene(scene);
// Note: it is not best practice to store API keys in source code.// The API key is referenced here for the convenience of this tutorial. String yourApiKey = "YOUR_API_KEY";
ArcGISRuntimeEnvironment.setApiKey(yourApiKey);
Prepare files before coding the app
Modify the files from the Display a map tutorial so they can be used in this tutorial: you will add imports, change the application title, and remove unnecessary code; you will then add a dependency to the build configuration.
In the IntelliJ IDEA > Project tool window, open src/main/java/com.example.app and click App. Add the following imports, replacing those from the Display a map tutorial
Simulation of location data allows this app to run on devices that do not have location services or do not have an actively updating GPS signal. Simulated data is also useful for testing your own location-enabled apps. For more information, see Simulated device location updates.
For this tutorial, you will use simulated location data: a set of location points defined in json. The location points are from a walk around a large parking lot. To display a user's real position, you would use NmeaLocationDataSource instead.
On your file system, create a file named polyline_data.json in the src/main/resources/ directory of your project. Then paste the following json code into it.
From those location points, create a Polyline that traces the route through the parking lot.
In App.java, get the data from the json file, using IOUtils.string(), which you imported from the commons-io dependency in the previous section. Then call Geometry.fromJson() and cast the returned Geometry to a Polyline.
Each map view has its own instance of a LocationDisplay that shows the current location (point) of the device. This is displayed as an overlay in the map view.
Instances of this class manage the display of device location on a map view: the symbols, animation, auto pan behavior, and so on. Location display is an overlay of the map view, and displays above everything else, including graphics overlays.
The location display does not retrieve location information, that is the job of the associated data source, which provides location updates on a regular basis. In addition to the default system location data source, you can use location providers based on external GPS devices or a simulated location source.
Each map view has its own instance of a location display and instances of location display and location data source are not shared by multiple map views. This allows you to start and stop location display independently on multiple map views without affecting each other.
In start(), get the location display and set the simulated location data source on it.
Run the app. Ensure to run the app as a Gradle task and not as an application in your IDE. In the Gradle tool window, under Tasks > application, double-click run.
You will see the initial location displayed as a round blue symbol on the map. The location symbol then changes into a white arrowhead within a blue circle and begins walking around the parking lot as the location display consumes the simulated data. When the end of the data is reached, the route repeats.
Different location symbols are used in different autopan modes, and a location symbol's appearance changes whenever a location is acquired. See LocationDisplay.AutoPanMode for details.
By default, a round blue symbol is used to display the device's location. The location data source tries to get the most accurate location available but depending upon signal strength, satellite positions, and other factors, the location reported could be an approximation. A semi-transparent circle around the location symbol indicates the range of accuracy. As the device moves and location updates are received, the location symbol will be repositioned on the map.