Edit using the toolkit

There are a number of useful Swing JComponents available in the toolkit jar for building rich applications in Java quickly. For editing, the key UI components in the toolkit are the JEditToolsPicker, JTemplatePicker, and JAttachmentEditor. You can also use the API class PopupView to display a callout dialog to edit a feature. These components make programming quicker and easier, and they hide some of the low-level API details of editing features, editing attributes and tables, and editing feature attachments when building editing apps. These components are also showcased in ArcGIS Runtime SDK for Java sample apps with the key code snippets highlighted for you to cut and paste.

At version 10.2.3 of Runtime SDK for Java, a new API was introduced to edit features in offline geodatabases and (online) feature service tables. To help you quickly build applications using this new editing model and set of API classes, new toolkit packages and classes are provided. The new classes are in the com.esri.toolkit.* packages. Use these toolkit classes to edit features in GeodatabaseFeatureTables and GeodatabaseFeatureServiceTables, alonsgide a FeatureLayer to display the features.

The original toolkit classes are deprecated (com.esri.client.toolkit.* packages) but are supported for 10.2.3. Use these classes to edit features in ArcGISFeatureLayers or Local Server based services. For information on a specific toolkit class, see the class Javadoc in the toolkit jar. See the Editing topic for an overview of your editing options.

JEditToolsPicker

The JEditToolsPicker component provides all the editing tools you need to add, update, and delete features in a feature layer in your application, all within a single Swing component that you can add to your visual application. It's also designed to allow the user to edit all feature layers at the same time as well as individual layers in the map it is associated with.

JEditToolsPicker screen shot

From left to right, the tools are described as follows:

  • Select/Add features to the current selection set
  • Remove features from the selection
  • Clear the selection set
  • Delete selected feature or features
  • For linear or polygon features, edit the vertices (move, add, delete)

Individual layers can be chosen for editing using the Selected Layers radio button:

JEditToolsPicker Selected Layers screen shot

Based on the layer type chosen for editing, additional tools will appear on the toolbar. If the chosen layer is a point feature layer, it will appear as follows. The new tool shown below will add a point feature to the layer:

JEditToolsPicker Point screen shot

When a line or polygon layer is specified, the toolbar appears as follows:

JEditToolsPicker Polygon screen shot

In the application code, the JEditToolsPicker component is created by passing in a map that contains the feature layers to be edited:

// add edit tools picker
JEditToolsPicker editToolsPicker = new JEditToolsPicker(map);
jPanel.add(editToolsPicker, BorderLayout.NORTH);

JTemplatePicker

This class extends JList to provide a list for picking feature "types" from "feature templates" provided by the feature layer itself. Feature templates have properties that define all the information required to create a feature. That is, they specify the exact symbology to draw features when created and added to the map, and they specify the pre-determined schema of the feature and default attributes. Effective use of feature templates can help make your editing easier and more efficient.

Template Picker

In the example above, the map contains three feature layers. The first layer is called Markup Polygons and the feature service layer is configured to use a simple red fill symbol. The second layer is a point layer called Water Sampling Stations which only has one type of features in it, so uses a simple renderer to draw water sampling stations. The third layer is called Water Network Structures and has two types of structures drawn with a unique value renderer for each type: treatment plants, and enclosed storage facilities. So, instead of adding "feature elements" to the map, the editor is adding "treatment plants" or "water sampling stations" to the database, and they display with the correct symbology as they should. This greatly streamlines the editing process.

The templates come directly from the feature layers in the map. You can control properties on the JTemplatePicker such as the size of the icons in the template and visibility of the text for each feature type. The following code shows how to add a JTemplatePicker to the user interface of an editing application:

// create template picker
JTemplatePicker jPicker = new JTemplatePicker(map);
jPicker.setIconWidth(36);
jPicker.setIconHeight(36);
jPicker.setShowNames(true);
jPicker.setWatchMap(true);

// add template picker to a component, such as a JPanel also containing your map
jPanel.add(jMap, BorderLayout.CENTER);
jPanel.add(jPicker, BorderLayout.WEST);

A demonstration of the JTemplatePicker and the JEditToolsPicker working together in an editing app can be found in the ArcGIS Runtime SDK for Java samples installed with the SDK. Open the sample viewer application (for example, by searching for 'Runtime Java Samples' on your machine) and look for the Editing tools samples in the Editing section.

PopupView

The PopupView component can be used as a simple way to edit the tabular attributes of features.

The PopupView can be created in a number of ways, to edit or simply show the attribute names and values in a pop-up window. In the following example, you'll create a PopupView that will allow the user to type edits into the appropriate attribute fields. This view is created by calling the static createEditView method. It will display the attributes in a pop-up window entitled Edit Attributes with the values displayed from non-null fields in the featureLayer.

// for an ArcGISFeatureLayer
PopupView contentPanel = PopupView.createEditView("Edit Attributes", arcGISFeatureLayer);
// set layer and feature - edits take place on the layer
contentPanel.setGraphic(arcGISFeatureLayer, feature);

// for a FeatureLayer
PopupView contentPanel = PopupView.createEditView("Edit Attributes", featureLayer);
// set layer, geodatabase feature table, and feature - edits take place on the feature table
contentPanel.setFeature(featureLayer, (GeodatabaseFeatureTable) featureLayer.getFeatureTable(), feature);

Once you have the PopupView defined, use a PopupDialog component to display the PopupView in a callout dialog.

PopupDialog popup = jMap.createPopup(new JComponent[]{contentPanel}, feature);
popup.setVisible(true);

PopupDialog with PopupView displaying

The PopupView component uses a PopupViewListener to handle the Cancel and Save actions on the popup. The code to commit edits when Save is clicked is built in to the component, but you may want to take additional action, such as closing the popup dialog, or getting additional confirmation from the user. The example below asks the user whether they are done editing when they click the Save button, and if not the user can continue the editing session, but with their previous changes already commited.

contentPanel.addPopupViewListener(new PopupViewListener() {

  @Override
  public void commitEdit(PopupViewEvent popupViewEvent, Feature feature) { 
    int close = JOptionPane.showConfirmDialog(popup, "Finished editing?");
    // if the user chooses 'yes', close the popup dialog
    if (close == JOptionPane.YES_OPTION) {
      popup.close();
    }
  } 
 
  @Override 
  public void cancelEdit(PopupViewEvent popupViewEvent, Feature feature) {
    // close the popup dialog
    popup.close(); 
  } 
});

Optionally, you can set a callback on the PopupView component if you want to override the default behavior of the Zoom to button shown in the popup. This is shown in the following code snippet:

contentPanel.setZoomToGraphicCallback(new ZoomToGraphicCallback() {

  @Override
  public void zoomToGraphic(Feature feature) {
    // override the 'Zoom to' button behavior here
  }
});

To bring this together to make it work all work in your editing application, you can use a toolkit overlay called HitTestOverlay. This overlay uses a HitTestListener that sends back a list of "hit" features if there were any features within a specified number of pixels from where you clicked the map. One of these features can then be used to construct your pop-up dialog.

HitTestOverlay hitTestOverlay = new HitTestOverlay(featureLayer); 
hitTestOverlay.addHitTestListener(new HitTestListener() { 
  @Override 
  public void featureHit(HitTestEvent event) {
    HitTestOverlay overlay = event.getOverlay();
    // get first (top-most) graphic or feature hit by the mouse

    // cast to Graphic if using an ArcGISFeatureLayer
    Graphic hitGraphic = (Graphic) overlay.getHitFeatures().get(0);
    // cast to GeodatabaseFeature if using a FeatureLayer and GeodatabaseFeatureTable
    //GeodatabaseFeature hitFeature = (GeodatabaseFeature) overlay.getHitFeatures().get(0);

    // create and display popup as shown above
    PopupView contentPanel = PopupView.createEditView("Edit Attributes", featureLayer);
    ...

JAttachmentEditor

In some situations, you may want to associate a downloadable file with a feature, whether it's a photo, spreadsheet, or some other type of document. For example, you might want users to be able to click a feature representing a piece of real estate and see a link to a PDF file of the title deed. In the ArcGIS Runtime SDKs, an associated downloadable file like this is known as a feature attachment.

The JAttachmentEditor is a component in the toolkit that helps users add, update, view, and delete feature attachments. The JAttachmentEditor includes a list of current attachments, as well as an Add button that can be used to upload additional attachments. The JAttachmentEditor can be added to your Swing apps easily by constructing it with a map and feature layer. The code below shows how this is done when using a FeatureLayer:

// scroll pane for the attachment editor
JScrollPane scrollPane = new JScrollPane();

// create attachment editor using a FeatureLayer
attachmentEditor = new JAttachmentEditor(jMap, featureLayer);
scrollPane.setViewportView(attachmentEditor);

jPanel.add(scrollPane, BorderLayout.WEST);

To use feature attachments, attachments must be enabled on the source feature class. You can enable attachments for a feature class in ArcCatalog or in the Catalog window in ArcMap.