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 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     * @see #setSelectedFile
075     * @return the selected file
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(final 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     * @exception IllegalArgumentException  if <code>mode</code> is an
157     *                          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     * @beaninfo
166     *       bound: true
167     * description: Sets multiple file selection mode.
168     *
169     * @see #isMultiSelectionEnabled
170     */
171    public abstract void setMultiSelectionEnabled(boolean multiple);
172
173    /**
174     * Sets the selected file. If the file's parent directory is
175     * not the current directory, changes the current directory
176     * to be the file's parent directory.
177     *
178     * @see #getSelectedFile
179     *
180     * @param file the selected file
181     */
182    public abstract void setSelectedFile(File file);
183
184    /**
185     * Pops up an "Open File" file chooser dialog. Note that the
186     * text that appears in the approve button is determined by
187     * the L&F.
188     *
189     * @param    parent  the parent component of the dialog,
190     *                  can be <code>null</code>;
191     *                  see <code>showDialog</code> for details
192     * @return   the return state of the file chooser on popdown:
193     * <ul>
194     * <li>JFileChooser.CANCEL_OPTION
195     * <li>JFileChooser.APPROVE_OPTION
196     * <li>JFileChooser.ERROR_OPTION if an error occurs or the
197     *                  dialog is dismissed
198     * </ul>
199     * @exception HeadlessException if GraphicsEnvironment.isHeadless()
200     * returns true.
201     * @see java.awt.GraphicsEnvironment#isHeadless
202     */
203    public abstract int showOpenDialog(Component parent);
204
205    /**
206     * Pops up a "Save File" file chooser dialog. Note that the
207     * text that appears in the approve button is determined by
208     * the L&F.
209     *
210     * @param    parent  the parent component of the dialog,
211     *                  can be <code>null</code>;
212     *                  see <code>showDialog</code> for details
213     * @return   the return state of the file chooser on popdown:
214     * <ul>
215     * <li>JFileChooser.CANCEL_OPTION
216     * <li>JFileChooser.APPROVE_OPTION
217     * <li>JFileChooser.ERROR_OPTION if an error occurs or the
218     *                  dialog is dismissed
219     * </ul>
220     * @exception HeadlessException if GraphicsEnvironment.isHeadless()
221     * returns true.
222     * @see java.awt.GraphicsEnvironment#isHeadless
223     */
224    public abstract int showSaveDialog(Component parent);
225}