Java > Open Source Codes > javax > swing > JFileChooser


1 /*
2  * @(#)JFileChooser.java 1.108 07/03/16
3  *
4  * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5  * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6  */
7
8 package javax.swing;
9
10 import javax.swing.event.*;
11 import javax.swing.filechooser.*;
12 import javax.swing.plaf.FileChooserUI ;
13
14 import javax.accessibility.*;
15
16 import java.io.File ;
17 import java.io.ObjectOutputStream ;
18 import java.io.ObjectInputStream ;
19 import java.io.IOException ;
20
21 import java.util.Vector ;
22 import java.awt.AWTEvent ;
23 import java.awt.Component ;
24 import java.awt.Container ;
25 import java.awt.BorderLayout ;
26 import java.awt.Window ;
27 import java.awt.Dialog ;
28 import java.awt.Frame ;
29 import java.awt.GraphicsEnvironment ;
30 import java.awt.HeadlessException ;
31 import java.awt.EventQueue ;
32 import java.awt.Toolkit ;
33 import java.awt.event.*;
34 import java.beans.PropertyChangeListener ;
35 import java.beans.PropertyChangeEvent ;
36 import java.lang.ref.WeakReference ;
37
38 /**
39  * <code>JFileChooser</code> provides a simple mechanism for the user to
40  * choose a file.
41  * For information about using <code>JFileChooser</code>, see
42  * <a
43  href="http://java.sun.com/docs/books/tutorial/uiswing/components/filechooser.html">How to Use File Choosers</a>,
44  * a section in <em>The Java Tutorial</em>.
45  *
46  * <p>
47  *
48  * The following code pops up a file chooser for the user's home directory that
49  * sees only .jpg and .gif images:
50  * <pre>
51  * JFileChooser chooser = new JFileChooser();
52  * // Note: source for ExampleFileFilter can be found in FileChooserDemo,
53  * // under the demo/jfc directory in the JDK.
54  * ExampleFileFilter filter = new ExampleFileFilter();
55  * filter.addExtension("jpg");
56  * filter.addExtension("gif");
57  * filter.setDescription("JPG & GIF Images");
58  * chooser.setFileFilter(filter);
59  * int returnVal = chooser.showOpenDialog(parent);
60  * if(returnVal == JFileChooser.APPROVE_OPTION) {
61  * System.out.println("You chose to open this file: " +
62  * chooser.getSelectedFile().getName());
63  * }
64  * </pre>
65  *
66  * @beaninfo
67  * attribute: isContainer false
68  * description: A component which allows for the interactive selection of a file.
69  *
70  * @version 1.108 03/16/07
71  * @author Jeff Dinkins
72  *
73  */
74 public class JFileChooser extends JComponent implements Accessible {
75
76     /**
77      * @see #getUIClassID
78      * @see #readObject
79      */
80     private static final String uiClassID = "FileChooserUI";
81
82     // ************************
83 // ***** Dialog Types *****
84 // ************************
85
86     /**
87      * Type value indicating that the <code>JFileChooser</code> supports an
88      * "Open" file operation.
89      */
90     public static final int OPEN_DIALOG = 0;
91
92     /**
93      * Type value indicating that the <code>JFileChooser</code> supports a
94      * "Save" file operation.
95      */
96     public static final int SAVE_DIALOG = 1;
97
98     /**
99      * Type value indicating that the <code>JFileChooser</code> supports a
100      * developer-specified file operation.
101      */
102     public static final int CUSTOM_DIALOG = 2;
103
104
105     // ********************************
106 // ***** Dialog Return Values *****
107 // ********************************
108
109     /**
110      * Return value if cancel is chosen.
111      */
112     public static final int CANCEL_OPTION = 1;
113
114     /**
115      * Return value if approve (yes, ok) is chosen.
116      */
117     public static final int APPROVE_OPTION = 0;
118
119     /**
120      * Return value if an error occured.
121      */
122     public static final int ERROR_OPTION = -1;
123
124
125     // **********************************
126 // ***** JFileChooser properties *****
127 // **********************************
128
129
130     /** Instruction to display only files. */
131     public static final int FILES_ONLY = 0;
132
133     /** Instruction to display only directories. */
134     public static final int DIRECTORIES_ONLY = 1;
135
136     /** Instruction to display both files and directories. */
137     public static final int FILES_AND_DIRECTORIES = 2;
138
139     /** Instruction to cancel the current selection. */
140     public static final String CANCEL_SELECTION = "CancelSelection";
141
142     /**
143      * Instruction to approve the current selection
144      * (same as pressing yes or ok).
145      */
146     public static final String APPROVE_SELECTION = "ApproveSelection";
147
148     /** Identifies change in the text on the approve (yes, ok) button. */
149     public static final String APPROVE_BUTTON_TEXT_CHANGED_PROPERTY = "ApproveButtonTextChangedProperty";
150
151     /**
152      * Identifies change in the tooltip text for the approve (yes, ok)
153      * button.
154      */
155     public static final String APPROVE_BUTTON_TOOL_TIP_TEXT_CHANGED_PROPERTY = "ApproveButtonToolTipTextChangedProperty";
156
157     /** Identifies change in the mnemonic for the approve (yes, ok) button. */
158     public static final String APPROVE_BUTTON_MNEMONIC_CHANGED_PROPERTY = "ApproveButtonMnemonicChangedProperty";
159
160     /** Instruction to display the control buttons. */
161     public static final String CONTROL_BUTTONS_ARE_SHOWN_CHANGED_PROPERTY = "ControlButtonsAreShownChangedProperty";
162
163     /** Identifies user's directory change. */
164     public static final String DIRECTORY_CHANGED_PROPERTY = "directoryChanged";
165
166     /** Identifies change in user's single-file selection. */
167     public static final String SELECTED_FILE_CHANGED_PROPERTY = "SelectedFileChangedProperty";
168
169     /** Identifies change in user's multiple-file selection. */
170     public static final String SELECTED_FILES_CHANGED_PROPERTY = "SelectedFilesChangedProperty";
171
172     /** Enables multiple-file selections. */
173     public static final String MULTI_SELECTION_ENABLED_CHANGED_PROPERTY = "MultiSelectionEnabledChangedProperty";
174
175     /**
176      * Says that a different object is being used to find available drives
177      * on the system.
178      */
179     public static final String FILE_SYSTEM_VIEW_CHANGED_PROPERTY = "FileSystemViewChanged";
180
181     /**
182      * Says that a different object is being used to retrieve file
183      * information.
184      */
185     public static final String FILE_VIEW_CHANGED_PROPERTY = "fileViewChanged";
186
187     /** Identifies a change in the display-hidden-files property. */
188     public static final String FILE_HIDING_CHANGED_PROPERTY = "FileHidingChanged";
189
190     /** User changed the kind of files to display. */
191     public static final String FILE_FILTER_CHANGED_PROPERTY = "fileFilterChanged";
192
193     /**
194      * Identifies a change in the kind of selection (single,
195      * multiple, etc.).
196      */
197     public static final String FILE_SELECTION_MODE_CHANGED_PROPERTY = "fileSelectionChanged";
198
199     /**
200      * Says that a different accessory component is in use
201      * (for example, to preview files).
202      */
203     public static final String ACCESSORY_CHANGED_PROPERTY = "AccessoryChangedProperty";
204
205     /**
206      * Identifies whether a the AcceptAllFileFilter is used or not.
207      */
208     public static final String ACCEPT_ALL_FILE_FILTER_USED_CHANGED_PROPERTY = "acceptAllFileFilterUsedChanged";
209
210     /** Identifies a change in the dialog title. */
211     public static final String DIALOG_TITLE_CHANGED_PROPERTY = "DialogTitleChangedProperty";
212
213     /**
214      * Identifies a change in the type of files displayed (files only,
215      * directories only, or both files and directories).
216      */
217     public static final String DIALOG_TYPE_CHANGED_PROPERTY = "DialogTypeChangedProperty";
218
219     /**
220      * Identifies a change in the list of predefined file filters
221      * the user can choose from.
222      */
223     public static final String CHOOSABLE_FILE_FILTER_CHANGED_PROPERTY = "ChoosableFileFilterChangedProperty";
224
225     // ******************************
226 // ***** instance variables *****
227 // ******************************
228
229     private String dialogTitle = null;
230     private String approveButtonText = null;
231     private String approveButtonToolTipText = null;
232     private int approveButtonMnemonic = 0;
233
234     private ActionListener actionListener = null;
235
236     private Vector filters = new Vector (5);
237     private JDialog dialog = null;
238     private int dialogType = OPEN_DIALOG;
239     private int returnValue = ERROR_OPTION;
240     private JComponent accessory = null;
241
242     private FileView fileView = null;
243
244     // uiFileView is not serialized, as it is initialized
245 // by updateUI() after deserialization
246 private transient FileView uiFileView = null;
247
248     private boolean controlsShown = true;
249
250     private boolean useFileHiding = true;
251     private static final String SHOW_HIDDEN_PROP = "awt.file.showHiddenFiles";
252
253     // Listens to changes in the native setting for showing hidden files.
254 // The Listener is removed and the native setting is ignored if
255 // setFileHidingEnabled() is ever called.
256 private PropertyChangeListener showFilesListener = null;
257
258     private int fileSelectionMode = FILES_ONLY;
259
260     private boolean multiSelectionEnabled = false;
261
262     private boolean useAcceptAllFileFilter = true;
263
264     private boolean dragEnabled = false;
265
266     private FileFilter fileFilter = null;
267
268     private FileSystemView fileSystemView = null;
269
270     private File currentDirectory = null;
271     private File selectedFile = null;
272     private File [] selectedFiles;
273
274     // *************************************
275 // ***** JFileChooser Constructors *****
276 // *************************************
277
278     /**
279      * Constructs a <code>JFileChooser</code> pointing to the user's
280      * default directory. This default depends on the operating system.
281      * It is typically the "My Documents" folder on Windows, and the
282      * user's home directory on Unix.
283      */
284     public JFileChooser() {
285     this((File ) null, (FileSystemView) null);
286     }
287     
288     /**
289      * Constructs a <code>JFileChooser</code> using the given path.
290      * Passing in a <code>null</code>
291      * string causes the file chooser to point to the user's default directory.
292      * This default depends on the operating system. It is
293      * typically the "My Documents" folder on Windows, and the user's
294      * home directory on Unix.
295      *
296      * @param currentDirectoryPath a <code>String</code> giving the path
297      * to a file or directory
298      */
299     public JFileChooser(String currentDirectoryPath) {
300     this(currentDirectoryPath, (FileSystemView) null);
301     }
302
303     /**
304      * Constructs a <code>JFileChooser</code> using the given <code>File</code>
305      * as the path. Passing in a <code>null</code> file
306      * causes the file chooser to point to the user's default directory.
307      * This default depends on the operating system. It is
308      * typically the "My Documents" folder on Windows, and the user's
309      * home directory on Unix.
310      *
311      * @param currentDirectory a <code>File</code> object specifying
312      * the path to a file or directory
313      */
314     public JFileChooser(File currentDirectory) {
315     this(currentDirectory, (FileSystemView) null);
316     }
317
318     /**
319      * Constructs a <code>JFileChooser</code> using the given
320      * <code>FileSystemView</code>.
321      */
322     public JFileChooser(FileSystemView fsv) {
323     this((File ) null, fsv);
324     }
325
326
327     /**
328      * Constructs a <code>JFileChooser</code> using the given current directory
329      * and <code>FileSystemView</code>.
330      */
331     public JFileChooser(File currentDirectory, FileSystemView fsv) {
332     setup(fsv);
333     setCurrentDirectory(currentDirectory);
334     }
335
336     /**
337      * Constructs a <code>JFileChooser</code> using the given current directory
338      * path and <code>FileSystemView</code>.
339      */
340     public JFileChooser(String currentDirectoryPath, FileSystemView fsv) {
341     setup(fsv);
342     if(currentDirectoryPath == null) {
343         setCurrentDirectory(null);
344         } else {
345         setCurrentDirectory(fileSystemView.createFileObject(currentDirectoryPath));
346     }
347     }
348
349     /**
350      * Performs common constructor initialization and setup.
351      */
352     protected void setup(FileSystemView view) {
353         // Track native setting for showing hidden files
354 Toolkit tk = Toolkit.getDefaultToolkit();
355         Object showHiddenProperty = tk.getDesktopProperty(SHOW_HIDDEN_PROP);
356         if (showHiddenProperty instanceof Boolean ) {
357             useFileHiding = !((Boolean )showHiddenProperty).booleanValue();
358             showFilesListener = new WeakPCL(this);
359             tk.addPropertyChangeListener(SHOW_HIDDEN_PROP, showFilesListener);
360         }
361
362         if(view == null) {
363             view = FileSystemView.getFileSystemView();
364         }
365         setFileSystemView(view);
366         updateUI();
367         if(isAcceptAllFileFilterUsed()) {
368             setFileFilter(getAcceptAllFileFilter());
369         }
370     }
371
372     /**
373      * Sets the <code>dragEnabled</code> property,
374      * which must be <code>true</code> to enable
375      * automatic drag handling (the first part of drag and drop)
376      * on this component.
377      * The <code>transferHandler</code> property needs to be set
378      * to a non-<code>null</code> value for the drag to do
379      * anything. The default value of the <code>dragEnabled</code>
380      * property
381      * is <code>false</code>.
382      *
383      * <p>
384      *
385      * When automatic drag handling is enabled,
386      * most look and feels begin a drag-and-drop operation
387      * whenever the user presses the mouse button over a selection
388      * and then moves the mouse a few pixels.
389      * Setting this property to <code>true</code>
390      * can therefore have a subtle effect on
391      * how selections behave.
392      *
393      * <p>
394      *
395      * Some look and feels might not support automatic drag and drop;
396      * they will ignore this property. You can work around such
397      * look and feels by modifying the component
398      * to directly call the <code>exportAsDrag</code> method of a
399      * <code>TransferHandler</code>.
400      *
401      * @param b the value to set the <code>dragEnabled</code> property to
402      * @exception HeadlessException if
403      * <code>b</code> is <code>true</code> and
404      * <code>GraphicsEnvironment.isHeadless()</code>
405      * returns <code>true</code>
406      * @see java.awt.GraphicsEnvironment#isHeadless
407      * @see #getDragEnabled
408      * @see #setTransferHandler
409      * @see TransferHandler
410      * @since 1.4
411      *
412      * @beaninfo
413      * description: determines whether automatic drag handling is enabled
414      * bound: false
415      */
416     public void setDragEnabled(boolean b) {
417         if (b && GraphicsEnvironment.isHeadless()) {
418             throw new HeadlessException ();
419         }
420     dragEnabled = b;
421     }
422
423     /**
424      * Gets the value of the <code>dragEnabled</code> property.
425      *
426      * @return the value of the <code>dragEnabled</code> property
427      * @see #setDragEnabled
428      * @since 1.4
429      */
430     public boolean getDragEnabled() {
431     return dragEnabled;
432     }
433
434     // *****************************
435 // ****** File Operations ******
436 // *****************************
437
438     /**
439      * Returns the selected file. This can be set either by the
440      * programmer via <code>setFile</code> or by a user action, such as
441      * either typing the filename into the UI or selecting the
442      * file from a list in the UI.
443      *
444      * @see #setSelectedFile
445      * @return the selected file
446      */
447     public File getSelectedFile() {
448     return selectedFile;
449     }
450
451     /**
452      * Sets the selected file. If the file's parent directory is
453      * not the current directory, changes the current directory
454      * to be the file's parent directory.
455      *
456      * @beaninfo
457      * preferred: true
458      * bound: true
459      *
460      * @see #getSelectedFile
461      *
462      * @param file the selected file
463      */
464     public void setSelectedFile(File file) {
465     File oldValue = selectedFile;
466     selectedFile = file;
467     if(selectedFile != null) {
468         if (file.isAbsolute() && !getFileSystemView().isParent(getCurrentDirectory(), selectedFile)) {
469         setCurrentDirectory(selectedFile.getParentFile());
470         }
471         if (!isMultiSelectionEnabled() || selectedFiles == null || selectedFiles.length == 1) {
472         ensureFileIsVisible(selectedFile);
473         }
474     }
475     firePropertyChange(SELECTED_FILE_CHANGED_PROPERTY, oldValue, selectedFile);
476     }
477
478     /**
479      * Returns a list of selected files if the file chooser is
480      * set to allow multiple selection.
481      */
482     public File [] getSelectedFiles() {
483     if(selectedFiles == null) {
484         return new File [0];
485     } else {
486         return (File []) selectedFiles.clone();
487     }
488     }
489
490     /**
491      * Sets the list of selected files if the file chooser is
492      * set to allow multiple selection.
493      *
494      * @beaninfo
495      * bound: true
496      * description: The list of selected files if the chooser is in multiple selection mode.
497      */
498     public void setSelectedFiles(File [] selectedFiles) {
499     File [] oldValue = this.selectedFiles;
500     if (selectedFiles != null && selectedFiles.length == 0) {
501         selectedFiles = null;
502     }
503     this.selectedFiles = selectedFiles;
504     setSelectedFile((selectedFiles != null) ? selectedFiles[0] : null);
505     firePropertyChange(SELECTED_FILES_CHANGED_PROPERTY, oldValue, this.selectedFiles);
506     }
507
508     /**
509      * Returns the current directory.
510      *
511      * @return the current directory
512      * @see #setCurrentDirectory
513      */
514     public File getCurrentDirectory() {
515     return currentDirectory;
516     }
517
518     /**
519      * Sets the current directory. Passing in <code>null</code> sets the
520      * file chooser to point to the user's default directory.
521      * This default depends on the operating system. It is
522      * typically the "My Documents" folder on Windows, and the user's
523      * home directory on Unix.
524      *
525      * If the file passed in as <code>currentDirectory</code> is not a
526      * directory, the parent of the file will be used as the currentDirectory.
527      * If the parent is not traversable, then it will walk up the parent tree
528      * until it finds a traversable directory, or hits the root of the
529      * file system.
530      *
531      * @beaninfo
532      * preferred: true
533      * bound: true
534      * description: The directory that the JFileChooser is showing files of.
535      *
536      * @param dir the current directory to point to
537      * @see #getCurrentDirectory
538      */
539     public void setCurrentDirectory(File dir) {
540     File oldValue = currentDirectory;
541     
542     if (dir != null && !dir.exists()) {
543         dir = currentDirectory;
544     }
545     if (dir == null) {
546         dir = getFileSystemView().getDefaultDirectory();
547     }
548     if (currentDirectory != null) {
549         /* Verify the toString of object */
550         if (this.currentDirectory.equals(dir)) {
551         return;
552         }
553     }
554     
555     File prev = null;
556     while (!isTraversable(dir) && prev != dir) {
557         prev = dir;
558         dir = getFileSystemView().getParentDirectory(dir);
559     }
560     currentDirectory = dir;
561
562     firePropertyChange(DIRECTORY_CHANGED_PROPERTY, oldValue, currentDirectory);
563     }
564
565     /**
566      * Changes the directory to be set to the parent of the
567      * current directory.
568      *
569      * @see #getCurrentDirectory
570      */
571     public void changeToParentDirectory() {
572     selectedFile = null;
573     File oldValue = getCurrentDirectory();
574     setCurrentDirectory(getFileSystemView().getParentDirectory(oldValue));
575     }
576
577     /**
578      * Tells the UI to rescan its files list from the current directory.
579      */
580     public void rescanCurrentDirectory() {
581         getUI().rescanCurrentDirectory(this);
582     }
583
584     /**
585      * Makes sure that the specified file is viewable, and
586      * not hidden.
587      *
588      * @param f a File object
589      */
590     public void ensureFileIsVisible(File f) {
591         getUI().ensureFileIsVisible(this, f);
592     }
593
594     // **************************************
595 // ***** JFileChooser Dialog methods *****
596 // **************************************
597
598     /**
599      * Pops up an "Open File" file chooser dialog. Note that the
600      * text that appears in the approve button is determined by
601      * the L&F.
602      *
603      * @param parent the parent component of the dialog,
604      * can be <code>null</code>;
605      * see <code>showDialog</code> for details
606      * @return the return state of the file chooser on popdown:
607      * <ul>
608      * <li>JFileChooser.CANCEL_OPTION
609      * <li>JFileChooser.APPROVE_OPTION
610      * <li>JFileCHooser.ERROR_OPTION if an error occurs or the
611      * dialog is dismissed
612      * </ul>
613      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
614      * returns true.
615      * @see java.awt.GraphicsEnvironment#isHeadless
616      * @see #showDialog
617      */
618     public int showOpenDialog(Component parent) throws HeadlessException {
619     setDialogType(OPEN_DIALOG);
620     return showDialog(parent, null);
621     }
622
623     /**
624      * Pops up a "Save File" file chooser dialog. Note that the
625      * text that appears in the approve button is determined by
626      * the L&F.
627      *
628      * @param parent the parent component of the dialog,
629      * can be <code>null</code>;
630      * see <code>showDialog</code> for details
631      * @return the return state of the file chooser on popdown:
632      * <ul>
633      * <li>JFileChooser.CANCEL_OPTION
634      * <li>JFileChooser.APPROVE_OPTION
635      * <li>JFileCHooser.ERROR_OPTION if an error occurs or the
636      * dialog is dismissed
637      * </ul>
638      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
639      * returns true.
640      * @see java.awt.GraphicsEnvironment#isHeadless
641      * @see #showDialog
642      */
643     public int showSaveDialog(Component parent) throws HeadlessException {
644     setDialogType(SAVE_DIALOG);
645     return showDialog(parent, null);
646     }
647
648     /**
649      * Pops a custom file chooser dialog with a custom approve button.
650      * For example, the following code
651      * pops up a file chooser with a "Run Application" button
652      * (instead of the normal "Save" or "Open" button):
653      * <pre>
654      * filechooser.showDialog(parentFrame, "Run Application");
655      * </pre>
656      *
657      * Alternatively, the following code does the same thing:
658      * <pre>
659      * JFileChooser chooser = new JFileChooser(null);
660      * chooser.setApproveButtonText("Run Application");
661      * chooser.showDialog(parentFrame, null);
662      * </pre>
663      *
664      * <!--PENDING(jeff) - the following method should be added to the api:
665      * showDialog(Component parent);-->
666      * <!--PENDING(kwalrath) - should specify modality and what
667      * "depends" means.-->
668      *
669      * <p>
670      *
671      * The <code>parent</code> argument determines two things:
672      * the frame on which the open dialog depends and
673      * the component whose position the look and feel
674      * should consider when placing the dialog. If the parent
675      * is a <code>Frame</code> object (such as a <code>JFrame</code>)
676      * then the dialog depends on the frame and
677      * the look and feel positions the dialog
678      * relative to the frame (for example, centered over the frame).
679      * If the parent is a component, then the dialog
680      * depends on the frame containing the component,
681      * and is positioned relative to the component
682      * (for example, centered over the component).
683      * If the parent is <code>null</code>, then the dialog depends on
684      * no visible window, and it's placed in a
685      * look-and-feel-dependent position
686      * such as the center of the screen.
687      *
688      * @param parent the parent component of the dialog;
689      * can be <code>null</code>
690      * @param approveButtonText the text of the <code>ApproveButton</code>
691      * @return the return state of the file chooser on popdown:
692      * <ul>
693      * <li>JFileChooser.CANCEL_OPTION
694      * <li>JFileChooser.APPROVE_OPTION
695      * <li>JFileCHooser.ERROR_OPTION if an error occurs or the
696      * dialog is dismissed
697      * </ul>
698      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
699      * returns true.
700      * @see java.awt.GraphicsEnvironment#isHeadless
701      */
702     public int showDialog(Component parent, String approveButtonText)
703         throws HeadlessException {
704     if(approveButtonText != null) {
705         setApproveButtonText(approveButtonText);
706         setDialogType(CUSTOM_DIALOG);
707     }
708     dialog = createDialog(parent);
709     dialog.addWindowListener(new WindowAdapter() {
710         public void windowClosing(WindowEvent e) {
711         returnValue = CANCEL_OPTION;
712         }
713     });
714     returnValue = ERROR_OPTION;
715     rescanCurrentDirectory();
716
717     dialog.show();
718     firePropertyChange("JFileChooserDialogIsClosingProperty", dialog, null);
719     dialog.removeAll();
720     dialog.dispose();
721     dialog = null;
722     return returnValue;
723     }
724
725     /**
726      * Creates and returns a new <code>JDialog</code> wrapping
727      * <code>this</code> centered on the <code>parent</code>
728      * in the <code>parent</code>'s frame.
729      * This method can be overriden to further manipulate the dialog,
730      * to disable resizing, set the location, etc. Example:
731      * <pre>
732      * class MyFileChooser extends JFileChooser {
733      * protected JDialog createDialog(Component parent) throws HeadlessException {
734      * JDialog dialog = super.createDialog(parent);
735      * dialog.setLocation(300, 200);
736      * dialog.setResizable(false);
737      * return dialog;
738      * }
739      * }
740      * </pre>
741      *
742      * @param parent the parent component of the dialog;
743      * can be <code>null</code>
744      * @return a new <code>JDialog</code> containing this instance
745      * @exception HeadlessException if GraphicsEnvironment.isHeadless()
746      * returns true.
747      * @see java.awt.GraphicsEnvironment#isHeadless
748      * @since 1.4
749      */
750     protected JDialog createDialog(Component parent) throws HeadlessException {
751     String title = getUI().getDialogTitle(this);
752         getAccessibleContext().setAccessibleDescription(title);
753
754         JDialog dialog;
755         Window window = JOptionPane.getWindowForComponent(parent);
756         if (window instanceof Frame ) {
757             dialog = new JDialog ((Frame )window, title, true);
758         } else {
759             dialog = new JDialog ((Dialog )window, title, true);
760         }
761         dialog.setComponentOrientation(this.getComponentOrientation());
762
763         Container contentPane = dialog.getContentPane();
764         contentPane.setLayout(new BorderLayout ());
765         contentPane.add(this, BorderLayout.CENTER);
766  
767         if (JDialog.isDefaultLookAndFeelDecorated()) {
768             boolean supportsWindowDecorations =
769             UIManager.getLookAndFeel().getSupportsWindowDecorations();
770             if (supportsWindowDecorations) {
771                 dialog.getRootPane().setWindowDecorationStyle(JRootPane.FILE_CHOOSER_DIALOG);
772             }
773         }
774         dialog.pack();
775         dialog.setLocationRelativeTo(parent);
776
777     return dialog;
778     }
779
780     // **************************
781 // ***** Dialog Options *****
782 // **************************
783
784     /**
785      * Returns the value of the <code>controlButtonsAreShown</code>
786      * property.
787      *
788      * @return the value of the <code>controlButtonsAreShown</code>
789      * property
790      *
791      * @see #setControlButtonsAreShown
792      * @since 1.3
793      */
794     public boolean getControlButtonsAreShown() {
795     return controlsShown;
796     }
797
798     
799     /**
800      * Sets the property
801      * that indicates whether the <i>approve</i> and <i>cancel</i>
802      * buttons are shown in the file chooser. This property
803      * is <code>true</code> by default. Look and feels
804      * that always show these buttons will ignore the value
805      * of this property.
806      * This method fires a property-changed event,
807      * using the string value of
808      * <code>CONTROL_BUTTONS_ARE_SHOWN_CHANGED_PROPERTY</code>
809      * as the name of the property.
810      *
811      * @param b <code>false</code> if control buttons should not be
812      * shown; otherwise, <code>true</code>
813      *
814      * @beaninfo
815      * preferred: true
816      * bound: true
817      * description: Sets whether the approve & cancel buttons are shown.
818      *
819      * @see #getControlButtonsAreShown
820      * @see #CONTROL_BUTTONS_ARE_SHOWN_CHANGED_PROPERTY
821      * @since 1.3
822      */
823     public void setControlButtonsAreShown(boolean b) {
824     if(controlsShown == b) {
825         return;
826     }
827     boolean oldValue = controlsShown;
828     controlsShown = b;
829     firePropertyChange(CONTROL_BUTTONS_ARE_SHOWN_CHANGED_PROPERTY, oldValue, controlsShown);
830     }
831
832     /**
833      * Returns the type of this dialog. The default is
834      * <code>JFileChooser.OPEN_DIALOG</code>.
835      *
836      * @return the type of dialog to be displayed:
837      * <ul>
838      * <li>JFileChooser.OPEN_DIALOG
839      * <li>JFileChooser.SAVE_DIALOG
840      * <li>JFileChooser.CUSTOM_DIALOG
841      * </ul>
842      *
843      * @see #setDialogType
844      */
845     public int getDialogType() {
846     return dialogType;
847     }
848
849     /**
850      * Sets the type of this dialog. Use <code>OPEN_DIALOG</code> when you
851      * want to bring up a file chooser that the user can use to open a file.
852      * Likewise, use <code>SAVE_DIALOG</code> for letting the user choose
853      * a file for saving.
854      * Use <code>CUSTOM_DIALOG</code> when you want to use the file
855      * chooser in a context other than "Open" or "Save".
856      * For instance, you might want to bring up a file chooser that allows
857      * the user to choose a file to execute. Note that you normally would not
858      * need to set the <code>JFileChooser</code> to use
859      * <code>CUSTOM_DIALOG</code>
860      * since a call to <code>setApproveButtonText</code> does this for you.
861      * The default dialog type is <code>JFileChooser.OPEN_DIALOG</code>.
862      *
863      * @param dialogType the type of dialog to be displayed:
864      * <ul>
865      * <li>JFileChooser.OPEN_DIALOG
866      * <li>JFileChooser.SAVE_DIALOG
867      * <li>JFileChooser.CUSTOM_DIALOG
868      * </ul>
869      *
870      * @exception IllegalArgumentException if <code>dialogType</code> is
871      * not legal
872      * @beaninfo
873      * preferred: true
874      * bound: true
875      * description: The type (open, save, custom) of the JFileChooser.
876      * enum:
877      * OPEN_DIALOG JFileChooser.OPEN_DIALOG
878      * SAVE_DIALOG JFileChooser.SAVE_DIALOG
879      * CUSTOM_DIALOG JFileChooser.CUSTOM_DIALOG
880      *
881      * @see #getDialogType
882      * @see #setApproveButtonText
883      */
884     // PENDING(jeff) - fire button text change property
885 public void setDialogType(int dialogType) {
886     if(this.dialogType == dialogType) {
887         return;
888     }
889     if(!(dialogType == OPEN_DIALOG || dialogType == SAVE_DIALOG || dialogType == CUSTOM_DIALOG)) {
890         throw new IllegalArgumentException ("Incorrect Dialog Type: " + dialogType);
891     }
892     int oldValue = this.dialogType;
893     this.dialogType = dialogType;
894     if(dialogType == OPEN_DIALOG || dialogType == SAVE_DIALOG) {
895         setApproveButtonText(null);
896     }
897     firePropertyChange(DIALOG_TYPE_CHANGED_PROPERTY, oldValue, dialogType);
898     }
899
900     /**
901      * Sets the string that goes in the <code>JFileChooser</code> window's
902      * title bar.
903      *
904      * @param dialogTitle the new <code>String</code> for the title bar
905      *
906      * @beaninfo
907      * preferred: true
908      * bound: true
909      * description: The title of the JFileChooser dialog window.
910      *
911      * @see #getDialogTitle
912      *
913      */
914     public void setDialogTitle(String dialogTitle) {
915     String oldValue = this.dialogTitle;
916     this.dialogTitle = dialogTitle;
917     if(dialog != null) {
918         dialog.setTitle(dialogTitle);
919     }
920     firePropertyChange(DIALOG_TITLE_CHANGED_PROPERTY, oldValue, dialogTitle);
921     }
922
923     /**
924      * Gets the string that goes in the <code>JFileChooser</code>'s titlebar.
925      *
926      * @see #setDialogTitle
927      */
928     public String getDialogTitle() {
929     return dialogTitle;
930     }
931
932     // ************************************
933 // ***** JFileChooser View Options *****
934 // ************************************
935
936
937
938     /**
939      * Sets the tooltip text used in the <code>ApproveButton</code>.
940      * If <code>null</code>, the UI object will determine the button's text.
941      *
942      * @beaninfo
943      * preferred: true
944      * bound: true
945      * description: The tooltip text for the ApproveButton.
946      *
947      * @return the text used in the ApproveButton
948      *
949      * @see #setApproveButtonText
950      * @see #setDialogType
951      * @see #showDialog
952      */
953     public void setApproveButtonToolTipText(String toolTipText) {
954     if(approveButtonToolTipText == toolTipText) {
955         return;
956     }
957     String oldValue = approveButtonToolTipText;
958     approveButtonToolTipText = toolTipText;
959     firePropertyChange(APPROVE_BUTTON_TOOL_TIP_TEXT_CHANGED_PROPERTY, oldValue, approveButtonToolTipText);
960     }
961
962
963     /**
964      * Returns the tooltip text used in the <code>ApproveButton</code>.
965      * If <code>null</code>, the UI object will determine the button's text.
966      *
967      * @return the text used in the <code>ApproveButton</code>
968      *
969      * @see #setApproveButtonText
970      * @see #setDialogType
971      * @see #showDialog
972      */
973     public String getApproveButtonToolTipText() {
974     return approveButtonToolTipText;
975     }
976
977     /**
978      * Returns the approve button's mnemonic.
979      * @return an integer value for the mnemonic key
980      *
981      * @see #setApproveButtonMnemonic
982      */