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}