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         * 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         */
041        Projection getProjection();
042    
043        /**
044         * Generate and provide the GUI.
045         *
046         * It will be displayed to the user. Call the listener, when the user makes
047         * changes in the GUI, so the projection info in the top panel gets updated.
048         *
049         * @param listener   listener for any change of preferences
050         * @return the GUI panel
051         */
052        JPanel getPreferencePanel(ActionListener listener);
053    
054        /**
055         * Extract preferences from the GUI.
056         *
057         * Will be called when the preference dialog is dismissed or
058         * when the listener from getPreferencePanel is invoked.
059         */
060        Collection<String> getPreferences(JPanel panel);
061    
062        /**
063         * Return all projection codes supported by this projection choice.
064         */
065        String[] allCodes();
066    
067        /**
068         * Get Preferences from projection code.
069         * 
070         * @return null when code is not part of this projection choice.
071         * An empty Collection as return value indicates, that the code is supported,
072         * but no preferences are required to set it up.
073         */
074        Collection<String> getPreferencesFromCode(String code);
075    
076        /**
077         * Short name of the projection choice as shown in the GUI (combo box).
078         * 
079         * @return the name
080         */
081        String toString();
082    
083    }