001// License: GPL. For details, see LICENSE file.
002package org.openstreetmap.josm.gui.widgets;
003
004import java.awt.Component;
005import java.awt.HeadlessException;
006import java.io.File;
007import java.util.Locale;
008
009import javax.swing.filechooser.FileFilter;
010
011/**
012 * Abstract class to allow different file chooser implementations.
013 * @since 7578
014 */
015public abstract class AbstractFileChooser {
016
017    /** The locale for both implementations */
018    protected static volatile Locale locale;
019
020    /**
021     * Sets the default locale for all implementations.
022     * @param l locale
023     */
024    public static void setDefaultLocale(Locale l) {
025        locale = l;
026    }
027
028    /**
029     * Adds a filter to the list of user choosable file filters.
030     * For information on setting the file selection mode, see
031     * {@link #setFileSelectionMode setFileSelectionMode}.
032     *
033     * @param filter the <code>FileFilter</code> to add to the choosable file
034     *               filter list
035     *
036     * @see #getChoosableFileFilters
037     * @see #setFileSelectionMode
038     */
039    public abstract void addChoosableFileFilter(FileFilter filter);
040
041    /**
042     * Gets the list of user choosable file filters.
043     *
044     * @return a <code>FileFilter</code> array containing all the choosable
045     *         file filters
046     *
047     * @see #addChoosableFileFilter
048     */
049    public abstract FileFilter[] getChoosableFileFilters();
050
051    /**
052     * Returns the current directory.
053     *
054     * @return the current directory
055     * @see #setCurrentDirectory
056     */
057    public abstract File getCurrentDirectory();
058
059    /**
060     * Returns the currently selected file filter.
061     *
062     * @return the current file filter
063     * @see #setFileFilter
064     * @see #addChoosableFileFilter
065     */
066    public abstract FileFilter getFileFilter();
067
068    /**
069     * Returns the selected file. This can be set either by the
070     * programmer via <code>setSelectedFile</code> or by a user action, such as
071     * either typing the filename into the UI or selecting the
072     * file from a list in the UI.
073     *
074     * @return the selected file
075     * @see #setSelectedFile
076     */
077    public abstract File getSelectedFile();
078
079    /**
080     * Returns a list of selected files if the file chooser is
081     * set to allow multiple selection.
082     * @return a list of selected files if the file chooser is
083     * set to allow multiple selection, or an empty array otherwise.
084     */
085    public abstract File[] getSelectedFiles();
086
087    /**
088     * Returns true if multiple files can be selected.
089     * @return true if multiple files can be selected
090     * @see #setMultiSelectionEnabled
091     */
092    public abstract boolean isMultiSelectionEnabled();
093
094    /**
095     * Determines whether the <code>AcceptAll FileFilter</code> is used
096     * as an available choice in the choosable filter list.
097     * If false, the <code>AcceptAll</code> file filter is removed from
098     * the list of available file filters.
099     * If true, the <code>AcceptAll</code> file filter will become the
100     * the actively used file filter.
101     * @param b whether the <code>AcceptAll FileFilter</code> is used
102     * as an available choice in the choosable filter list
103     *
104     * @see #setFileFilter
105     */
106    public abstract void setAcceptAllFileFilterUsed(boolean b);
107
108    /**
109     * Sets the current directory. Passing in <code>null</code> sets the
110     * file chooser to point to the user's default directory.
111     * This default depends on the operating system. It is
112     * typically the "My Documents" folder on Windows, and the user's
113     * home directory on Unix.
114     *
115     * If the file passed in as <code>currentDirectory</code> is not a
116     * directory, the parent of the file will be used as the currentDirectory.
117     * If the parent is not traversable, then it will walk up the parent tree
118     * until it finds a traversable directory, or hits the root of the
119     * file system.
120     *
121     * @param dir the current directory to point to
122     * @see #getCurrentDirectory
123     */
124    public abstract void setCurrentDirectory(File dir);
125
126    /**
127     * Sets the string that goes in the <code>JFileChooser</code> window's
128     * title bar.
129     *
130     * @param title the new <code>String</code> for the title bar
131     */
132    public abstract void setDialogTitle(String title);
133
134    /**
135     * Sets the current file filter. The file filter is used by the
136     * file chooser to filter out files from the user's view.
137     *
138     * @param filter the new current file filter to use
139     * @see #getFileFilter
140     */
141    public abstract void setFileFilter(FileFilter filter);
142
143    /**
144     * Sets the <code>JFileChooser</code> to allow the user to just
145     * select files, just select
146     * directories, or select both files and directories.  The default is
147     * <code>JFilesChooser.FILES_ONLY</code>.
148     *
149     * @param selectionMode the type of files to be displayed:
150     * <ul>
151     * <li>JFileChooser.FILES_ONLY
152     * <li>JFileChooser.DIRECTORIES_ONLY
153     * <li>JFileChooser.FILES_AND_DIRECTORIES
154     * </ul>
155     *
156     * @throws IllegalArgumentException if <code>mode</code> is an illegal file selection mode
157     */
158    public abstract void setFileSelectionMode(int selectionMode);
159
160    /**
161     * Sets the file chooser to allow multiple file selections.
162     *
163     * @param multiple true if multiple files may be selected
164     * @see #isMultiSelectionEnabled
165     */
166    public abstract void setMultiSelectionEnabled(boolean multiple);
167
168    /**
169     * Sets the selected file. If the file's parent directory is
170     * not the current directory, changes the current directory
171     * to be the file's parent directory.
172     *
173     * @param file the selected file
174     * @see #getSelectedFile
175     */
176    public abstract void setSelectedFile(File file);
177
178    /**
179     * Pops up an "Open File" file chooser dialog. Note that the
180     * text that appears in the approve button is determined by
181     * the L&amp;F.
182     *
183     * @param    parent  the parent component of the dialog,
184     *                  can be <code>null</code>;
185     *                  see <code>showDialog</code> for details
186     * @return   the return state of the file chooser on popdown:
187     * <ul>
188     * <li>JFileChooser.CANCEL_OPTION
189     * <li>JFileChooser.APPROVE_OPTION
190     * <li>JFileChooser.ERROR_OPTION if an error occurs or the
191     *                  dialog is dismissed
192     * </ul>
193     * @throws HeadlessException if GraphicsEnvironment.isHeadless() returns true.
194     * @see java.awt.GraphicsEnvironment#isHeadless
195     */
196    public abstract int showOpenDialog(Component parent);
197
198    /**
199     * Pops up a "Save File" file chooser dialog. Note that the
200     * text that appears in the approve button is determined by
201     * the L&amp;F.
202     *
203     * @param    parent  the parent component of the dialog,
204     *                  can be <code>null</code>;
205     *                  see <code>showDialog</code> for details
206     * @return   the return state of the file chooser on popdown:
207     * <ul>
208     * <li>JFileChooser.CANCEL_OPTION
209     * <li>JFileChooser.APPROVE_OPTION
210     * <li>JFileChooser.ERROR_OPTION if an error occurs or the
211     *                  dialog is dismissed
212     * </ul>
213     * @throws HeadlessException if GraphicsEnvironment.isHeadless() returns true.
214     * @see java.awt.GraphicsEnvironment#isHeadless
215     */
216    public abstract int showSaveDialog(Component parent);
217}