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