Interact with the map

The map control (JMap) comes with built-in responses to mouse actions, such as panning when a user clicks and drags the mouse and zooming in or out in response to mouse wheel rolls. When you're developing a mapping application, it's likely that in addition to the map control's built-in responses, you'll want to add your own custom responses to mouse input. For example, you may want to:

  • Highlight and select features on the map when a user clicks a feature
  • Enable users to draw graphics on the map using the mouse
  • Show information about a particular feature when a user clicks on it

You can implement all of these behaviors using map overlays.

Map overlays

Map overlays are the API's mechanism to enable you to program custom map interaction into an app or draw custom components or images onto the map. You can create a map overlay by extending the MapOverlay class and overriding the appropriate methods to achieve the desired behavior. For example, override the onMouseClicked method to respond to mouse clicks, or override the onPaint method to show a custom image or component on the map each time the map is "painted" (that is, rendered on screen).

You can also use the overlays provided in the SDK's toolkit. The source code to all the toolkit classes is provided, so these overlays can be used out-of-the-box or as a starting point for you to build your own map overlays. The toolkit includes overlays to accomplish the following:

  • Draw a scale bar onto the map
  • Add a navigator component to the map
  • Draw graphics on the map using mouse clicks
  • Show a pop-up window when the user clicks a feature.
  • Enable users to zoom to an extent by drawing a zoom box onto the map
Additional map overlays are provided in the toolkit for you to use or modify.

Map overlays are added to a JMap instance and can be activated or deactivated. When multiple overlays are added to a JMap, they form a stack such that the last overlay added will be the first to capture the mouse input, and so on, with the map itself and its built-in map interaction at the bottom of the stack. Each time you override a MapOverlay method, you can choose whether or not to pass on the mouse event to the next overlay in the stack (or the JMap itself if there is only one overlay). Thus, you can also use map overlays to block the map's built-in mouse interaction.

Create a map overlay

Follow these steps to create your own map overlay:

  1. Create a class that extends the MapOverlay class:
    public class MyOverlay extends MapOverlay {
     
    }
  2. Decide which methods to override according to what mouse event you want to handle. If you're using the eclipse IDE, you can hover over your class name (MyOverlay in the code snippet above), right-click and choose Source > Override/Implement Methods, and then in the dialog box that appears, choose the MapOverlay methods you want to override to get method stubs for each.

    For example, the following code sample is the result of selecting the onMouseMoved and onMouseClicked methods to override:

    public class MyOverlay extends MapOverlay {
     
      @Override
      public void onMouseMoved(MouseEvent event) {
            // TODO Auto-generated method stub
        super.onMouseMoved(event);
      }
     
      @Override
      public void onMouseClicked(MouseEvent event) {
            // TODO Auto-generated method stub
        super.onMouseClicked(event);
      }
    }

  3. Fill in the method code as appropriate with how you want to handle the particular mouse event, or how you want to perform custom painting in the case of overriding the onPaint method. For each of the mouse event handling methods, calling the superclass method of the same name will pass the mouse event on to the overlay below it in the map. If you choose not to call the superclass method, the mouse event will not be handled by any other overlay or the map itself, and that type of mouse input will effectively be blocked at your overlay.

    The following code sample shows the custom overlay passing on mouse clicked events, but not passing on mouse dragged events:

    public class MyOverlay extends MapOverlay {
     
      @Override
      public void onMouseClicked(MouseEvent event) {
        // take some action when the mouse is clicked
        customResponseToMouseClick(event);
        // then pass the event onto the next component in the stack, either the map itself or another map overlay
        super.onMouseMoved(event);
      }
    
      @Override
      public void onMouseDragged(MouseEvent event) {
        // take some action when the mouse is dragged
        System.out.println("Dragging, but the event is not passed to the map so you can't pan any more!");
        // don't pass the event on - mouse clicks will only do what is in this method
      }
    }

  4. Create an instance of your overlay and add it to the map using JMap's addMapOverlay method:
    MyOverlay overlay = new MyOverlay();
    jMap.addMapOverlay(overlay);
  5. The overlay is active by default, but often you want to control when to start and stop capturing mouse input via your overlay (or when to draw onto the map), so you may want to deactivate your overlay right after you've added it to your map. You can then activate it when the user takes some action such as clicking a toolbar button. The following code sample shows code to toggle the activation of your overlay and could go in a button handler:
    // check whether overlay is active
    if (overlay.isActive()) {
      // if so, deactivate it
      overlay.setActive(false);
    } else {
      // overlay is not active: activate it
      overlay.setActive(true);
    };

You now have a working map overlay which, when active, responds to mouse events or performs custom painting on the JMap.

For complete code examples of map overlays, see the SDK's toolkit source code, particularly the com.esri.toolkit.overlays package. For code examples of overlays being used by an app, browse the interactive sample app installed with the SDK.