FileDialog


1   /*
2    * @(#)FileDialog.java  1.53 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   package java.awt;
8   
9   import java.awt.peer.FileDialogPeer;
10  import java.io.FilenameFilter  ;
11  import java.io.IOException  ;
12  import java.io.ObjectInputStream  ;
13  
14  /**
15   * The <code>FileDialog</code> class displays a dialog window
16   * from which the user can select a file.
17   * <p>
18   * Since it is a modal dialog, when the application calls
19   * its <code>show</code> method to display the dialog,
20   * it blocks the rest of the application until the user has
21   * chosen a file.
22   *
23   * @see Window#show
24   *
25   * @version     1.53, 12/19/03
26   * @author  Sami Shaio
27   * @author  Arthur van Hoff
28   * @since       JDK1.0
29   */
30  public class FileDialog extends Dialog   {
31  
32      /**
33       * This constant value indicates that the purpose of the file
34       * dialog window is to locate a file from which to read.
35       */
36      public static final int LOAD = 0;
37  
38      /**
39       * This constant value indicates that the purpose of the file
40       * dialog window is to locate a file to which to write.
41       */
42      public static final int SAVE = 1;
43  
44      /*
45       * There are two <code>FileDialog</code> modes: <code>LOAD<code> and
46       * <code>SAVE<code>.
47       * This integer will represent one or the other.
48       * If the mode is not specified it will default to <code>LOAD</code>.
49       *
50       * @serial
51       * @see getMode()
52       * @see setMode()
53       * @see java.awt.FileDialog#LOAD
54       * @see java.awt.FileDialog#SAVE
55       */
56      int mode;
57  
58      /*
59       * The string specifying the directory to display
60       * in the file dialog.  This variable may be <code>null</code>.
61       *
62       * @serial
63       * @see getDirectory()
64       * @see setDirectory()
65       */
66      String   dir;
67  
68      /*
69       * The string specifying the initial value of the
70       * filename text field in the file dialog.
71       * This variable may be <code>null</code>.
72       *
73       * @serial
74       * @see getFile()
75       * @see setFile()
76       */
77      String   file;
78  
79      /*
80       * The filter used as the file dialog's filename filter.
81       * The file dialog will only be displaying files whose
82       * names are accepted by this filter.
83       * This variable may be <code>null</code>.
84       *
85       * @serial
86       * @see #getFilenameFilter()
87       * @see #setFilenameFilter()
88       * @see FileNameFilter
89       */
90      FilenameFilter   filter;
91  
92      private static final String   base = "filedlg";
93      private static int nameCounter = 0;
94  
95      /*
96       * JDK 1.1 serialVersionUID
97       */
98       private static final long serialVersionUID = 5035145889651310422L;
99  
100 
101     static {
102         /* ensure that the necessary native libraries are loaded */
103     Toolkit.loadLibraries();
104         if (!GraphicsEnvironment.isHeadless()) {
105             initIDs();
106         }
107     }
108 
109     /**
110      * Initialize JNI field and method IDs for fields that may be
111        accessed from C.
112      */
113     private static native void initIDs();
114 
115     /**
116      * Creates a file dialog for loading a file.  The title of the
117      * file dialog is initially empty.  This is a convenience method for
118      * <code>FileDialog(parent, "", LOAD)</code>.
119      *
120      * @param parent the owner of the dialog
121      * @since JDK1.1
122      */
123     public FileDialog(Frame   parent) {
124     this(parent, "", LOAD);
125     }
126 
127     /**
128      * Creates a file dialog window with the specified title for loading
129      * a file. The files shown are those in the current directory.
130      * This is a convenience method for
131      * <code>FileDialog(parent, title, LOAD)</code>.
132      *
133      * @param     parent   the owner of the dialog
134      * @param     title    the title of the dialog
135      */
136     public FileDialog(Frame   parent, String   title) {
137     this(parent, title, LOAD);
138     }
139 
140     /**
141      * Creates a file dialog window with the specified title for loading
142      * or saving a file.
143      * <p>
144      * If the value of <code>mode</code> is <code>LOAD</code>, then the
145      * file dialog is finding a file to read, and the files shown are those
146      * in the current directory.   If the value of
147      * <code>mode</code> is <code>SAVE</code>, the file dialog is finding
148      * a place to write a file.
149      *
150      * @param     parent   the owner of the dialog
151      * @param     title   the title of the dialog
152      * @param     mode   the mode of the dialog; either
153      *      <code>FileDialog.LOAD</code> or <code>FileDialog.SAVE</code>
154      * @exception  IllegalArgumentException if an illegal file
155      *                 dialog mode is supplied
156      * @see       java.awt.FileDialog#LOAD
157      * @see       java.awt.FileDialog#SAVE
158      */
159     public FileDialog(Frame   parent, String   title, int mode) {
160     super(parent, title, true);
161         this.setMode(mode);
162     setLayout(null);
163     }
164 
165     /**
166      * Creates a file dialog for loading a file.  The title of the
167      * file dialog is initially empty.  This is a convenience method for
168      * <code>FileDialog(parent, "", LOAD)</code>.
169      *
170      * @param     parent   the owner of the dialog
171      * @exception java.lang.IllegalArgumentException if the <code>parent</code>'s
172      *            <code>GraphicsConfiguration</code>
173      *            is not from a screen device;
174      * @exception java.lang.IllegalArgumentException if <code>parent</code>
175      *            is <code>null</code>; this exception is always thrown when
176      *            <code>GraphicsEnvironment.isHeadless</code>
177      *            returns <code>true</code>
178      * @see java.awt.GraphicsEnvironment#isHeadless
179      * @since 1.5
180      */
181     public FileDialog(Dialog   parent) {
182         this(parent, "", LOAD);
183     }
184 
185     /**
186      * Creates a file dialog window with the specified title for loading
187      * a file. The files shown are those in the current directory.
188      * This is a convenience method for
189      * <code>FileDialog(parent, title, LOAD)</code>.
190      *
191      * @param     parent   the owner of the dialog
192      * @param     title    the title of the dialog; a <code>null</code> value
193      *                     will be accepted without causing a
194      *                     <code>NullPointerException</code> to be thrown
195      * @exception java.lang.IllegalArgumentException if the <code>parent</code>'s
196      *            <code>GraphicsConfiguration</code>
197      *            is not from a screen device;
198      * @exception java.lang.IllegalArgumentException if <code>parent</code>
199      *            is <code>null</code>; this exception is always thrown when
200      *            <code>GraphicsEnvironment.isHeadless</code>
201      *            returns <code>true</code>
202      * @see java.awt.GraphicsEnvironment#isHeadless
203      * @since     1.5
204      */
205     public FileDialog(Dialog   parent, String   title) {
206         this(parent, title, LOAD);
207     }
208 
209     /**
210      * Creates a file dialog window with the specified title for loading
211      * or saving a file.
212      * <p>
213      * If the value of <code>mode</code> is <code>LOAD</code>, then the
214      * file dialog is finding a file to read, and the files shown are those
215      * in the current directory.   If the value of
216      * <code>mode</code> is <code>SAVE</code>, the file dialog is finding
217      * a place to write a file.
218      *
219      * @param     parent   the owner of the dialog
220      * @param     title    the title of the dialog; a <code>null</code> value
221      *                     will be accepted without causing a
222      *                     <code>NullPointerException</code> to be thrown
223      * @param     mode     the mode of the dialog; either
224      *                 <code>FileDialog.LOAD</code> or <code>FileDialog.SAVE</code>
225      * @exception java.lang.IllegalArgumentException if an illegal 
226      *            file dialog mode is supplied;
227      * @exception java.lang.IllegalArgumentException if the <code>parent</code>'s
228      *            <code>GraphicsConfiguration</code>
229      *            is not from a screen device;
230      * @exception java.lang.IllegalArgumentException if <code>parent</code>
231      *            is <code>null</code>; this exception is always thrown when
232      *            <code>GraphicsEnvironment.isHeadless</code>
233      *            returns <code>true</code>
234      * @see       java.awt.GraphicsEnvironment#isHeadless
235      * @see       java.awt.FileDialog#LOAD
236      * @see       java.awt.FileDialog#SAVE
237      * @since     1.5
238      */
239     public FileDialog(Dialog   parent, String   title, int mode) {
240         super(parent, title, true);
241         this.setMode(mode);
242         setLayout(null);
243     }
244 
245     /**
246      * Constructs a name for this component. Called by <code>getName()</code>
247      * when the name is <code>null</code>.
248      */
249     String   constructComponentName() {
250         synchronized (getClass()) {
251         return base + nameCounter++;
252     }
253     }
254 
255     /**
256      * Creates the file dialog's peer.  The peer allows us to change the look
257      * of the file dialog without changing its functionality.
258      */
259     public void addNotify() {
260         synchronized(getTreeLock()) {
261         if (parent != null && parent.getPeer() == null) {
262         parent.addNotify();
263         }
264         if (peer == null)
265             peer = getToolkit().createFileDialog(this);
266         super.addNotify();
267     }
268     }
269 
270     /**
271      * Indicates whether this file dialog box is for loading from a file
272      * or for saving to a file.
273      *
274      * @return   the mode of this file dialog window, either
275      *               <code>FileDialog.LOAD</code> or
276      *               <code>FileDialog.SAVE</code>
277      * @see      java.awt.FileDialog#LOAD
278      * @see      java.awt.FileDialog#SAVE
279      * @see      java.awt.FileDialog#setMode
280      */
281     public int getMode() {
282     return mode;
283     }
284 
285     /**
286      * Sets the mode of the file dialog.  If <code>mode</code> is not
287      * a legal value, an exception will be thrown and <code>mode</code>
288      * will not be set.
289      *
290      * @param      mode  the mode for this file dialog, either
291      *                 <code>FileDialog.LOAD</code> or
292      *                 <code>FileDialog.SAVE</code>
293      * @see        java.awt.FileDialog#LOAD
294      * @see        java.awt.FileDialog#SAVE
295      * @see        java.awt.FileDialog#getMode
296      * @exception  IllegalArgumentException if an illegal file
297      *                 dialog mode is supplied
298      * @since      JDK1.1
299      */
300     public void setMode(int mode) {
301     switch (mode) {
302       case LOAD:
303       case SAVE:
304         this.mode = mode;
305         break;
306       default:
307         throw new IllegalArgumentException  ("illegal file dialog mode");
308     }
309     }
310 
311     /**
312      * Gets the directory of this file dialog.
313      *
314      * @return  the (potentially <code>null</code> or invalid)
315      *      directory of this <code>FileDialog</code>
316      * @see       java.awt.FileDialog#setDirectory
317      */
318     public String   getDirectory() {
319     return dir;
320     }
321 
322     /**
323      * Sets the directory of this file dialog window to be the
324      * specified directory. Specifying a <code>null</code> or an
325      * invalid directory implies an implementation-defined default.
326      * This default will not be realized, however, until the user
327      * has selected a file. Until this point, <code>getDirectory()</code>
328      * will return the value passed into this method.
329      * <p>
330      * Specifying "" as the directory is exactly equivalent to
331      * specifying <code>null</code> as the directory.
332      *
333      * @param     dir   the specified directory
334      * @see       java.awt.FileDialog#getDirectory
335      */
336     public void setDirectory(String   dir) {
337         this.dir = (dir != null && dir.equals("")) ? null : dir;
338     FileDialogPeer peer = (FileDialogPeer)this.peer;
339     if (peer != null) {
340         peer.setDirectory(this.dir);
341     }
342     }
343 
344     /**
345      * Gets the selected file of this file dialog.  If the user
346      * selected <code>CANCEL</code>, the returned file is <code>null</code>.
347      *
348      * @return    the currently selected file of this file dialog window,
349      *                or <code>null</code> if none is selected
350      * @see       java.awt.FileDialog#setFile
351      */
352     public String   getFile() {
353     return file;
354     }
355 
356     /**
357      * Sets the selected file for this file dialog window to be the
358      * specified file. This file becomes the default file if it is set
359      * before the file dialog window is first shown.
360      * <p>
361      * Specifying "" as the file is exactly equivalent to specifying
362      * <code>null</code>
363      * as the file.
364      *
365      * @param    file   the file being set
366      * @see      java.awt.FileDialog#getFile
367      */
368     public void setFile(String   file) {
369         this.file = (file != null && file.equals("")) ? null : file;
370     FileDialogPeer peer = (FileDialogPeer)this.peer;
371     if (peer != null) {
372         peer.setFile(this.file);
373     }
374     }
375 
376     /**
377      * Determines this file dialog's filename filter. A filename filter
378      * allows the user to specify which files appear in the file dialog
379      * window.  Filename filters do not function in Sun's reference
380      * implementation for Microsoft Windows.
381      *
382      * @return    this file dialog's filename filter
383      * @see       java.io.FilenameFilter
384      * @see       java.awt.FileDialog#setFilenameFilter
385      */
386     public FilenameFilter   getFilenameFilter() {
387     return filter;
388     }
389 
390     /**
391      * Sets the filename filter for this file dialog window to the
392      * specified filter.
393      * Filename filters do not function in Sun's reference
394      * implementation for Microsoft Windows.
395      *
396      * @param   filter   the specified filter
397      * @see     java.io.FilenameFilter
398      * @see     java.awt.FileDialog#getFilenameFilter
399      */
400     public synchronized void setFilenameFilter(FilenameFilter   filter) {
401     this.filter = filter;
402     FileDialogPeer peer = (FileDialogPeer)this.peer;
403     if (peer != null) {
404         peer.setFilenameFilter(filter);
405     }
406     }
407 
408     /** 
409      * Reads the <code>ObjectInputStream</code> and performs
410      * a backwards compatibility check by converting
411      * either a <code>dir</code> or a <code>file</code>
412      * equal to an empty string to <code>null</code>.
413      *
414      * @param s the <code>ObjectInputStream</code> to read
415      */
416     private void readObject(ObjectInputStream   s)
417         throws ClassNotFoundException  , IOException  
418     {
419         s.defaultReadObject();
420 
421     // 1.1 Compatibility: "" is not converted to null in 1.1
422     if (dir != null && dir.equals("")) {
423         dir = null;
424     }
425     if (file != null && file.equals("")) {
426         file = null;
427     }
428     }
429 
430     /**
431      * Returns a string representing the state of this <code>FileDialog</code>
432      * window. This method is intended to be used only for debugging purposes,
433      * and the content and format of the returned string may vary between 
434      * implementations. The returned string may be empty but may not be 
435      * <code>null</code>.
436      *
437      * @return  the parameter string of this file dialog window
438      */
439     protected String   paramString() {
440     String   str = super.paramString();
441     str += ",dir= " + dir;
442     str += ",file= " + file;
443     return str + ((mode == LOAD) ? ",load" : ",save");
444     }
445 
446     boolean postsOldMouseEvents() {
447         return false;
448     }
449 }
450
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags