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