001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.gui.preferences;
003
004import java.awt.Component;
005
006/**
007 * Preference settings, that display a top level tab.
008 *
009 * This preference setting's addGui method is called after the user clicked the tab.
010 */
011public interface TabPreferenceSetting extends PreferenceSetting {
012    
013    /**
014     * Called during preferences dialog initialization to display the preferences tab with the returned icon.
015     * @return The icon name in the preferences folder.
016     */
017    public String getIconName();
018
019    /**
020     * Called during preferences tab initialization to display its title.
021     * @return The title of this preferences tab.
022     */
023    String getTitle();
024    
025    /**
026     * Called during preferences dialog initialization to display the preferences tab with the returned tooltip.
027     * @return The tooltip of this preferences tab.
028     */
029    public String getTooltip();
030
031    /**
032     * Called during preferences tab initialization to display a description in one sentence for this tab. 
033     * Will be displayed in italic under the title.
034     * @return The description of this preferences tab.
035     */
036    public String getDescription();
037
038    /**
039     * Adds a new sub preference settings tab with the given title and component.
040     * @param sub The new sub preference settings.
041     * @param title The tab title.
042     * @param component The tab component.
043     * @since 5631
044     */
045    public void addSubTab(SubPreferenceSetting sub, String title, Component component);
046    
047    /**
048     * Adds a new sub preference settings tab with the given title, component and tooltip.
049     * @param sub The new sub preference settings.
050     * @param title The tab title.
051     * @param component The tab component.
052     * @param tip The tab tooltip.
053     * @since 5631
054     */
055    public void addSubTab(SubPreferenceSetting sub, String title, Component component, String tip);
056
057    /**
058     * Registers a sub preference settings to an existing tab component.
059     * @param sub The new sub preference settings.
060     * @param component The component for which a tab already exists.
061     * @since 5631
062     */
063    public void registerSubTab(SubPreferenceSetting sub, Component component);
064    
065    /**
066     * Returns the tab component related to the specified sub preference settings
067     * @param sub The requested sub preference settings.
068     * @return The component related to the specified sub preference settings, or null.
069     * @since 5631
070     */
071    public Component getSubTab(SubPreferenceSetting sub);
072
073    /**
074     * Selects the specified sub preference settings, if applicable. Not all Tab preference settings need to implement this.
075     * @param subPref The sub preference settings to be selected.
076     * @return true if the specified preference settings have been selected, false otherwise.
077     * @since 5631
078     */
079    public boolean selectSubTab(SubPreferenceSetting subPref);
080}