Context Navigation

Editing DevelopersGuide/DevelopingPlugins

Adjust edit area height: Edit side-by-side

This page gives a short introduction for developers how to create, deploy and develop plugins for JOSM.
Any Questions left? Ask [mailto:immanuel.scholz@gmx.de Imi].

[[PageOutline]]

= 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 have the always latest callback function signatures (see below) as hint 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.

= Some tips about the JOSM object tree or ''What us 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 to few so-called ''singleton-factories'' that become popular in the past years in JOSM. 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 programms).''

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 immediatly 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 holdes 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''

Note: See WikiFormatting and TracWiki for help on editing wiki content.

Change information

Your email or username:

E-mail address and name can be saved in the Preferences

Comment about this change (optional):

Note: See TracWiki for help on using the wiki.