| JVM | Platform | Status |
|---|---|---|
| OpenJDK (Temurin) Current | Linux |  |
| OpenJDK (Temurin) LTS | Linux |  |
| OpenJDK (Temurin) Current | Windows |  |
| OpenJDK (Temurin) LTS | Windows |  |
An alternative to JavaFX's FileChooser that aims to be feature-compatible, if not fully API-compatible.
- Configurable, styleable (CSS), consistent, non-native JavaFX file chooser.
- Compatible with any JSR 203 filesystem.
- Directory creation.
- Configurable, extensible file/directory filtering.
- Simple case-insensitive directory searching.
- Written in pure Java 21.
- OSGi ready
- JPMS ready
- ISC license
- High-coverage automated test suite
JavaFX provides FileChooser and DirectoryChooser
classes that delegate to the operating system's default file chooser implementation on each platform.
This is in contrast to the file chooser abstractions available in Swing,
which provides a single non-native file chooser that behaves identically on all platforms. While native file
choosers do have certain benefits, it also means that the file choosers in JavaFX applications cannot be easily
styled to match the rest of the application. It also means that applications, for better or worse, behave
slightly differently on each platform. The purpose of the jwheatsheaf package is to provide a
configurable, styleable, consistent, non-native file chooser implementation analogous to the JFileChooser
class.
$ mvn clean verify
Note: The above will run the test suite, and this will take over your
keyboard and mouse for the duration of the test suite run. If you don't
want to run the tests, use the skipTests propery:
$ mvn -DskipTests=true clean verify
The simplest possible code that can open a file chooser and select at most one file:
final Window mainWindow = ...;
final var configuration =
JWFileChooserConfiguration.builder()
.build();
final var choosers = JWFileChoosers.create();
final var chooser = choosers.create(configuration);
final List<Path> selected = chooser.showAndWait();
The above code will open a modal file chooser that can choose files from the
default Java NIO filesystem, and will return the selected files (if any) in
selected.
The JWFileChooserConfiguration class comes with numerous configuration parameters,
with the FileSystem parameter being the only mandatory parameter.
A list of file filters can be passed to file choosers via the fileFilters configuration
parameter. File choosers are always equipped with a file filter that displays all files
(in other words, does no filtering) even if an empty list is passed in fileFilters. The
list of file filters will appear in the menu at the bottom of file chooser dialogs, allowing the
user to select one to filter results.
final var configuration =
JWFileChooserConfiguration.builder()
.addFileFilters(new ExampleFilterRejectAll())
.addFileFilters(new ExampleFilterXML())
.build();
The com.io7m.jwheatsheaf.filter.glob module provides a convenient system for constructing rule-based filters for files.
A Glob Filter consists of rules evaluated in declaration order against incoming filenames.
A filter rule must be one of INCLUDE, EXCLUDE, INCLUDE_AND_HALT, or
EXCLUDE_AND_HALT. The incoming file names are matched against the
patterns given in the filter rules. The patterns are given in
PathMatcher glob syntax.
A file is included or excluded based on the result of the last rule that matched the file.
The INCLUDE rule marks a file as included if the pattern matches the file
name. Evaluation of other rules continues if the pattern matches.
The EXCLUDE rule marks a file as excluded if the pattern matches the file
name. Evaluation of other rules continues if the pattern matches.
The INCLUDE_AND_HALT rule marks a file as included if the pattern matches
the file name. Evaluation of other rules halts if the pattern matches.
The EXCLUDE_AND_HALT rule marks a file as excluded if the pattern matches
the file name. Evaluation of other rules halts if the pattern matches.
If no rules are specified at all, no files are included. If no rules match at all for a given file, the file is not included.
As an example, a filter that allows access to .txt and .png files but
excludes data.txt:
final var filters =
new JWFilterGlobFactory();
final var filter =
filters.create("Text and images (*.txt, *.png)")
.addRule(INCLUDE, "**/*.txt")
.addRule(INCLUDE, "**/*.png")
.addRule(EXCLUDE_AND_HALT, "**/data.txt")
.build();
By default, file choosers are configured to allow the selection of at most one file. The "OK" button cannot be clicked until one file is selected. Other behaviours can be specified by setting the action for the chooser:
final var configuration =
JWFileChooserConfiguration.builder()
.setAction(OPEN_EXISTING_MULTIPLE)
.build();
If a home directory path is specified (typically a value taken from System.getProperty("user.home")),
a button will be displayed in the UI that allows for navigating directly to this path.
final var configuration =
JWFileChooserConfiguration.builder()
.setHomeDirectory(someHomeDirectoryPath)
.build();
The titles of file chooser dialogs can be adjusted in the configuration. By default, a generic "Please select…" title is used if no other value is specified.
final var configuration =
JWFileChooserConfiguration.builder()
.setTitle("Export to PNG…")
.build();
Some of the strings in the file chooser UI may be customized on a per-chooser basis. For example, this can be useful for specifying strings such as "Export" instead of "Save" for the "Save" button in the file chooser. To specify custom strings, provide an implementation of JWFileChooserStringOverridesType in the constructor. An abstract implementation is available for convenience.
final var customStrings =
new JWFileChooserStringOverridesAbstract() {
@Override
public Optional<String> buttonSave()
{
return Optional.of("Export");
}
};
final var configuration =
JWFileChooserConfiguration.builder()
.setStringOverrides(customStrings)
.build();
The file chooser can optionally prompt for confirmation of the selection of
files when in CREATE mode.
final var configuration =
JWFileChooserConfiguration.builder()
.setAction(CREATE)
.setConfirmFileSelection(true)
.build();
The file chooser can display a list of recently used items. It is the responsibility of
applications using the file chooser to save and otherwise manage this list between
application runs; the jwheatsheaf file chooser simply displays whatever list
of paths is passed in:
final var configuration =
JWFileChooserConfiguration.builder()
.setRecentFiles(List.of(
Paths.get("/tmp/x"),
Paths.get("/tmp/y"),
Paths.get("/tmp/z"),
))
.build();
The file chooser contains a button that allows for the creation of new directories. This can be disabled.
final var configuration =
JWFileChooserConfiguration.builder()
.setAllowDirectoryCreation(false)
.build();
The file chooser provides a JWFileImageSetType interface that allows for
defining the icons used by the user interface. Users wishing to use custom icon
sets should implement this interface and pass in an instance to the configuration:
final var configuration =
JWFileChooserConfiguration.builder()
.setFileImageSet(new CustomIcons())
.build();
The jwheatsheaf file chooser is styleable via CSS. By default, the file chooser applies
no styling and uses whatever is the default for the application. A custom stylesheet and icon set
can be supplied via the JWFileChooserConfiguration class, allowing for very different
visuals:
All of the elements in a file chooser window are assigned CSS identifiers.
| Identifier | Description |
|---|---|
| fileChooserPathMenu | The path menu used to select directory ancestors. |
| fileChooserUpButton | The button used to move to the parent directory. |
| fileChooserHomeButton | The button used to move to the home directory. |
| fileChooserCreateDirectoryButton | The button used to create directories. |
| fileChooserSelectDirectButton | The button used to enter paths directly. |
| fileChooserSearchField | The search field used to filter the directory table. |
| fileChooserDirectoryTable | The table that shows the contents of the current directory. |
| fileChooserSourceList | The list view that shows the recent items and the filesystem roots. |
| fileChooserNameField | The field that shows the selected file name. |
| fileChooserFilterMenu | The menu that allows for selecting file filters. |
| fileChooserCancelButton | The cancel button. |
| fileChooserOKButton | The confirmation button. |
| fileChooserProgress | The indeterminate progress indicator shown during I/O operations. |