Navigate the map

This topic describes how to navigate the map at runtime with the mouse and keyboard, as well as the navigation methods that can be used at design time.

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 that are enabled on a JMap component by default:

Map actionMouse actionKey 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 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 screen shot of the navigator added to a map:

Navigator screen shot

The remainder of this topic describes how to perform navigation actions programmatically.

Set the initial extent

To control which area of your map displays when a user first loads your application, set the initial extent on your JMap instance. To construct an extent, you can create an Envelope instance from a point and a desired width and height, or from 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).

// create an initial extent (coordinates are in the map spatial reference's units)
Envelope initialExtent = new Envelope(-20042400, 856094, -2783530, 11716267);
// set the extent on the JMap
jMap.setExtent(initialExtent);
Note:

Since 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 (EDT). A call to SwingUtilities.invokeLater ensures this is the case if you are not sure whether you are on the EDT. For more information on threading in Swing, see the Java Concurrency in Swing tutorial.

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

Pan and zoom

In addition to the built-in panning in zooming via the mouse and keyboard, you can programmatically 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 following code snippet shows how to 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);

Rotate 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 following code snippet sets the map rotation to the position of 45 degrees counter-clockwise:

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

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

Set 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 following code snippet sets 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.

For interactive samples using many of the navigation methods in the API, see the ArcGIS Runtime for Java sample application that's installed with the SDK. Relevant samples are mainly under the Map table of contents heading.