001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.gui.preferences;
003
004import java.awt.Component;
005
006import javax.swing.ImageIcon;
007
008import org.openstreetmap.josm.tools.ImageProvider;
009import org.openstreetmap.josm.tools.Utils;
010
011/**
012 * Preference settings, that display a top level tab.
013 *
014 * This preference setting's addGui method is called after the user clicked the tab.
015 */
016public interface TabPreferenceSetting extends PreferenceSetting {
017
018    /**
019     * Called during preferences dialog initialization to display the preferences tab with the returned icon.
020     * @return The icon name in the preferences folder.
021     */
022    String getIconName();
023
024    /**
025     * Returns the icon for this preference setting
026     * @param size the icon size
027     * @return the icon or {@code null}
028     */
029    default ImageIcon getIcon(ImageProvider.ImageSizes size) {
030        String iconName = getIconName();
031        return Utils.isEmpty(iconName)
032                ? null
033                : iconName.contains("/")
034                ? ImageProvider.get(iconName, size)
035                : ImageProvider.get("preferences", iconName, size);
036    }
037
038    /**
039     * Called during preferences tab initialization to display its title.
040     * @return The title of this preferences tab.
041     */
042    String getTitle();
043
044    /**
045     * Called during preferences dialog initialization to display the preferences tab with the returned tooltip.
046     * @return The tooltip of this preferences tab.
047     */
048    String getTooltip();
049
050    /**
051     * Called during preferences tab initialization to display a description in one sentence for this tab.
052     * Will be displayed in italic under the title.
053     * @return The description of this preferences tab.
054     */
055    String getDescription();
056
057    /**
058     * Adds a new sub preference settings tab with the given title and component.
059     * @param sub The new sub preference settings.
060     * @param title The tab title.
061     * @param component The tab component.
062     * @since 5631
063     */
064    void addSubTab(SubPreferenceSetting sub, String title, Component component);
065
066    /**
067     * Adds a new sub preference settings tab with the given title, component and tooltip.
068     * @param sub The new sub preference settings.
069     * @param title The tab title.
070     * @param component The tab component.
071     * @param tip The tab tooltip.
072     * @since 5631
073     */
074    void addSubTab(SubPreferenceSetting sub, String title, Component component, String tip);
075
076    /**
077     * Registers a sub preference settings to an existing tab component.
078     * @param sub The new sub preference settings.
079     * @param component The component for which a tab already exists.
080     * @since 5631
081     */
082    void registerSubTab(SubPreferenceSetting sub, Component component);
083
084    /**
085     * Returns the tab component related to the specified sub preference settings
086     * @param sub The requested sub preference settings.
087     * @return The component related to the specified sub preference settings, or null.
088     * @since 5631
089     */
090    Component getSubTab(SubPreferenceSetting sub);
091
092    /**
093     * Returns the currently selected sub preference setting
094     * @return the currently selected sub preference setting
095     */
096    Class<? extends SubPreferenceSetting> getSelectedSubTab();
097
098    /**
099     * Selects the specified sub preference settings, if applicable. Not all Tab preference settings need to implement this.
100     * @param subPref The sub preference settings to be selected.
101     * @return true if the specified preference settings have been selected, false otherwise.
102     * @since 5631
103     */
104    boolean selectSubTab(SubPreferenceSetting subPref);
105
106    /**
107     * Returns the help context for this preferences settings tab.
108     * @return the help context for this preferences settings tab
109     * @since 13431
110     */
111    String getHelpContext();
112}