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}