| 61 | | 2. Either |
| 62 | | a. Import the JOSM project to the same workspace and add it as a required project on the build path (your extension -> Properties -> Java Build Path -> Projects -> Add). Or |
| 63 | | b. Open your project properties to add required libraries (Properties -> Java Build Path -> Libraries -> Add External JARs). You must at least add `josm/core/dist/josm-custom.jar`, but you may also add your plugin dependencies if any (for instance `josm/dist/utilsplugin2.jar`). |
| 64 | | 3. Make sure the plugin is added to the `plugins` list in the [wiki:/Help/Preferences/Advanced Advanced preferences] in JOSM and copy any version of your extension to the plugin directory (essentially, only the entry point is relevant here, so `plugin.class` has to be set correctly). |
| 65 | | 4. Create a `Run Configuration` (Properties -> Run/Debug Settings -> New -> Java Application). Main class must be set to `org.openstreetmap.josm.gui.MainApplication`. |
| 66 | | 5. You can now tweak your plugin and/or set breakpoints… etc. |
| | 59 | 1. Either |
| | 60 | a. Import the JOSM project to the same workspace and add it as a required project on the build path (your extension -> Properties -> Java Build Path -> Projects -> Add). Or |
| | 61 | a. Open your project properties to add required libraries (Properties -> Java Build Path -> Libraries -> Add External JARs). You must at least add `josm/core/dist/josm-custom.jar`, but you may also add your plugin dependencies if any (for instance `josm/dist/utilsplugin2.jar`). |
| | 62 | 1. Make sure the plugin is added to the `plugins` list in the [wiki:/Help/Preferences/Advanced Advanced preferences] in JOSM and copy any version of your extension to the plugin directory (essentially, only the entry point is relevant here, so `plugin.class` has to be set correctly). |
| | 63 | 1. Create a `Run Configuration` (Properties -> Run/Debug Settings -> New -> Java Application). Main class must be set to `org.openstreetmap.josm.gui.MainApplication`. |
| | 64 | 1. You can now tweak your plugin and/or set breakpoints… etc. |
| 144 | | * {{{public void mapFrameInitialized(MapFrame old, MapFrame new)}}} |
| 145 | | |
| 146 | | JOSM manages at most one [source:/trunk/src/org/openstreetmap/josm/gui/MapFrame.java MapFrame]. At startup, when JOSM displays the Message of the Day (MOTD) panel, the MapFrame is null. It is only created when the first [source:/trunk/src/org/openstreetmap/josm/gui/layer/Layer.java Layer] is added and it is removed and reset to null if the last layer is removed. Plugins implementing a method {{{mapFrameInitialized}}} are notified about the change of the current map frame. |
| | 140 | * {{{public void mapFrameInitialized(MapFrame old, MapFrame new)}}} \\ |
| | 141 | JOSM manages at most one [source:/trunk/src/org/openstreetmap/josm/gui/MapFrame.java MapFrame]. At startup, when JOSM displays the Message of the Day (MOTD) panel, the MapFrame is null. It is only created when the first [source:/trunk/src/org/openstreetmap/josm/gui/layer/Layer.java Layer] is added and it is removed and reset to null if the last layer is removed. Plugins implementing a method {{{mapFrameInitialized}}} are notified about the change of the current map frame. |
| 148 | | * {{{public PreferenceSetting getPreferenceSetting()}}} |
| 149 | | |
| 150 | | The [source:/trunk/src/org/openstreetmap/josm/gui/preferences/PreferenceDialog.java JOSM preference dialog] asks a plugin to supply an editor for its preferences. The editor must implement [source:/trunk/src/org/openstreetmap/josm/gui/preferences/PreferenceSetting.java PreferenceSetting]. Return null from {{{getPreferenceSetting}}} or don't implement it if your plugin has no need to manage preferences. |
| 151 | | |
| 152 | | You have basically two choices to implement your preferences editor. The first one is to provide a preferences editor with its own toolbar button in the preferences dialog. To do this, the editor must implement [source:/trunk/src/org/openstreetmap/josm/gui/preferences/TabPreferenceSetting.java TabPreferenceSetting]. The class [source:/trunk/src/org/openstreetmap/josm/gui/preferences/DefaultTabPreferenceSetting.java DefaultTabPreferenceSetting] may help you to achieve this. Alternatively, the editor may plug itself as an additional tab of an existing editor (for example, Display settings). To do this, the editor must implement [source:/trunk/src/org/openstreetmap/josm/gui/preferences/SubPreferenceSetting.java SubPreferenceSetting]. |
| 153 | | |
| 154 | | * {{{public void addDownloadSelection(List<DownloadSelection> list)}}} |
| 155 | | |
| 156 | | The [source:/trunk/src/org/openstreetmap/josm/gui/download/DownloadDialog.java JOSM download dialog] asks a plugin to supply its own download method when the download dialog is created. The plugin must supply an object implementing [source:/trunk/src/org/openstreetmap/josm/gui/download/DownloadSelection.java DownloadSelection]. The download dialog also invokes {{{addGui(DownloadDialog gui)}}} on the supplied [source:/trunk/src/org/openstreetmap/josm/gui/download/DownloadSelection.java DownloadSelection] which gives you the chance to create an UI component (i.e. a JPanel) JOSM adds to the tabbed pane in the download dialog. Reply the unmodified {{{list}}} or don't implement the method if your plugin doesn't provide its own download method. Plugins shouldn't remove and or reorder elements in {{{list}}}. |
| 157 | | |
| 158 | | |
| | 143 | * {{{public PreferenceSetting getPreferenceSetting()}}} \\ |
| | 144 | The [source:/trunk/src/org/openstreetmap/josm/gui/preferences/PreferenceDialog.java JOSM preference dialog] asks a plugin to supply an editor for its preferences. The editor must implement [source:/trunk/src/org/openstreetmap/josm/gui/preferences/PreferenceSetting.java PreferenceSetting]. Return null from {{{getPreferenceSetting}}} or don't implement it if your plugin has no need to manage preferences. |
| | 145 | |
| | 146 | You have basically two choices to implement your preferences editor. The first one is to provide a preferences editor with its own toolbar button in the preferences dialog. To do this, the editor must implement [source:/trunk/src/org/openstreetmap/josm/gui/preferences/TabPreferenceSetting.java TabPreferenceSetting]. The class [source:/trunk/src/org/openstreetmap/josm/gui/preferences/DefaultTabPreferenceSetting.java DefaultTabPreferenceSetting] may help you to achieve this. Alternatively, the editor may plug itself as an additional tab of an existing editor (for example, Display settings). To do this, the editor must implement [source:/trunk/src/org/openstreetmap/josm/gui/preferences/SubPreferenceSetting.java SubPreferenceSetting]. |
| | 147 | |
| | 148 | * {{{public void addDownloadSelection(List<DownloadSelection> list)}}} \\ |
| | 149 | The [source:/trunk/src/org/openstreetmap/josm/gui/download/DownloadDialog.java JOSM download dialog] asks a plugin to supply its own download method when the download dialog is created. The plugin must supply an object implementing [source:/trunk/src/org/openstreetmap/josm/gui/download/DownloadSelection.java DownloadSelection]. The download dialog also invokes {{{addGui(DownloadDialog gui)}}} on the supplied [source:/trunk/src/org/openstreetmap/josm/gui/download/DownloadSelection.java DownloadSelection] which gives you the chance to create an UI component (i.e. a JPanel) JOSM adds to the tabbed pane in the download dialog. Reply the unmodified {{{list}}} or don't implement the method if your plugin doesn't provide its own download method. Plugins shouldn't remove and or reorder elements in {{{list}}}. |
| | 150 | |
| 176 | | * '''layer change events''' |
| 177 | | |
| 178 | | Implement a [source:/trunk/src/org/openstreetmap/josm/gui/layer/LayerManager.java LayerChangeListener] and register it using [source:/trunk/src/org/openstreetmap/josm/gui/layer/LayerManager.java#L33 Main.getLayerManager().addLayerChangeListener(LayerChangeListener listener)]. JOSM will then notify you about added, removed, and renamed layers. You may only or also register an [source:/trunk/src/org/openstreetmap/josm/gui/layer/LayerManager.java org.openstreetmap.josm.gui.MapView.ActiveLayerChangeListener] in which case JOSM will notify the plugin about changes in the current edit layer, in particular whether there is or there isn't a current edit layer. |
| 179 | | |
| 180 | | * '''selection change listener''' |
| 181 | | |
| 182 | | If your plugin needs to respond to changes in the currently selected set of OSM objects it can implement a [source:/trunk/src/org/openstreetmap/josm/data/SelectionChangedListener.java org.openstreetmap.josm.data.SelectionChangedListener] and add it to the global list {{{org.openstreetmap.josm.data.osm.DataSet.selListeners}}}. |
| 183 | | |
| 184 | | * '''data change events''' |
| 185 | | |
| 186 | | If your plugin needs to respond to changes in the data managed by [source:/trunk/src/org/openstreetmap/josm/layer/OsmDataLayer.java org.openstreetmap.josm.layer.OsmDataLayer]s it can implement a [source:/trunk/src/org/openstreetmap/josm/data/osm/event/DataSetListener.java org.openstreetmap.josm.data.osm.event.DataSetListener] and register it on the data set of an OsmDataLayer using {{{layer.ds.addDataSetListener(yourlistener)}}}. JOSM will notify the listener about added, modified, and deleted objects in the dataset. |
| 187 | | |
| 188 | | Make sure your plugin also unregisters as data set listener when the respective OsmDataLayer is deleted. Listen to layer change events to and respond to layer deleted events. |
| 189 | | |
| 190 | | * ''' preference change listener''' |
| 191 | | If your plugin needs to respond to general changes in the JOSM preferences it can implement a [source:/trunk/src/org/openstreetmap/josm/data/Preferences.java org.openstreetmap.josm.data.Preferences.PreferenceChangedListener]. Invoke {{{addPreferenceChangedListener(PreferenceChangedListener listener)}}} on {{{Main.pref}}}. You are encouraged to use a property object like [source:/trunk/src/org/openstreetmap/josm/data/preferences/IntegerProperty.java IntegerProperty] to access preferences. You can register a listener to that single preference there. |
| | 168 | * '''layer change events''' \\ |
| | 169 | Implement a [source:/trunk/src/org/openstreetmap/josm/gui/layer/LayerManager.java LayerChangeListener] and register it using [source:/trunk/src/org/openstreetmap/josm/gui/layer/LayerManager.java#L33 Main.getLayerManager().addLayerChangeListener(LayerChangeListener listener)]. JOSM will then notify you about added, removed, and renamed layers. You may only or also register an [source:/trunk/src/org/openstreetmap/josm/gui/layer/LayerManager.java org.openstreetmap.josm.gui.MapView.ActiveLayerChangeListener] in which case JOSM will notify the plugin about changes in the current edit layer, in particular whether there is or there isn't a current edit layer. |
| | 170 | |
| | 171 | * '''selection change listener''' \\ |
| | 172 | If your plugin needs to respond to changes in the currently selected set of OSM objects it can implement a [source:/trunk/src/org/openstreetmap/josm/data/SelectionChangedListener.java org.openstreetmap.josm.data.SelectionChangedListener] and add it to the global list {{{org.openstreetmap.josm.data.osm.DataSet.selListeners}}}. |
| | 173 | |
| | 174 | * '''data change events''' \\ |
| | 175 | If your plugin needs to respond to changes in the data managed by [source:/trunk/src/org/openstreetmap/josm/gui/layer/OsmDataLayer.java org.openstreetmap.josm.layer.OsmDataLayer]s it can implement a [source:/trunk/src/org/openstreetmap/josm/data/osm/event/DataSetListener.java org.openstreetmap.josm.data.osm.event.DataSetListener] and register it on the data set of an OsmDataLayer using {{{layer.ds.addDataSetListener(yourlistener)}}}. JOSM will notify the listener about added, modified, and deleted objects in the dataset. |
| | 176 | |
| | 177 | Make sure your plugin also unregisters as data set listener when the respective OsmDataLayer is deleted. Listen to layer change events to and respond to layer deleted events. |
| | 178 | |
| | 179 | * ''' preference change listener''' \\ |
| | 180 | If your plugin needs to respond to general changes in the JOSM preferences it can implement a [source:/trunk/src/org/openstreetmap/josm/data/Preferences.java org.openstreetmap.josm.data.Preferences.PreferenceChangedListener]. Invoke {{{addPreferenceChangedListener(PreferenceChangedListener listener)}}} on {{{Main.pref}}}. You are encouraged to use a property object like [source:/trunk/src/org/openstreetmap/josm/data/preferences/IntegerProperty.java IntegerProperty] to access preferences. You can register a listener to that single preference there. |
| 202 | | * the required java classes, including any additional libraries the plugin requires |
| 203 | | * icons (.png or .svg, .svg is preferred), deployed data files, and other resources |
| 204 | | * a manifest file with JOSM specific entries (see below) |
| | 191 | * the required java classes, including any additional libraries the plugin requires |
| | 192 | * icons (.png or .svg, .svg is preferred), deployed data files, and other resources |
| | 193 | * a manifest file with JOSM specific entries (see below) |
| 226 | | ||'''<xxx>_Plugin-Url'''||optional||To support older JOSM versions, special entries may be added to supply older, compatible, versions of the plugin. For plugins maintained in the main plugin subversion repository, this is usually not necessary, since the JOSM server keeps track of compatible versions, when the '''Plugin-Mainversion''' is updated (see section '''Publishing the new plugin''' below). It ''is'' however useful, when the plugin is hosted on a different server, but still available as convenient download from within JOSM. [[br]]This information will then be used by the internal plugin handler to download a matching plugin version both for the first download and on update. There can be multiple '''<xxx>_Plugin-Url''' entries, the format is ''<josm_version>_Plugin-Url: <plugin_version>;<url>''. Here, ''<josm_version>'' denotes the lowest JOSM version, the plugin ''<plugin_version>'' will work with and it can be downloaded using ''<url>''. || |
| | 215 | ||'''<xxx>_Plugin-Url'''||optional||To support older JOSM versions, special entries may be added to supply older, compatible, versions of the plugin. For plugins maintained in the main plugin subversion repository, this is usually not necessary, since the JOSM server keeps track of compatible versions, when the '''Plugin-Mainversion''' is updated (see section '''Publishing the new plugin''' below). It ''is'' however useful, when the plugin is hosted on a different server, but still available as convenient download from within JOSM. \\ This information will then be used by the internal plugin handler to download a matching plugin version both for the first download and on update. There can be multiple '''<xxx>_Plugin-Url''' entries, the format is ''<josm_version>_Plugin-Url: <plugin_version>;<url>''. Here, ''<josm_version>'' denotes the lowest JOSM version, the plugin ''<plugin_version>'' will work with and it can be downloaded using ''<url>''. || |
| 283 | | 1. Did you change something which will not work with every JOSM version? Then you should update '''Plugin-Mainversion''' in {{{build.xml}}} |
| 284 | | * look for the line {{{<attribute name="Plugin-Mainversion" value="..."/>}}} |
| 285 | | * replace the value by the lowest JOSM version required for the plugin after you've applied your fix [[BR]]Do not increase '''Plugin-Mainversion''' if not necessary, though. If you do, JOSM ''requires'' users to update to the new version, otherwise users can ''choose'' whether they want to upgrade. {{{Plugin-Mainversion}}} should always consist of the ''lowest possible revision''. |
| 286 | | 1. commit the new modified source |
| 287 | | 1. '''counter intuitive, but important - update again from the SVN''' - after having commited you '''must''' update the source again from the SVN. This ensures that {{{Plugin-Version}}} in the plugin {{{MANIFEST}}} will reflect the plugins SVN revision number |
| 288 | | 1. build the plugin using {{{ant clean}}} and {{{ant dist}}}. This creates the plugin jar file in the {{{/dist}}} directory. |
| 289 | | 1. commit the {{{.jar}}} file in the {{{dist}}} directory |
| | 271 | 1. Did you change something which will not work with every JOSM version? Then you should update '''Plugin-Mainversion''' in {{{build.xml}}} |
| | 272 | * look for the line {{{<attribute name="Plugin-Mainversion" value="..."/>}}} |
| | 273 | * replace the value by the lowest JOSM version required for the plugin after you've applied your fix \\ Do not increase '''Plugin-Mainversion''' if not necessary, though. If you do, JOSM ''requires'' users to update to the new version, otherwise users can ''choose'' whether they want to upgrade. {{{Plugin-Mainversion}}} should always consist of the ''lowest possible revision''. |
| | 274 | 1. commit the new modified source |
| | 275 | 1. '''counter intuitive, but important - update again from the SVN''' - after having commited you '''must''' update the source again from the SVN. This ensures that {{{Plugin-Version}}} in the plugin {{{MANIFEST}}} will reflect the plugins SVN revision number |
| | 276 | 1. build the plugin using {{{ant clean}}} and {{{ant dist}}}. This creates the plugin jar file in the {{{/dist}}} directory. |
| | 277 | 1. commit the {{{.jar}}} file in the {{{dist}}} directory |
