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