001 /*
002 * Copyright 1995-2006 Sun Microsystems, Inc. All Rights Reserved.
003 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
004 *
005 * This code is free software; you can redistribute it and/or modify it
006 * under the terms of the GNU General Public License version 2 only, as
007 * published by the Free Software Foundation. Sun designates this
008 * particular file as subject to the "Classpath" exception as provided
009 * by Sun in the LICENSE file that accompanied this code.
010 *
011 * This code is distributed in the hope that it will be useful, but WITHOUT
012 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
013 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
014 * version 2 for more details (a copy is included in the LICENSE file that
015 * accompanied this code).
016 *
017 * You should have received a copy of the GNU General Public License version
018 * 2 along with this work; if not, write to the Free Software Foundation,
019 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
020 *
021 * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
022 * CA 95054 USA or visit www.sun.com if you need additional information or
023 * have any questions.
024 */
025 package java.awt;
026
027 import java.awt.peer.FileDialogPeer;
028 import java.io.FilenameFilter;
029 import java.io.IOException;
030 import java.io.ObjectInputStream;
031
032 /**
033 * The <code>FileDialog</code> class displays a dialog window
034 * from which the user can select a file.
035 * <p>
036 * Since it is a modal dialog, when the application calls
037 * its <code>show</code> method to display the dialog,
038 * it blocks the rest of the application until the user has
039 * chosen a file.
040 *
041 * @see Window#show
042 *
043 * @version 1.62, 05/05/07
044 * @author Sami Shaio
045 * @author Arthur van Hoff
046 * @since JDK1.0
047 */
048 public class FileDialog extends Dialog {
049
050 /**
051 * This constant value indicates that the purpose of the file
052 * dialog window is to locate a file from which to read.
053 */
054 public static final int LOAD = 0;
055
056 /**
057 * This constant value indicates that the purpose of the file
058 * dialog window is to locate a file to which to write.
059 */
060 public static final int SAVE = 1;
061
062 /*
063 * There are two <code>FileDialog</code> modes: <code>LOAD</code> and
064 * <code>SAVE</code>.
065 * This integer will represent one or the other.
066 * If the mode is not specified it will default to <code>LOAD</code>.
067 *
068 * @serial
069 * @see getMode()
070 * @see setMode()
071 * @see java.awt.FileDialog#LOAD
072 * @see java.awt.FileDialog#SAVE
073 */
074 int mode;
075
076 /*
077 * The string specifying the directory to display
078 * in the file dialog. This variable may be <code>null</code>.
079 *
080 * @serial
081 * @see getDirectory()
082 * @see setDirectory()
083 */
084 String dir;
085
086 /*
087 * The string specifying the initial value of the
088 * filename text field in the file dialog.
089 * This variable may be <code>null</code>.
090 *
091 * @serial
092 * @see getFile()
093 * @see setFile()
094 */
095 String file;
096
097 /*
098 * The filter used as the file dialog's filename filter.
099 * The file dialog will only be displaying files whose
100 * names are accepted by this filter.
101 * This variable may be <code>null</code>.
102 *
103 * @serial
104 * @see #getFilenameFilter()
105 * @see #setFilenameFilter()
106 * @see FileNameFilter
107 */
108 FilenameFilter filter;
109
110 private static final String base = "filedlg";
111 private static int nameCounter = 0;
112
113 /*
114 * JDK 1.1 serialVersionUID
115 */
116 private static final long serialVersionUID = 5035145889651310422L;
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(
325 "illegal file dialog mode");
326 }
327 }
328
329 /**
330 * Gets the directory of this file dialog.
331 *
332 * @return the (potentially <code>null</code> or invalid)
333 * directory of this <code>FileDialog</code>
334 * @see java.awt.FileDialog#setDirectory
335 */
336 public String getDirectory() {
337 return dir;
338 }
339
340 /**
341 * Sets the directory of this file dialog window to be the
342 * specified directory. Specifying a <code>null</code> or an
343 * invalid directory implies an implementation-defined default.
344 * This default will not be realized, however, until the user
345 * has selected a file. Until this point, <code>getDirectory()</code>
346 * will return the value passed into this method.
347 * <p>
348 * Specifying "" as the directory is exactly equivalent to
349 * specifying <code>null</code> as the directory.
350 *
351 * @param dir the specified directory
352 * @see java.awt.FileDialog#getDirectory
353 */
354 public void setDirectory(String dir) {
355 this .dir = (dir != null && dir.equals("")) ? null : dir;
356 FileDialogPeer peer = (FileDialogPeer) this .peer;
357 if (peer != null) {
358 peer.setDirectory(this .dir);
359 }
360 }
361
362 /**
363 * Gets the selected file of this file dialog. If the user
364 * selected <code>CANCEL</code>, the returned file is <code>null</code>.
365 *
366 * @return the currently selected file of this file dialog window,
367 * or <code>null</code> if none is selected
368 * @see java.awt.FileDialog#setFile
369 */
370 public String getFile() {
371 return file;
372 }
373
374 /**
375 * Sets the selected file for this file dialog window to be the
376 * specified file. This file becomes the default file if it is set
377 * before the file dialog window is first shown.
378 * <p>
379 * Specifying "" as the file is exactly equivalent to specifying
380 * <code>null</code>
381 * as the file.
382 *
383 * @param file the file being set
384 * @see java.awt.FileDialog#getFile
385 */
386 public void setFile(String file) {
387 this .file = (file != null && file.equals("")) ? null : file;
388 FileDialogPeer peer = (FileDialogPeer) this .peer;
389 if (peer != null) {
390 peer.setFile(this .file);
391 }
392 }
393
394 /**
395 * Determines this file dialog's filename filter. A filename filter
396 * allows the user to specify which files appear in the file dialog
397 * window. Filename filters do not function in Sun's reference
398 * implementation for Microsoft Windows.
399 *
400 * @return this file dialog's filename filter
401 * @see java.io.FilenameFilter
402 * @see java.awt.FileDialog#setFilenameFilter
403 */
404 public FilenameFilter getFilenameFilter() {
405 return filter;
406 }
407
408 /**
409 * Sets the filename filter for this file dialog window to the
410 * specified filter.
411 * Filename filters do not function in Sun's reference
412 * implementation for Microsoft Windows.
413 *
414 * @param filter the specified filter
415 * @see java.io.FilenameFilter
416 * @see java.awt.FileDialog#getFilenameFilter
417 */
418 public synchronized void setFilenameFilter(FilenameFilter filter) {
419 this .filter = filter;
420 FileDialogPeer peer = (FileDialogPeer) this .peer;
421 if (peer != null) {
422 peer.setFilenameFilter(filter);
423 }
424 }
425
426 /**
427 * Reads the <code>ObjectInputStream</code> and performs
428 * a backwards compatibility check by converting
429 * either a <code>dir</code> or a <code>file</code>
430 * equal to an empty string to <code>null</code>.
431 *
432 * @param s the <code>ObjectInputStream</code> to read
433 */
434 private void readObject(ObjectInputStream s)
435 throws ClassNotFoundException, IOException {
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 }
|