001    // License: GPL. For details, see LICENSE file.
002    package org.openstreetmap.josm.gui.preferences.projection;
003    
004    import java.awt.event.ActionListener;
005    import java.util.Collection;
006    
007    import javax.swing.JPanel;
008    
009    import 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     */
016    public interface ProjectionChoice {
017    
018        /**
019         * Get a unique id for the projection choice.
020         */
021        String getId();
022    
023        /**
024         * Set the internal state to match the preferences.
025         *
026         * Will be called before getPreferencePanel and when the
027         * listener from getPreferencePanel is invoked.
028         *
029         * Argument may be null to reset everything.
030         */
031        void setPreferences(Collection<String> args);
032    
033        /**
034         * Get the projection that matches the internal state.
035         */
036        Projection getProjection();
037    
038        /**
039         * Generate and provide the GUI.
040         *
041         * It will be displayed to the user. Call the listener, when the user makes
042         * changes in the GUI, so the projection info in the top panel gets updated.
043         *
044         * @param listener   listener for any change of preferences
045         * @return the GUI panel
046         */
047        JPanel getPreferencePanel(ActionListener listener);
048    
049        /**
050         * Extract preferences from the GUI.
051         *
052         * Will be called when the preference dialog is dismissed or
053         * when the listener from getPreferencePanel is invoked.
054         */
055        Collection<String> getPreferences(JPanel panel);
056    
057        /**
058         * Return all projection codes supported by this projection class.
059         */
060        String[] allCodes();
061    
062        /**
063         * Get Preferences from projection code.
064         * 
065         * @return null when code is not part of this projection choice.
066         * An empty Collection as return value indicates, that the code is supported,
067         * but no preferences are required to set it up.
068         */
069        Collection<String> getPreferencesFromCode(String code);
070    
071    }