This page gives a short introduction for developers how to create, deploy and develop plugins for JOSM. Any Questions left? Ask Imi.

Setting up the environment

• Get the complete osm - trunk from ​http://svn.openstreetmap.org. This checks out everything into a directory called osm

  svn co http://svn.openstreetmap.org osm
  

• create a new plugin-directory osm/utils/josm/plugins/yourpluginname
• copy an ant script (build.xml) from an other plugin (TODO: Someone familar with ant could be so nice and setup a template plugin with an almost complete configured ant script and then change this here)
• The important thing of your build script is, that it places two attributes into the MANIFEST.MF of the jar file:
  • Plugin-Class points to the main plugin file (see below)
  • Plugin-Description gives the description of the plugin visible in the preferences page. Currently, you have to enter some <br> (not <br/>) by yourself (blame Swing ;)

The Plugin class

After setting everything up, you need to create the plugin main class specified in the jar's manifest. The only prerequisite of this class is, that it must have an standard constructor taking no arguments. The constructor of the plugin class will be called during the JOSM startup if the plugin is registered. Here, you have full access to the object tree within JOSM.

It is recommended (but not required), that you subclass org.openstreetmap.josm.plugins.Plugin. This way you get some helper functions and always have the latest callback function signatures (see below) as hints in your baseclass to override them ;)

Callbacks

Most of your plugin work will probably be tweaking the JOSM object tree at startup time, but there are a few callbacks that get automatically called on every plugin.

mapFrameInitialized

This is called after the first data has been loaded and the mapFrame is initialized. Use this to change something on the new MapFrame (or more common: the MapView (THE map ;) behind the frame)- As example, you could add yourself as LayerChangeListener to newMapFrame.mapView (please don't forget to remove yourself from oldMapFrame, if newMapFrame is null). This way you can capture changes of the active layer or the addition/removal of layers.

getPreferenceSetting

This will be called to retrieve an creator for GUI elements for the preferences dialog. The return is an interface with two methods: one to add the GUI elements to the dialog and on that is called when the preferences dialog finishes with ok. Be sure not to write preferences in your GUI code, but remember settings and only write them in the ok() method.

Some tips about the JOSM object tree or What is where?

First some words about my style of accessing public variables. Most people find this annoying and bad coding style in Java. If this would be an enterprise project, where most of the code is glue code and had to work with objects in a generic way, I would agree with them. But as JOSM is not, I like to keep the classes as simple as possible, which includes, that I don't add standard getter/setter but make the variable public. Also, there are no or very few so-called singleton-factories in JOSM that became popular in the past years. I use to reference singleton objects as global statics. This is unusual but equivalent to having stuff like Dependency Injection or Factory Methods (except you want to make complex things like auto-distributing stuff as seen in some enterprise programs).

Most objects are accessible through the class org.openstreetmap.josm.Main. There are numerous entry points for various parts of JOSM here.

Main.parent

This is the parent of all GUI elements. Use this as first parameter to JOptionPane.show* if you want to popup a message.

Main.pref

This is the (ONLY!) access to the global preferences file, located in .josm/preferences. Use Main.pref.get(...) and Main.pref.put(...) to access the preferences. They will be saved immediately after an put, so don't put anything you dont want to have there ;).

Please, prefix custom plugin preferences with your plugin name.

Main.ds

The data layer. Since JOSM currently supports only one data layer, this holds the complete osm data in JOSM. In the future, here will be the currently active (selected layer) data set stored instead.

Main.proj

If you want to translate between Lat/Lon and East/North, use Main.proj.latlon2eastnorth and Main.proj.eastnorth2latlon.

Main.map.mapView

This is the GUI class of the map. You usually access this to call stuff like getCenter, getScale or zoomTo.

BEWARE: Main.map can be null, in which case no data is loaded yet.

Main.main.editLayer()

Call this to get the current OsmDataLayer. If there is no such layer, an empty will be created!

Plugin.getPluginDir()

If you subclass from the plugin class (see above), then you can call this function to retrieve your plugin directory where you can freely store/read data from. It is located at ~/.josm/plugins/youpluginname