1 /*
   2  * Copyright (c) 1995, 2015, Oracle and/or its affiliates. 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.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * 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 import java.io.File;
  32 import sun.awt.AWTAccessor;
  33 
  34 /**
  35  * The <code>FileDialog</code> class displays a dialog window
  36  * from which the user can select a file.
  37  * <p>
  38  * Since it is a modal dialog, when the application calls
  39  * its <code>show</code> method to display the dialog,
  40  * it blocks the rest of the application until the user has
  41  * chosen a file.
  42  *
  43  * @see Window#show
  44  *
  45  * @author      Sami Shaio
  46  * @author      Arthur van Hoff
  47  * @since       1.0
  48  */
  49 public class FileDialog extends Dialog {
  50 
  51     /**
  52      * This constant value indicates that the purpose of the file
  53      * dialog window is to locate a file from which to read.
  54      */
  55     public static final int LOAD = 0;
  56 
  57     /**
  58      * This constant value indicates that the purpose of the file
  59      * dialog window is to locate a file to which to write.
  60      */
  61     public static final int SAVE = 1;
  62 
  63     /*
  64      * There are two <code>FileDialog</code> modes: <code>LOAD</code> and
  65      * <code>SAVE</code>.
  66      * This integer will represent one or the other.
  67      * If the mode is not specified it will default to <code>LOAD</code>.
  68      *
  69      * @serial
  70      * @see getMode()
  71      * @see setMode()
  72      * @see java.awt.FileDialog#LOAD
  73      * @see java.awt.FileDialog#SAVE
  74      */
  75     int mode;
  76 
  77     /*
  78      * The string specifying the directory to display
  79      * in the file dialog.  This variable may be <code>null</code>.
  80      *
  81      * @serial
  82      * @see getDirectory()
  83      * @see setDirectory()
  84      */
  85     String dir;
  86 
  87     /*
  88      * The string specifying the initial value of the
  89      * filename text field in the file dialog.
  90      * This variable may be <code>null</code>.
  91      *
  92      * @serial
  93      * @see getFile()
  94      * @see setFile()
  95      */
  96     String file;
  97 
  98     /**
  99      * Contains the File instances for all the files that the user selects.
 100      *
 101      * @serial
 102      * @see #getFiles
 103      * @since 1.7
 104      */
 105     private File[] files;
 106 
 107     /**
 108      * Represents whether the file dialog allows the multiple file selection.
 109      *
 110      * @serial
 111      * @see #setMultipleMode
 112      * @see #isMultipleMode
 113      * @since 1.7
 114      */
 115     private boolean multipleMode = false;
 116 
 117     /*
 118      * The filter used as the file dialog's filename filter.
 119      * The file dialog will only be displaying files whose
 120      * names are accepted by this filter.
 121      * This variable may be <code>null</code>.
 122      *
 123      * @serial
 124      * @see #getFilenameFilter()
 125      * @see #setFilenameFilter()
 126      * @see FileNameFilter
 127      */
 128     FilenameFilter filter;
 129 
 130     private static final String base = "filedlg";
 131     private static int nameCounter = 0;
 132 
 133     /*
 134      * JDK 1.1 serialVersionUID
 135      */
 136      private static final long serialVersionUID = 5035145889651310422L;
 137 
 138 
 139     static {
 140         /* ensure that the necessary native libraries are loaded */
 141         Toolkit.loadLibraries();
 142         if (!GraphicsEnvironment.isHeadless()) {
 143             initIDs();
 144         }
 145     }
 146 
 147     static {
 148         AWTAccessor.setFileDialogAccessor(
 149             new AWTAccessor.FileDialogAccessor() {
 150                 public void setFiles(FileDialog fileDialog, File files[]) {
 151                     fileDialog.setFiles(files);
 152                 }
 153                 public void setFile(FileDialog fileDialog, String file) {
 154                     fileDialog.file = ("".equals(file)) ? null : file;
 155                 }
 156                 public void setDirectory(FileDialog fileDialog, String directory) {
 157                     fileDialog.dir = ("".equals(directory)) ? null : directory;
 158                 }
 159                 public boolean isMultipleMode(FileDialog fileDialog) {
 160                     synchronized (fileDialog.getObjectLock()) {
 161                         return fileDialog.multipleMode;
 162                     }
 163                 }
 164             });
 165     }
 166 
 167     /**
 168      * Initialize JNI field and method IDs for fields that may be
 169        accessed from C.
 170      */
 171     private static native void initIDs();
 172 
 173     /**
 174      * Creates a file dialog for loading a file.  The title of the
 175      * file dialog is initially empty.  This is a convenience method for
 176      * <code>FileDialog(parent, "", LOAD)</code>.
 177      *
 178      * @param parent the owner of the dialog
 179      * @since 1.1
 180      */
 181     public FileDialog(Frame 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
 193      */
 194     public FileDialog(Frame parent, String title) {
 195         this(parent, title, LOAD);
 196     }
 197 
 198     /**
 199      * Creates a file dialog window with the specified title for loading
 200      * or saving a file.
 201      * <p>
 202      * If the value of <code>mode</code> is <code>LOAD</code>, then the
 203      * file dialog is finding a file to read, and the files shown are those
 204      * in the current directory.   If the value of
 205      * <code>mode</code> is <code>SAVE</code>, the file dialog is finding
 206      * a place to write a file.
 207      *
 208      * @param     parent   the owner of the dialog
 209      * @param     title   the title of the dialog
 210      * @param     mode   the mode of the dialog; either
 211      *          <code>FileDialog.LOAD</code> or <code>FileDialog.SAVE</code>
 212      * @exception  IllegalArgumentException if an illegal file
 213      *                 dialog mode is supplied
 214      * @see       java.awt.FileDialog#LOAD
 215      * @see       java.awt.FileDialog#SAVE
 216      */
 217     public FileDialog(Frame parent, String title, int mode) {
 218         super(parent, title, true);
 219         this.setMode(mode);
 220         setLayout(null);
 221     }
 222 
 223     /**
 224      * Creates a file dialog for loading a file.  The title of the
 225      * file dialog is initially empty.  This is a convenience method for
 226      * <code>FileDialog(parent, "", LOAD)</code>.
 227      *
 228      * @param     parent   the owner of the dialog
 229      * @exception java.lang.IllegalArgumentException if the <code>parent</code>'s
 230      *            <code>GraphicsConfiguration</code>
 231      *            is not from a screen device;
 232      * @exception java.lang.IllegalArgumentException if <code>parent</code>
 233      *            is <code>null</code>; this exception is always thrown when
 234      *            <code>GraphicsEnvironment.isHeadless</code>
 235      *            returns <code>true</code>
 236      * @see java.awt.GraphicsEnvironment#isHeadless
 237      * @since 1.5
 238      */
 239     public FileDialog(Dialog parent) {
 240         this(parent, "", LOAD);
 241     }
 242 
 243     /**
 244      * Creates a file dialog window with the specified title for loading
 245      * a file. The files shown are those in the current directory.
 246      * This is a convenience method for
 247      * <code>FileDialog(parent, title, LOAD)</code>.
 248      *
 249      * @param     parent   the owner of the dialog
 250      * @param     title    the title of the dialog; a <code>null</code> value
 251      *                     will be accepted without causing a
 252      *                     <code>NullPointerException</code> to be thrown
 253      * @exception java.lang.IllegalArgumentException if the <code>parent</code>'s
 254      *            <code>GraphicsConfiguration</code>
 255      *            is not from a screen device;
 256      * @exception java.lang.IllegalArgumentException if <code>parent</code>
 257      *            is <code>null</code>; this exception is always thrown when
 258      *            <code>GraphicsEnvironment.isHeadless</code>
 259      *            returns <code>true</code>
 260      * @see java.awt.GraphicsEnvironment#isHeadless
 261      * @since     1.5
 262      */
 263     public FileDialog(Dialog parent, String title) {
 264         this(parent, title, LOAD);
 265     }
 266 
 267     /**
 268      * Creates a file dialog window with the specified title for loading
 269      * or saving a file.
 270      * <p>
 271      * If the value of <code>mode</code> is <code>LOAD</code>, then the
 272      * file dialog is finding a file to read, and the files shown are those
 273      * in the current directory.   If the value of
 274      * <code>mode</code> is <code>SAVE</code>, the file dialog is finding
 275      * a place to write a file.
 276      *
 277      * @param     parent   the owner of the dialog
 278      * @param     title    the title of the dialog; a <code>null</code> value
 279      *                     will be accepted without causing a
 280      *                     <code>NullPointerException</code> to be thrown
 281      * @param     mode     the mode of the dialog; either
 282      *                     <code>FileDialog.LOAD</code> or <code>FileDialog.SAVE</code>
 283      * @exception java.lang.IllegalArgumentException if an illegal
 284      *            file dialog mode is supplied;
 285      * @exception java.lang.IllegalArgumentException if the <code>parent</code>'s
 286      *            <code>GraphicsConfiguration</code>
 287      *            is not from a screen device;
 288      * @exception java.lang.IllegalArgumentException if <code>parent</code>
 289      *            is <code>null</code>; this exception is always thrown when
 290      *            <code>GraphicsEnvironment.isHeadless</code>
 291      *            returns <code>true</code>
 292      * @see       java.awt.GraphicsEnvironment#isHeadless
 293      * @see       java.awt.FileDialog#LOAD
 294      * @see       java.awt.FileDialog#SAVE
 295      * @since     1.5
 296      */
 297     public FileDialog(Dialog parent, String title, int mode) {
 298         super(parent, title, true);
 299         this.setMode(mode);
 300         setLayout(null);
 301     }
 302 
 303     /**
 304      * Constructs a name for this component. Called by <code>getName()</code>
 305      * when the name is <code>null</code>.
 306      */
 307     String constructComponentName() {
 308         synchronized (FileDialog.class) {
 309             return base + nameCounter++;
 310         }
 311     }
 312 
 313     /**
 314      * Creates the file dialog's peer.  The peer allows us to change the look
 315      * of the file dialog without changing its functionality.
 316      */
 317     public void addNotify() {
 318         synchronized(getTreeLock()) {
 319             if (parent != null && parent.peer == null) {
 320                 parent.addNotify();
 321             }
 322             if (peer == null)
 323                 peer = getComponentFactory().createFileDialog(this);
 324             super.addNotify();
 325         }
 326     }
 327 
 328     /**
 329      * Indicates whether this file dialog box is for loading from a file
 330      * or for saving to a file.
 331      *
 332      * @return   the mode of this file dialog window, either
 333      *               <code>FileDialog.LOAD</code> or
 334      *               <code>FileDialog.SAVE</code>
 335      * @see      java.awt.FileDialog#LOAD
 336      * @see      java.awt.FileDialog#SAVE
 337      * @see      java.awt.FileDialog#setMode
 338      */
 339     public int getMode() {
 340         return mode;
 341     }
 342 
 343     /**
 344      * Sets the mode of the file dialog.  If <code>mode</code> is not
 345      * a legal value, an exception will be thrown and <code>mode</code>
 346      * will not be set.
 347      *
 348      * @param      mode  the mode for this file dialog, either
 349      *                 <code>FileDialog.LOAD</code> or
 350      *                 <code>FileDialog.SAVE</code>
 351      * @see        java.awt.FileDialog#LOAD
 352      * @see        java.awt.FileDialog#SAVE
 353      * @see        java.awt.FileDialog#getMode
 354      * @exception  IllegalArgumentException if an illegal file
 355      *                 dialog mode is supplied
 356      * @since      1.1
 357      */
 358     public void setMode(int mode) {
 359         switch (mode) {
 360           case LOAD:
 361           case SAVE:
 362             this.mode = mode;
 363             break;
 364           default:
 365             throw new IllegalArgumentException("illegal file dialog mode");
 366         }
 367     }
 368 
 369     /**
 370      * Gets the directory of this file dialog.
 371      *
 372      * @return  the (potentially <code>null</code> or invalid)
 373      *          directory of this <code>FileDialog</code>
 374      * @see       java.awt.FileDialog#setDirectory
 375      */
 376     public String getDirectory() {
 377         return dir;
 378     }
 379 
 380     /**
 381      * Sets the directory of this file dialog window to be the
 382      * specified directory. Specifying a <code>null</code> or an
 383      * invalid directory implies an implementation-defined default.
 384      * This default will not be realized, however, until the user
 385      * has selected a file. Until this point, <code>getDirectory()</code>
 386      * will return the value passed into this method.
 387      * <p>
 388      * Specifying "" as the directory is exactly equivalent to
 389      * specifying <code>null</code> as the directory.
 390      *
 391      * @param     dir   the specified directory
 392      * @see       java.awt.FileDialog#getDirectory
 393      */
 394     public void setDirectory(String dir) {
 395         this.dir = (dir != null && dir.equals("")) ? null : dir;
 396         FileDialogPeer peer = (FileDialogPeer)this.peer;
 397         if (peer != null) {
 398             peer.setDirectory(this.dir);
 399         }
 400     }
 401 
 402     /**
 403      * Gets the selected file of this file dialog.  If the user
 404      * selected <code>CANCEL</code>, the returned file is <code>null</code>.
 405      *
 406      * @return    the currently selected file of this file dialog window,
 407      *                or <code>null</code> if none is selected
 408      * @see       java.awt.FileDialog#setFile
 409      */
 410     public String getFile() {
 411         return file;
 412     }
 413 
 414     /**
 415      * Returns files that the user selects.
 416      * <p>
 417      * If the user cancels the file dialog,
 418      * then the method returns an empty array.
 419      *
 420      * @return    files that the user selects or an empty array
 421      *            if the user cancels the file dialog.
 422      * @see       #setFile(String)
 423      * @see       #getFile
 424      * @since 1.7
 425      */
 426     public File[] getFiles() {
 427         synchronized (getObjectLock()) {
 428             if (files != null) {
 429                 return files.clone();
 430             } else {
 431                 return new File[0];
 432             }
 433         }
 434     }
 435 
 436     /**
 437      * Stores the names of all the files that the user selects.
 438      *
 439      * Note that the method is private and it's intended to be used
 440      * by the peers through the AWTAccessor API.
 441      *
 442      * @param files     the array that contains the short names of
 443      *                  all the files that the user selects.
 444      *
 445      * @see #getFiles
 446      * @since 1.7
 447      */
 448     private void setFiles(File files[]) {
 449         synchronized (getObjectLock()) {
 450             this.files = files;
 451         }
 452     }
 453 
 454     /**
 455      * Sets the selected file for this file dialog window to be the
 456      * specified file. This file becomes the default file if it is set
 457      * before the file dialog window is first shown.
 458      * <p>
 459      * When the dialog is shown, the specified file is selected. The kind of
 460      * selection depends on the file existence, the dialog type, and the native
 461      * platform. E.g., the file could be highlighted in the file list, or a
 462      * file name editbox could be populated with the file name.
 463      * <p>
 464      * This method accepts either a full file path, or a file name with an
 465      * extension if used together with the {@code setDirectory} method.
 466      * <p>
 467      * Specifying "" as the file is exactly equivalent to specifying
 468      * {@code null} as the file.
 469      *
 470      * @param    file   the file being set
 471      * @see      #getFile
 472      * @see      #getFiles
 473      */
 474     public void setFile(String file) {
 475         this.file = (file != null && file.equals("")) ? null : file;
 476         FileDialogPeer peer = (FileDialogPeer)this.peer;
 477         if (peer != null) {
 478             peer.setFile(this.file);
 479         }
 480     }
 481 
 482     /**
 483      * Enables or disables multiple file selection for the file dialog.
 484      *
 485      * @param enable    if {@code true}, multiple file selection is enabled;
 486      *                  {@code false} - disabled.
 487      * @see #isMultipleMode
 488      * @since 1.7
 489      */
 490     public void setMultipleMode(boolean enable) {
 491         synchronized (getObjectLock()) {
 492             this.multipleMode = enable;
 493         }
 494     }
 495 
 496     /**
 497      * Returns whether the file dialog allows the multiple file selection.
 498      *
 499      * @return          {@code true} if the file dialog allows the multiple
 500      *                  file selection; {@code false} otherwise.
 501      * @see #setMultipleMode
 502      * @since 1.7
 503      */
 504     public boolean isMultipleMode() {
 505         synchronized (getObjectLock()) {
 506             return multipleMode;
 507         }
 508     }
 509 
 510     /**
 511      * Determines this file dialog's filename filter. A filename filter
 512      * allows the user to specify which files appear in the file dialog
 513      * window.  Filename filters do not function in Sun's reference
 514      * implementation for Microsoft Windows.
 515      *
 516      * @return    this file dialog's filename filter
 517      * @see       java.io.FilenameFilter
 518      * @see       java.awt.FileDialog#setFilenameFilter
 519      */
 520     public FilenameFilter getFilenameFilter() {
 521         return filter;
 522     }
 523 
 524     /**
 525      * Sets the filename filter for this file dialog window to the
 526      * specified filter.
 527      * Filename filters do not function in Sun's reference
 528      * implementation for Microsoft Windows.
 529      *
 530      * @param   filter   the specified filter
 531      * @see     java.io.FilenameFilter
 532      * @see     java.awt.FileDialog#getFilenameFilter
 533      */
 534     public synchronized void setFilenameFilter(FilenameFilter filter) {
 535         this.filter = filter;
 536         FileDialogPeer peer = (FileDialogPeer)this.peer;
 537         if (peer != null) {
 538             peer.setFilenameFilter(filter);
 539         }
 540     }
 541 
 542     /**
 543      * Reads the <code>ObjectInputStream</code> and performs
 544      * a backwards compatibility check by converting
 545      * either a <code>dir</code> or a <code>file</code>
 546      * equal to an empty string to <code>null</code>.
 547      *
 548      * @param s the <code>ObjectInputStream</code> to read
 549      */
 550     private void readObject(ObjectInputStream s)
 551         throws ClassNotFoundException, IOException
 552     {
 553         s.defaultReadObject();
 554 
 555         // 1.1 Compatibility: "" is not converted to null in 1.1
 556         if (dir != null && dir.equals("")) {
 557             dir = null;
 558         }
 559         if (file != null && file.equals("")) {
 560             file = null;
 561         }
 562     }
 563 
 564     /**
 565      * Returns a string representing the state of this <code>FileDialog</code>
 566      * window. This method is intended to be used only for debugging purposes,
 567      * and the content and format of the returned string may vary between
 568      * implementations. The returned string may be empty but may not be
 569      * <code>null</code>.
 570      *
 571      * @return  the parameter string of this file dialog window
 572      */
 573     protected String paramString() {
 574         String str = super.paramString();
 575         str += ",dir= " + dir;
 576         str += ",file= " + file;
 577         return str + ((mode == LOAD) ? ",load" : ",save");
 578     }
 579 
 580     boolean postsOldMouseEvents() {
 581         return false;
 582     }
 583 }