How to use the Roam tool

Summary
This topic shows how to use the out-of-the box Roam tool with ArcGIS Engine controls.

Using the Roam tool

When the ControlsMapRoamTool is set as the current tool, the end user can pan the display of the MapControl or PageLayoutControl by moving the tool in any direction to pan.
To successfully use the ControlsMapRoamTool on a ToolbarControl buddied to a MapControl or PageLayoutControl, the tool requires the DynamicMap property of the map object to be enabled. If the DynamicMap property is not enabled, the tool will be disabled. Hence, to enable the DynamicMap property, invoke the Map.setDynamicMapEnabled() method with a Boolean true value as its argument. 
The DynamicMap property is related to the current map document contained in the MapControl; therefore, enable it only after a map document is loaded onto the MapControl and it is visible in the application. It is a reasonable assumption to enable the DynamicMap property after the JFrame.setVisible() method, but it is possible that the map document might not have been completely loaded at that point. An automation exception will be encountered in these scenarios. 
To avoid an automation exception, call the Map.setDynamicMapEnabled() method after the map document becomes visible in a MapControl, for example, clicking a button or a custom command.
The following code example creates a button and on its click event, enables the Roam tool:
[Java] 
// Step 1: Create a variable of map.

MapBean mapBean = getMapBean();
final Map map = (Map)mapBean.getMap();


//Step 2: Create a button to enable dynamic mode on the onClick event.
JButton enableDynamicMode = new JButton();

//Step 3: Set the map into dynamic mode when the Swing button is clicked.
enableDynamicMode.addActionListener(new ActionListener(){
    public void actionPerformed(ActionEvent e){
        try{
            if (!map.isDynamicMapEnabled()){
                map.setDynamicMapEnabled(true); 
            }
        }
        catch (Exception ex){
            ex.printStackTrace(); 
        }
    }
}

    ;

// Step 4: Initialize the ToolbarBean and add the Roam tool.

private ToolbarBean getToolbarBean(){
    if (toolbarBean == null){
        try{
            toolbarBean = new ToolbarBean();
            //Set the MapBean as its buddy control.
            toolbarBean.setBuddyControl(getMapBean());
            //Add the Roam tool to the toolbar.
            toolbarBean.addItem(ControlsMapRoamTool.getClsid(), 0,  - 1, false, 0,
                esriCommandStyles.esriCommandStyleIconAndText);
        }
        catch (Exception e){
            e.printStackTrace();
        }
    }
    return toolbarBean;
}

//Step 5: Initialize MapBean.

private MapBean getMapBean(){
    if (mapBean == null){
        try{
            mapBean = new MapBean();
        }
        catch (Exception ex){
            e.printStackTrace();
        }
    }
    return mapBean;
}
When using the Roam tool, the map display can pause while caching the data that displays.


See Also:

ControlsMapRoamTool
How to use Flicker and NearbyPlaces command
How to use Swipe tool and Transparency commands



Development licensingDeployment licensing
Engine Developer KitEngine
ArcGIS for Desktop Basic
ArcGIS for Desktop Standard
ArcGIS for Desktop Advanced