ArcGIS Runtime SDK for Java - Navigating the map

When you add a map (JMap) to your Java application, you can automatically pan and zoom the map using the mouse or keyboard. The following table lists the set of pre-defined keyboard and mouse shortcuts which are enabled on a JMap component by default:

Map action	Mouse action	Key action
Pan in the direction of the arrow key pressed		Press left, right, up, down arrow
Zoom in (+) or zoom out (-) to next level of detail or by a factor of 2	Scroll wheel forward/backward	Press +/- key
Zoom in to next level of detail or by a factor of 2	Left mouse button double-click
Pan the map	Left mouse button hold and drag

You can also add a navigator component to your map which gives your user additional control over map navigation using the mouse, including map rotation and setting the map to the full extent. The navigator component is in the SDK's toolkit as the NavigatorOverlay class and it can be added to a map as follows:

// create and add a navigator to the map
NavigatorOverlay navigator = new NavigatorOverlay();
map.addMapOverlay(navigator);

Here is a screenshot of the navigator added to a map:

Navigator screenshot

The remainder of this topic will go into how to perform navigation actions programmatically.

Setting the initial extent

To control which area of your map displays when a user first loads your application, set the initial extent when the 'mapReady' event fires. The 'mapReady' event fires when you add a first layer to your map (typically a basemap) as the map's spatial reference gets set to this layer's spatial reference. To construct an initial extent, you can create an Envelope instance from a Point and a desired width and height, or by passing in the coordinates of the four corners of your desired extent. The latter method is shown in the code sample that follows, where an initial extent is constructed from four coordinates in the units of the basemap's spatial reference. In this case the units are meters ('esriMeters') and the spatial reference is Web Mercator (wkid = 102100).

map.addMapEventListener(new MapEventListenerAdapter() {
   @Override
   public void mapReady(final MapEvent event) {
      SwingUtilities.invokeLater(new Runnable() {
         @Override
         public void run() {
            // create an initial extent
            Envelope initialExtent = new Envelope(-20042400,856094,-2783530,11716267);
            // set the extent on the JMap
            ((JMap) event.getSource()).setExtent(initialExtent);
         }
      });
   }
});

Note:

As a call to set the extent modifies the visual appearance of your application and interacts with Swing components, ensure this operation is performed on Swing's event dispatch thread. The call to SwingUtilities.invokeLater ensures this is the case. For more information on threading in Swing, please consult Java's Concurrency in Swing tutorial.

You can similarly use the setExtent method on the JMap instance at any point after your map is ready in order to set a custom extent, for example in response to a button click or when a query result is returned.

Panning and zooming

In addition to the built-in panning in zooming via the mouse and keyboard, you can programatically pan or zoom the map in various ways using the API. For example, you may want to zoom to a certain part of the world in response to a button click, pan the map by a fixed distance, or zoom the map to a certain scale. Methods operating on the JMap class allow you to perform all of these actions. The code snippet below shows how you would zoom to a geometry, for example a state polygon, with a custom buffer distance around the geometry in order to give the user some context:

// buffer distance in the map's units (metres in this case)
double BUFFER_DISTANCE = 500000; // 500 km
// calculate a buffer around the geometry
Geometry geometryForZoom = GeometryEngine.buffer(
   polygonGraphic.getGeometry(), map.getSpatialReference(), BUFFER_DISTANCE, map.getSpatialReference().getUnit());
// zoom to this buffered geometry
map.zoomTo(geometryForZoom);

Rotating the map

You can rotate the map by the desired angle in degrees using the setRotation method which takes an angle and, optionally, coordinates around which to rotate the map. If these coordinates are omitted, the map will rotate around the center point. The code snippet below will rotate the map by 45 degrees counter-clockwise:

double degreesToRotate = 45;
map.setRotation(degreesToRotate);

To give your users the ability to rotate the map using the mouse, you can use the navigator toolkit component, as discussed above.

Setting the scale

You can use the API to set your map to a particular scale anytime after your map control is usable (after the mapReady event has fired). For example the code snippet below will set the map to a 1:100000 scale:

// set scale to 1:100000
double scale = 100000;
map.setScale(scale);

You can also use the zoomToScale method with an optional parameter to zoom around a Point. The zoomToScale method will perform an animated zoom to a scale if animation is turned on in your map, and the setScale method will not animate the change of scale.

Sample code

For working samples using many of the navigation methods in the API, have a look at the ArcGIS Runtime for Java sample application which is installed with the SDK. Relevant samples will mainly be under the Mapping > Map table of contents heading.

2/7/2013