001package jmri.swing;
002
003import javax.swing.JComponent;
004import jmri.spi.JmriServiceProviderInterface;
005
006/**
007 * An interface to define methods that the Preferences Window can and should
008 * expect Preferences panels to implement.
009 *
010 * This class allows the Preferences Window become less formally aware of all
011 * possible preferences settings in JMRI, and to instead interrogate a
012 * PreferencesPanel for most of the information that the Preferences window
013 * requires to add the PreferencesPanel to the window.
014 *
015 * @author Randall Wood (C) 2012, 2014
016 */
017public interface PreferencesPanel extends JmriServiceProviderInterface {
018
019    /**
020     * Get the Preferences Item identifier.
021     *
022     * Multiple PreferencePanels can be displayed as tabs in a single item.
023     * Preferences items are listed in the menu on the left of the preferences
024     * window.
025     *
026     * @return the preferences item identifier.
027     */
028    public abstract String getPreferencesItem();
029
030    /**
031     * Get the text for the Preferences Item in the preferences window list of
032     * preferences categories.
033     *
034     * Multiple PreferencePanels can be displayed as tabs in a single item.
035     * Preferences items are listed in the menu on the left of the preferences
036     * window.
037     *
038     * @return the text for the preferences item.
039     */
040    public abstract String getPreferencesItemText();
041
042    /**
043     * Get the title for the tab containing this preferences item.
044     *
045     * @return a tab title
046     */
047    public abstract String getTabbedPreferencesTitle();
048
049    /**
050     * Text displayed above the preferences panel
051     *
052     * This label is only displayed if the preferences panel is in a tabbed set
053     * of preferences. This label can contain multiple lines.
054     *
055     * @return label text
056     */
057    public abstract String getLabelKey();
058
059    /**
060     * Get the preferences component for display
061     *
062     * @return the preferences panel
063     */
064    public abstract JComponent getPreferencesComponent();
065
066    /**
067     * Indicates that this PrefernecesPanel should be stored across application
068     * starts by the PreferencesManager
069     *
070     * This should be true if the implementing class relies on the
071     * {@link jmri.ConfigureManager} stores and retrieves the preferences
072     * managed by the implementing class on behalf of the implementing class.
073     *
074     * @return false if the implementing class stores its own preferences
075     */
076    public abstract boolean isPersistant();
077
078    /**
079     * The tooltip to display for a tabbed preferences panel
080     *
081     * @return tooltip text
082     */
083    public abstract String getPreferencesTooltip();
084
085    /**
086     * Save any changes to preferences.
087     *
088     * This method is called for every instance of a PreferencesPanel that is
089     * loaded by {@link apps.gui3.tabbedpreferences.TabbedPreferences} if {@link #isPersistant()}
090     * is false.
091     */
092    public abstract void savePreferences();
093
094    /**
095     * Indicate that preferences need to be saved.
096     *
097     * @return true if preferences need to be saved, false otherwise
098     */
099    public abstract boolean isDirty();
100
101    /**
102     * Indicate that the preferences will not take effect until restarted.
103     *
104     * @return true if the application needs to restart
105     */
106    public abstract boolean isRestartRequired();
107
108    /**
109     * Indicate that the preferences are valid.
110     *
111     * @return true if the preferences are valid, false otherwise
112     */
113    public abstract boolean isPreferencesValid();
114
115    /**
116     * Indicate the sort order to be used to sort PreferencesPanels in
117     * TabbedPreferences. PreferencesPanels with the same sort order value are
118     * alphabetically within that sort order.
119     *
120     * @return the sort order; default implementation returns
121     *         {@link java.lang.Integer#MAX_VALUE}.
122     */
123    public default int getSortOrder() {
124        return Integer.MAX_VALUE;
125    }
126}