We have been able to make the following plug-in tutorial available:

The tutorial is in the form of a Adobe PDF file and has been converted to confluence.
This tutorial was also coverted in the uDig presentation at OSG'05.

Distance Tool Tutorial

Create your first uDig plug-in! (Featured at OSG'05 conference)

This example only works with the uDig 1.1.x branch and later. If you are developing against uDig 1.0.x follow the instructions in this document

Goals

After completing this tutorial, you will have gained the skills to:

  • Create a new Plugin
  • Define a new Extension
  • Implement a new Tool Extension
  • Update the user interface from within a tool

Create a New Plugin

  1. Open the Plug-in Development perspective (click on )
  2. From the File menu, select New > Project…. Select Plug-in Project from the dialog, and then click the Next button.

    Figure 1 - New Plug-in Project
  3. Create a name for the plug-in by entering net.refractions.udig.tutorials.distancetool in the Project Name text field and click the Next button.

    Figure 2 - Naming the New Plug-in
  4. Accept the default values used to generate the plug-in and click the Finish button.

    Figure 3 - New Plug-in Details
    At this point the feature editor plug-in is created. Configuring the plug-in is the focus of the next section.

Configuring Your New Plug-in

In this section you will configure the feature editor plug-in. Specifically, you will specify dependencies on other plug-ins in order to create a new feature editor.

  1. Open the Plug-in Development perspective.
  2. In the Package Explorer navigate to the plug-in created in the previous section. Open the plug-in manifest by navigating to the META-INF/MANIFEST.MF file under the root of the feature editor plug-in. Double click on the file to open the plug-in manifest editor.

    Figure 4 - Plug-in Manifest Editor
  3. Open the plug-in dependencies by clicking on the Dependencies tab located at the bottom of the editor area.
  4. Click the Add… button in the Required plugins column and add the following plugin:
    net.refractions.udig.project.ui

    Figure 5 - Add New Plugin Dependencies
  5. At this point it is critical that you Save your work as the dependencies need to propagate into the project.

    Figure 6 - Plug-in Dependencies

Import Resources Into Project

In this section we are going to set up an icon directory and import the pictures we will use for our measure tool.

  1. Download measure_source.gif and measure_mode.gif to your desktop (Right click and Save Link As...)
  2. Select your plug-in project, net.refractions.udig.tutorials.distancetool, in the Package Explorer.
  3. Select File → New → Folder from the Menubar.
  4. Enter icons/etool16 as the folder name.
  5. Click the Finish button.
  6. Select icons directory.
  7. Select File → New → Folder from the Menubar.
  8. Enter pointers as the folder name.
  9. Click the Finish button.
  10. Right click on etool16 and select Import.
  11. Select File System.
  12. Click on browse and choose Desktop from the list (this will populate the directory field).
  13. Select the measure_mode.gif file and press Finish.
  14. Import the measure_source.gif file into the pointers directory following the same steps.

Define a New Extension

  1. Open the extensions page by clicking on the Extensions tab
  2. Click the Add… button
  3. Select the net.refractions.udig.project.ui.tool extension point from the list.
  4. Click the Finish button.
  5. Enter the following Extension Details:
    • ID: net.refractions.udig.tutorial.distancetool
    • Name: Distance Tool Example

Create a New Tool

  1. Right click on newly added extension, net.refractions.udig.project.ui.tool, and select New > modalTool
  2. Replace the default data in the id field with net.refractions.udig.tutorial.distancetool.
  3. Enter a tool tip message into the tooltip field: Measure the surface distance between two points
  4. Enter net.refractions.udig.tutorial.distancetool.DistanceTool into the class field.
  5. Enter icons/etool16/measure_mode.gif into the icon field.
    (Or press the Browse button and locate the icon)
  6. Enter Distance into the name field.
  7. Set onToolbar to true.
  8. Enter net.refractions.udig.tool.category.info into the categoryId field.

Providing a Cursor

  1. Right click on net.refractions.udig.tutorial.distancetool (modalTool) and select New > cursor.
  2. Enter icons/pointers/measure_source.gif in the image field.
    Or press the browse button and find the pointer icon.
  3. Enter 10 in the hotSpotX field.
  4. Enter 10 in the hotSpotY field.
  5. Save your work before proceeding to the next section.
Optional

This file contains the plugin you are creating at this stage of development:
plugin.zip

You can compare the work you have done with the plugin provided if you are having problems.

Implementing a Modal Tool

  1. Select net.refractions.udig.tutorial.distancetool (modalTool) in the Extensions editor.
  2. It is a child of the net.refractions.udig.project.ui.tool.
  3. Click the class hotlink.
  4. A dialog is brought up describing the class to be created, Check Generate comments.
  5. Press Finish, if not available ensure that all the information is in agreement with the picture above.
  6. Right click on editor and select * Source > Override/Implement Methods*
  7. Expand SimpleTool node and check the following:
    • Check onMousePressed(MapMouseEvent)
    • Check onMouseReleased(MapMouseEvent)
  8. Click the OK button.
  9. Implement the onMousePressed(MapMouseEvent) method.
    Coordinate start; // records where in the world the user clicked
    public void onMousePressed(MapMouseEvent e) {
    	start=getContext().pixelToWorld(e.x, e.y);
    }
  10. Implement the onMouseReleased(MapMouseEvent) method.
    public void onMouseReleased(MapMouseEvent e) {
    	Coordinate end=getContext().pixelToWorld(e.x, e.y);
    	try {
    		double distance=JTS.orthodromicDistance(
                  start, end,
                  getContext().getCRS() );
    		displayOnStatusBar(distance);
    	} catch (Exception e1) {
    	}
    }
  11. Implement the displayError () method.
    private void displayError() {
    	final IStatusLineManager statusBar =
                  getContext().getActionBars().getStatusLineManager ();
    
    	if( statusBar==null )
    		return; // shouldn't happen if the tool is being used.
    	
    	getContext().updateUI(new Runnable() {
    		public void run() {
    			statusBar.setErrorMessage("Unable to calculate the distance");
    	        }
    	});
      }
  12. Implement the displayOnStatusBar(double) method.
    private void displayOnStatusBar(double distance) {
        final IStatusLineManager statusBar =
            getContext().getActionBars().getStatusLineManager ();
    
        if( statusBar==null )
    		return; // shouldn't happen if the tool is being used.
    	int totalmeters=(int)distance;
    	final int km=totalmeters/1000;
    	final int meters=totalmeters-(km*1000);
    	float cm = (float) (distance-totalmeters)*10000;
    	cm = Math.round(cm);
    	final float finalcm=cm/100;
    	getContext().updateUI(new Runnable(){
                    public void run() {
    			statusBar.setMessage("Distance =  "+km+","+meters+"m "+finalcm+"cm");
    		}		
    	});
    }
  13. At this point you may have red x's on the project - Lets fix them!
    1. Press Ctrl+Shift+0 to import any needed classes
    2. GeoTools contains two classes called JTS (they are moving the class to a more appropriate home), please choose org.geotools.geometry.jts.JTS:
    3. And then save the file. This should refresh the project and clear up any error markers left behind.
Optional

You may check your work against the completed plugin code available here:
completeplugin.zip archive file.

Testing The Plug-in

  1. From the Project menu select Run and choose the configuration you set-up in the previous tutorial (see 0 SDK Quickstart).
  2. When uDig launches make a new map and your Distance tool should now be in the tool bar ready for use.
    1. File -> New Map
    2. Drag and Drop a Web Map Server url onto the screen:
    3. Select the Distance Tool and drag from one point to another in the Map View and the distance should display in the bottom left corner.

Common Problems

Q: Unable to calculate the distance!
A: The projection of your data must be defined, you may see this if you are working with a shapefile that does not have a ".prj" file defined.

Q: A connection error has occured
A: Sounds like the data you were looking for is unavailable, try a different WMS.

Did you Know?

  • Tools are organized into "Categories" each with their own keyboard short-cut, the Distance Tool is in the category "Information".
  • You can select the "Information" category by pressing "i" while working with the Map, you can cycle between the different information tools by pressing "i" additional times.

1NewProject.png (image/png)
1NewProject.png (image/png)
2NewPluginProject.png (image/png)
3NewPluginContent.png (image/png)
4PluginManifest.png (image/png)
4PluginManifest.png (image/png)
5PluginDependencies.png (image/png)
5PluginDependencies.png (image/png)
6AddDependencies.png (image/png)
6AddDependencies.png (image/png)
measure_mode.gif (image/gif)
measure_source.gif (image/gif)
7NewFolder.png (image/png)
8Import.png (image/png)
9ImportToolIcon.png (image/png)
11NewExtention.png (image/png)
11NewExtention.png (image/png)
12ExtentionDetails.png (image/png)
12ExtentionDetails.png (image/png)
0Prespective.gif (image/gif)
save.gif (image/gif)
10Extention.png (image/png)
13CompleteModalToolDefinition.png (image/png)
14ToolCursorDefinition.png (image/png)
plugin.zip (application/zip)
15NewClassWizard.png (image/png)
15NewClassWizard.png (image/png)
15NewClassWizard.png (image/png)
16OverrideMethodDialog.png (image/png)
16OverrideMethodDialog.png (image/png)
completeplugin.zip (application/zip)
15ClassLabel.png (image/png)
JTSImport.png (image/png)
[view] [edit]
(c) Copyright (c) 2004,2005 Refractions Research Inc. and others.