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}