org.openide.filesystems 7.38.1

org.openide.filesystems
Class FileChooserBuilder

java.lang.Object
  extended by org.openide.filesystems.FileChooserBuilder

public class FileChooserBuilder
extends Object

Utility class for working with JFileChoosers. In particular, remembering the last-used directory for a given file is made transparent. You pass an ad-hoc string key to the constructor (the fully qualified name of the calling class is good for uniqueness, and there is a constructor that takes a Class object as an argument for this purpose). That key is used to look up the most recently-used directory from any previous invocations with the same key. This makes it easy to have your user interface “remember” where the user keeps particular types of files, and saves the user from having to navigate through the same set of directories every time they need to locate a file from a particular place.

FileChooserBuilder's methods each return this, so it is possible to chain invocations to simplify setting up a file chooser. Example usage:

      //The default dir to use if no value is stored
      File home = new File (System.getProperty("user.home") + File.separator + "lib");
      //Now build a file chooser and invoke the dialog in one line of code
      //"libraries-dir" is our unique key
      File toAdd = new FileChooserBuilder ("libraries-dir").setTitle("Add Library").
              setDefaultWorkingDirectory(home).setApproveText("Add").showOpenDialog();
      //Result will be null if the user clicked cancel or closed the dialog w/o OK
      if (toAdd != null) {
          //do something
      }

Instances of this class are intended to be thrown away after use. Typically you create a builder, set it to create file choosers as you wish, then use it to show a dialog or create a file chooser you then do something with.

Supports the most common subset of JFileChooser functionality; if you need to do something exotic with a file chooser, you are probably better off creating your own.

Note: If you use the constructor that takes a Class object, please use new FileChooserBuilder(MyClass.class), not new FileChooserBuilder(getClass()). This avoids unexpected behavior in the case of subclassing.


Nested Class Summary
static interface FileChooserBuilder.BadgeProvider
          Provides "badges" for icons that indicate files or folders of particular interest to the user.
static interface FileChooserBuilder.SelectionApprover
          Object which can approve the selection (enabling the OK button or equivalent) in a JFileChooser.
 
Constructor Summary
FileChooserBuilder(Class type)
          Create a new FileChooserBuilder using the name of the passed class as the metadata for looking up a starting directory from previous application sessions or invocations.
FileChooserBuilder(String dirKey)
          Create a new FileChooserBuilder.
 
Method Summary
 FileChooserBuilder addFileFilter(FileFilter filter)
          Equivalent to calling JFileChooser.addChoosableFileFilter(filter).
 JFileChooser createFileChooser()
          Create a JFileChooser that conforms to the parameters set in this builder.
 FileChooserBuilder forceUseOfDefaultWorkingDirectory(boolean val)
          Force use of the failover directory - i.e.
 FileChooserBuilder setAccessibleDescription(String aDescription)
          Set the accessible description for any file choosers created by this builder
 FileChooserBuilder setApproveText(String val)
          Set the text on the OK button for any file chooser dialogs produced by this builder.
 FileChooserBuilder setBadgeProvider(FileChooserBuilder.BadgeProvider provider)
          Provide an implementation of BadgeProvider which will "badge" the icons of some files.
 FileChooserBuilder setControlButtonsAreShown(boolean val)
          Show/hide control buttons
 FileChooserBuilder setDefaultWorkingDirectory(File dir)
          Set the current directory which should be used only if a last-used directory cannot be found for the key string passed into this builder's constructor.
 FileChooserBuilder setDirectoriesOnly(boolean val)
          Set whether or not any file choosers created by this builder will show only directories.
 FileChooserBuilder setFileFilter(FileFilter filter)
          Set a file filter which filters the list of selectable files.
 FileChooserBuilder setFileHiding(boolean fileHiding)
          Enable file hiding in any created file choosers
 FileChooserBuilder setFilesOnly(boolean val)
           
 FileChooserBuilder setSelectionApprover(FileChooserBuilder.SelectionApprover approver)
          Set a selection approver which can display an "Overwrite file?" or similar dialog if necessary, when the user presses the accept button in the file chooser dialog.
 FileChooserBuilder setTitle(String val)
          Set the dialog title for any JFileChoosers created by this builder.
 File[] showMultiOpenDialog()
          Show an open dialog that allows multiple selection.
 File showOpenDialog()
          Show an open dialog with a file chooser set up according to the parameters of this builder.
 File showSaveDialog()
          Show a save dialog with the file chooser set up according to the parameters of this builder.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

FileChooserBuilder

public FileChooserBuilder(Class type)
Create a new FileChooserBuilder using the name of the passed class as the metadata for looking up a starting directory from previous application sessions or invocations.

Parameters:
type - A non-null class object, typically the calling class

FileChooserBuilder

public FileChooserBuilder(String dirKey)
Create a new FileChooserBuilder. The passed key is used as a key into NbPreferences to look up the directory the file chooser should initially be rooted on.

Parameters:
dirKey - A non-null ad-hoc string. If a FileChooser was previously used with the same string as is passed, then the initial directory
Method Detail

setDirectoriesOnly

public FileChooserBuilder setDirectoriesOnly(boolean val)
Set whether or not any file choosers created by this builder will show only directories.

Parameters:
val - true if files should not be shown
Returns:
this

setFilesOnly

public FileChooserBuilder setFilesOnly(boolean val)

setBadgeProvider

public FileChooserBuilder setBadgeProvider(FileChooserBuilder.BadgeProvider provider)
Provide an implementation of BadgeProvider which will "badge" the icons of some files.

Parameters:
provider - A badge provider which will alter the icon of files or folders that may be of particular interest to the user
Returns:
this

setTitle

public FileChooserBuilder setTitle(String val)
Set the dialog title for any JFileChoosers created by this builder.

Parameters:
val - A localized, human-readable title
Returns:
this

setApproveText

public FileChooserBuilder setApproveText(String val)
Set the text on the OK button for any file chooser dialogs produced by this builder.

Parameters:
val - A short, localized, human-readable string
Returns:
this

setFileFilter

public FileChooserBuilder setFileFilter(FileFilter filter)
Set a file filter which filters the list of selectable files.

Parameters:
filter -
Returns:
this

setDefaultWorkingDirectory

public FileChooserBuilder setDefaultWorkingDirectory(File dir)
Set the current directory which should be used only if a last-used directory cannot be found for the key string passed into this builder's constructor.

Parameters:
dir - A directory to root any created file choosers on if there is no stored path for this builder's key
Returns:
this

setFileHiding

public FileChooserBuilder setFileHiding(boolean fileHiding)
Enable file hiding in any created file choosers

Parameters:
fileHiding - Whether or not to hide files. Default is no.
Returns:
this

setControlButtonsAreShown

public FileChooserBuilder setControlButtonsAreShown(boolean val)
Show/hide control buttons

Parameters:
val - Whether or not to hide files. Default is no.
Returns:
this

setAccessibleDescription

public FileChooserBuilder setAccessibleDescription(String aDescription)
Set the accessible description for any file choosers created by this builder

Parameters:
aDescription - The description
Returns:
this

createFileChooser

public JFileChooser createFileChooser()
Create a JFileChooser that conforms to the parameters set in this builder.

Returns:
A file chooser

forceUseOfDefaultWorkingDirectory

public FileChooserBuilder forceUseOfDefaultWorkingDirectory(boolean val)
Force use of the failover directory - i.e. ignore the directory key passed in.

Parameters:
val -
Returns:
this

showMultiOpenDialog

public File[] showMultiOpenDialog()
Show an open dialog that allows multiple selection.

Returns:
An array of files, or null if the user cancelled the dialog

showOpenDialog

public File showOpenDialog()
Show an open dialog with a file chooser set up according to the parameters of this builder.

Returns:
A file if the user clicks the accept button and a file or folder was selected at the time the user clicked cancel.

showSaveDialog

public File showSaveDialog()
Show a save dialog with the file chooser set up according to the parameters of this builder.

Returns:
A file if the user clicks the accept button and a file or folder was selected at the time the user clicked cancel.

addFileFilter

public FileChooserBuilder addFileFilter(FileFilter filter)
Equivalent to calling JFileChooser.addChoosableFileFilter(filter). Adds another file filter that can be displayed in the file filters combo box in the file chooser.

Parameters:
filter - The file filter to add
Returns:
this
Since:
7.26.0

setSelectionApprover

public FileChooserBuilder setSelectionApprover(FileChooserBuilder.SelectionApprover approver)
Set a selection approver which can display an "Overwrite file?" or similar dialog if necessary, when the user presses the accept button in the file chooser dialog.

Parameters:
approver - A SelectionApprover which will determine if the selection is valid
Returns:
this
Since:
7.26.0

org.openide.filesystems 7.38.1

Built on November 27 2010.  |  Portions Copyright 1997-2010 Sun Microsystems, Inc. All rights reserved.