Home » openjdk-7 » java » awt » [javadoc | source]

    1   /*
    2    * Copyright (c) 1995, 2010, 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       JDK1.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, String directory, String files[]) {
  151                       fileDialog.setFiles(directory, 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 JDK1.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.getPeer() == null) {
  320                   parent.addNotify();
  321               }
  322               if (peer == null)
  323                   peer = getToolkit().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      JDK1.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 directory the current directory
  443        * @param files     the array that contains the short names of
  444        *                  all the files that the user selects.
  445        *
  446        * @see #getFiles
  447        * @since 1.7
  448        */
  449       private void setFiles(String directory, String files[]) {
  450           synchronized (getObjectLock()) {
  451               int filesNumber = (files != null) ? files.length : 0;
  452               this.files = new File[filesNumber];
  453               for (int i = 0; i < filesNumber; i++) {
  454                   this.files[i] = new File(directory, files[i]);
  455               }
  456           }
  457       }
  458   
  459       /**
  460        * Sets the selected file for this file dialog window to be the
  461        * specified file. This file becomes the default file if it is set
  462        * before the file dialog window is first shown.
  463        * <p>
  464        * Specifying "" as the file is exactly equivalent to specifying
  465        * <code>null</code>
  466        * as the file.
  467        *
  468        * @param    file   the file being set
  469        * @see      #getFile
  470        * @see      #getFiles
  471        */
  472       public void setFile(String file) {
  473           this.file = (file != null && file.equals("")) ? null : file;
  474           FileDialogPeer peer = (FileDialogPeer)this.peer;
  475           if (peer != null) {
  476               peer.setFile(this.file);
  477           }
  478       }
  479   
  480       /**
  481        * Enables or disables multiple file selection for the file dialog.
  482        *
  483        * @param enable    if {@code true}, multiple file selection is enabled;
  484        *                  {@code false} - disabled.
  485        * @see #isMultipleMode
  486        * @since 1.7
  487        */
  488       public void setMultipleMode(boolean enable) {
  489           synchronized (getObjectLock()) {
  490               this.multipleMode = enable;
  491           }
  492       }
  493   
  494       /**
  495        * Returns whether the file dialog allows the multiple file selection.
  496        *
  497        * @return          {@code true} if the file dialog allows the multiple
  498        *                  file selection; {@code false} otherwise.
  499        * @see #setMultipleMode
  500        * @since 1.7
  501        */
  502       public boolean isMultipleMode() {
  503           synchronized (getObjectLock()) {
  504               return multipleMode;
  505           }
  506       }
  507   
  508       /**
  509        * Determines this file dialog's filename filter. A filename filter
  510        * allows the user to specify which files appear in the file dialog
  511        * window.  Filename filters do not function in Sun's reference
  512        * implementation for Microsoft Windows.
  513        *
  514        * @return    this file dialog's filename filter
  515        * @see       java.io.FilenameFilter
  516        * @see       java.awt.FileDialog#setFilenameFilter
  517        */
  518       public FilenameFilter getFilenameFilter() {
  519           return filter;
  520       }
  521   
  522       /**
  523        * Sets the filename filter for this file dialog window to the
  524        * specified filter.
  525        * Filename filters do not function in Sun's reference
  526        * implementation for Microsoft Windows.
  527        *
  528        * @param   filter   the specified filter
  529        * @see     java.io.FilenameFilter
  530        * @see     java.awt.FileDialog#getFilenameFilter
  531        */
  532       public synchronized void setFilenameFilter(FilenameFilter filter) {
  533           this.filter = filter;
  534           FileDialogPeer peer = (FileDialogPeer)this.peer;
  535           if (peer != null) {
  536               peer.setFilenameFilter(filter);
  537           }
  538       }
  539   
  540       /**
  541        * Reads the <code>ObjectInputStream</code> and performs
  542        * a backwards compatibility check by converting
  543        * either a <code>dir</code> or a <code>file</code>
  544        * equal to an empty string to <code>null</code>.
  545        *
  546        * @param s the <code>ObjectInputStream</code> to read
  547        */
  548       private void readObject(ObjectInputStream s)
  549           throws ClassNotFoundException, IOException
  550       {
  551           s.defaultReadObject();
  552   
  553           // 1.1 Compatibility: "" is not converted to null in 1.1
  554           if (dir != null && dir.equals("")) {
  555               dir = null;
  556           }
  557           if (file != null && file.equals("")) {
  558               file = null;
  559           }
  560       }
  561   
  562       /**
  563        * Returns a string representing the state of this <code>FileDialog</code>
  564        * window. This method is intended to be used only for debugging purposes,
  565        * and the content and format of the returned string may vary between
  566        * implementations. The returned string may be empty but may not be
  567        * <code>null</code>.
  568        *
  569        * @return  the parameter string of this file dialog window
  570        */
  571       protected String paramString() {
  572           String str = super.paramString();
  573           str += ",dir= " + dir;
  574           str += ",file= " + file;
  575           return str + ((mode == LOAD) ? ",load" : ",save");
  576       }
  577   
  578       boolean postsOldMouseEvents() {
  579           return false;
  580       }
  581   }

Home » openjdk-7 » java » awt » [javadoc | source]