001// License: GPL. For details, see LICENSE file. 002package org.openstreetmap.josm.gui.preferences.projection; 003 004import java.awt.event.ActionListener; 005import java.util.Collection; 006 007import javax.swing.JPanel; 008 009import org.openstreetmap.josm.data.projection.Projection; 010 011/** 012 * This class offers a choice of projections to the user. 013 * 014 * It can display a GUI panel, in order to select the parameters. 015 */ 016public interface ProjectionChoice { 017 018 /** 019 * Get a unique id for the projection choice. 020 * 021 * Will be used to save the user selection to the preference file. 022 * 023 * @return the string identifier 024 */ 025 String getId(); 026 027 /** 028 * Set the internal state to match the preferences. 029 * 030 * Will be called before getPreferencePanel and when the 031 * listener from getPreferencePanel is invoked. 032 * 033 * @param args preferences as a list of strings; may be null 034 * to reset everything. 035 */ 036 void setPreferences(Collection<String> args); 037 038 /** 039 * Get the projection that matches the internal state. 040 * @return the effective projection 041 */ 042 Projection getProjection(); 043 044 /** 045 * Generate and provide the GUI. 046 * 047 * It will be displayed to the user. Call the listener, when the user makes 048 * changes in the GUI, so the projection info in the top panel gets updated. 049 * 050 * @param listener listener for any change of preferences 051 * @return the GUI panel 052 */ 053 JPanel getPreferencePanel(ActionListener listener); 054 055 /** 056 * Extract preferences from the GUI. 057 * 058 * Will be called when the preference dialog is dismissed or 059 * when the listener from getPreferencePanel is invoked. 060 * @param panel projection preferences panel 061 * @return preferences as a list of strings; may be null to reset everything. 062 * @see #setPreferences 063 */ 064 Collection<String> getPreferences(JPanel panel); 065 066 /** 067 * Return all projection codes supported by this projection choice. 068 * @return all supported projection codes 069 */ 070 String[] allCodes(); 071 072 /** 073 * Get Preferences from projection code. 074 * @param code projection code 075 * 076 * @return null when code is not part of this projection choice. 077 * An empty Collection as return value indicates, that the code is supported, 078 * but no preferences are required to set it up. 079 */ 080 Collection<String> getPreferencesFromCode(String code); 081 082 /** 083 * Short name of the projection choice as shown in the GUI (combo box). 084 * 085 * @return the name 086 */ 087 @Override 088 String toString(); 089}