Using the JFC/Swing Packages

How to Use File Choosers

The JFileChooser class provides a UI for choosing a file from a list. A file chooser is a component that you can place anywhere within your program's GUI. However, programs typically display file choosers in modal dialogs because file operations are sensitive to changes within the program. The JFileChooser class makes it easy to bring up a modal dialog that contains a file chooser.

File choosers are most commonly used for two purposes:

• to present a list of files that can be opened by the application.
• to allow the user to select or enter the name of a file to be saved.

Note that the file chooser doesn't itself open or save files. It presents a GUI for choosing a file from a list. The program is responsible for then doing something with the file, such as opening or saving it.

Because most programmers just want an open file chooser or a save file chooser, the JFileChooser class provides convenience methods for displaying these types of file choosers in a dialog. Our first example, FileChooserDemo.java, illustrates the use of both:

When you click the Open button the program brings up an open file chooser. When you click the Save button the program brings up a save file chooser. Here's a picture of the the open file chooser:

Here's the code that creates and shows the open file chooser:

private JFileChooser filechooser = new JFileChooser();
...
int returnVal = filechooser.showOpenDialog(FileChooserDemo.this);

By default, a file chooser that hasn't been shown before displays all files in the user's home directory. You can specify the file chooser's initial directory using one of JFileChooser's other constructors, or you can set the directory with the setCurrentDirectory method.

The example program uses the same instance of JFileChooser to display the save file chooser. Here's the actionPerformed method for the Save button's listener:

private JFileChooser filechooser = new JFileChooser();
...
public void actionPerformed(ActionEvent e) {
    int returnVal = filechooser.showSaveDialog(FileChooserDemo.this);

    if (returnVal == JFileChooser.APPROVE_OPTION) {
	File file = filechooser.getSelectedFile();
	log.append("Saving: " + file.getName() + "." + newline);
    } else {
	log.append("Save command cancelled by user." + newline);
    }
}

By using the same file chooser for its open and save file chooser, the program reaps these benefits:

• The chooser remembers the current directory between uses so the open and save dialogs automatically share the same current directory.
• You have to customize only one file chooser, and your customizations apply to both the open and save versions of it.
• [PENDING: Any others?]

As you can see from the previous code snippet, the showXxxxDialog methods return an integer that indicates whether the user selected a file. You can use the return value to determine whether to perform the required operation.

If the user chooses a file, the code calls getSelectedFile on the file chooser to get an instance of File, which represents the chosen file. The example gets the name of the file and uses it in the log message. You can call other methods on the File object, such as getPath or isDirectory, to get information about the file. You can also call other methods such as delete and rename to change the file in some way. Of course, you might also want to open or save the file using one of the reader or writer classes provided by the JDK. See Reading and Writing for information about using readers and writers to read and write data to the file system.

If you want to create a file chooser for a task other than opening or saving, or if you want to customize the file chooser, keep reading. These exciting topics about the file chooser follow:

• FileChooserDemo: Take 2
• Using a File Chooser for a Custom Task
• Filtering the List of Files
• Customizing the File View
• Providing an Accessory View
• The File Chooser API
• Examples that Use File Choosers

FileChooserDemo: Take 2

Now let's look at FileChooserDemo2.java, a modified version of the previous demo program that uses more of the JFileChooser API. This example uses a file chooser that has been customized in several ways. Like the original example, the user invokes a file chooser with the push of a button. Here's a picture of the file chooser:

[PENDING: add callouts to figure to point out file view, accessory, user-choosable filter, etc]

You need these source files to run this example: FileChooserDemo2.java, ImageFilter.java, ImageFileView.java, and ImagePreview.java.

As the figure shows, this file chooser has been customized for a special task (sending), provides a user-choosable file filter, uses a special file view for image files, and has an accessory view that displays a thumbnail sketch of the currently selected image file.

The remainder of this section shows you the code that creates and customizes this file chooser.

Using a File Chooser for a Custom Task

As you've seen, JFileChooser provides a method for displaying an open file chooser and another method for displaying a save as file chooser. In the Metal Look and Feel, the only difference between the two choosers is the title on the dialog window and the label on the "accept" button.

The class has a third method, showDialog, for displaying a file chooser for a custom task. Here's the code from FileChooserDemo2 that brings up the file chooser dialog for the Send task.

JFileChooser filechooser = new JFileChooser();

int returnVal = filechooser.showDialog(FileChooserDemo2.this,
				       "Send");

The first argument to the showDialog method is the parent component for the dialog. The second argument is a String that provides both the title for the dialog window and the label for the accept button.

Once again, the file chooser doesn't do anything with the selected file. The program is responsible for implementing the custom task for which the file chooser was created.

Filtering the List of Files

By default, a file chooser displays all of the files and directories that it detects. A program can apply one or more file filters to a file chooser so that the chooser shows only some files. The file chooser calls the filter's accept method for each file to determine whether it should be displayed. A file filter accepts or rejects a file based on some criteria such as file type, size, ownership, and so on.

JFileChooser supports three different kinds of filtering. The filters are checked in the order listed here. So a filter of the second type can filter only those files accepted by the first and so on.

Built-in filtering

Filtering is set up through specific method calls on a file chooser. Currently the only built-in filter available is for hidden files. Call setFileHidingEnabled(true) to turn off the display of hidden files (such as those that begin with '.' on UNIX systems).

Application-controlled filtering

The application determines which files are shown. Create a custom subclass of FileFilter, instantiate it, and use the instance as an argument to setFileFilter. The file chooser shows only those files that the filter accepts.

User-choosable filtering

The file chooser GUI provides a list of filters that the user can choose from. When the user chooses a filter, the file chooser shows only those file accepted by that filter. FileChooserDemo2 adds a custom file filter to its file chooser's list of user-choosable filters:

filechooser.addChoosableFileFilter(new ImageFilter());

The custom file filter is implemented in ImageFilter.java, as a subclass of FileFilter. The ImageFilter class implements the getDescription method to return a string to put in the list of user-choosable filters. As the following code shows, ImageFilter implements the accept method to accept all directories and any file that has a ".jpg", ".jpeg", ".gif", ".tif", or ".tiff" filename extension.

public boolean accept(File f) {

    if (f.isDirectory()) {
	return true;
    }

    String s = f.getName();
    int i = s.lastIndexOf('.');

    if (i > 0 &&  i < s.length() - 1) {
	String extension = s.substring(i+1).toLowerCase();
	if (tiff.equals(extension) ||
	    tif.equals(extension) ||
	    gif.equals(extension) ||
	    jpeg.equals(extension) ||
	    jpg.equals(extension)) {
	        return true;
	} else {
	    return false;
	}
    }

    return false;
}

By accepting all directories, this filter allows the user to navigate around the file system. If the bold lines were omitted from this method, the user would be limited to the directory with which the chooser was initialized.

Customizing the File View

File choosers present a list of files to choose from. In the Metal Look and Feel, the chooser's list shows each file's name and displays a small icon that represents whether the file is a true file or a directory. You can customize the list's file view by creating a custom subclass of FileView, using an instance of the class as an argument to setFileView. The example uses an instance of ImageFileView as the file chooser's file view:

filechooser.setFileView(new ImageFileView());

ImageFileView shows a different icon for each type of image accepted by the image filter described previously.

The ImageFileView class overrides the five abstract methods defined in FileView:

String getTypeDescription(File f)

Returns a description of the file type. Here is ImageFileView's implementation of this method:

public String getTypeDescription(File f) {
    String extension = getExtension(f);
    String type = null;

    if (extension != null) {
        if (extension.equals("jpeg")) {
            type = "JPEG Image";
        } else if (extension.equals("gif")){
            type = "GIF Image";
        } else if (extension.equals("tiff")) {
            type = "TIFF Image";
        }
    }
    return type;
}

[PENDING: where is this used?]

Icon getIcon(File f)

Returns an icon representing the file or its type. Here is ImageFileView's implementation of this method:

public Icon getIcon(File f) {
    String extension = getExtension(f);
    Icon icon = null;
    if (extension != null) {
        if (extension.equals("jpeg")) {
            icon = jpgIcon;
        } else if (extension.equals("gif")) {
            icon = gifIcon;
        } else if (extension.equals("tiff")) {
            icon = tiffIcon;
        }
    }
    return icon;
}

String getName(File f)

Returns the name of the file. Most implementations of this method should return null to indicate that the Look and Feel should figure it out. Another common implementation returns f.getName().

String getDescription(File f)

Returns a description of the file. A common implementation of this method returns null to indicate that the Look and Feel should figure it out. [PENDING: where is this used?]

Boolean isTraversable(File f)

Returns whether a directory is traversable or not. Most implementations of this method should return null to indicate that the Look and Feel should figure it out. Some applications might want to prevent users from descending into certain type of directory because it represents a compound document.

The ImageFileView implementation of both the getTypeDescription and getIcon methods uses a custom method called getExtension:

private String getExtension(File f) {

    String ext = null;
    String s = f.getName();
    int i = s.lastIndexOf('.');

    if (i > 0 &&  i < s.length() - 1) {
        ext = s.substring(i+1).toLowerCase();
    }
    return ext;
}

Providing an Accessory View

The customized file chooser in FileChooserDemo2 has an accessory view. If the currently selected item is a JPEG, TIFF, or GIF image, the accessory view displays a thumbnail sketch of the image. Otherwise, the accessory view is empty.

The example calls the setAccessory method to establish an instance of ImagePreview as the chooser's accessory view:

filechooser.setAccessory(new ImagePreview(filechooser));

Any object that inherits from JComponent can be an accessory view. The component should implement either paint or paintComponent, and have a preferred size that looks good in the file chooser.

The file chooser fires a property change event when the user selects an item in the list. So, a program with an accessory view must register to receive these events to update the accessory view whenever the selection changes. In the example, the ImagePreview object itself registers for these events. This keeps all the code related to the accessory view together in one class.

Here is the example's implementation of the propertyChange method, which is the method called when a property change event is fired:

public void propertyChange(PropertyChangeEvent e) {
    String prop = e.getPropertyName();
    if (prop == JFileChooser.SELECTED_FILE_CHANGED_PROPERTY) {
        f = (File) e.getNewValue();
        if (isShowing()) {
            loadImage();
            repaint();
        }
    }
}

This method loads the image and repaints the accessory view, if SELECTED_FILE_CHANGED_PROPERTY is the property that changed.

The File Chooser API

The API for using file choosers falls into these categories:

• Creating and Showing a File Chooser
• Navigating the File Chooser's List
• Customizing the File Chooser
• Selecting Files and Directories

Creating and Showing a File Chooser

Method	Purpose
JFileChooser() JFileChooser(File, FileSystemView) JFileChooser(File) JFileChooser(FileSystemView) JFileChooser(String, FileSystemView) JFileChooser(String)	Create a file chooser instance. The File and String arguments, when present, provide the initial directory. The FileSystemView argument, when present, [PENDING: does something].
int showOpenDialog(Component) int showSaveDialog(Component) int showDialog(Component, String)	Show a modal dialog containing the file chooser.

Navigating the File Chooser's List

Method	Purpose
void ensureFileIsVisible(File)	Force the indicated file to be visible in the file chooser's list.
void setCurrentDirectory(File) File getCurrentDirectory	Set or get the directory whose files are displayed in the file chooser's list.
void changeToParentDirectory()	Change the list to display the current directory's parent.
void rescanCurrentDirectory()	Check the file system and update the chooser's list.

Customizing the File Chooser

Method	Purpose
JComponent getAccessory() void setAccessory(JComponent)	Set or get the file chooser's accessory.
void setFileFilter(FileFilter) FileFilter getFileFilter()	Set or get the file chooser's primary file filter.
void setFileView(FileView) FileView getFileView()	Set or get the chooser's file view.
FileFilter[] getChoosableFileFilters() void setChoosableFileFilters(FileFilter[]) void addChoosableFileFilter(FileFilter) boolean removeChoosableFileFilter(FileFilter) void resetChoosable(FileFilter) FileFilter getAcceptAllFileFilter()	Set, get, or modify the list of user-choosable file filters.
void setFileHidingEnabled(boolean) boolean isFileHidingEnabled()	Set or get whether hidden files are displayed.

Selecting Files and Directories

Method	Purpose
void setFileSelectionMode(int) int getFileSelectionMode() boolean isDirectorySelectionEnabled() boolean isFileSelectionEnabled()	Set the file selection mode. Acceptable values are FILES_ONLY, DIRECTORIES_ONLY, and FILES_AND_DIRECTORIES.
void setMultiSelectionEnabled(boolean) boolean isMultiSelectionEnabled()	Set or get whether multiple files can be selected at once.
void setSelectedFile(File) File getSelectedFile()	Set or get the currently selected file.
void setSelectedFiles(File[]) File[] getSelectedFiles()	Set or get the currently selected files.

Examples that Use File Choosers

This table shows the examples that use JFileChooser and where those examples are described.

Example	Where Described	Notes
FileChooserDemo.java	This page	Invokes an open file chooser and a save as file chooser.
FileChooserDemo2.java	This page	Uses a file chooser with custom filtering, a custom file view, and an accessory view.

Using the JFC/Swing Packages