001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.gui.download;
003
004import java.util.Objects;
005
006import javax.swing.Icon;
007import javax.swing.JPanel;
008
009import org.openstreetmap.josm.data.Bounds;
010import org.openstreetmap.josm.gui.download.DownloadSourceSizingPolicy.FixedDownloadSourceSizePolicy;
011
012/**
013 * GUI representation of {@link DownloadSource} that is shown to the user in
014 * {@link DownloadDialog}.
015 * @param <T> The type of the data that a download source uses.
016 * @since 12652
017 */
018public abstract class AbstractDownloadSourcePanel<T> extends JPanel {
019
020    /**
021     * A prefix to be used for tab height preferences
022     */
023    public static final String TAB_SPLIT_NAMESPACE = "download.tabsplit.";
024
025    /**
026     * Called when creating a new {@link AbstractDownloadSourcePanel} for the given download source
027     * @param downloadSource The download source this panel is for
028     */
029    protected AbstractDownloadSourcePanel(final DownloadSource<T> downloadSource) {
030        Objects.requireNonNull(downloadSource);
031        this.downloadSource = downloadSource;
032    }
033
034    /**
035     * The download source of this panel.
036     */
037    protected transient DownloadSource<T> downloadSource;
038
039    /**
040     * Gets the data.
041     * @return Returns the data.
042     */
043    public abstract T getData();
044
045    /**
046     * Gets the download source of this panel.
047     * @return Returns the download source of this panel.
048     */
049    public DownloadSource<T> getDownloadSource() {
050        return this.downloadSource;
051    }
052
053    /**
054     * Saves the current user preferences devoted to the data source.
055     */
056    public abstract void rememberSettings();
057
058    /**
059     * Restores the latest user preferences devoted to the data source.
060     */
061    public abstract void restoreSettings();
062
063    /**
064     * Performs the logic needed in case if the user triggered the download
065     * action in {@link DownloadDialog}.
066     * @param settings The settings to check.
067     * @return Returns {@code true} if the required procedure of handling the
068     * download action succeeded and {@link DownloadDialog} can be closed, e.g. validation,
069     * otherwise {@code false}.
070     */
071    public abstract boolean checkDownload(DownloadSettings settings);
072
073    /**
074     * Performs the logic needed in case if the user triggered the cancel
075     * action in {@link DownloadDialog}.
076     */
077    public void checkCancel() {
078        // nothing, let download dialog to close
079        // override if necessary
080    }
081
082    /**
083     * Gets the icon of the download source panel.
084     * @return The icon. Can be {@code null} if there is no icon associated with
085     * this download source.
086     */
087    public Icon getIcon() {
088        return null;
089    }
090
091    /**
092     * Updates GUI components of the panel according to the bbox changes.
093     * @param bbox The new value for the bounding box.
094     * @since 13498
095     */
096    public void boundingBoxChanged(Bounds bbox) {
097        // override this if the panel must react on bbox changes
098    }
099
100    /**
101     * Tells the {@link DownloadSource} to start downloading
102     * @param downloadSettings The download settings
103     */
104    public void triggerDownload(DownloadSettings downloadSettings) {
105        getDownloadSource().doDownload(getData(), downloadSettings);
106    }
107
108    /**
109     * Returns a simple name describing this panel. This string can be used from other GUI parts
110     * of JOSM to save the user preferences related to the GUI settings. For example, the panel for downloading
111     * the OSM data can be named 'downloadosmpanel'. Note, choose the name such that it is unique to avoid
112     * collisions with other names.
113     * @return A simple name describing this panel.
114     */
115    public abstract String getSimpleName();
116
117    /**
118     * Gets the policy that defines how this component should be sized
119     * @return The sizing policy. A fixed policy on default.
120     * @since 12705
121     */
122    public DownloadSourceSizingPolicy getSizingPolicy() {
123        return new FixedDownloadSourceSizePolicy(this);
124    }
125}